# WooCommerce Documentation - Complete

This file contains the complete content of all documentation files combined.

## Getting Started with WooCommerce APIs

*Source: apis/README.md*

# Getting Started with WooCommerce APIs

WooCommerce provides a number of programmatic APIs to interact with WooCommerce store data.

## WC REST API

The WC REST API is a powerful part of WooCommerce which lets you read and write various parts of WooCommerce data such as orders, products, coupons, customers, and shipping zones. It based on the [WordPress REST API](https://developer.wordpress.org/rest-api/).

Explore the [WC REST API](./rest-api/) documentation.

## Store API

The Store API provides public REST API endpoints for the development of customer-facing cart, checkout, and product functionality. In contrast to the WooCommerce REST API, the Store API is unauthenticated and does not provide access to sensitive store data or other customer information.

Explore the [Store API](./store-api/README.md) documentation.

## Dual API (code + GraphQL, experimental)

The dual API is an experimental, code-first API architecture: you write plain PHP classes (the code API) and a build script generates a matching GraphQL endpoint from them. The engine is provided by the WooCommerce Dual API plugin, and any plugin can use it to build its own dual API.

Explore the [Dual API](./dual-api/README.md) documentation.

## Other Resources

Beyond the powerful REST APIs, WooCommerce offers a suite of PHP-based APIs designed for developers to deeply integrate and extend the core functionality of their store. These APIs allow for direct interaction with WooCommerce classes, enabling custom behaviors for settings, payment gateways, shipping methods, and more.

### Settings API

The Settings API is used by extensions to display, save, and load settings.

Explore the [Settings API](/docs/extensions/settings-and-config/settings-api) documentation.

### Payment Gateway API

The Payment Gateway API is used by extensions to interact with the payment gateway.

Explore the [Payment Gateway API](/docs/features/payments/payment-gateway-api/) documentation.

### Shipping Method API

The Shipping Method API is used by extensions to extend shipping methods and add their own rates.

Explore the [Shipping Method API](/docs/features/shipping/shipping-method-api/) documentation.

### Payment Token API

The Payment Token API is used for storing and managing payment tokens for gateways.

Explore the [Payment Token API](/docs/features/payments/payment-token-api/) documentation.

### WooCommerce Code Reference

The WooCommerce Code Reference is a comprehensive documentation of the WooCommerce API. It is a great resource for developers to learn about the WooCommerce API and how to use it.

The WooCommerce Code Reference is a comprehensive documentation of the internal WooCommerce Classes, API, and functions. It is a great resource for developers to learn about the WooCommerce functionality and how to extend it.

Explore the [WooCommerce Code Reference](https://woocommerce.github.io/code-reference/) documentation.


---

## WooCommerce Dual API

*Source: apis/dual-api/README.md*

# WooCommerce Dual API

The **dual API** is a code-first API architecture: you write plain PHP classes (the **code API**), and a build script generates a fully functional **GraphQL API** that mirrors them.

The dual API was introduced as an experimental feature in WooCommerce core 10.9, but as of WooCommerce 11.2 its engine has moved to a dedicated plugin, [WooCommerce Dual API](https://github.com/woocommerce/woocommerce-dual-api), which any plugin can use to build its own dual API.

> **This feature is experimental.** Everything under the `Automattic\WooCommerce\Api` namespace can change in backwards-incompatible ways, or be removed, in any release. Do not use it in production extensions.

## Where the documentation lives

The engine and its documentation live in the plugin's repository:

- **Plugin**: [woocommerce/woocommerce-dual-api](https://github.com/woocommerce/woocommerce-dual-api)
- **Documentation**: the [`docs/` directory](https://github.com/woocommerce/woocommerce-dual-api/tree/trunk/docs) of that repository
- **Working example**: [woocommerce/woocommerce-simple-events](https://github.com/woocommerce/woocommerce-simple-events), a runnable reference plugin that exercises the engine end to end

## Requirements

WooCommerce 11.2 or newer on PHP 8.1+, with the WooCommerce Dual API plugin installed and active. There is no feature flag: activating the plugin enables the engine.

WooCommerce 10.9 to 11.1 ship the engine inside core, behind a hidden `dual_code_graphql_api` feature flag (`wp option update woocommerce_feature_dual_code_graphql_api_enabled yes` to enable it). The plugin stays dormant on those versions and the flag remains the switch there.


---

## Authentication

*Source: apis/rest-api/authentication.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Authentication

WooCommerce includes two ways to authenticate with the WP REST API. It is also possible to authenticate using any [WP REST API authentication](http://v3.wp-api.org/guide/authentication/) plugin or method.

## REST API keys

Pre-generated keys can be used to authenticate use of the REST API endpoints. New keys can be generated either through the WordPress admin interface or they can be auto-generated through an endpoint.

### Generating API keys in the WordPress admin interface

To create or manage keys for a specific WordPress user, go to WooCommerce > Settings > Advanced > REST API.

*Note: Keys/Apps was found at WooCommerce > Settings > API > Key/Apps prior to WooCommerce 3.4.*

![WooCommerce REST API keys settings](v3/images/woocommerce-api-keys-settings.png)

Click the "Add Key" button. In the next screen, add a description and select the WordPress user you would like to generate the key for. Use of the REST API with the generated keys will conform to that user's WordPress roles and capabilities.

Choose the level of access for this REST API key, which can be _Read_ access, _Write_ access or _Read/Write_ access. Then click the "Generate API Key" button and WooCommerce will generate REST API keys for the selected user.

![Creating a new REST API key](v3/images/woocommerce-creating-api-keys.png)

Now that keys have been generated, you should see two new keys, a QRCode, and a Revoke API Key button. These two keys are your Consumer Key and Consumer Secret.

![Generated REST API key](v3/images/woocommerce-api-key-generated.png)

If the WordPress user associated with an API key is deleted, the API key will cease to function. API keys are not transferred to other users.

### Auto generating API keys using our Application Authentication Endpoint

This endpoint can be used by any APP to *allow users to generate API keys* for your APP. This makes integration with WooCommerce API easier because the user only needs to grant access to your APP via a URL. After being redirected back to your APP, the API keys will be sent back in a separate POST request.

The following image illustrates how this works:

![Authentication Endpoint flow](v3/images/woocommerce-auth-endpoint-flow.png)

:::warning
This endpoint works exclusively for users to generate API keys and facilitate integration between the WooCommerce REST API and an application. In no way is this endpoint intended to be used as login method for customers.
:::

#### URL parameters

|   Parameter    |  Type  |                                                                                  Description                                                                                  |
|----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `app_name`     | string | Your APP name `MANDATORY`                                                                                                                       |
| `scope`        | string | Level of access. Available: `read`, `write` and `read_write` `MANDATORY`                                                                        |
| `user_id`      | string | User ID in your APP. For your internal reference, used when the user is redirected back to your APP. NOT THE USER ID IN WOOCOMMERCE `MANDATORY` |
| `return_url`   | string | URL the user will be redirected to after authentication `MANDATORY`                                                                             |
| `callback_url` | string | URL that will receive the generated API key. Note: this URL should be over **HTTPS** `MANDATORY`                                                |

#### Creating an authentication endpoint URL

You must use the `/wc-auth/v1/authorize` endpoint and pass the above parameters as a query string.

> Example of how to build an authentication URL:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
# Bash example
STORE_URL='http://example.com'
ENDPOINT='/wc-auth/v1/authorize'
PARAMS="app_name=My App Name&scope=read_write&user_id=123&return_url=http://app.com/return-page&callback_url=https://app.com/callback-endpoint"
QUERY_STRING="$(perl -MURI::Escape -e 'print uri_escape($ARGV[0]);' "$PARAMS")"
QUERY_STRING=$(echo $QUERY_STRING | sed -e "s/%20/\+/g" -e "s/%3D/\=/g" -e "s/%26/\&/g")

echo "$STORE_URL$ENDPOINT?$QUERY_STRING"
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const querystring = require('querystring');

const store_url = 'http://example.com';
const endpoint = '/wc-auth/v1/authorize';
const params = {
  app_name: 'My App Name',
  scope: 'read_write',
  user_id: 123,
  return_url: 'http://app.com/return-page',
  callback_url: 'https://app.com/callback-endpoint'
};
const query_string = querystring.stringify(params).replace(/%20/g, '+');

console.log(store_url + endpoint + '?' + query_string);
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$store_url = 'http://example.com';
$endpoint = '/wc-auth/v1/authorize';
$params = [
    'app_name' => 'My App Name',
    'scope' => 'write',
    'user_id' => 123,
    'return_url' => 'http://app.com',
    'callback_url' => 'https://app.com'
];
$query_string = http_build_query( $params );

echo $store_url . $endpoint . '?' . $query_string;
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
from urllib.parse import urlencode

store_url = 'http://example.com'
endpoint = '/wc-auth/v1/authorize'
params = {
    "app_name": "My App Name",
    "scope": "read_write",
    "user_id": 123,
    "return_url": "http://app.com/return-page",
    "callback_url": "https://app.com/callback-endpoint"
}
query_string = urlencode(params)

print("%s%s?%s" % (store_url, endpoint, query_string))
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
require "uri"

store_url = 'http://example.com'
endpoint = '/wc-auth/v1/authorize'
params = {
  app_name: "My App Name",
  scope: "read_write",
  user_id: 123,
  return_url: "http://app.com/return-page",
  callback_url: "https://app.com/callback-endpoint"
}
query_string = URI.encode_www_form(params)

puts "#{store_url}#{endpoint}?#{query_string}"
```

  </TabItem>
</Tabs>

> Example of JSON posted with the API Keys

```
{
    "key_id": 1,
    "user_id": 123,
    "consumer_key": "ck_xxxxxxxxxxxxxxxx",
    "consumer_secret": "cs_xxxxxxxxxxxxxxxx",
    "key_permissions": "read_write"
}
```

Example of the screen that the user will see:

![Authentication Endpoint example](v3/images/woocommerce-auth-endpoint-example.png)

#### Notes

- While redirecting the user using `return_url`, you are also sent `success` and `user_id` parameters as query strings.
- `success` sends `0` if the user denied, or `1` if authenticated successfully.
- Use `user_id` to identify the user when redirected back to the (`return_url`) and also remember to save the API Keys when your `callback_url` is posted to after auth.
- The auth endpoint will send the API Keys in JSON format to the `callback_url`, so it's important to remember that some languages such as PHP will not display it inside the `$_POST` global variable, in PHP you can access it using `$HTTP_RAW_POST_DATA` (for old PHP versions) or `file_get_contents('php://input');`.
- The URL generated must have all query string values encoded.

## Authentication over HTTPS

You may use [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication) by providing the REST API Consumer Key as the username and the REST API Consumer Secret as the password.

> HTTP Basic Auth example

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://www.example.com/wp-json/wc/v3/orders \
    -u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
// import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api"; // Supports ESM

const WooCommerce = new WooCommerceRestApi({
  url: 'https://example.com',
  consumerKey: 'consumer_key',
  consumerSecret: 'consumer_secret',
  version: 'wc/v3'
});
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Automattic\WooCommerce\Client;

$woocommerce = new Client(
    'https://example.com',
    'consumer_key',
    'consumer_secret',
    [
        'wp_api' => true,
        'version' => 'wc/v3'
    ]
);
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
from woocommerce import API

wcapi = API(
    url="https://example.com",
    consumer_key="consumer_key",
    consumer_secret="consumer_secret",
    wp_api=True,
    version="wc/v3"
)
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
require "woocommerce_api"

woocommerce = WooCommerce::API.new(
  "https://example.com",
  "consumer_key",
  "consumer_secret",
  {
    wp_json: true,
    version: "wc/v3"
  }
)
```

  </TabItem>
</Tabs>

Occasionally some servers may not parse the Authorization header correctly (if you see a "Consumer key is missing" error when authenticating over SSL, you have a server issue). In this case, you may provide the consumer key/secret as query string parameters instead.

> Example for servers that not properly parse the Authorization header:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://www.example.com/wp-json/wc/v3/orders?consumer_key=123&consumer_secret=abc
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
// import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api"; // Supports ESM

const WooCommerce = new WooCommerceRestApi({
  url: 'https://example.com',
  consumerKey: 'consumer_key',
  consumerSecret: 'consumer_secret',
  version: 'wc/v3',
  queryStringAuth: true // Force Basic Authentication as query string true and using under HTTPS
});
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Automattic\WooCommerce\Client;

$woocommerce = new Client(
    'https://example.com',
    'consumer_key',
    'consumer_secret',
    [
        'wp_api' => true,
        'version' => 'wc/v3',
        'query_string_auth' => true // Force Basic Authentication as query string true and using under HTTPS
    ]
);
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
from woocommerce import API

wcapi = API(
    url="https://example.com",
    consumer_key="consumer_key",
    consumer_secret="consumer_secret",
    wp_api=True,
    version="wc/v3",
    query_string_auth=True  # Force Basic Authentication as query string true and using under HTTPS
)
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
require "woocommerce_api"

woocommerce = WooCommerce::API.new(
  "https://example.com",
  "consumer_key",
  "consumer_secret",
  {
    wp_json: true,
    version: "wc/v3",
    query_string_auth: true  # Force Basic Authentication as query string true and using under HTTPS
  }
)
```

  </TabItem>
</Tabs>

## Authentication over HTTP

You must use [OAuth 1.0a "one-legged" authentication](http://tools.ietf.org/html/rfc5849) to ensure REST API credentials cannot be intercepted by an attacker. Typically you will use any standard OAuth 1.0a library in the language of your choice to handle the authentication, or generate the necessary parameters by following the following instructions.

### Creating a signature

#### Collect the request method and URL

First you need to determine the HTTP method you will be using for the request, and the URL of the request.

The **HTTP method** will be `GET` in our case.

The **Request URL** will be the endpoint you are posting to, e.g. `http://www.example.com/wp-json/wc/v3/orders`.

#### Collect parameters

Collect and normalize your parameters. This includes all `oauth_*` parameters except for the `oauth_signature` itself.

These values need to be encoded into a single string which will be used later on. The process to build the string is very specific:

1. [Percent encode](https://dev.twitter.com/oauth/overview/percent-encoding-parameters) every key and value that will be signed.
2. Sort the list of parameters alphabetically by encoded key.
3. For each key/value pair:
	- Append the encoded key to the output string.
	- Append the `=` character to the output string.
	- Append the encoded value to the output string.
	- If there are more key/value pairs remaining, append a `&` character to the output string.

When percent encoding in PHP for example, you would use `rawurlencode()`.

When sorting parameters in PHP for example, you would use `uksort( $params, 'strcmp' )`.

> Parameters example:

```
oauth_consumer_key=abc123&oauth_signature_method=HMAC-SHA1
```

#### Create the signature base string

The above values collected so far must be joined to make a single string, from which the signature will be generated. This is called the signature base string in the OAuth specification.

To encode the HTTP method, request URL, and parameter string into a single string:

1. Set the output string equal to the uppercase **HTTP Method**.
2. Append the `&` character to the output string.
3. [Percent encode](https://dev.twitter.com/oauth/overview/percent-encoding-parameters) the URL and append it to the output string.
4. Append the `&` character to the output string.
5. [Percent encode](https://dev.twitter.com/oauth/overview/percent-encoding-parameters) the parameter string and append it to the output string.

> Example signature base string:

```
GET&http%3A%2F%2Fwww.example.com%2Fwp-json%2Fwc%2Fv3%2Forders&oauth_consumer_key%3Dabc123%26oauth_signature_method%3DHMAC-SHA1
```

#### Generate the signature

Generate the signature using the *signature base string* and your consumer secret key with a `&` character with the HMAC-SHA1 hashing algorithm.

In PHP you can use the [hash_hmac](http://php.net/manual/en/function.hash-hmac.php) function.

HMAC-SHA1 or HMAC-SHA256 are the only accepted hash algorithms.

If you are having trouble generating a correct signature, you'll want to review the string you are signing for encoding errors. The [authentication source](https://github.com/woocommerce/woocommerce/blob/master/includes/class-wc-rest-authentication.php#L185) can also be helpful in understanding how to properly generate the signature.

### OAuth tips

* The OAuth parameters may be added as query string parameters or included in the Authorization header.
* Note there is no reliable cross-platform way to get the raw request headers in WordPress, so query string should be more reliable in some cases.
* The required parameters are: `oauth_consumer_key`, `oauth_timestamp`, `oauth_nonce`, `oauth_signature`, and `oauth_signature_method`. `oauth_version` is not required and should be omitted.
* The OAuth nonce can be any randomly generated 32 character (recommended) string that is unique to the consumer key.
* The OAuth timestamp should be the unix timestamp at the time of the request. The REST API will deny any requests that include a timestamp outside of a 15 minute window to prevent replay attacks.
* You must use the store URL provided by the index when forming the base string used for the signature, as this is what the server will use. (e.g. if the store URL includes a `www` sub-domain, you should use it for requests)
* Note that the request body is *not* signed as per the OAuth spec.
* If including parameters in your request, it saves a lot of trouble if you can order your items alphabetically.
* Authorization header is supported starting WooCommerce 3.0.


---

## WooCommerce REST API

*Source: apis/rest-api/index.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# WooCommerce REST API

WooCommerce (WC) 2.6+ is fully integrated with the WordPress [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) API. This allows WC data to be created, read, updated, and deleted using requests in JSON format and using WordPress REST API Authentication methods and standard HTTP verbs which are understood by most HTTP clients.

The current WP REST API integration version is `v3` which takes a first-order position in endpoints.

## Requirements

To use the REST API you must be using:

- WooCommerce 3.5+
- WordPress 4.4+
- Pretty permalinks in **Settings > Permalinks** (default permalinks will not work)

You may access the API over either HTTP or HTTPS, but *HTTPS is recommended where possible*.

:::note
You are **not** required to install the [WP REST API (WP API)](https://wordpress.org/plugins/rest-api/) plugin.
:::

If you use ModSecurity and see `501 Method Not Implemented` errors, see [this issue](https://github.com/woocommerce/woocommerce/issues/9838) for details.

## Libraries and tools

### Official libraries

- [JavaScript](https://www.npmjs.com/package/@woocommerce/woocommerce-rest-api) Library
- [PHP](https://packagist.org/packages/automattic/woocommerce) Library
- [Python](https://pypi.python.org/pypi/WooCommerce) Library
- [Ruby](https://rubygems.org/gems/woocommerce_api) Library

<Tabs>
  <TabItem value="js" label="JavaScript">

```javascript
// Install:
// npm install --save @woocommerce/woocommerce-rest-api

// Setup:
const WooCommerceRestApi = require("@woocommerce/woocommerce-rest-api").default;
// import WooCommerceRestApi from "@woocommerce/woocommerce-rest-api"; // Supports ESM

const WooCommerce = new WooCommerceRestApi({
  url: 'http://example.com', // Your store URL
  consumerKey: 'consumer_key', // Your consumer key
  consumerSecret: 'consumer_secret', // Your consumer secret
  version: 'wc/v3' // WooCommerce WP REST API version
});
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
// Install:
// composer require automattic/woocommerce

// Setup:
require __DIR__ . '/vendor/autoload.php';

use Automattic\WooCommerce\Client;

$woocommerce = new Client(
    'http://example.com', // Your store URL
    'consumer_key', // Your consumer key
    'consumer_secret', // Your consumer secret
    [
        'wp_api' => true, // Enable the WP REST API integration
        'version' => 'wc/v3' // WooCommerce WP REST API version
    ]
);
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
# Install:
# pip install woocommerce

# Setup:
from woocommerce import API

wcapi = API(
    url="http://example.com", # Your store URL
    consumer_key="consumer_key", # Your consumer key
    consumer_secret="consumer_secret", # Your consumer secret
    wp_api=True, # Enable the WP REST API integration
    version="wc/v3" # WooCommerce WP REST API version
)
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
# Install:
# gem install woocommerce_api

# Setup:
require "woocommerce_api"

woocommerce = WooCommerce::API.new(
  "https://example.com", # Your store URL
  "consumer_key", # Your consumer key
  "consumer_secret", # Your consumer secret
  {
    wp_api: true, # Enable the WP REST API integration
    version: "wc/v3" # WooCommerce WP REST API version
  }
)
```

  </TabItem>
</Tabs>

### Third party libraries

- [Java](https://github.com/icoderman/wc-api-java) Library
- [.NET](https://github.com/XiaoFaye/WooCommerce.NET) Library
- [Android](https://github.com/gilokimu/WooDroid) Library

:::note
We don't offer support for third party libraries. If you have questions about how to use any of these libraries, contact the respective authors.
:::

### Tools

- [Insomnia](https://insomnia.rest) - Cross-platform GraphQL and REST client, available for Mac, Windows, and Linux.
- [Postman](https://www.getpostman.com/) - Cross-platform REST client, available for Mac, Windows, and Linux.
- [RequestBin](https://requestbin.com) - Allows you test webhooks.
- [Hookbin](https://hookbin.com/) - Another tool to test webhooks.

## Generate keys

To start using REST API, you first need to generate API keys.

1. Go to **WooCommerce > Settings > Advanced**
2. Go to the **REST API** tab and click **Add key**
3. Give the key a description for your own reference, choose a user with access to orders etc, and give the key **read/write** permissions
4. Click **Generate API key**
5. Your keys will be shown - do not close this tab yet, the secret will be hidden if you try to view the key again

![Generated API Keys](https://developer.woocommerce.com/wp-content/uploads/2023/12/keys.png)

## Make a basic request

The request URL we'll test is `wp-json/wc/v3/orders`. On localhost the full URL may look something like this: `https://localhost:8888/wp-json/wc/v3/orders`. Modify this to use your own site URL.

In Postman, you need to set the fields for request type, request URL, and the settings on the authorization tab. For Authorization, choose **basic auth** and enter your **consumer key** and **consumer secret** keys from WooCommerce into the username and password fields.

Once done, hit send and you'll see the JSON response from the API if all worked well:

![Postman example](https://developer.woocommerce.com/wp-content/uploads/2023/12/postman.png)

Insomnia is almost identical to Postman; fill in the same fields and again use basic auth:

![Insomnia example](https://developer.woocommerce.com/wp-content/uploads/2023/12/insomnia.png)

## Request/Response format

The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a `200 OK` HTTP status.

Some general information about responses:

- Dates are returned in ISO8601 format: `YYYY-MM-DDTHH:MM:SS`
- Resource IDs are returned as integers
- Any decimal monetary amount, such as prices or totals, will be returned as strings with two decimal places
- Other amounts, such as item counts, are returned as integers
- Blank fields are generally included as `null` or empty string instead of being omitted

### JSONP support

The WP REST API supports JSONP by default. JSONP responses use the `application/javascript` content-type. You can specify the callback using the `?_jsonp` parameter for `GET` requests to have the response wrapped in a JSON function:

```http
GET /wp-json/wc/v3?_jsonp=callback
```

## Parameters

Almost all endpoints accept optional parameters which can be passed as a HTTP query string parameter, e.g. `GET /orders?status=completed`. All parameters are documented along each endpoint.

## Pagination

Requests that return multiple items will be paginated to 10 items by default. This default can be changed by the site administrator by changing the `posts_per_page` option. Alternatively the items per page can be specified with the `?per_page` parameter:

```http
GET /orders?per_page=15
```

You can specify further pages with the `?page` parameter:

```http
GET /orders?page=2
```

You may also specify the offset from the first resource using the `?offset` parameter:

```http
GET /orders?offset=5
```

Page number is 1-based and omitting the `?page` parameter will return the first page.

The total number of resources and pages are always included in the `X-WP-Total` and `X-WP-TotalPages` HTTP headers.

### Link header

Pagination info is included in the [Link Header](http://tools.ietf.org/html/rfc5988). It's recommended that you follow these values instead of building your own URLs where possible.

```
Link: <https://www.example.com/wp-json/wc/v3/products?page=2>; rel="next",
<https://www.example.com/wp-json/wc/v3/products?page=3>; rel="last"
```

| Value   | Description                                              |
|---------|----------------------------------------------------------|
| `next`  | Shows the URL of the immediate next page of results.     |
| `last`  | Shows the URL of the last page of results.               |
| `first` | Shows the URL of the first page of results.              |
| `prev`  | Shows the URL of the immediate previous page of results. |

## Errors

Occasionally you might encounter errors when accessing the REST API. There are four possible types:

| Error Code                  | Error Type                                                  |
|-----------------------------|-------------------------------------------------------------|
| `400 Bad Request`           | Invalid request, e.g. using an unsupported HTTP method      |
| `401 Unauthorized`          | Authentication or permission error, e.g. incorrect API keys |
| `404 Not Found`             | Requests to resources that don't exist or are missing       |
| `500 Internal Server Error` | Server error                                                |

Errors return both an appropriate HTTP status code and response object which contains a `code`, `message` and `data` attribute:

```json
{
  "code": "woocommerce_rest_term_invalid",
  "message": "Resource doesn't exist.",
  "data": {
    "status": 404
  }
}
```

## Common connection issues

### Connection issues with localhost and self-signed SSL certificates

If you're having problems connecting to the REST API on your localhost and seeing SSL errors, you need to disable SSL verification.

In Postman you can find this in the settings:

![Postman settings](https://developer.woocommerce.com/wp-content/uploads/2023/12/postman-ssl.png)

Insomnia also has this setting in the preferences area:

![Insomnia settings](https://developer.woocommerce.com/wp-content/uploads/2023/12/insomnia-ssl.png)

### 401 Unauthorized

Your API keys or signature is wrong. Ensure that:

- The user you generated API keys for actually has access to those resources
- The username when authenticating is your consumer key
- The password when authenticating is your consumer secret
- Make a new set of keys to be sure

If your server utilizes FastCGI, check that your [authorization headers are properly read](https://web.archive.org/web/20230330133128/https://support.metalocator.com/en/articles/1654091-wp-json-basic-auth-with-fastcgi).

### Consumer key is missing

Occasionally servers may not parse the Authorization header correctly (if you see a "Consumer key is missing" error when authenticating over SSL, you have a server issue).

In this case, you may provide the consumer key/secret as query string parameters instead:

```text
https://local.wordpress.dev/wp-json/wc/v2/orders?consumer_key=XXXX&consumer_secret=XXXX
```

### Server does not support POST/DELETE/PUT

Ideally, your server should be configured to accept these types of API request, but if not you can use the [`_method` property](https://developer.wordpress.org/rest-api/using-the-rest-api/global-parameters/#_method-or-x-http-method-override-header).

## API version history

| API Version | WC Version     | WP Version   |
|-------------|----------------|--------------|
| `v3`        | 3.5.x or later | 4.4 or later |
| `v2`        | 3.0.x or later | 4.4 or later |
| `v1`        | 2.6.x or later | 4.4 or later |

## Learn more

Learn more about the REST API checking the [official WordPress REST API documentation](https://developer.wordpress.org/rest-api/).


---

## Coupons

*Source: apis/rest-api/v1/coupons.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Coupons
The coupons API allows you to create, view, update, and delete individual, or a batch, of coupon codes.

## Coupon properties
|           Attribute           |    Type   |                                                                      Description                                                                      |
|-------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                          | integer   | Unique identifier for the object. `READ-ONLY`                                                                           |
| `code`                        | string    | Coupon code. `MANDATORY`                                                                                                |
| `date_created`                | date-time | The date the coupon was created, in the site's timezone. `READ-ONLY`                                                    |
| `date_modified`               | date-time | The date the coupon was last modified, in the site's timezone. `READ-ONLY`                                              |
| `description`                 | string    | Coupon description.                                                                                                                                   |
| `discount_type`               | string    | Determines the type of discount that will be applied. Options: `fixed_cart`, `percent`, `fixed_product` and `percent_product`. Default: `fixed_cart`. |
| `amount`                      | string    | The amount of discount.                                                                                                                               |
| `expiry_date`                 | string    | UTC DateTime when the coupon expires.                                                                                                                 |
| `usage_count`                 | integer   | Number of times the coupon has been used already. `READ-ONLY`                                                           |
| `individual_use`              | boolean   | Whether coupon can only be used individually.                                                                                                         |
| `product_ids`                 | array     | List of product ID's the coupon can be used on.                                                                                                       |
| `exclude_product_ids`         | array     | List of product ID's the coupon cannot be used on.                                                                                                    |
| `usage_limit`                 | integer   | How many times the coupon can be used.                                                                                                                |
| `usage_limit_per_user`        | integer   | How many times the coupon can be used per customer.                                                                                                   |
| `limit_usage_to_x_items`      | integer   | Max number of items in the cart the coupon can be applied to.                                                                                         |
| `free_shipping`               | boolean   | Define if can be applied for free shipping.                                                                                                           |
| `product_categories`          | array     | List of category ID's the coupon applies to.                                                                                                          |
| `excluded_product_categories` | array     | List of category ID's the coupon does not apply to.                                                                                                   |
| `exclude_sale_items`          | boolean   | Define if should not apply when have sale items.                                                                                                      |
| `minimum_amount`              | string    | Minimum order amount that needs to be in the cart before coupon applies.                                                                              |
| `maximum_amount`              | string    | Maximum order amount allowed when using the coupon.                                                                                                   |
| `email_restrictions`          | array     | List of email addresses that can use this coupon.                                                                                                     |
| `used_by`                     | array     | List of user IDs who have used the coupon. `READ-ONLY`                                                                  |

## Create a coupon
This API helps you to create a new coupon.

```http
POST /wp-json/wc/v1/coupons
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/coupons \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "code": "10off",
  "discount_type": "percent",
  "amount": 10,
  "individual_use": true,
  "exclude_sale_items": true,
  "minimum_amount": "100.00"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  code: "10off",
  discount_type: "percent",
  amount: 10,
  individual_use: true,
  exclude_sale_items: true,
  minimum_amount: "100.00"
};

WooCommerce.post("coupons", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });

```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'code' => '10off',
    'discount_type' => 'percent',
    'amount' => 10,
    'individual_use' => true,
    'exclude_sale_items' => true,
    'minimum_amount' => '100.00'
];

print_r($woocommerce->post('coupons', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "code": "10off",
    "discount_type": "percent",
    "amount": 10,
    "individual_use": True,
    "exclude_sale_items": True,
    "minimum_amount": "100.00"
}

print(wcapi.post("coupons", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  code: "10off",
  discount_type: "percent",
  amount: 10,
  individual_use: true,
  exclude_sale_items: true,
  minimum_amount: "100.00"
}

woocommerce.post("coupons", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 113,
  "code": "10off",
  "date_created": "2016-04-28T21:55:54",
  "date_modified": "2016-04-28T21:55:54",
  "discount_type": "percent",
  "description": "",
  "amount": "10.00",
  "expiry_date": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "exclude_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": 0,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons/113"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a coupon
This API lets you retrieve and view a specific coupon by ID.

```http
GET /wp-json/wc/v1/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/coupons/113 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("coupons/113")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('coupons/113')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("coupons/113").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("coupons/113").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 113,
  "code": "10off",
  "date_created": "2016-04-28T21:55:54",
  "date_modified": "2016-04-28T21:55:54",
  "discount_type": "percent",
  "description": "",
  "amount": "10.00",
  "expiry_date": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "exclude_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": 0,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons/113"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all coupons
This API helps you to list all the coupons that have been created.

```http
GET /wp-json/wc/v1/coupons
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/coupons \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("coupons")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('coupons')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("coupons").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("coupons").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 114,
    "code": "free-shipping",
    "date_created": "2016-04-28T21:58:25",
    "date_modified": "2016-04-28T21:58:25",
    "discount_type": "fixed_cart",
    "description": "",
    "amount": "0.00",
    "expiry_date": null,
    "usage_count": 0,
    "individual_use": true,
    "product_ids": [],
    "exclude_product_ids": [],
    "usage_limit": null,
    "usage_limit_per_user": null,
    "limit_usage_to_x_items": 0,
    "free_shipping": false,
    "product_categories": [],
    "excluded_product_categories": [],
    "exclude_sale_items": true,
    "minimum_amount": "50.00",
    "maximum_amount": "0.00",
    "email_restrictions": [],
    "used_by": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/coupons/114"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/coupons"
        }
      ]
    }
  },
  {
    "id": 113,
    "code": "10off",
    "date_created": "2016-04-28T21:55:54",
    "date_modified": "2016-04-28T21:55:54",
    "discount_type": "percent",
    "description": "",
    "amount": "10.00",
    "expiry_date": null,
    "usage_count": 0,
    "individual_use": true,
    "product_ids": [],
    "exclude_product_ids": [],
    "usage_limit": null,
    "usage_limit_per_user": null,
    "limit_usage_to_x_items": 0,
    "free_shipping": false,
    "product_categories": [],
    "excluded_product_categories": [],
    "exclude_sale_items": true,
    "minimum_amount": "100.00",
    "maximum_amount": "0.00",
    "email_restrictions": [],
    "used_by": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/coupons/113"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/coupons"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter       |   Type  |                                                  Description                                                  |
|-----------------|---------|---------------------------------------------------------------------------------------------------------------|
| `context`       | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.     |
| `page`          | integer | Current page of the collection.                                                                               |
| `per_page`      | integer | Maximum number of items to be returned in result set.                                                         |
| `search`        | string  | Limit results to those matching a string.                                                                     |
| `after`         | string  | Limit response to resources published after a given ISO8601 compliant date.                                   |
| `before`        | string  | Limit response to resources published before a given ISO8601 compliant date.                                  |
| `dates_are_gmt` | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                      |
| `exclude`       | string  | Ensure result set excludes specific ids.                                                                      |
| `include`       | string  | Limit result set to specific ids.                                                                             |
| `offset`        | integer | Offset the result set by a specific number of items.                                                          |
| `order`         | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                    |
| `orderby`       | string  | Sort collection by object attribute. Default is `date`, Options: `date`, `id`, `include`, `title` and `slug`. |
| `code`          | string  | Limit result set to resources with a specific code.                                                           |

## Update a coupon
This API lets you make changes to a coupon.

```http
PUT /wp-json/wc/v1/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/coupons/113 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "amount": 5
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  amount: 5
};

WooCommerce.put("coupons/113", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php 
$data = [
    'amount' => 5
];

print_r($woocommerce->put('coupons/113', $data)); 
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "amount": 5
}

print(wcapi.put("coupons/113", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  amount: 5
}

woocommerce.put("coupons/113", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 113,
  "code": "10off",
  "date_created": "2016-04-28T21:55:54",
  "date_modified": "2016-04-28T22:00:49",
  "discount_type": "percent",
  "description": "",
  "amount": "5.00",
  "expiry_date": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "exclude_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": 0,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons/113"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a coupon
This API helps you delete a coupon.

```http
DELETE /wp-json/wc/v1/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/coupons/113?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("coupons/113", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('coupons/113', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("coupons/113", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("coupons/113", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 113,
  "code": "10off",
  "date_created": "2016-04-28T21:55:54",
  "date_modified": "2016-04-28T22:00:49",
  "discount_type": "percent",
  "description": "",
  "amount": "5.00",
  "expiry_date": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "exclude_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": 0,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons/113"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                               Description                                |
|-----------|--------|--------------------------------------------------------------------------|
| `force`   | string | Use `true` whether to permanently delete the coupon, Default is `false`. |

## Batch update coupons
This API helps you to batch create, update and delete multiple coupons.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/coupons/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/coupons/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "code": "20off",
      "discount_type": "percent",
      "amount": 20,
      "individual_use": true,
      "exclude_sale_items": true,
      "minimum_amount": "100.00"
    },
    {
      "code": "30off",
      "discount_type": "percent",
      "amount": 30,
      "individual_use": true,
      "exclude_sale_items": true,
      "minimum_amount": "100.00"
    }
  ],
  "update": [
    {
      "id": 113,
      "minimum_amount": "50.00"
    }
  ],
  "delete": [
    137
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      code: "20off",
      discount_type: "percent",
      amount: 20,
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    },
    {
      code: "30off",
      discount_type: "percent",
      amount: 30,
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    }
  ],
  update: [
    {
      id: 113,
      minimum_amount: "50.00"
    }
  ],
  delete: [
    137
  ]
};

WooCommerce.post("coupons/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'code' => '20off',
            'discount_type' => 'percent',
            'amount' => 20,
            'individual_use' => true,
            'exclude_sale_items' => true,
            'minimum_amount' => '100.00'
        ],
        [
            'code' => '30off',
            'discount_type' => 'percent',
            'amount' => 30,
            'individual_use' => true,
            'exclude_sale_items' => true,
            'minimum_amount' => '100.00'
        ]
    ],
    'update' => [
        [
            'id' => 113,
            'minimum_amount' => '50.00'
        ]
    ],
    'delete' => [
        137
    ]
];

print_r($woocommerce->post('coupons/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "code": "20off",
            "discount_type": "percent",
            "amount": 20,
            "individual_use": True,
            "exclude_sale_items": True,
            "minimum_amount": "100.00"
        },
        {
            "code": "30off",
            "discount_type": "percent",
            "amount": 30,
            "individual_use": True,
            "exclude_sale_items": True,
            "minimum_amount": "100.00"
        }
    ],
    "update": [
        {
            "id": 113,
            "minimum_amount": "50.00"
        }
    ],
    "delete": [
        137
    ]
}

print(wcapi.post("coupons/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      code: "20off",
      discount_type: "percent",
      amount: 20,
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    },
    {
      code: "30off",
      discount_type: "percent",
      amount: 30,
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    }
  ],
  update: [
    {
      id: 113,
      minimum_amount: "50.00"
    }
  ],
  delete: [
    137
  ]
}

woocommerce.post("coupons/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 138,
      "code": "20off",
      "date_created": "2016-05-17T20:52:21",
      "date_modified": "2016-05-17T20:52:21",
      "discount_type": "percent",
      "description": "",
      "amount": "20.00",
      "expiry_date": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "exclude_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": 0,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "100.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons/138"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons"
          }
        ]
      }
    },
    {
      "id": 139,
      "code": "30off",
      "date_created": "2016-05-17T20:52:22",
      "date_modified": "2016-05-17T20:52:22",
      "discount_type": "percent",
      "description": "",
      "amount": "30.00",
      "expiry_date": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "exclude_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": 0,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "100.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons/139"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 113,
      "code": "10off",
      "date_created": "2016-04-28T21:55:54",
      "date_modified": "2016-05-17T20:52:23",
      "discount_type": "percent",
      "description": "",
      "amount": "5.00",
      "expiry_date": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "exclude_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": 0,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "50.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons/113"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 137,
      "code": "50off",
      "date_created": "2016-05-17T20:49:12",
      "date_modified": "2016-05-17T20:50:30",
      "discount_type": "fixed_cart",
      "description": "",
      "amount": "50.00",
      "expiry_date": null,
      "usage_count": 0,
      "individual_use": false,
      "product_ids": [],
      "exclude_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": 0,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": false,
      "minimum_amount": "0.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons/137"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Customers

*Source: apis/rest-api/v1/customers.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Customers
The customer API allows you to create, view, update, and delete individual, or a batch, of customers.

## Customer properties
|    Attribute    |    Type   |                                                                                                                                                                            Description                                                                                                                                                                             |
|-----------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`            | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                                                                                                                                                                                                                      |
| `date_created`  | date-time | The date the customer was created, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                               |
| `date_modified` | date-time | The date the customer was last modified, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                         |
| `email`         | string    | The email address for the customer. `MANDATORY`                                                                                                                                                                                                                                                                                      |
| `first_name`    | string    | Customer first name.                                                                                                                                                                                                                                                                                                                                               |
| `last_name`     | string    | Customer last name.                                                                                                                                                                                                                                                                                                                                                |
| `username`      | string    | Customer login name. Can be generated automatically from the customer's email address if the option `woocommerce_registration_generate_username` is equal to `yes` `CANNOT BE CHANGED` `MAYBE MANDATORY`                                                                                               |
| `password`      | string    | Customer password. Can be generated automatically with [`wp_generate_password()`](http://codex.wordpress.org/Function_Reference/wp_generate_password) if the "Automatically generate customer password" option is enabled, check the index meta for `generate_password` `WRITE-ONLY` `MAYBE MANDATORY` |
| `last_order`    | array     | Last order data. See [Customer Last Order properties](#customer-last-order-properties). `READ-ONLY`                                                                                                                                                                                                                                  |
| `orders_count`  | integer   | Quantity of orders made by the customer. `READ-ONLY`                                                                                                                                                                                                                                                                                 |
| `total_spent`   | string    | Total amount spent. `READ-ONLY`                                                                                                                                                                                                                                                                                                      |
| `avatar_url`    | string    | Avatar URL.                                                                                                                                                                                                                                                                                                                                                        |
| `billing`       | array     | List of billing address data. See [Billing Address properties](#billing-address-properties).                                                                                                                                                                                                                                                                       |
| `shipping`      | array     | List of shipping address data. See [Shipping Address properties](#shipping-address-properties).                                                                                                                                                                                                                                                                    |

### Customer last order properties
| Attribute |    Type   |                                    Description                                     |
|-----------|-----------|------------------------------------------------------------------------------------|
| `id`      | integer   | Last order ID. `READ-ONLY`                           |
| `date`    | date-time | UTC DateTime of the customer last order. `READ-ONLY` |

### Billing address properties
|  Attribute   |  Type  |                     Description                      |
|--------------|--------|------------------------------------------------------|
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1.                                      |
| `address_2`  | string | Address line 2.                                      |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | ISO code of the country.                             |
| `email`      | string | Email address.                                       |
| `phone`      | string | Phone number.                                        |

### Shipping address properties
|  Attribute   |  Type  |                     Description                      |
|--------------|--------|------------------------------------------------------|
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1.                                      |
| `address_2`  | string | Address line 2.                                      |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | ISO code of the country.                             |

## Create a customer
This API helps you to create a new customer.

```http
POST /wp-json/wc/v1/customers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/customers \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "username": "john.doe",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  email: "john.doe@example.com",
  first_name: "John",
  last_name: "Doe",
  username: "john.doe",
  billing: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  }
};

WooCommerce.post("customers", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'email' => 'john.doe@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'username' => 'john.doe',
    'billing' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'company' => '',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US',
        'email' => 'john.doe@example.com',
        'phone' => '(555) 555-5555'
    ],
    'shipping' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'company' => '',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US'
    ]
];

print_r($woocommerce->post('customers', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe",
    "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
    },
    "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
    }
}

print(wcapi.post("customers", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  email: "john.doe@example.com",
  first_name: "John",
  last_name: "Doe",
  username: "john.doe",
  billing: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  }
}

woocommerce.post("customers", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 2,
  "date_created": "2016-05-03T17:58:35",
  "date_modified": "2016-05-11T21:34:43",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "username": "john.doe",
  "last_order": {
    "id": 118,
    "date": "2016-05-03T18:10:43"
  },
  "orders_count": 3,
  "total_spent": "28.00",
  "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/customers/2"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/customers"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a customer
This API lets you retrieve and view a specific customer by ID.

```http
GET /wp-json/wc/v1/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/customers/2 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("customers/2")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers/2')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers/2").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers/2").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 2,
  "date_created": "2016-05-03T17:58:35",
  "date_modified": "2016-05-11T21:34:43",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "username": "john.doe",
  "last_order": {
    "id": 118,
    "date": "2016-05-03T18:10:43"
  },
  "orders_count": 3,
  "total_spent": "28.00",
  "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/customers/2"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/customers"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all customers
This API helps you to view all the customers.

```http
GET /wp-json/wc/v1/customers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/customers \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("customers")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 5,
    "date_created": "2016-05-11T21:39:01",
    "date_modified": "2016-05-11T21:40:02",
    "email": "joao.silva@example.com",
    "first_name": "João",
    "last_name": "Silva",
    "username": "joao.silva",
    "last_order": {
      "id": null,
      "date": null
    },
    "orders_count": 0,
    "total_spent": "0.00",
    "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
    "billing": {
      "first_name": "João",
      "last_name": "Silva",
      "company": "",
      "address_1": "Av. Brasil, 432",
      "address_2": "",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postcode": "12345-000",
      "country": "BR",
      "email": "joao.silva@example.com",
      "phone": "(55) 5555-5555"
    },
    "shipping": {
      "first_name": "João",
      "last_name": "Silva",
      "company": "",
      "address_1": "Av. Brasil, 432",
      "address_2": "",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postcode": "12345-000",
      "country": "BR"
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/customers/5"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/customers"
        }
      ]
    }
  },
  {
    "id": 2,
    "date_created": "2016-05-03T17:58:35",
    "date_modified": "2016-05-11T21:34:43",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe",
    "last_order": {
      "id": 118,
      "date": "2016-05-03T18:10:43"
    },
    "orders_count": 3,
    "total_spent": "28.00",
    "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 555-5555"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/customers/2"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/customers"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter  |   Type  |                                                                                                           Description                                                                                                           |
|------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `context`  | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                                                                                                       |
| `page`     | integer | Current page of the collection.                                                                                                                                                                                                 |
| `per_page` | integer | Maximum number of items to be returned in result set.                                                                                                                                                                           |
| `search`   | string  | Limit results to those matching a string.                                                                                                                                                                                       |
| `exclude`  | string  | Ensure result set excludes specific ids.                                                                                                                                                                                        |
| `include`  | string  | Limit result set to specific ids.                                                                                                                                                                                               |
| `offset`   | integer | Offset the result set by a specific number of items.                                                                                                                                                                            |
| `order`    | string  | Order sort attribute ascending or descending. Default is `asc`, Options: `asc` and `desc`.                                                                                                                                      |
| `orderby`  | string  | Sort collection by object attribute. Default is `name`. Options: `id`, `include`, `name` and `registered_date`.                                                                                                                 |
| `email`    | string  | Limit result set to resources with a specific email.                                                                                                                                                                            |
| `role`     | string  | Limit result set to resources with a specific role. Default: `customer`. Options (some plugins can add more user roles): `all`, `administrator`, `editor`, `author`, `contributor`, `subscriber`, `customer` and `shop_manager` |

## Update a customer
This API lets you make changes to a customer.

```http
PUT /wp-json/wc/v1/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/customers/2 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "first_name": "James",
  "billing": {
    "first_name": "James"
  },
  "shipping": {
    "first_name": "James"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  first_name: "James",
  billing: {
    first_name: "James"
  },
  shipping: {
    first_name: "James"
  }
};

WooCommerce.put("customers/2", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php 
$data = [
    'first_name' => 'James',
    'billing' => [
        'first_name' => 'James'
    ],
    'shipping' => [
        'first_name' => 'James'
    ]
];

print_r($woocommerce->put('customers/2', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "first_name": "James",
    "billing": {
        "first_name": "James"
    },
    "shipping": {
        "first_name": "James"
    }
}

print(wcapi.put("customers/2", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  first_name: "James",
  billing: {
    first_name: "James"
  },
  shipping: {
    first_name: "James"
  }
}

woocommerce.put("customers/2", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 2,
  "date_created": "2016-05-03T17:58:35",
  "date_modified": "2016-05-11T21:43:45",
  "email": "john.doe@example.com",
  "first_name": "James",
  "last_name": "Doe",
  "username": "john.doe",
  "last_order": {
    "id": 118,
    "date": "2016-05-03T18:10:43"
  },
  "orders_count": 3,
  "total_spent": "28.00",
  "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
  "billing": {
    "first_name": "James",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "James",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/customers/2"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/customers"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a customer
This API helps you delete a customer.

```http
DELETE /wp-json/wc/v1/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/customers/2?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("customers/2", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('customers/2', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("customers/2", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("customers/2", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 2,
  "date_created": "2016-05-03T17:58:35",
  "date_modified": "2016-05-11T21:43:45",
  "email": "john.doe@example.com",
  "first_name": "James",
  "last_name": "Doe",
  "username": "john.doe",
  "last_order": {
    "id": 118,
    "date": "2016-05-03T18:10:43"
  },
  "orders_count": 3,
  "total_spent": "28.00",
  "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
  "billing": {
    "first_name": "James",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "James",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/customers/2"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/customers"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update customers
This API helps you to batch create, update and delete multiple customers.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/customers/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/customers/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "email": "john.doe2@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "username": "john.doe2",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      }
    },
    {
      "email": "joao.silva2@example.com",
      "first_name": "João",
      "last_name": "Silva",
      "username": "joao.silva2",
      "billing": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(55) 5555-5555"
      },
      "shipping": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      }
    }
  ],
  "update": [
    {
      "id": 5,
      "billing": {
        "phone": "(11) 1111-1111"
      }
    }
  ],
  "delete": [
    2
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      email: "john.doe2@example.com",
      first_name: "John",
      last_name: "Doe",
      username: "john.doe2",
      billing: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      }
    },
    {
      email: "joao.silva2@example.com",
      first_name: "João",
      last_name: "Silva",
      username: "joao.silva2",
      billing: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR",
        email: "joao.silva@example.com",
        phone: "(55) 5555-5555"
      },
      shipping: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR"
      }
    }
  ],
  update: [
    {
      id: 5,
      billing: {
        phone: "(11) 1111-1111"
      }
    }
  ],
  delete: [
    2
  ]
};

WooCommerce.post("customers/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php 
$data = [
    'create' => [
        [
            'email' => 'john.doe2@example.com',
            'first_name' => 'John',
            'last_name' => 'Doe',
            'username' => 'john.doe2',
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'company' => '',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'company' => '',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ]
        ],
        [
            'email' => 'joao.silva2@example.com',
            'first_name' => 'João',
            'last_name' => 'Silva',
            'username' => 'joao.silva2',
            'billing' => [
                'first_name' => 'João',
                'last_name' => 'Silva',
                'company' => '',
                'address_1' => 'Av. Brasil, 432',
                'address_2' => '',
                'city' => 'Rio de Janeiro',
                'state' => 'RJ',
                'postcode' => '12345-000',
                'country' => 'BR',
                'email' => 'joao.silva@example.com',
                'phone' => '(55) 5555-5555'
            ],
            'shipping' => [
                'first_name' => 'João',
                'last_name' => 'Silva',
                'company' => '',
                'address_1' => 'Av. Brasil, 432',
                'address_2' => '',
                'city' => 'Rio de Janeiro',
                'state' => 'RJ',
                'postcode' => '12345-000',
                'country' => 'BR'
            ]
        ]
    ],
    'update' => [
        [
            'id' => 5,
            'billing' => [
                'phone' => '(11) 1111-1111'
            ]
        ]
    ],
    'delete' => [
        2
    ]
];

print_r($woocommerce->post('customers/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "email": "john.doe2@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "username": "john.doe2",
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "company": "",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "company": "",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            }
        },
        {
            "email": "joao.silva2@example.com",
            "first_name": "João",
            "last_name": "Silva",
            "username": "joao.silva2",
            "billing": {
                "first_name": "João",
                "last_name": "Silva",
                "company": "",
                "address_1": "Av. Brasil, 432",
                "address_2": "",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "postcode": "12345-000",
                "country": "BR",
                "email": "joao.silva@example.com",
                "phone": "(55) 5555-5555"
            },
            "shipping": {
                "first_name": "João",
                "last_name": "Silva",
                "company": "",
                "address_1": "Av. Brasil, 432",
                "address_2": "",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "postcode": "12345-000",
                "country": "BR"
            }
        }
    ],
    "update": [
        {
            "id": 5,
            "billing": {
                "phone": "(11) 1111-1111"
            }
        }
    ],
    "delete": [
        2
    ]
}

print(wcapi.post("customers/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      email: "john.doe2@example.com",
      first_name: "John",
      last_name: "Doe",
      username: "john.doe2",
      billing: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      }
    },
    {
      email: "joao.silva2@example.com",
      first_name: "João",
      last_name: "Silva",
      username: "joao.silva2",
      billing: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR",
        email: "joao.silva@example.com",
        phone: "(55) 5555-5555"
      },
      shipping: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR"
      }
    }
  ],
  update: [
    {
      id: 5,
      billing: {
        phone: "(11) 1111-1111"
      }
    }
  ],
  delete: [
    2
  ]
}

woocommerce.post("customers/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 6,
      "date_created": "2016-05-11T22:06:32",
      "date_modified": "2016-05-11T22:07:31",
      "email": "john.doe2@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "username": "john.doe2",
      "last_order": {
        "id": null,
        "date": null
      },
      "orders_count": 0,
      "total_spent": "0.00",
      "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/customers/6"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/customers"
          }
        ]
      }
    },
    {
      "id": 7,
      "date_created": "2016-05-11T22:07:33",
      "date_modified": "2016-05-11T22:07:37",
      "email": "joao.silva2@example.com",
      "first_name": "João",
      "last_name": "Silva",
      "username": "joao.silva2",
      "last_order": {
        "id": null,
        "date": null
      },
      "orders_count": 0,
      "total_spent": "0.00",
      "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
      "billing": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(55) 5555-5555"
      },
      "shipping": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      },
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/customers/7"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/customers"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 5,
      "date_created": "2016-05-11T21:39:01",
      "date_modified": "2016-05-11T22:04:36",
      "email": "joao.silva@example.com",
      "first_name": "João",
      "last_name": "Silva",
      "username": "joao.silva",
      "last_order": {
        "id": null,
        "date": null
      },
      "orders_count": 0,
      "total_spent": "0.00",
      "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
      "billing": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(11) 1111-1111"
      },
      "shipping": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      },
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/customers/5"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/customers"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 2,
      "date_created": "2016-05-03T17:58:35",
      "date_modified": "2016-05-11T21:43:45",
      "email": "john.doe@example.com",
      "first_name": "James",
      "last_name": "Doe",
      "username": "john.doe",
      "last_order": {
        "id": 118,
        "date": "2016-05-03T18:10:43"
      },
      "orders_count": 3,
      "total_spent": "28.00",
      "avatar_url": "https://secure.gravatar.com/avatar/?s=96",
      "billing": {
        "first_name": "James",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "James",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/customers/2"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/customers"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>

## Retrieve customer downloads
This API lets you retrieve customer downloads permissions.

```http
GET /wp-json/wc/v1/customers/<id>/downloads
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/customers/2/downloads \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("customers/2/downloads")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers/2/downloads')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers/2/downloads").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers/2/downloads").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "download_url": "https://example.com/?download_file=96&order=wc_order_571a7260c0da5&email=john.dow@xanmple.com&key=1789931e0c14ad9909a50c826f10c169",
    "download_id": "1789931e0c14ad9909a50c826f10c169",
    "product_id": 96,
    "download_name": "Woo Album #4 &ndash; Testing",
    "order_id": 105,
    "order_key": "wc_order_571a7260c0da5",
    "downloads_remaining": "unlimited",
    "access_expires": "never",
    "file": {
      "name": "Testing",
      "file": "http://example.com/wp-content/uploads/2013/06/cd_5_angle.jpg"
    },
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/customers/1/downloads"
        }
      ],
      "product": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/96"
        }
      ],
      "order": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/105"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

### Customer downloads properties
|       Attribute       |   Type  |                                                   Description                                                    |
|-----------------------|---------|------------------------------------------------------------------------------------------------------------------|
| `download_url`        | string  | Download file URL. `READ-ONLY`                                                     |
| `download_id`         | string  | Download ID (MD5). `READ-ONLY`                                                     |
| `product_id`          | integer | Downloadable product ID. `READ-ONLY`                                               |
| `download_name`       | string  | Downloadable file name. `READ-ONLY`                                                |
| `order_id`            | integer | Order ID. `READ-ONLY`                                                              |
| `order_key`           | string  | Order key. `READ-ONLY`                                                             |
| `downloads_remaining` | string  | Amount of downloads remaining. `READ-ONLY`                                         |
| `access_expires`      | string  | The date when the download access expires, in the site's timezone. `READ-ONLY`     |
| `file`                | array   | File details with `name` (file name) and `file` (file URL) attributes. `READ-ONLY` |


---

## REST API v1

*Source: apis/rest-api/v1/index.mdx*

import DocCardList from '@theme/DocCardList';

Legacy version of the WooCommerce REST API. Use `/wp-json/wc/v1/` endpoints. Consider migrating to v3 for new integrations.

<DocCardList />


---

## Order notes

*Source: apis/rest-api/v1/order-notes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Order notes
The order notes API allows you to create, view, and delete individual order notes.  
Order notes are added by administrators and programmatically to store data about an order, or order events.

## Order note properties
|    Attribute    |    Type   |                                                     Description                                                     |
|-----------------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `id`            | integer   | Unique identifier for the resource. `READ-ONLY`                                       |
| `date_created`  | date-time | The date the order note was created, in the site's timezone. `READ-ONLY`              |
| `note`          | string    | Order note. `REQUIRED`                                                                |
| `customer_note` | boolean   | Shows/define if the note is only for reference or for the customer (the user will be notified). Default is `false`. |

## Create an order note
This API helps you to create a new note for an order.

```http
POST /wp-json/wc/v1/orders/<id>/notes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/orders/645/notes \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "note": "Order ok!!!"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  note: "Order ok!!!"
};

WooCommerce.post("orders/645/notes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'note' => 'Order ok!!!'
];

print_r($woocommerce->post('orders/645/notes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "note": "Order ok!!!"
}

print(wcapi.post("orders/645/notes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  note: "Order ok!!!"
}

woocommerce.post("orders/645/notes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 51,
  "date_created": "2016-05-13T20:51:55",
  "note": "Order ok!!!",
  "customer_note": false,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118/notes/51"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118/notes"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve an order note
This API lets you retrieve and view a specific note from an order.

```http
GET /wp-json/wc/v1/orders/<id>/notes/<note_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/orders/645/notes/51 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/645/notes/51")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/645/notes/51')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/645/notes/51").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/645/notes/51").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 51,
  "date_created": "2016-05-13T20:51:55",
  "note": "Order ok!!!",
  "customer_note": false,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118/notes/51"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118/notes"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all order notes
This API helps you to view all the notes from an order.

```http
GET /wp-json/wc/v1/orders/<id>/notes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/orders/645/notes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/645/notes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/645/notes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/645/notes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/645/notes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 51,
    "date_created": "2016-05-13T20:51:55",
    "note": "Order ok!!!",
    "customer_note": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/118/notes/51"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/118/notes"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/118"
        }
      ]
    }
  },
  {
    "id": 46,
    "date_created": "2016-05-03T18:10:43",
    "note": "Order status changed from Pending Payment to Processing.",
    "customer_note": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/118/notes/46"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/118/notes"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/118"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Delete an order note
This API helps you delete an order note.

```http
DELETE /wp-json/wc/v1/orders/<id>/notes/<note_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/orders/645/notes/51?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("orders/645/notes/51", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/645/notes/51', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/645/notes/51", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/645/notes/51", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 51,
  "date_created": "2016-05-13T20:51:55",
  "note": "Order ok!!!",
  "customer_note": false,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118/notes/51"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118/notes"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/118"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>
#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## Refunds

*Source: apis/rest-api/v1/order-refunds.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Refunds
The refunds API allows you to create, view, and delete individual refunds.

## Refund properties
|   Attribute    |    Type   |                                               Description                                                |
|----------------|-----------|----------------------------------------------------------------------------------------------------------|
| `id`           | integer   | Unique identifier for the resource. `READ-ONLY`                            |
| `date_created` | date-time | The date the order refund was created, in the site's timezone. `READ-ONLY` |
| `amount`       | string    | Refund amount. `REQUIRED`                                                  |
| `reason`       | string    | Reason for refund.                                                                                       |
| `line_items`   | array     | Line items data. See [Refunds Line Items properties](#refund-line-item-properties).                    |

### Refund line item properties
|   Attribute    |   Type  |                                          Description                                           |
|----------------|---------|------------------------------------------------------------------------------------------------|
| `id`           | integer | Item ID. `READ-ONLY`                                             |
| `name`         | string  | Product name. `READ-ONLY`                                        |
| `sku`          | string  | Product SKU. `READ-ONLY`                                         |
| `product_id`   | integer | Product ID.                                                                                    |
| `variation_id` | integer | Variation ID, if applicable.                                                                   |
| `quantity`     | integer | Quantity ordered.                                                                              |
| `tax_class`    | string  | Tax class of product. `READ-ONLY`                                |
| `price`        | string  | Product price. `READ-ONLY`                                       |
| `subtotal`     | string  | Line subtotal (before discounts).                                                              |
| `subtotal_tax` | string  | Line subtotal tax (before discounts).                                                          |
| `total`        | string  | Line total (after discounts).                                                                  |
| `total_tax`    | string  | Line total tax (after discounts).                                                              |
| `taxes`        | array   | Line total tax with `id`, `total` and `subtotal`. `READ-ONLY`    |
| `meta`         | array   | Line item meta data with `key`, `label` and `value`. `READ-ONLY` |

## Create a refund
This API helps you to create a new refund for an order.

```http
POST /wp-json/wc/v1/orders/<id>/refunds
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/orders/116/refunds \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "amount": "10"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  amount: "10"
};

WooCommerce.post("orders/116/refunds", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'amount' => '10'
];

print_r($woocommerce->post('orders/116/refunds', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "amount": "10"
}

print(wcapi.post("orders/116/refunds", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  amount: "10"
}

woocommerce.post("orders/116/refunds", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 150,
  "date_created": "2016-05-30T17:28:05",
  "amount": "10.00",
  "reason": "",
  "line_items": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116/refunds/150"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116/refunds"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a refund
This API lets you retrieve and view a specific refund from an order.

```http
GET /wp-json/wc/v1/orders/<id>/refunds/<refund_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/orders/116/refunds/150 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/116/refunds/150")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/116/refunds/150')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/116/refunds/150").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/116/refunds/150").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 150,
  "date_created": "2016-05-30T17:28:05",
  "amount": "10.00",
  "reason": "",
  "line_items": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116/refunds/150"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116/refunds"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                    Description                    |
|-----------|--------|---------------------------------------------------|
| `dp`      | string | Number of decimal points to use in each resource. |

## List all refunds
This API helps you to view all the refunds from an order.

```http
GET /wp-json/wc/v1/orders/<id>/refunds
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/orders/116/refunds \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/116/refunds")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/116/refunds')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/116/refunds").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/116/refunds").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 151,
    "date_created": "2016-05-30T17:31:48",
    "amount": "2.00",
    "reason": "",
    "line_items": [
      {
        "id": 11,
        "name": "Woo Single #2",
        "sku": "12345",
        "product_id": 99,
        "variation_id": 0,
        "quantity": -1,
        "tax_class": "",
        "price": "-2.00",
        "subtotal": "-2.00",
        "subtotal_tax": "0.00",
        "total": "-2.00",
        "total_tax": "0.00",
        "taxes": [],
        "meta": []
      }
    ],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/116/refunds/151"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/116/refunds"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/116"
        }
      ]
    }
  },
  {
    "id": 150,
    "date_created": "2016-05-30T17:28:05",
    "amount": "10.00",
    "reason": "",
    "line_items": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/116/refunds/150"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/116/refunds"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/116"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter       |   Type  |                                                  Description                                                  |
|-----------------|---------|---------------------------------------------------------------------------------------------------------------|
| `context`       | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.     |
| `page`          | integer | Current page of the collection.                                                                               |
| `per_page`      | integer | Maximum number of items to be returned in result set.                                                         |
| `search`        | string  | Limit results to those matching a string.                                                                     |
| `after`         | string  | Limit response to resources published after a given ISO8601 compliant date.                                   |
| `before`        | string  | Limit response to resources published before a given ISO8601 compliant date.                                  |
| `dates_are_gmt` | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                      |
| `exclude`       | string  | Ensure result set excludes specific ids.                                                                      |
| `include`       | string  | Limit result set to specific ids.                                                                             |
| `offset`        | integer | Offset the result set by a specific number of items.                                                          |
| `order`         | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                    |
| `orderby`       | string  | Sort collection by object attribute. Default is `date`, Options: `date`, `id`, `include`, `title` and `slug`. |
| `dp`            | string  | Number of decimal points to use in each resource.                                                             |

## Delete a refund
This API helps you delete an order refund.

```http
DELETE /wp-json/wc/v1/orders/<id>/refunds/<refund_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/orders/116/refunds/150?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("orders/116/refunds/150", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/116/refunds/150', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/116/refunds/150", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/116/refunds/150", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 150,
  "date_created": "2016-05-30T17:28:05",
  "amount": "10.00",
  "reason": "",
  "line_items": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116/refunds/150"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116/refunds"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/116"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## Orders

*Source: apis/rest-api/v1/orders.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Orders
The orders API allows you to create, view, update, and delete individual, or a batch, of orders.

## Order properties
|       Attribute        |    Type   |                                                                             Description                                                                              |
|------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                   | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                        |
| `parent_id`            | integer   | Parent order ID.                                                                                                                                                     |
| `status`               | string    | Order status. Default is `pending`. Options (plugins may include new status): `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded` and `failed`. |
| `order_key`            | string    | Order key. `READ-ONLY`                                                                                                                 |
| `number`               | string    | Order number. `READ-ONLY`                                                                                                              |
| `currency`             | string    | Currency the order was created with, in ISO format, e.g `USD`. Default is the current store currency.                                                                |
| `version`              | string    | Version of WooCommerce when the order was made. `READ-ONLY`                                                                            |
| `prices_include_tax`   | boolean   | Shows if the prices included tax during checkout. `READ-ONLY`                                                                          |
| `date_created`         | date-time | The date the order was created, in the site's timezone. `READ-ONLY`                                                                    |
| `date_modified`        | date-time | The date the order was last modified, in the site's timezone. `READ-ONLY`                                                              |
| `customer_id`          | integer   | User ID who owns the order. Use `0` for guests. Default is `0`.                                                                                                      |
| `discount_total`       | string    | Total discount amount for the order. `READ-ONLY`                                                                                       |
| `discount_tax`         | string    | Total discount tax amount for the order. `READ-ONLY`                                                                                   |
| `shipping_total`       | string    | Total shipping amount for the order. `READ-ONLY`                                                                                       |
| `shipping_tax`         | string    | Total shipping tax amount for the order. `READ-ONLY`                                                                                   |
| `cart_tax`             | string    | Sum of line item taxes only. `READ-ONLY`                                                                                               |
| `total`                | string    | Grand total. `READ-ONLY`                                                                                                               |
| `total_tax`            | string    | Sum of all taxes. `READ-ONLY`                                                                                                          |
| `billing`              | object    | Billing address. See [Customer Billing Address properties](#billing-address-properties).                                                                             |
| `shipping`             | object    | Shipping address. See [Customer Shipping Address properties](#shipping-address-properties).                                                                          |
| `payment_method`       | string    | Payment method ID.                                                                                                                                                   |
| `payment_method_title` | string    | Payment method title.                                                                                                                                                |
| `set_paid`             | boolean   | Define if the order is paid. It will set the status to processing and reduce stock items. Default is `false`. `WRITE-ONLY`             |
| `transaction_id`       | string    | Unique transaction ID. In write-mode only is available if `set_paid` is `true`.                                                                                      |
| `customer_ip_address`  | string    | Customer's IP address. `READ-ONLY`                                                                                                     |
| `customer_user_agent`  | string    | User agent of the customer. `READ-ONLY`                                                                                                |
| `created_via`          | string    | Shows where the order was created. `READ-ONLY`                                                                                         |
| `customer_note`        | string    | Note left by customer during checkout.                                                                                                                               |
| `date_completed`       | date-time | The date the order was completed, in the site's timezone. `READ-ONLY`                                                                  |
| `date_paid`            | date-time | The date the order has been paid, in the site's timezone. `READ-ONLY`                                                                  |
| `cart_hash`            | string    | MD5 hash of cart items to ensure orders are not modified. `READ-ONLY`                                                                  |
| `line_items`           | array     | Line items data. See [Line Items properties](#line-item-properties).                                                                                                 |
| `tax_lines`            | array     | Tax lines data. See [Tax Lines properties](#tax-line-properties). `READ-ONLY`                                                          |
| `shipping_lines`       | array     | Shipping lines data. See [Shipping Lines properties](#shipping-line-properties).                                                                                     |
| `fee_lines`            | array     | Fee lines data. See [Fee Lines Properties](#fee-line-properties).                                                                                                    |
| `coupon_lines`         | array     | Coupons line data. See [Coupon Lines properties](#coupon-line-properties).                                                                                           |
| `refunds`              | array     | List of refunds. See [Refund line properties](#refund-line-properties). `READ-ONLY`                                                 |

### Billing address properties
| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1.                                      |
| `address_2`  | string | Address line 2.                                      |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | ISO code of the country.                             |
| `email`      | string | Email address.                                       |
| `phone`      | string | Phone number.                                        |

### Shipping address properties
| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1.                                      |
| `address_2`  | string | Address line 2.                                      |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | ISO code of the country.                             |

### Line item properties
|   Attribute    |   Type  |                                          Description                                           |
|----------------|---------|------------------------------------------------------------------------------------------------|
| `id`           | integer | Item ID. `READ-ONLY`                                             |
| `name`         | string  | Product name. `READ-ONLY`                                        |
| `sku`          | string  | Product SKU. `READ-ONLY`                                         |
| `product_id`   | integer | Product ID.                                                                                    |
| `variation_id` | integer | Variation ID, if applicable.                                                                   |
| `quantity`     | integer | Quantity ordered.                                                                              |
| `tax_class`    | string  | Tax class of product. `READ-ONLY`                                |
| `price`        | string  | Product price. `READ-ONLY`                                       |
| `subtotal`     | string  | Line subtotal (before discounts).                                                              |
| `subtotal_tax` | string  | Line subtotal tax (before discounts).                                                          |
| `total`        | string  | Line total (after discounts).                                                                  |
| `total_tax`    | string  | Line total tax (after discounts).                                                              |
| `taxes`        | array   | Line taxes with `id`, `total` and `subtotal`. `READ-ONLY`    |
| `meta`         | array   | Line item meta data with `key`, `label` and `value`. `READ-ONLY` |

### Tax line properties
|      Attribute       |   Type  |                                                             Description                                                             |
|----------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------|
| `id`                 | integer | Item ID. `READ-ONLY`                                                                                  |
| `rate_code`          | string  | Tax rate code. `READ-ONLY`                                                                            |
| `rate_id`            | string  | Tax rate ID. `READ-ONLY`                                                                              |
| `label`              | string  | Tax rate label. `READ-ONLY`                                                                           |
| `compound`           | boolean | Show if is a compound tax rate. Compound tax rates are applied on top of other tax rates. `READ-ONLY` |
| `tax_total`          | string  | Tax total (not including shipping taxes). `READ-ONLY`                                                 |
| `shipping_tax_total` | string  | Shipping tax total. `READ-ONLY`                                                                       |

### Shipping line properties
|   Attribute    |   Type  |                                 Description                                 |
|----------------|---------|-----------------------------------------------------------------------------|
| `id`           | integer | Item ID. `READ-ONLY`                          |
| `method_title` | string  | Shipping method name.                                                       |
| `method_id`    | string  | Shipping method ID. `REQUIRED`                |
| `total`        | string  | Line total (after discounts).                                               |
| `total_tax`    | string  | Line total tax (after discounts). `READ-ONLY` |
| `taxes`        | array   | Line taxes with `id` and `total`. `READ-ONLY` |

### Fee line properties
|  Attribute   |   Type  |                                       Description                                       |
|--------------|---------|-----------------------------------------------------------------------------------------|
| `id`         | integer | Item ID. `READ-ONLY`                                      |
| `name`       | string  | Fee name. `REQUIRED`                                      |
| `tax_class`  | string  | Tax class. `REQUIRED IF THE FEE IS TAXABLE`               |
| `tax_status` | string  | Tax status of fee. Set to `taxable` if need apply taxes.                                |
| `total`      | string  | Line total (after discounts).                                                           |
| `total_tax`  | string  | Line total tax (after discounts).                                                       |
| `taxes`      | array   | Line taxes with `id`, `total` and `subtotal`. `READ-ONLY` |

### Coupon line properties
|   Attribute    |   Type  |                          Description                          |
|----------------|---------|---------------------------------------------------------------|
| `id`           | integer | Item ID. `READ-ONLY`            |
| `code`         | string  | Coupon code. `REQUIRED`         |
| `discount`     | string  | Discount total. `REQUIRED`      |
| `discount_tax` | string  | Discount total tax. `READ-ONLY` |

### Refund line properties
| Attribute |   Type  |                       Description                        |
|-----------|---------|----------------------------------------------------------|
| `id`      | integer | Refund ID. `READ-ONLY`     |
| `reason`  | string  | Refund reason. `READ-ONLY` |
| `total`   | string  | Refund total. `READ-ONLY`  |

## Create an order
This API helps you to create a new order.

```http
POST /wp-json/wc/v1/orders
```

> Example of create a paid order:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/orders \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "line_items": [
    {
      "product_id": 93,
      "quantity": 2
    },
    {
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1
    }
  ],
  "shipping_lines": [
    {
      "method_id": "flat_rate",
      "method_title": "Flat Rate",
      "total": "10.00"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  payment_method: "bacs",
  payment_method_title: "Direct Bank Transfer",
  set_paid: true,
  billing: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  },
  line_items: [
    {
      product_id: 93,
      quantity: 2
    },
    {
      product_id: 22,
      variation_id: 23,
      quantity: 1
    }
  ],
  shipping_lines: [
    {
      method_id: "flat_rate",
      method_title: "Flat Rate",
      total: "10.00"
    }
  ]
};

WooCommerce.post("orders", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'payment_method' => 'bacs',
    'payment_method_title' => 'Direct Bank Transfer',
    'set_paid' => true,
    'billing' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US',
        'email' => 'john.doe@example.com',
        'phone' => '(555) 555-5555'
    ],
    'shipping' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US'
    ],
    'line_items' => [
        [
            'product_id' => 93,
            'quantity' => 2
        ],
        [
            'product_id' => 22,
            'variation_id' => 23,
            'quantity' => 1
        ]
    ],
    'shipping_lines' => [
        [
            'method_id' => 'flat_rate',
            'method_title' => 'Flat Rate',
            'total' => '10.00'
        ]
    ]
];

print_r($woocommerce->post('orders', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "payment_method": "bacs",
    "payment_method_title": "Direct Bank Transfer",
    "set_paid": True,
    "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
    },
    "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
    },
    "line_items": [
        {
            "product_id": 93,
            "quantity": 2
        },
        {
            "product_id": 22,
            "variation_id": 23,
            "quantity": 1
        }
    ],
    "shipping_lines": [
        {
            "method_id": "flat_rate",
            "method_title": "Flat Rate",
            "total": "10.00"
        }
    ]
}

print(wcapi.post("orders", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  payment_method: "bacs",
  payment_method_title: "Direct Bank Transfer",
  set_paid: true,
  billing: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  },
  line_items: [
    {
      product_id: 93,
      quantity: 2
    },
    {
      product_id: 22,
      variation_id: 23,
      quantity: 1
    }
  ],
  shipping_lines: [
    {
      method_id: "flat_rate",
      method_title: "Flat Rate",
      total: "10.00"
    }
  ]
}

woocommerce.post("orders", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 154,
  "parent_id": 0,
  "status": "processing",
  "order_key": "wc_order_574cc02467274",
  "number": "154",
  "currency": "USD",
  "version": "2.6.0",
  "prices_include_tax": false,
  "date_created": "2016-05-30T22:35:16",
  "date_modified": "2016-05-30T22:35:16",
  "customer_id": 0,
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "10.00",
  "shipping_tax": "0.00",
  "cart_tax": "1.95",
  "total": "37.95",
  "total_tax": "1.95",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "bacs",
  "payment_method_title": "bacs",
  "transaction_id": "",
  "customer_ip_address": "127.0.0.1",
  "customer_user_agent": "curl/7.47.0",
  "created_via": "rest-api",
  "customer_note": "",
  "date_completed": "2016-05-30T19:35:16",
  "date_paid": "2016-05-30 19:35:25",
  "cart_hash": "",
  "line_items": [
    {
      "id": 18,
      "name": "Woo Single #1",
      "sku": "",
      "product_id": 93,
      "variation_id": 0,
      "quantity": 2,
      "tax_class": "",
      "price": "3.00",
      "subtotal": "6.00",
      "subtotal_tax": "0.45",
      "total": "6.00",
      "total_tax": "0.45",
      "taxes": [
        {
          "id": 75,
          "total": 0.45,
          "subtotal": 0.45
        }
      ],
      "meta": []
    },
    {
      "id": 19,
      "name": "Ship Your Idea",
      "sku": "",
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1,
      "tax_class": "",
      "price": "20.00",
      "subtotal": "20.00",
      "subtotal_tax": "1.50",
      "total": "20.00",
      "total_tax": "1.50",
      "taxes": [
        {
          "id": 75,
          "total": 1.5,
          "subtotal": 1.5
        }
      ],
      "meta": [
        {
          "key": "pa_color",
          "label": "Color",
          "value": "Black"
        }
      ]
    }
  ],
  "tax_lines": [
    {
      "id": 21,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": "75",
      "label": "State Tax",
      "compound": false,
      "tax_total": "1.95",
      "shipping_tax_total": "0.00"
    }
  ],
  "shipping_lines": [
    {
      "id": 20,
      "method_title": "Flat Rate",
      "method_id": "flat_rate",
      "total": "10.00",
      "total_tax": "0.00",
      "taxes": []
    }
  ],
  "fee_lines": [],
  "coupon_lines": [],
  "refunds": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/154"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve an order
This API lets you retrieve and view a specific order.

```http
GET /wp-json/wc/v1/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/orders/154 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/154")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/154')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/154").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/154").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 154,
  "parent_id": 0,
  "status": "processing",
  "order_key": "wc_order_574cc02467274",
  "number": "154",
  "currency": "USD",
  "version": "2.6.0",
  "prices_include_tax": false,
  "date_created": "2016-05-30T22:35:16",
  "date_modified": "2016-05-30T22:35:16",
  "customer_id": 0,
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "10.00",
  "shipping_tax": "0.00",
  "cart_tax": "1.95",
  "total": "37.95",
  "total_tax": "1.95",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "bacs",
  "payment_method_title": "bacs",
  "transaction_id": "",
  "customer_ip_address": "127.0.0.1",
  "customer_user_agent": "curl/7.47.0",
  "created_via": "rest-api",
  "customer_note": "",
  "date_completed": "2016-05-30T19:35:16",
  "date_paid": "2016-05-30 19:35:25",
  "cart_hash": "",
  "line_items": [
    {
      "id": 18,
      "name": "Woo Single #1",
      "sku": "",
      "product_id": 93,
      "variation_id": 0,
      "quantity": 2,
      "tax_class": "",
      "price": "3.00",
      "subtotal": "6.00",
      "subtotal_tax": "0.45",
      "total": "6.00",
      "total_tax": "0.45",
      "taxes": [
        {
          "id": 75,
          "total": 0.45,
          "subtotal": 0.45
        }
      ],
      "meta": []
    },
    {
      "id": 19,
      "name": "Ship Your Idea",
      "sku": "",
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1,
      "tax_class": "",
      "price": "20.00",
      "subtotal": "20.00",
      "subtotal_tax": "1.50",
      "total": "20.00",
      "total_tax": "1.50",
      "taxes": [
        {
          "id": 75,
          "total": 1.5,
          "subtotal": 1.5
        }
      ],
      "meta": [
        {
          "key": "pa_color",
          "label": "Color",
          "value": "Black"
        }
      ]
    }
  ],
  "tax_lines": [
    {
      "id": 21,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": "75",
      "label": "State Tax",
      "compound": false,
      "tax_total": "1.95",
      "shipping_tax_total": "0.00"
    }
  ],
  "shipping_lines": [
    {
      "id": 20,
      "method_title": "Flat Rate",
      "method_id": "flat_rate",
      "total": "10.00",
      "total_tax": "0.00",
      "taxes": []
    }
  ],
  "fee_lines": [],
  "coupon_lines": [],
  "refunds": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/154"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                    Description                    |
|-----------|--------|---------------------------------------------------|
| `dp`      | string | Number of decimal points to use in each resource. |

## List all orders
This API helps you to view all the orders.

```http
GET /wp-json/wc/v1/orders
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/orders \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 154,
    "parent_id": 0,
    "status": "processing",
    "order_key": "wc_order_574cc02467274",
    "number": "154",
    "currency": "USD",
    "version": "2.6.0",
    "prices_include_tax": false,
    "date_created": "2016-05-30T22:35:16",
    "date_modified": "2016-05-30T22:35:16",
    "customer_id": 0,
    "discount_total": "0.00",
    "discount_tax": "0.00",
    "shipping_total": "10.00",
    "shipping_tax": "0.00",
    "cart_tax": "1.95",
    "total": "37.95",
    "total_tax": "1.95",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 555-5555"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    },
    "payment_method": "bacs",
    "payment_method_title": "bacs",
    "transaction_id": "",
    "customer_ip_address": "127.0.0.1",
    "customer_user_agent": "curl/7.47.0",
    "created_via": "rest-api",
    "customer_note": "",
    "date_completed": "2016-05-30T19:35:16",
    "date_paid": "2016-05-30 19:35:25",
    "cart_hash": "",
    "line_items": [
      {
        "id": 18,
        "name": "Woo Single #1",
        "sku": "",
        "product_id": 93,
        "variation_id": 0,
        "quantity": 2,
        "tax_class": "",
        "price": "3.00",
        "subtotal": "6.00",
        "subtotal_tax": "0.45",
        "total": "6.00",
        "total_tax": "0.45",
        "taxes": [
          {
            "id": 75,
            "total": 0.45,
            "subtotal": 0.45
          }
        ],
        "meta": []
      },
      {
        "id": 19,
        "name": "Ship Your Idea",
        "sku": "",
        "product_id": 22,
        "variation_id": 23,
        "quantity": 1,
        "tax_class": "",
        "price": "20.00",
        "subtotal": "20.00",
        "subtotal_tax": "1.50",
        "total": "20.00",
        "total_tax": "1.50",
        "taxes": [
          {
            "id": 75,
            "total": 1.5,
            "subtotal": 1.5
          }
        ],
        "meta": [
          {
            "key": "pa_color",
            "label": "Color",
            "value": "Black"
          }
        ]
      }
    ],
    "tax_lines": [
      {
        "id": 21,
        "rate_code": "US-CA-STATE TAX",
        "rate_id": "75",
        "label": "State Tax",
        "compound": false,
        "tax_total": "1.95",
        "shipping_tax_total": "0.00"
      }
    ],
    "shipping_lines": [
      {
        "id": 20,
        "method_title": "Flat Rate",
        "method_id": "flat_rate",
        "total": "10.00",
        "total_tax": "0.00",
        "taxes": []
      }
    ],
    "fee_lines": [],
    "coupon_lines": [],
    "refunds": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/154"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders"
        }
      ]
    }
  },
  {
    "id": 116,
    "parent_id": 0,
    "status": "processing",
    "order_key": "wc_order_5728e6e53d2a4",
    "number": "116",
    "currency": "USD",
    "version": "2.6.0",
    "prices_include_tax": false,
    "date_created": "2016-05-03T17:59:00",
    "date_modified": "2016-05-30T22:37:31",
    "customer_id": 1,
    "discount_total": "0.00",
    "discount_tax": "0.00",
    "shipping_total": "10.00",
    "shipping_tax": "0.00",
    "cart_tax": "0.00",
    "total": "14.00",
    "total_tax": "0.00",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@claudiosmweb.com",
      "phone": "(555) 555-5555"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    },
    "payment_method": "bacs",
    "payment_method_title": "Direct Bank Transfer",
    "transaction_id": "",
    "customer_ip_address": "127.0.0.1",
    "customer_user_agent": "curl/7.47.0",
    "created_via": "",
    "customer_note": "",
    "date_completed": "2016-05-30T19:35:16",
    "date_paid": "2016-05-03 14:59:12",
    "cart_hash": "",
    "line_items": [
      {
        "id": 6,
        "name": "Woo Single #2",
        "sku": "12345",
        "product_id": 99,
        "variation_id": 0,
        "quantity": 2,
        "tax_class": "",
        "price": "2.00",
        "subtotal": "4.00",
        "subtotal_tax": "0.00",
        "total": "4.00",
        "total_tax": "0.00",
        "taxes": [],
        "meta": []
      }
    ],
    "tax_lines": [],
    "shipping_lines": [
      {
        "id": 7,
        "method_title": "Flat Rate",
        "method_id": "flat_rate",
        "total": "10.00",
        "total_tax": "0.00",
        "taxes": []
      }
    ],
    "fee_lines": [],
    "coupon_lines": [],
    "refunds": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders/116"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/orders"
        }
      ],
      "customer": [
        {
          "href": "https://example.com/wp-json/wc/v1/customers/1"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter       |   Type  |                                                                                                 Description                                                                                                  |
|-----------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `context`       | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                                                                                    |
| `page`          | integer | Current page of the collection.                                                                                                                                                                              |
| `per_page`      | integer | Maximum number of items to be returned in result set.                                                                                                                                                        |
| `search`        | string  | Limit results to those matching a string.                                                                                                                                                                    |
| `after`         | string  | Limit response to resources published after a given ISO8601 compliant date.                                                                                                                                  |
| `before`        | string  | Limit response to resources published before a given ISO8601 compliant date.                                                                                                                                 |
| `dates_are_gmt` | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                                                                                                     |
| `exclude`       | string  | Ensure result set excludes specific ids.                                                                                                                                                                     |
| `include`       | string  | Limit result set to specific ids.                                                                                                                                                                            |
| `offset`        | integer | Offset the result set by a specific number of items.                                                                                                                                                         |
| `order`         | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                                                                                                   |
| `orderby`       | string  | Sort collection by object attribute. Default is `date`, Options: `date`, `id`, `include`, `title` and `slug`.                                                                                                |
| `status`        | string  | Limit result set to orders assigned a specific status. Default is `any`. Options (plugins may add new status): `any`, `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded` and `failed`. |
| `customer`      | string  | Limit result set to orders assigned a specific customer.                                                                                                                                                     |
| `product`       | string  | Limit result set to orders assigned a specific product.                                                                                                                                                      |
| `dp`            | string  | Number of decimal points to use in each resource.                                                                                                                                                            |

## Update an Order
This API lets you make changes to an order.

### HTTP Request
```http
PUT /wp-json/wc/v1/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/orders/154 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "status": "completed"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  status: "completed"
};

WooCommerce.put("orders/154", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'status' => 'completed'
];

print_r($woocommerce->put('orders/154', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "status": "completed"
}

print(wcapi.put("orders/154", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  status: "completed"
}

woocommerce.put("orders/154", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 154,
  "parent_id": 0,
  "status": "completed",
  "order_key": "wc_order_574cc02467274",
  "number": "154",
  "currency": "USD",
  "version": "2.6.0",
  "prices_include_tax": false,
  "date_created": "2016-05-30T22:35:16",
  "date_modified": "2016-05-30T22:46:16",
  "customer_id": 0,
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "10.00",
  "shipping_tax": "0.00",
  "cart_tax": "1.95",
  "total": "37.95",
  "total_tax": "1.95",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "bacs",
  "payment_method_title": "bacs",
  "transaction_id": "",
  "customer_ip_address": "127.0.0.1",
  "customer_user_agent": "curl/7.47.0",
  "created_via": "rest-api",
  "customer_note": "",
  "date_completed": "2016-05-30T19:47:46",
  "date_paid": "2016-05-30 19:35:25",
  "cart_hash": "",
  "line_items": [
    {
      "id": 18,
      "name": "Woo Single #1",
      "sku": "",
      "product_id": 93,
      "variation_id": 0,
      "quantity": 2,
      "tax_class": "",
      "price": "3.00",
      "subtotal": "6.00",
      "subtotal_tax": "0.45",
      "total": "6.00",
      "total_tax": "0.45",
      "taxes": [
        {
          "id": 75,
          "total": 0.45,
          "subtotal": 0.45
        }
      ],
      "meta": []
    },
    {
      "id": 19,
      "name": "Ship Your Idea",
      "sku": "",
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1,
      "tax_class": "",
      "price": "20.00",
      "subtotal": "20.00",
      "subtotal_tax": "1.50",
      "total": "20.00",
      "total_tax": "1.50",
      "taxes": [
        {
          "id": 75,
          "total": 1.5,
          "subtotal": 1.5
        }
      ],
      "meta": [
        {
          "key": "pa_color",
          "label": "Color",
          "value": "Black"
        }
      ]
    }
  ],
  "tax_lines": [
    {
      "id": 21,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": "75",
      "label": "State Tax",
      "compound": false,
      "tax_total": "1.95",
      "shipping_tax_total": "0.00"
    }
  ],
  "shipping_lines": [
    {
      "id": 20,
      "method_title": "Flat Rate",
      "method_id": "flat_rate",
      "total": "10.00",
      "total_tax": "0.00",
      "taxes": []
    }
  ],
  "fee_lines": [],
  "coupon_lines": [],
  "refunds": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/154"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete an order
This API helps you delete an order.

```http
DELETE /wp-json/wc/v1/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/orders/154?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("orders/154", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/154', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/154", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/154", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 154,
  "parent_id": 0,
  "status": "completed",
  "order_key": "wc_order_574cc02467274",
  "number": "154",
  "currency": "USD",
  "version": "2.6.0",
  "prices_include_tax": false,
  "date_created": "2016-05-30T22:35:16",
  "date_modified": "2016-05-30T22:46:16",
  "customer_id": 0,
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "10.00",
  "shipping_tax": "0.00",
  "cart_tax": "1.95",
  "total": "37.95",
  "total_tax": "1.95",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "bacs",
  "payment_method_title": "bacs",
  "transaction_id": "",
  "customer_ip_address": "127.0.0.1",
  "customer_user_agent": "curl/7.47.0",
  "created_via": "rest-api",
  "customer_note": "",
  "date_completed": "2016-05-30T19:47:46",
  "date_paid": "2016-05-30 19:35:25",
  "cart_hash": "",
  "line_items": [
    {
      "id": 18,
      "name": "Woo Single #1",
      "sku": "",
      "product_id": 93,
      "variation_id": 0,
      "quantity": 2,
      "tax_class": "",
      "price": "3.00",
      "subtotal": "6.00",
      "subtotal_tax": "0.45",
      "total": "6.00",
      "total_tax": "0.45",
      "taxes": [
        {
          "id": 75,
          "total": 0.45,
          "subtotal": 0.45
        }
      ],
      "meta": []
    },
    {
      "id": 19,
      "name": "Ship Your Idea",
      "sku": "",
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1,
      "tax_class": "",
      "price": "20.00",
      "subtotal": "20.00",
      "subtotal_tax": "1.50",
      "total": "20.00",
      "total_tax": "1.50",
      "taxes": [
        {
          "id": 75,
          "total": 1.5,
          "subtotal": 1.5
        }
      ],
      "meta": [
        {
          "key": "pa_color",
          "label": "Color",
          "value": "Black"
        }
      ]
    }
  ],
  "tax_lines": [
    {
      "id": 21,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": "75",
      "label": "State Tax",
      "compound": false,
      "tax_total": "1.95",
      "shipping_tax_total": "0.00"
    }
  ],
  "shipping_lines": [
    {
      "id": 20,
      "method_title": "Flat Rate",
      "method_id": "flat_rate",
      "total": "10.00",
      "total_tax": "0.00",
      "taxes": []
    }
  ],
  "fee_lines": [],
  "coupon_lines": [],
  "refunds": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders/154"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/orders"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                               Description                               |
|-----------|--------|-------------------------------------------------------------------------|
| `force`   | boolean | Use `true` to permanently delete the order. Default is `false`. |

## Batch update orders
This API helps you to batch create, update and delete multiple orders.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/orders/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/orders/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "line_items": [
        {
          "product_id": 79,
          "quantity": 1
        },
        {
          "product_id": 93,
          "quantity": 1
        },
        {
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1
        }
      ],
      "shipping_lines": [
        {
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "30.00"
        }
      ]
    },
    {
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "set_paid": true,
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "line_items": [
        {
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1
        },
        {
          "product_id": 22,
          "variation_id": 24,
          "quantity": 1
        }
      ],
      "shipping_lines": [
        {
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "20.00"
        }
      ]
    }
  ],
  "update": [
    {
      "id": 154,
      "shipping_methods": "Local Delivery"
    }
  ],
  "delete": [
    154
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 79,
          quantity: 1
        },
        {
          product_id: 93,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "30.00"
        }
      ]
    },
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      set_paid: true,
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 24,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "20.00"
        }
      ]
    }
  ],
  update: [
    {
      id: 154,
      shipping_methods: "Local Delivery"
    }
  ],
  delete: [
    154
  ]
};

WooCommerce.post("orders/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'payment_method' => 'bacs',
            'payment_method_title' => 'Direct Bank Transfer',
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ],
            'line_items' => [
                [
                    'product_id' => 79,
                    'quantity' => 1
                ],
                [
                    'product_id' => 93,
                    'quantity' => 1
                ],
                [
                    'product_id' => 22,
                    'variation_id' => 23,
                    'quantity' => 1
                ]
            ],
            'shipping_lines' => [
                [
                    'method_id' => 'flat_rate',
                    'method_title' => 'Flat Rate',
                    'total' => '30.00'
                ]
            ]
        ],
        [
            'payment_method' => 'bacs',
            'payment_method_title' => 'Direct Bank Transfer',
            'set_paid' => true,
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ],
            'line_items' => [
                [
                    'product_id' => 22,
                    'variation_id' => 23,
                    'quantity' => 1
                ],
                [
                    'product_id' => 22,
                    'variation_id' => 24,
                    'quantity' => 1
                ]
            ],
            'shipping_lines' => [
                [
                    'method_id' => 'flat_rate',
                    'method_title' => 'Flat Rate',
                    'total' => '20.00'
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 154,
            'shipping_methods' => 'Local Delivery'
        ]
    ],
    'delete' => [
        154
    ]
];

print_r($woocommerce->post('orders/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "payment_method": "bacs",
            "payment_method_title": "Direct Bank Transfer",
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            },
            "line_items": [
                {
                    "product_id": 79,
                    "quantity": 1
                },
                {
                    "product_id": 93,
                    "quantity": 1
                },
                {
                    "product_id": 22,
                    "variation_id": 23,
                    "quantity": 1
                }
            ],
            "shipping_lines": [
                {
                    "method_id": "flat_rate",
                    "method_title": "Flat Rate",
                    "total": "30.00"
                }
            ]
        },
        {
            "payment_method": "bacs",
            "payment_method_title": "Direct Bank Transfer",
            "set_paid": True,
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            },
            "line_items": [
                {
                    "product_id": 22,
                    "variation_id": 23,
                    "quantity": 1
                },
                {
                    "product_id": 22,
                    "variation_id": 24,
                    "quantity": 1
                }
            ],
            "shipping_lines": [
                {
                    "method_id": "flat_rate",
                    "method_title": "Flat Rate",
                    "total": "20.00"
                }
            ]
        }
    ],
    "update": [
        {
            "id": 154,
            "shipping_methods": "Local Delivery"
        }
    ],
    "delete": [
        154
    ]
}

print(wcapi.post("orders/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 79,
          quantity: 1
        },
        {
          product_id: 93,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "30.00"
        }
      ]
    },
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      set_paid: true,
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 24,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "20.00"
        }
      ]
    }
  ],
  update: [
    {
      id: 154,
      shipping_methods: "Local Delivery"
    }
  ],
  delete: [
    154
  ]
}

woocommerce.post("orders/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 155,
      "parent_id": 0,
      "status": "pending",
      "order_key": "wc_order_574cc9541cea3",
      "number": "155",
      "currency": "USD",
      "version": "2.6.0",
      "prices_include_tax": false,
      "date_created": "2016-05-30T23:14:28",
      "date_modified": "2016-05-30T23:14:28",
      "customer_id": 0,
      "discount_total": "0.00",
      "discount_tax": "0.00",
      "shipping_total": "30.00",
      "shipping_tax": "0.00",
      "cart_tax": "2.85",
      "total": "70.85",
      "total_tax": "2.85",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "payment_method": "bacs",
      "payment_method_title": "bacs",
      "transaction_id": "",
      "customer_ip_address": "127.0.0.1",
      "customer_user_agent": "curl/7.47.0",
      "created_via": "rest-api",
      "customer_note": "",
      "date_completed": "2016-05-30T20:14:28",
      "date_paid": "",
      "cart_hash": "",
      "line_items": [
        {
          "id": 22,
          "name": "Woo Logo",
          "sku": "",
          "product_id": 79,
          "variation_id": 0,
          "quantity": 1,
          "tax_class": "",
          "price": "15.00",
          "subtotal": "15.00",
          "subtotal_tax": "1.13",
          "total": "15.00",
          "total_tax": "1.13",
          "taxes": [
            {
              "id": 75,
              "total": 1.125,
              "subtotal": 1.125
            }
          ],
          "meta": []
        },
        {
          "id": 23,
          "name": "Woo Single #1",
          "sku": "",
          "product_id": 93,
          "variation_id": 0,
          "quantity": 1,
          "tax_class": "",
          "price": "3.00",
          "subtotal": "3.00",
          "subtotal_tax": "0.23",
          "total": "3.00",
          "total_tax": "0.23",
          "taxes": [
            {
              "id": 75,
              "total": 0.225,
              "subtotal": 0.225
            }
          ],
          "meta": []
        },
        {
          "id": 24,
          "name": "Ship Your Idea",
          "sku": "",
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1,
          "tax_class": "",
          "price": "20.00",
          "subtotal": "20.00",
          "subtotal_tax": "1.50",
          "total": "20.00",
          "total_tax": "1.50",
          "taxes": [
            {
              "id": 75,
              "total": 1.5,
              "subtotal": 1.5
            }
          ],
          "meta": [
            {
              "key": "pa_color",
              "label": "Color",
              "value": "Black"
            }
          ]
        }
      ],
      "tax_lines": [
        {
          "id": 26,
          "rate_code": "US-CA-STATE TAX",
          "rate_id": "75",
          "label": "State Tax",
          "compound": false,
          "tax_total": "2.85",
          "shipping_tax_total": "0.00"
        }
      ],
      "shipping_lines": [
        {
          "id": 25,
          "method_title": "Flat Rate",
          "method_id": "flat_rate",
          "total": "30.00",
          "total_tax": "0.00",
          "taxes": []
        }
      ],
      "fee_lines": [],
      "coupon_lines": [],
      "refunds": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/orders/155"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/orders"
          }
        ]
      }
    },
    {
      "id": 156,
      "parent_id": 0,
      "status": "processing",
      "order_key": "wc_order_574cc95465214",
      "number": "156",
      "currency": "USD",
      "version": "2.6.0",
      "prices_include_tax": false,
      "date_created": "2016-05-30T23:14:28",
      "date_modified": "2016-05-30T23:14:28",
      "customer_id": 0,
      "discount_total": "0.00",
      "discount_tax": "0.00",
      "shipping_total": "20.00",
      "shipping_tax": "0.00",
      "cart_tax": "3.00",
      "total": "63.00",
      "total_tax": "3.00",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "payment_method": "bacs",
      "payment_method_title": "bacs",
      "transaction_id": "",
      "customer_ip_address": "127.0.0.1",
      "customer_user_agent": "curl/7.47.0",
      "created_via": "rest-api",
      "customer_note": "",
      "date_completed": "2016-05-30T20:14:28",
      "date_paid": "2016-05-30 20:14:37",
      "cart_hash": "",
      "line_items": [
        {
          "id": 27,
          "name": "Ship Your Idea",
          "sku": "",
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1,
          "tax_class": "",
          "price": "20.00",
          "subtotal": "20.00",
          "subtotal_tax": "1.50",
          "total": "20.00",
          "total_tax": "1.50",
          "taxes": [
            {
              "id": 75,
              "total": 1.5,
              "subtotal": 1.5
            }
          ],
          "meta": [
            {
              "key": "pa_color",
              "label": "Color",
              "value": "Black"
            }
          ]
        },
        {
          "id": 28,
          "name": "Ship Your Idea",
          "sku": "",
          "product_id": 22,
          "variation_id": 24,
          "quantity": 1,
          "tax_class": "",
          "price": "20.00",
          "subtotal": "20.00",
          "subtotal_tax": "1.50",
          "total": "20.00",
          "total_tax": "1.50",
          "taxes": [
            {
              "id": 75,
              "total": 1.5,
              "subtotal": 1.5
            }
          ],
          "meta": [
            {
              "key": "pa_color",
              "label": "Color",
              "value": "Green"
            }
          ]
        }
      ],
      "tax_lines": [
        {
          "id": 30,
          "rate_code": "US-CA-STATE TAX",
          "rate_id": "75",
          "label": "State Tax",
          "compound": false,
          "tax_total": "3.00",
          "shipping_tax_total": "0.00"
        }
      ],
      "shipping_lines": [
        {
          "id": 29,
          "method_title": "Flat Rate",
          "method_id": "flat_rate",
          "total": "20.00",
          "total_tax": "0.00",
          "taxes": []
        }
      ],
      "fee_lines": [],
      "coupon_lines": [],
      "refunds": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/orders/156"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/orders"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 154,
      "parent_id": 0,
      "status": "completed",
      "order_key": "wc_order_574cc02467274",
      "number": "154",
      "currency": "USD",
      "version": "2.6.0",
      "prices_include_tax": false,
      "date_created": "2016-05-30T22:35:16",
      "date_modified": "2016-05-30T22:55:19",
      "customer_id": 0,
      "discount_total": "0.00",
      "discount_tax": "0.00",
      "shipping_total": "10.00",
      "shipping_tax": "0.00",
      "cart_tax": "1.95",
      "total": "37.95",
      "total_tax": "1.95",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "payment_method": "bacs",
      "payment_method_title": "bacs",
      "transaction_id": "",
      "customer_ip_address": "127.0.0.1",
      "customer_user_agent": "curl/7.47.0",
      "created_via": "rest-api",
      "customer_note": "",
      "date_completed": "2016-05-30T19:47:46",
      "date_paid": "2016-05-30 19:35:25",
      "cart_hash": "",
      "line_items": [
        {
          "id": 18,
          "name": "Woo Single #1",
          "sku": "",
          "product_id": 93,
          "variation_id": 0,
          "quantity": 2,
          "tax_class": "",
          "price": "3.00",
          "subtotal": "6.00",
          "subtotal_tax": "0.45",
          "total": "6.00",
          "total_tax": "0.45",
          "taxes": [
            {
              "id": 75,
              "total": 0.45,
              "subtotal": 0.45
            }
          ],
          "meta": []
        },
        {
          "id": 19,
          "name": "Ship Your Idea",
          "sku": "",
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1,
          "tax_class": "",
          "price": "20.00",
          "subtotal": "20.00",
          "subtotal_tax": "1.50",
          "total": "20.00",
          "total_tax": "1.50",
          "taxes": [
            {
              "id": 75,
              "total": 1.5,
              "subtotal": 1.5
            }
          ],
          "meta": [
            {
              "key": "pa_color",
              "label": "Color",
              "value": "Black"
            }
          ]
        }
      ],
      "tax_lines": [
        {
          "id": 21,
          "rate_code": "US-CA-STATE TAX",
          "rate_id": "75",
          "label": "State Tax",
          "compound": false,
          "tax_total": "1.95",
          "shipping_tax_total": "0.00"
        }
      ],
      "shipping_lines": [
        {
          "id": 20,
          "method_title": "Flat Rate",
          "method_id": "flat_rate",
          "total": "10.00",
          "total_tax": "0.00",
          "taxes": []
        }
      ],
      "fee_lines": [],
      "coupon_lines": [],
      "refunds": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/orders/154"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/orders"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 154,
      "parent_id": 0,
      "status": "completed",
      "order_key": "wc_order_574cc02467274",
      "number": "154",
      "currency": "USD",
      "version": "2.6.0",
      "prices_include_tax": false,
      "date_created": "2016-05-30T22:35:16",
      "date_modified": "2016-05-30T22:55:19",
      "customer_id": 0,
      "discount_total": "0.00",
      "discount_tax": "0.00",
      "shipping_total": "10.00",
      "shipping_tax": "0.00",
      "cart_tax": "1.95",
      "total": "37.95",
      "total_tax": "1.95",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "payment_method": "bacs",
      "payment_method_title": "bacs",
      "transaction_id": "",
      "customer_ip_address": "127.0.0.1",
      "customer_user_agent": "curl/7.47.0",
      "created_via": "rest-api",
      "customer_note": "",
      "date_completed": "2016-05-30T19:47:46",
      "date_paid": "2016-05-30 19:35:25",
      "cart_hash": "",
      "line_items": [
        {
          "id": 18,
          "name": "Woo Single #1",
          "sku": "",
          "product_id": 93,
          "variation_id": 0,
          "quantity": 2,
          "tax_class": "",
          "price": "3.00",
          "subtotal": "6.00",
          "subtotal_tax": "0.45",
          "total": "6.00",
          "total_tax": "0.45",
          "taxes": [
            {
              "id": 75,
              "total": 0.45,
              "subtotal": 0.45
            }
          ],
          "meta": []
        },
        {
          "id": 19,
          "name": "Ship Your Idea",
          "sku": "",
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1,
          "tax_class": "",
          "price": "20.00",
          "subtotal": "20.00",
          "subtotal_tax": "1.50",
          "total": "20.00",
          "total_tax": "1.50",
          "taxes": [
            {
              "id": 75,
              "total": 1.5,
              "subtotal": 1.5
            }
          ],
          "meta": [
            {
              "key": "pa_color",
              "label": "Color",
              "value": "Black"
            }
          ]
        }
      ],
      "tax_lines": [
        {
          "id": 21,
          "rate_code": "US-CA-STATE TAX",
          "rate_id": "75",
          "label": "State Tax",
          "compound": false,
          "tax_total": "1.95",
          "shipping_tax_total": "0.00"
        }
      ],
      "shipping_lines": [
        {
          "id": 20,
          "method_title": "Flat Rate",
          "method_id": "flat_rate",
          "total": "10.00",
          "total_tax": "0.00",
          "taxes": []
        }
      ],
      "fee_lines": [],
      "coupon_lines": [],
      "refunds": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/orders/154"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/orders"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product attribute terms

*Source: apis/rest-api/v1/product-attribute-terms.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product attribute terms
The product attribute terms API allows you to create, view, update, and delete individual, or a batch, of attribute terms.

## Attribute term properties
|   Attribute   |   Type  |                                       Description                                        |
|---------------|---------|------------------------------------------------------------------------------------------|
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Term name. `REQUIRED`                                      |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `menu_order`  | integer | Menu order, used to custom sort the resource.                                            |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create an attribute term
This API helps you to create a new product attribute term.

```http
POST /wp-json/wc/v1/products/attributes/<attribute_id>/terms
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/attributes/2/terms \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "XXS"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "XXS"
};

WooCommerce.post("products/attributes/2/terms", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'XXS'
];

print_r($woocommerce->post('products/attributes/2/terms', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "XXS"
}

print(wcapi.post("products/attributes/2/terms", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "XXS"
}

woocommerce.post("products/attributes/2/terms", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 23,
  "name": "XXS",
  "slug": "xxs",
  "description": "",
  "menu_order": 1,
  "count": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/23"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve an attribute term
This API lets you retrieve a product attribute term by ID.

```http
GET /wp-json/wc/v1/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/attributes/2/terms/23 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/attributes/2/terms/23")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/2/terms/23')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/2/terms/23").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/2/terms/23").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 23,
  "name": "XXS",
  "slug": "xxs",
  "description": "",
  "menu_order": 1,
  "count": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/23"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all attribute terms
This API lets you retrieve all terms from a product attribute.

```http
GET /wp-json/wc/v1/products/attributes/<attribute_id>/terms
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/attributes/2/terms \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/attributes/2/terms")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/2/terms')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/2/terms").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/2/terms").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 23,
    "name": "XXS",
    "slug": "xxs",
    "description": "",
    "menu_order": 1,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/23"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 22,
    "name": "XS",
    "slug": "xs",
    "description": "",
    "menu_order": 2,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/22"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 17,
    "name": "S",
    "slug": "s",
    "description": "",
    "menu_order": 3,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/17"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 18,
    "name": "M",
    "slug": "m",
    "description": "",
    "menu_order": 4,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/18"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 19,
    "name": "L",
    "slug": "l",
    "description": "",
    "menu_order": 5,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/19"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 20,
    "name": "XL",
    "slug": "xl",
    "description": "",
    "menu_order": 6,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/20"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 21,
    "name": "XXL",
    "slug": "xxl",
    "description": "",
    "menu_order": 7,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/21"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
|  Parameter   |   Type  |                                                                Description                                                                 |
|--------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                  |
| `page`       | integer | Current page of the collection.                                                                                                            |
| `per_page`   | integer | Maximum number of items to be returned in result set.                                                                                      |
| `search`     | string  | Limit results to those matching a string.                                                                                                  |
| `exclude`    | string  | Ensure result set excludes specific ids.                                                                                                   |
| `include`    | string  | Limit result set to specific ids.                                                                                                          |
| `order`      | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                                 |
| `orderby`    | string  | Sort collection by object attribute. Default is `name`. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. |
| `hide_empty` | bool    | Whether to hide resources not assigned to any products. Default is `false`.                                                                |
| `parent`     | integer | Limit result set to resources assigned to a specific parent.                                                                               |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                              |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                        |

## Update an attribute term
This API lets you make changes to a product attribute term.

```http
PUT /wp-json/wc/v1/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/products/attributes/2/terms/23 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "XXS"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "XXS"
};

WooCommerce.put("products/attributes/2/terms/23", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'XXS'
];

print_r($woocommerce->put('products/attributes/2/terms/23', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "XXS"
}

print(wcapi.put("products/attributes/2/terms/23", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "XXS"
}

woocommerce.put("products/attributes/2/terms/23", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 23,
  "name": "XXS",
  "slug": "xxs",
  "description": "",
  "menu_order": 1,
  "count": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/23"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete an attribute term
This API helps you delete a product attribute term.

```http
DELETE /wp-json/wc/v1/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/products/attributes/2/terms/23?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/attributes/2/terms/23", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/attributes/2/terms/23', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/attributes/2/terms/23", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/attributes/2/terms/23", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 23,
  "name": "XXS",
  "slug": "xxs",
  "description": "",
  "menu_order": 1,
  "count": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/23"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update attribute terms
This API helps you to batch create, update and delete multiple product attribute terms.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/products/attributes/<attribute_id>/terms/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/attributes/<attribute_id>/terms/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "XXS"
    },
    {
      "name": "S"
    }
  ],
  "update": [
    {
      "id": 19,
      "menu_order": 6
    }
  ],
  "delete": [
    21,
    20
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "XXS"
    },
    {
      name: "S"
    }
  ],
  update: [
    {
      id: 19,
      menu_order: 6
    }
  ],
  delete: [
    21,
    20
  ]
};

WooCommerce.post("products/attributes/2/terms/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'XXS'
        ],
        [
            'name' => 'S'
        ]
    ],
    'update' => [
        [
            'id' => 19,
            'menu_order' => 6
        ]
    ],
    'delete' => [
        21,
        20
    ]
];

print_r($woocommerce->post('products/attributes/2/terms/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "XXS"
        },
        {
            "name": "S"
        }
    ],
    "update": [
        {
            "id": 19,
            "menu_order": 6
        }
    ],
    "delete": [
        21,
        20
    ]
}

print(wcapi.post("products/attributes/2/terms/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "XXS"
    },
    {
      name: "S"
    }
  ],
  update: [
    {
      id: 19,
      menu_order: 6
    }
  ],
  delete: [
    21,
    20
  ]
}

woocommerce.post("products/attributes/2/terms/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 23,
      "name": "XXS",
      "slug": "xxs",
      "description": "",
      "menu_order": 1,
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/23"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
          }
        ]
      }
    },
    {
      "id": 17,
      "name": "S",
      "slug": "s",
      "description": "",
      "menu_order": 3,
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/17"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 19,
      "name": "L",
      "slug": "l",
      "description": "",
      "menu_order": 5,
      "count": 1,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/19"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 21,
      "name": "XXL",
      "slug": "xxl",
      "description": "",
      "menu_order": 7,
      "count": 1,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/21"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
          }
        ]
      }
    },
    {
      "id": 20,
      "name": "XL",
      "slug": "xl",
      "description": "",
      "menu_order": 6,
      "count": 1,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms/20"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2/terms"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product attributes

*Source: apis/rest-api/v1/product-attributes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product attributes
The product attributes API allows you to create, view, update, and delete individual, or a batch, of product attributes.

## Product attribute properties
|   Attribute    |   Type  |                                                Description                                                |
|----------------|---------|-----------------------------------------------------------------------------------------------------------|
| `id`           | integer | Unique identifier for the resource. `READ-ONLY`                             |
| `name`         | string  | Attribute name. `REQUIRED`                                                  |
| `slug`         | string  | An alphanumeric identifier for the resource unique to its type.                                           |
| `type`         | string  | Type of attribute. Default is `select`. Options: `select` and `text` (some plugins can include new types) |
| `order_by`     | string  | Default sort order. Default is `menu_order`. Options: `menu_order`, `name`, `name_num` and `id`.          |
| `has_archives` | boolean | Enable/Disable attribute archives. Default is `false`.                                                    |

## Create a product attribute
This API helps you to create a new product attribute.

```http
POST /wp-json/wc/v1/products/attributes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/attributes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Color",
  slug: "pa_color",
  type: "select",
  order_by: "menu_order",
  has_archives: true
};

WooCommerce.post("products/attributes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Color',
    'slug' => 'pa_color',
    'type' => 'select',
    'order_by' => 'menu_order',
    'has_archives' => true
];

print_r($woocommerce->post('products/attributes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Color",
    "slug": "pa_color",
    "type": "select",
    "order_by": "menu_order",
    "has_archives": True
}

print(wcapi.post("products/attributes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Color",
  slug: "pa_color",
  type: "select",
  order_by: "menu_order",
  has_archives: true
}

woocommerce.post("products/attributes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 1,
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/1"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product attribute
This API lets you retrieve and view a specific product attribute by ID.

```http
GET /wp-json/wc/v1/products/attributes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/attributes/1 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/attributes/1")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/1')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/1").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/1").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 1,
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/1"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all product attributes
This API helps you to view all the product attributes.

```http
GET /wp-json/wc/v1/products/attributes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/attributes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/attributes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 1,
    "name": "Color",
    "slug": "pa_color",
    "type": "select",
    "order_by": "menu_order",
    "has_archives": true,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/1"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes"
        }
      ]
    }
  },
  {
    "id": 2,
    "name": "Size",
    "slug": "pa_size",
    "type": "select",
    "order_by": "menu_order",
    "has_archives": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes/2"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/attributes"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Update a product attribute
This API lets you make changes to a product attribute.

```http
PUT /wp-json/wc/v1/products/attributes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/products/attributes/1 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "order_by": "name"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  order_by: "name"
};

WooCommerce.put("products/attributes/1", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'order_by' => 'name'
];

print_r($woocommerce->put('products/attributes/1', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "order_by": "name"
}

print(wcapi.put("products/attributes/1", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  order_by: "name"
}

woocommerce.put("products/attributes/1", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 1,
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "name",
  "has_archives": true,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/1"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product attribute
This API helps you delete a product attribute.

```http
DELETE /wp-json/wc/v1/products/attributes/<id>
```

:::warning
This also will delete all terms from the selected attribute.
:::

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/products/attributes/1?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/attributes/1", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/attributes/1', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/attributes/1", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/attributes/1", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 1,
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes/1"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/attributes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product attributes
This API helps you to batch create, update and delete multiple product attributes.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/products/attributes/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/attributes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Brand"
    },
    {
      "name": "Publisher"
    }
  ],
  "update": [
    {
      "id": 2,
      "order_by": "name"
    }
  ],
  "delete": [
    1
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Brand"
    },
    {
      name: "Publisher"
    }
  ],
  update: [
    {
      id: 2,
      order_by: "name"
    }
  ],
  delete: [
    1
  ]
};

WooCommerce.post("products/attributes/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Brand'
        ],
        [
            'name' => 'Publisher'
        ]
    ],
    'update' => [
        [
            'id' => 2,
            'order_by' => 'name'
        ]
    ],
    'delete' => [
        1
    ]
];

print_r($woocommerce->post('products/attributes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Brand"
        },
        {
            "name": "Publisher"
        }
    ],
    "update": [
        {
            "id": 2,
            "order_by": "name"
        }
    ],
    "delete": [
        1
    ]
}

print(wcapi.post("products/attributes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Round toe"
    },
    {
      name: "Flat"
    }
  ],
  update: [
    {
      id: 2,
      order_by: "name"
    }
  ],
  delete: [
    1
  ]
}

woocommerce.post("products/attributes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 7,
      "name": "Brand",
      "slug": "pa_brand",
      "type": "select",
      "order_by": "menu_order",
      "has_archives": false,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/7"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes"
          }
        ]
      }
    },
    {
      "id": 8,
      "name": "Publisher",
      "slug": "pa_publisher",
      "type": "select",
      "order_by": "menu_order",
      "has_archives": false,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/8"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 2,
      "name": "Size",
      "slug": "pa_size",
      "type": "select",
      "order_by": "menu_order",
      "has_archives": false,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/2"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 1,
      "name": "Color",
      "slug": "pa_color",
      "type": "select",
      "order_by": "menu_order",
      "has_archives": true,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes/1"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/attributes"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product categories

*Source: apis/rest-api/v1/product-categories.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product categories
The product categories API allows you to create, view, update, and delete individual, or a batch, of categories.

## Product category properties
|   Attribute   |   Type  |                                                   Description                                                   |
|---------------|---------|-----------------------------------------------------------------------------------------------------------------|
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`                                   |
| `name`        | string  | Category name. `REQUIRED`                                                         |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                                                 |
| `parent`      | integer | The id for the parent of the resource.                                                                          |
| `description` | string  | HTML description of the resource.                                                                               |
| `display`     | string  | Category archive display type. Default is `default`. Options: `default`, `products`, `subcategories` and `both` |
| `image`       | array   | Image data. See [Category Image properties](#category-image-properties)                                         |
| `menu_order`  | integer | Menu order, used to custom sort the resource.                                                                   |
| `count`       | integer | Number of published products for the resource. `READ-ONLY`                        |

### Category Image properties
|    Attribute    |    Type   |                                               Description                                               |
|-----------------|-----------|---------------------------------------------------------------------------------------------------------|
| `id`            | integer   | Image ID (attachment ID). In write-mode used to attach pre-existing images.                             |
| `date_created`  | date-time | The date the image was created, in the site's timezone. `READ-ONLY`       |
| `date_modified` | date-time | The date the image was last modified, in the site's timezone. `READ-ONLY` |
| `src`           | string    | Image URL. In write-mode used to upload new images.                                                     |
| `title`         | string    | Image name.                                                                                             |
| `alt`           | string    | Image alternative text.                                                                                 |

## Create a product category
This API helps you to create a new product category.

```http
POST /wp-json/wc/v1/products/categories
```

> Example of how to create a product category:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/categories \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Clothing",
  "image": {
    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Clothing",
  image: {
    src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
  }
};

WooCommerce.post("products/categories", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Clothing',
    'image' => [
        'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg'
    ]
];

print_r($woocommerce->post('products/categories', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Clothing",
    "image": {
        "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
    }
}

print(wcapi.post("products/categories", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Clothing",
  image: {
    src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
  }
}

woocommerce.post("products/categories", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "name": "Clothing",
  "slug": "clothing",
  "parent": 0,
  "description": "",
  "display": "default",
  "image": {
    "id": 173,
    "date_created": "2016-05-31T23:51:03",
    "date_modified": "2016-05-31T23:51:03",
    "src": "https://example/wp-content/uploads/2016/05/T_3_front-1.jpg",
    "title": "",
    "alt": ""
  },
  "menu_order": 0,
  "count": 18,
  "_links": {
    "self": [
      {
        "href": "https://example/wp-json/wc/v1/products/categories/9"
      }
    ],
    "collection": [
      {
        "href": "https://example/wp-json/wc/v1/products/categories"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product category
This API lets you retrieve a product category by ID.

```http
GET /wp-json/wc/v1/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/categories/9 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/categories/9")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/categories/9')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/categories/9").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/categories/9").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "name": "Clothing",
  "slug": "clothing",
  "parent": 0,
  "description": "",
  "display": "default",
  "image": {
    "id": 173,
    "date_created": "2016-05-31T23:51:03",
    "date_modified": "2016-05-31T23:51:03",
    "src": "https://example/wp-content/uploads/2016/05/T_3_front-1.jpg",
    "title": "",
    "alt": ""
  },
  "menu_order": 0,
  "count": 18,
  "_links": {
    "self": [
      {
        "href": "https://example/wp-json/wc/v1/products/categories/9"
      }
    ],
    "collection": [
      {
        "href": "https://example/wp-json/wc/v1/products/categories"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all product categories
This API lets you retrieve all product categories.

```http
GET /wp-json/wc/v1/products/categories
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/categories \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/categories")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/categories')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/categories").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/categories").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 15,
    "name": "Albums",
    "slug": "albums",
    "parent": 11,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 4,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/15"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/11"
        }
      ]
    }
  },
  {
    "id": 9,
    "name": "Clothing",
    "slug": "clothing",
    "parent": 0,
    "description": "",
    "display": "default",
    "image": {
      "id": 173,
      "date_created": "2016-05-31T23:51:03",
      "date_modified": "2016-05-31T23:51:03",
      "src": "https://example/wp-content/uploads/2016/05/T_3_front-1.jpg",
      "title": "",
      "alt": ""
    },
    "menu_order": 0,
    "count": 18,
    "_links": {
      "self": [
        {
          "href": "https://example/wp-json/wc/v1/products/categories/9"
        }
      ],
      "collection": [
        {
          "href": "https://example/wp-json/wc/v1/products/categories"
        }
      ]
    }
  },
  {
    "id": 10,
    "name": "Hoodies",
    "slug": "hoodies",
    "parent": 9,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 6,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/10"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/9"
        }
      ]
    }
  },
  {
    "id": 11,
    "name": "Music",
    "slug": "music",
    "parent": 0,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 7,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/11"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories"
        }
      ]
    }
  },
  {
    "id": 12,
    "name": "Posters",
    "slug": "posters",
    "parent": 0,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 5,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/12"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories"
        }
      ]
    }
  },
  {
    "id": 13,
    "name": "Singles",
    "slug": "singles",
    "parent": 11,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 3,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/13"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/11"
        }
      ]
    }
  },
  {
    "id": 14,
    "name": "T-shirts",
    "slug": "t-shirts",
    "parent": 9,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 6,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/14"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/categories/9"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
|  Parameter   |   Type  |                                                                Description                                                                 |
|--------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                  |
| `page`       | integer | Current page of the collection.                                                                                                            |
| `per_page`   | integer | Maximum number of items to be returned in result set.                                                                                      |
| `search`     | string  | Limit results to those matching a string.                                                                                                  |
| `exclude`    | string  | Ensure result set excludes specific ids.                                                                                                   |
| `include`    | string  | Limit result set to specific ids.                                                                                                          |
| `order`      | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                                 |
| `orderby`    | string  | Sort collection by object attribute. Default is `name`. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. |
| `hide_empty` | bool    | Whether to hide resources not assigned to any products. Default is `false`.                                                                |
| `parent`     | integer | Limit result set to resources assigned to a specific parent.                                                                               |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                              |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                        |

## Update a product category
This API lets you make changes to a product category.

```http
PUT /wp-json/wc/v1/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/products/categories/9 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "All kinds of clothes."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  description: "All kinds of clothes."
};

WooCommerce.put("products/categories/9", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description' => 'All kinds of clothes.'
];

print_r($woocommerce->put('products/categories/9', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "All kinds of clothes."
}

print(wcapi.put("products/categories/9", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "All kinds of clothes."
}

woocommerce.put("products/categories/9", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "name": "Clothing",
  "slug": "clothing",
  "parent": 0,
  "description": "All kinds of clothes.",
  "display": "default",
  "image": {
    "id": 173,
    "date_created": "2016-05-31T23:51:03",
    "date_modified": "2016-05-31T23:51:03",
    "src": "https://example/wp-content/uploads/2016/05/T_3_front-1.jpg",
    "title": "",
    "alt": ""
  },
  "menu_order": 0,
  "count": 18,
  "_links": {
    "self": [
      {
        "href": "https://example/wp-json/wc/v1/products/categories/9"
      }
    ],
    "collection": [
      {
        "href": "https://example/wp-json/wc/v1/products/categories"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product category
This API helps you delete a product category.

```http
DELETE /wp-json/wc/v1/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/products/categories/9?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/categories/9", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/categories/9', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/categories/9", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/categories/9", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "name": "Clothing",
  "slug": "clothing",
  "parent": 0,
  "description": "All kinds of clothes.",
  "display": "default",
  "image": {
    "id": 173,
    "date_created": "2016-05-31T23:51:03",
    "date_modified": "2016-05-31T23:51:03",
    "src": "https://example/wp-content/uploads/2016/05/T_3_front-1.jpg",
    "title": "",
    "alt": ""
  },
  "menu_order": 0,
  "count": 18,
  "_links": {
    "self": [
      {
        "href": "https://example/wp-json/wc/v1/products/categories/9"
      }
    ],
    "collection": [
      {
        "href": "https://example/wp-json/wc/v1/products/categories"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product categories
This API helps you to batch create, update and delete multiple product categories.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/products/categories/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/categories/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Albums"
    },
    {
      "name": "Clothing"
    }
  ],
  "update": [
    {
      "id": 10,
      "description": "Nice hoodies"
    }
  ],
  "delete": [
    11,
    12
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Albums"
    },
    {
      name: "Clothing"
    }
  ],
  update: [
    {
      id: 10,
      description: "Nice hoodies"
    }
  ],
  delete: [
    11,
    12
  ]
};

WooCommerce.post("products/categories/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Albums'
        ],
        [
            'name' => 'Clothing'
        ]
    ],
    'update' => [
        [
            'id' => 10,
            'description' => 'Nice hoodies'
        ]
    ],
    'delete' => [
        11,
        12
    ]
];

print_r($woocommerce->post('products/categories/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Albums"
        },
        {
            "name": "Clothing"
        }
    ],
    "update": [
        {
            "id": 10,
            "description": "Nice hoodies"
        }
    ],
    "delete": [
        11,
        12
    ]
}

print(wcapi.post("products/categories/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Albums"
    },
    {
      name: "Clothing"
    }
  ],
  update: [
    {
      id: 10,
      description: "Nice hoodies"
    }
  ],
  delete: [
    11,
    12
  ]
}

woocommerce.post("products/categories/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 15,
      "name": "Albums",
      "slug": "albums",
      "parent": 11,
      "description": "",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories/15"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories"
          }
        ],
        "up": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories/11"
          }
        ]
      }
    },
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing",
      "parent": 0,
      "description": "",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories/9"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 10,
      "name": "Hoodies",
      "slug": "hoodies",
      "parent": 9,
      "description": "Nice hoodies",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 6,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories/10"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories"
          }
        ],
        "up": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories/9"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 11,
      "name": "Music",
      "slug": "music",
      "parent": 0,
      "description": "",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 7,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories/11"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories"
          }
        ]
      }
    },
    {
      "id": 12,
      "name": "Posters",
      "slug": "posters",
      "parent": 0,
      "description": "",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 5,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories/12"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/categories"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product shipping classes

*Source: apis/rest-api/v1/product-shipping-classes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product shipping classes
The product shipping class API allows you to create, view, update, and delete individual, or a batch, of shipping classes.

## Shipping class properties
|   Attribute   |   Type  |                                       Description                                        |
|---------------|---------|------------------------------------------------------------------------------------------|
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Shipping class name. `REQUIRED`                            |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create a shipping class
This API helps you to create a new product shipping class.

```http
POST /wp-json/wc/v1/products/shipping_classes
```

> Example of how to create a product shipping class:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/shipping_classes \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Priority"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Priority"
};

WooCommerce.post("products/shipping_classes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Priority'
];

print_r($woocommerce->post('products/shipping_classes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Priority"
}

print(wcapi.post("products/shipping_classes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Priority"
}

woocommerce.post("products/shipping_classes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 32,
  "name": "Priority",
  "slug": "priority",
  "description": "",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/32"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a shipping class
This API lets you retrieve a product shipping class by ID.

```http
GET /wp-json/wc/v1/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/shipping_classes/32 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/shipping_classes/32")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/shipping_classes/32')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/shipping_classes/32").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/shipping_classes/32").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 32,
  "name": "Priority",
  "slug": "priority",
  "description": "",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/32"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all shipping classes
This API lets you retrieve all product shipping classes.

```http
GET /wp-json/wc/v1/products/shipping_classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/shipping_classes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/shipping_classes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/shipping_classes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/shipping_classes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/shipping_classes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 33,
    "name": "Express",
    "slug": "express",
    "description": "",
    "count": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/33"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
        }
      ]
    }
  },
  {
    "id": 32,
    "name": "Priority",
    "slug": "priority",
    "description": "",
    "count": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/32"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
|  Parameter   |   Type  |                                                                Description                                                                 |
|--------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                  |
| `page`       | integer | Current page of the collection.                                                                                                            |
| `per_page`   | integer | Maximum number of items to be returned in result set.                                                                                      |
| `search`     | string  | Limit results to those matching a string.                                                                                                  |
| `exclude`    | string  | Ensure result set excludes specific ids.                                                                                                   |
| `include`    | string  | Limit result set to specific ids.                                                                                                          |
| `order`      | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                                 |
| `orderby`    | string  | Sort collection by object attribute. Default is `name`. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. |
| `hide_empty` | bool    | Whether to hide resources not assigned to any products. Default is `false`.                                                                |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                              |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                        |

## Update a shipping class
This API lets you make changes to a product shipping class.

```http
PUT /wp-json/wc/v1/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/products/shipping_classes/32 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "Priority mail."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  description: "Priority mail."
};

WooCommerce.put("products/shipping_classes/32", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description' => 'Priority mail.'
];

print_r($woocommerce->put('products/shipping_classes/32', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "Priority mail."
}

print(wcapi.put("products/shipping_classes/32", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "Priority mail."
}

woocommerce.put("products/shipping_classes/32", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 32,
  "name": "Priority",
  "slug": "priority",
  "description": "Priority mail.",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/32"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a shipping class
This API helps you delete a product shipping class.

```http
DELETE /wp-json/wc/v1/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/products/shipping_classes/32?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/shipping_classes/32", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/shipping_classes/32', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/shipping_classes/32", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/shipping_classes/32", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 32,
  "name": "Priority",
  "slug": "priority",
  "description": "Priority mail.",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/32"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update shipping classes
This API helps you to batch create, update and delete multiple product shipping classes.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/products/shipping_classes/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/shipping_classes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Small items"
    },
    {
      "name": "Large items"
    }
  ],
  "update": [
    {
      "id": 33,
      "description": "Express shipping"
    }
  ],
  "delete": [
    32
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Small items"
    },
    {
      name: "Large items"
    }
  ],
  update: [
    {
      id: 33,
      description: "Express shipping"
    }
  ],
  delete: [
    32
  ]
};

WooCommerce.post("products/shipping_classes/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Small items'
        ],
        [
            'name' => 'Large items'
        ]
    ],
    'update' => [
        [
            'id' => 33,
            'description' => 'Express shipping'
        ]
    ],
    'delete' => [
        32
    ]
];

print_r($woocommerce->post('products/shipping_classes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Small items"
        },
        {
            "name": "Large items"
        }
    ],
    "update": [
        {
            "id": 33,
            "description": "Express shipping"
        }
    ],
    "delete": [
        32
    ]
}

print(wcapi.post("products/shipping_classes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Small items"
    },
    {
      name: "Large items"
    }
  ],
  update: [
    {
      id: 33,
      description: "Express shipping"
    }
  ],
  delete: [
    32
  ]
}

woocommerce.post("products/shipping_classes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 34,
      "name": "Small items",
      "slug": "small-items",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/34"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
          }
        ]
      }
    },
    {
      "id": 35,
      "name": "Large items",
      "slug": "large-items",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/35"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 33,
      "name": "Express",
      "slug": "express",
      "description": "Express shipping",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/33"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 32,
      "name": "Priority",
      "slug": "priority",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/shipping_classes/32"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/shipping_classes"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product tags

*Source: apis/rest-api/v1/product-tags.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product tags
The product tags API allows you to create, view, update, and delete individual, or a batch, of product tags.

## Product tag properties
|   Attribute   |   Type  |                                       Description                                        |
|---------------|---------|------------------------------------------------------------------------------------------|
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Tag name. `REQUIRED`                                       |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create a product tag
This API helps you to create a new product tag.

```http
POST /wp-json/wc/v1/products/tags
```

> Example of how to create a product tag:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/tags \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Leather Shoes"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Leather Shoes"
};

WooCommerce.post("products/tags", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Leather Shoes'
];

print_r($woocommerce->post('products/tags', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Leather Shoes"
}

print(wcapi.post("products/tags", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Leather Shoes"
}

woocommerce.post("products/tags", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 34,
  "name": "Leather Shoes",
  "slug": "leather-shoes",
  "description": "",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/tags/34"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/tags"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product tag
This API lets you retrieve a product tag by ID.

```http
GET /wp-json/wc/v1/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/tags/34 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/tags/34")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/tags/34')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/tags/34").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/tags/34").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 34,
  "name": "Leather Shoes",
  "slug": "leather-shoes",
  "description": "",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/tags/34"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/tags"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all product tags
This API lets you retrieve all product tag.

```http
GET /wp-json/wc/v1/products/tags
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/tags \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/tags")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/tags')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/tags").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/tags").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 34,
    "name": "Leather Shoes",
    "slug": "leather-shoes",
    "description": "",
    "count": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/tags/34"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/tags"
        }
      ]
    }
  },
  {
    "id": 35,
    "name": "Oxford Shoes",
    "slug": "oxford-shoes",
    "description": "",
    "count": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/tags/35"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/tags"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
|  Parameter   |   Type  |                                                                Description                                                                 |
|--------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                  |
| `page`       | integer | Current page of the collection.                                                                                                            |
| `per_page`   | integer | Maximum number of items to be returned in result set.                                                                                      |
| `search`     | string  | Limit results to those matching a string.                                                                                                  |
| `exclude`    | string  | Ensure result set excludes specific ids.                                                                                                   |
| `include`    | string  | Limit result set to specific ids.                                                                                                          |
| `order`      | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                                 |
| `orderby`    | string  | Sort collection by object attribute. Default is `name`. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. |
| `hide_empty` | bool    | Whether to hide resources not assigned to any products. Default is `false`.                                                                |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                              |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                        |

## Update a product tag
This API lets you make changes to a product tag.

```http
PUT /wp-json/wc/v1/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/products/tags/34 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "Genuine leather."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  description: "Genuine leather."
};

WooCommerce.put("products/tags/34", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description' => 'Genuine leather.'
];

print_r($woocommerce->put('products/tags/34', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "Genuine leather."
}

print(wcapi.put("products/tags/34", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "Genuine leather."
}

woocommerce.put("products/tags/34", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 34,
  "name": "Leather Shoes",
  "slug": "leather-shoes",
  "description": "Genuine leather.",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/tags/34"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/tags"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product tag
This API helps you delete a product tag.

```http
DELETE /wp-json/wc/v1/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/products/tags/34?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/tags/34", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/tags/34', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/tags/34", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/tags/34", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 34,
  "name": "Leather Shoes",
  "slug": "leather-shoes",
  "description": "Genuine leather.",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/tags/34"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/tags"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product tags
This API helps you to batch create, update and delete multiple product tags.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/products/tags/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/tags/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Round toe"
    },
    {
      "name": "Flat"
    }
  ],
  "update": [
    {
      "id": 34,
      "description": "Genuine leather."
    }
  ],
  "delete": [
    35
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Round toe"
    },
    {
      name: "Flat"
    }
  ],
  update: [
    {
      id: 34,
      description: "Genuine leather."
    }
  ],
  delete: [
    35
  ]
};

WooCommerce.post("products/tags/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Round toe'
        ],
        [
            'name' => 'Flat'
        ]
    ],
    'update' => [
        [
            'id' => 34,
            'description' => 'Genuine leather.'
        ]
    ],
    'delete' => [
        35
    ]
];

print_r($woocommerce->post('products/tags/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Round toe"
        },
        {
            "name": "Flat"
        }
    ],
    "update": [
        {
            "id": 34,
            "description": "Genuine leather."
        }
    ],
    "delete": [
        35
    ]
}

print(wcapi.post("products/tags/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Round toe"
    },
    {
      name: "Flat"
    }
  ],
  update: [
    {
      id: 34,
      description: "Genuine leather."
    }
  ],
  delete: [
    35
  ]
}

woocommerce.post("products/tags/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 36,
      "name": "Round toe",
      "slug": "round-toe",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/tags/36"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/tags"
          }
        ]
      }
    },
    {
      "id": 37,
      "name": "Flat",
      "slug": "flat",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/tags/37"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/tags"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 34,
      "name": "Leather Shoes",
      "slug": "leather-shoes",
      "description": "Genuine leather.",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/tags/34"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/tags"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 35,
      "name": "Oxford Shoes",
      "slug": "oxford-shoes",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/tags/35"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/tags"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Products

*Source: apis/rest-api/v1/products.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Products
The products API allows you to create, view, update, and delete individual, or a batch, of products.

## Product properties
| Attribute            | Type      | Description                                                                                                                                                                                                                                                                                                                                                   |
|----------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                 | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                                                                                                                                                                                                                 |
| `name`               | string    | Product name.                                                                                                                                                                                                                                                                                                                                                 |
| `slug`               | string    | Product slug.                                                                                                                                                                                                                                                                                                                                                 |
| `permalink`          | string    | Product URL. `READ-ONLY`                                                                                                                                                                                                                                                                                                        |
| `date_created`       | date-time | The date the product was created, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                           |
| `date_modified`      | date-time | The date the product was last modified, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                     |
| `type`               | string    | Product type. Default is `simple`. Options (plugins may add new options): `simple`, `grouped`, `external`, `variable`.                                                                                                                                                                                                                                        |
| `status`             | string    | Product status (post status). Default is `publish`. Options (plugins may add new options): `draft`, `pending`, `private` and `publish`.                                                                                                                                                                                                                       |
| `featured`           | boolean   | Featured product. Default is `false`.                                                                                                                                                                                                                                                                                                                         |
| `catalog_visibility` | string    | Catalog visibility. Default is `visible`. Options: `visible` (Catalog and search), `catalog` (Only in catalog), `search` (Only in search) and `hidden` (Hidden from all).                                                                                                                                                                                     |
| `description`        | string    | Product description.                                                                                                                                                                                                                                                                                                                                          |
| `short_description`  | string    | Product short description.                                                                                                                                                                                                                                                                                                                                    |
| `sku`                | string    | Unique identifier.                                                                                                                                                                                                                                                                                                                                            |
| `price`              | string    | Current product price. This is set from `regular_price` and `sale_price`. `READ-ONLY`                                                                                                                                                                                                                                        |
| `regular_price`      | string    | Product regular price.                                                                                                                                                                                                                                                                                                                                        |
| `sale_price`         | string    | Product sale price.                                                                                                                                                                                                                                                                                                                                           |
| `date_on_sale_from`  | string    | Start date of sale price. Date in the `YYYY-MM-DD` format.                                                                                                                                                                                                                                                                                                    |
| `date_on_sale_to`    | string    | Sets the sale end date. Date in the `YYYY-MM-DD` format.                                                                                                                                                                                                                                                                                                      |
| `price_html`         | string    | Price formatted in HTML, e.g. `<del><span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;&nbsp;3.00</span></span></del> <ins><span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;&nbsp;2.00</span></span></ins>` `READ-ONLY` |
| `on_sale`            | boolean   | Shows if the product is on sale. `READ-ONLY`                                                                                                                                                                                                                                                                                    |
| `purchasable`        | boolean   | Shows if the product can be bought. `READ-ONLY`                                                                                                                                                                                                                                                                                 |
| `total_sales`        | integer   | Amount of sales. `READ-ONLY`                                                                                                                                                                                                                                                                                                    |
| `virtual`            | boolean   | If the product is virtual. Virtual products are intangible and aren't shipped. Default is `false`.                                                                                                                                                                                                                                                            |
| `downloadable`       | boolean   | If the product is downloadable. Downloadable products give access to a file upon purchase. Default is `false`.                                                                                                                                                                                                                                                |
| `downloads`          | array     | List of downloadable files. See [Downloads properties](#download-properties).                                                                                                                                                                                                                                                                                 |
| `download_limit`     | integer   | Amount of times the product can be downloaded, the `-1` values means **unlimited re-downloads**. Default is `-1`.                                                                                                                                                                                                                                             |
| `download_expiry`    | integer   | Number of days that the customer has up to be able to download the product, the `-1` means that **downloads never expires**. Default is `-1`.                                                                                                                                                                                                                 |
| `download_type`      | string    | Download type, this controls the [schema](http://schema.org/) on the front-end. Default is `standard`. Options: `'standard'` (Standard Product), `application` (Application/Software) and `music` (Music).                                                                                                                                                    |
| `external_url`       | string    | Product external URL. Only for `external` products.                                                                                                                                                                                                                                                                                                           |
| `button_text`        | string    | Product external button text. Only for `external` products.                                                                                                                                                                                                                                                                                                   |
| `tax_status`         | string    | Tax status. Default is `taxable`. Options: `taxable`, `shipping` (Shipping only) and `none`.                                                                                                                                                                                                                                                                  |
| `tax_class`          | string    | Tax class.                                                                                                                                                                                                                                                                                                                                                    |
| `manage_stock`       | boolean   | Stock management at product level. Default is `false`.                                                                                                                                                                                                                                                                                                        |
| `stock_quantity`     | integer   | Stock quantity. If is a variable product this value will be used to control stock for all variations, unless you define stock at variation level.                                                                                                                                                                                                             |
| `in_stock`           | boolean   | Controls whether or not the product is listed as "in stock" or "out of stock" on the frontend. Default is `true`.                                                                                                                                                                                                                                             |
| `backorders`         | string    | If managing stock, this controls if backorders are allowed. If enabled, stock quantity can go below `0`. Default is `no`. Options are: `no` (Do not allow), `notify` (Allow, but notify customer), and `yes` (Allow).                                                                                                                                         |
| `backorders_allowed` | boolean   | Shows if backorders are allowed. `READ-ONLY`                                                                                                                                                                                                                                                                                    |
| `backordered`        | boolean   | Shows if a product is on backorder (if the product have the `stock_quantity` negative). `READ-ONLY`                                                                                                                                                                                                                             |
| `sold_individually`  | boolean   | Allow one item to be bought in a single order. Default is `false`.                                                                                                                                                                                                                                                                                            |
| `weight`             | string    | Product weight in decimal format.                                                                                                                                                                                                                                                                                                                             |
| `dimensions`         | object    | Product dimensions. See [Dimensions properties](#dimension-properties).                                                                                                                                                                                                                                                                                       |
| `shipping_required`  | boolean   | Shows if the product need to be shipped. `READ-ONLY`                                                                                                                                                                                                                                                                            |
| `shipping_taxable`   | boolean   | Shows whether or not the product shipping is taxable. `READ-ONLY`                                                                                                                                                                                                                                                               |
| `shipping_class`     | string    | Shipping class slug. Shipping classes are used by certain shipping methods to group similar products.                                                                                                                                                                                                                                                         |
| `shipping_class_id`  | integer   | Shipping class ID. `READ-ONLY`                                                                                                                                                                                                                                                                                                  |
| `reviews_allowed`    | boolean   | Allow reviews. Default is `true`.                                                                                                                                                                                                                                                                                                                             |
| `average_rating`     | string    | Reviews average rating. `READ-ONLY`                                                                                                                                                                                                                                                                                             |
| `rating_count`       | integer   | Amount of reviews that the product have. `READ-ONLY`                                                                                                                                                                                                                                                                            |
| `related_ids`        | array     | List of related products IDs (`integer`). `READ-ONLY`                                                                                                                                                                                                                                                                           |
| `upsell_ids`         | array     | List of up-sell products IDs (`integer`). Up-sells are products which you recommend instead of the currently viewed product, for example, products that are more profitable or better quality or more expensive.                                                                                                                                              |
| `cross_sell_ids`     | array     | List of cross-sell products IDs. Cross-sells are products which you promote in the cart, based on the current product.                                                                                                                                                                                                                                        |
| `parent_id`          | integer   | Product parent ID (`post_parent`).                                                                                                                                                                                                                                                                                                                            |
| `purchase_note`      | string    | Optional note to send the customer after purchase.                                                                                                                                                                                                                                                                                                            |
| `categories`         | array     | List of categories. See [Categories properties](#category-properties).                                                                                                                                                                                                                                                                                        |
| `tags`               | array     | List of tags. See [Tags properties](#tag-properties).                                                                                                                                                                                                                                                                                                         |
| `images`             | array     | List of images. See [Images properties](#image-properties)                                                                                                                                                                                                                                                                                                    |
| `attributes`         | array     | List of attributes. See [Attributes properties](#attribute-properties).                                                                                                                                                                                                                                                                                       |
| `default_attributes` | array     | Defaults variation attributes, used only for variations and pre-selected attributes on the frontend. See [Default Attributes properties](#default-attribute-properties).                                                                                                                                                                                      |
| `variations`         | array     | List of variations. See [Variations properties](#variation-properties)                                                                                                                                                                                                                                                                                        |
| `grouped_products`   | array     | List of grouped products ID, only for `group` type products. `READ-ONLY`                                                                                                                                                                                                                                                        |
| `menu_order`         | integer   | Menu order, used to custom sort products.                                                                                                                                                                                                                                                                                                                     |

### Download properties
| Attribute | Type   | Description                                                          |
|-----------|--------|----------------------------------------------------------------------|
| `id`      | string | File ID.                                                             |
| `name`    | string | File name.                                                           |
| `file`    | string | File URL. In write-mode you can use this property to send new files. |

### Dimension properties
| Attribute | Type   | Description                       |
|-----------|--------|-----------------------------------|
| `length`  | string | Product length in decimal format. |
| `width`   | string | Product width in decimal format.  |
| `height`  | string | Product height in decimal format. |

### Category properties
| Attribute | Type    | Description                                              |
|-----------|---------|----------------------------------------------------------|
| `id`      | integer | Category ID.                                             |
| `name`    | string  | Category name. `READ-ONLY` |
| `slug`    | string  | Category slug. `READ-ONLY` |

### Tag properties
| Attribute | Type    | Description                                         |
|-----------|---------|-----------------------------------------------------|
| `id`      | integer | Tag ID.                                             |
| `name`    | string  | Tag name. `READ-ONLY` |
| `slug`    | string  | Tag slug. `READ-ONLY` |

### Image properties
| Attribute       | Type      | Description                                                                                             |
|-----------------|-----------|---------------------------------------------------------------------------------------------------------|
| `id`            | integer   | Image ID (attachment ID). In write-mode used to attach pre-existing images.                             |
| `date_created`  | date-time | The date the image was created, in the site's timezone. `READ-ONLY`       |
| `date_modified` | date-time | The date the image was last modified, in the site's timezone. `READ-ONLY` |
| `src`           | string    | Image URL. In write-mode used to upload new images.                                                     |
| `name`          | string    | Image name.                                                                                             |
| `alt`           | string    | Image alternative text.                                                                                 |
| `position`      | integer   | Image position. `0` means that the image is featured.                                                   |

### Attribute properties
| Attribute   | Type    | Description                                                                                                       |
|-------------|---------|-------------------------------------------------------------------------------------------------------------------|
| `id`        | integer | Attribute ID (required if is a global attribute).                                                                 |
| `name`      | string  | Attribute name (required if is a non-global attribute).                                                           |
| `position`  | integer | Attribute position.                                                                                               |
| `visible`   | boolean | Define if the attribute is visible on the "Additional Information" tab in the product's page. Default is `false`. |
| `variation` | boolean | Define if the attribute can be used as variation. Default is `false`.                                             |
| `options`   | array   | List of available term names of the attribute.                                                                    |

### Default attribute properties
| Attribute | Type    | Description                                             |
|-----------|---------|---------------------------------------------------------|
| `id`      | integer | Attribute ID (required if is a global attribute).       |
| `name`    | string  | Attribute name (required if is a non-global attribute). |
| `option`  | string  | Selected attribute term name.                           |

### Variation properties
| Attribute            | Type      | Description                                                                                                                                                                                                           |
|----------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                 | integer   | Variation ID. `READ-ONLY`                                                                                                                                                               |
| `date_created`       | date-time | The date the variation was created, in the site's timezone. `READ-ONLY`                                                                                                                 |
| `date_modified`      | date-time | The date the variation was last modified, in the site's timezone. `READ-ONLY`                                                                                                           |
| `permalink`          | string    | Variation URL. `READ-ONLY`                                                                                                                                                              |
| `sku`                | string    | Unique identifier.                                                                                                                                                                                                    |
| `price`              | string    | Current variation price. This is set from `regular_price` and `sale_price`. `READ-ONLY`                                                                                              |
| `regular_price`      | string    | Variation regular price.                                                                                                                                                                                              |
| `sale_price`         | string    | Variation sale price.                                                                                                                                                                                                 |
| `date_on_sale_from`  | string    | Start date of sale price. Date in the `YYYY-MM-DD` format.                                                                                                                                                            |
| `date_on_sale_to`    | string    | Start date of sale price. Date in the `YYYY-MM-DD` format.                                                                                                                                                            |
| `on_sale`            | boolean   | Shows if the variation is on sale. `READ-ONLY`                                                                                                                                          |
| `purchasable`        | boolean   | Shows if the variation can be bought. `READ-ONLY`                                                                                                                                       |
| `visible`            | boolean   | If the variation is visible.                                                                                                                                                                                          |
| `virtual`            | boolean   | If the variation is virtual. Virtual variations are intangible and aren't shipped. Default is `false`.                                                                                                                |
| `downloadable`       | boolean   | If the variation is downloadable. Downloadable variations give access to a file upon purchase. Default is `false`.                                                                                                    |
| `downloads`          | array     | List of downloadable files. See [Downloads properties](#download-properties).                                                                                                                                         |
| `download_limit`     | integer   | Amount of times the variation can be downloaded, the `-1` values means **unlimited re-downloads**. Default is `-1`.                                                                                                   |
| `download_expiry`    | integer   | Number of days that the customer has up to be able to download the variation, the `-1` means that **downloads never expires**. Default is `-1`.                                                                       |
| `tax_status`         | string    | Tax status. Default is `taxable`. Options: `taxable`, `shipping` (Shipping only) and `none`.                                                                                                                          |
| `tax_class`          | string    | Tax class.                                                                                                                                                                                                            |
| `manage_stock`       | boolean, string   | Stock management at variation level. Possible values are either a boolean or `parent`. Default is `false`. |
| `stock_quantity`     | integer   | Stock quantity. If is a variable variation this value will be used to control stock for all variations, unless you define stock at variation level.                                                                   |
| `in_stock`           | boolean   | Controls whether or not the variation is listed as "in stock" or "out of stock" on the frontend. Default is `true`.                                                                                                   |
| `backorders`         | string    | If managing stock, this controls if backorders are allowed. If enabled, stock quantity can go below `0`. Default is `no`. Options are: `no` (Do not allow), `notify` (Allow, but notify customer), and `yes` (Allow). |
| `backorders_allowed` | boolean   | Shows if backorders are allowed." `READ-ONLY`                                                                                                                                           |
| `backordered`        | boolean   | Shows if a variation is on backorder (if the variation have the `stock_quantity` negative). `READ-ONLY`                                                                                 |
| `weight`             | string    | Variation weight in decimal format.                                                                                                                                                                                   |
| `dimensions`         | object    | Variation dimensions. See [Dimensions properties](#dimension-properties).                                                                                                                                             |
| `shipping_class`     | string    | Shipping class slug. Shipping classes are used by certain shipping methods to group similar products.                                                                                                                 |
| `shipping_class_id`  | integer   | Shipping class ID. `READ-ONLY`                                                                                                                                                          |
| `image`              | array     | Variation featured image. Only position `0` will be used. See [Images properties](#image-properties).                                                                                                                 |
| `attributes`         | array     | List of variation attributes. See [Variation Attributes properties](#variation-attribute-properties)                                                                                                                  |

### Variation attribute properties
| Attribute | Type    | Description                                             |
|-----------|---------|---------------------------------------------------------|
| `id`      | integer | Attribute ID (required if is a global attribute).       |
| `name`    | string  | Attribute name (required if is a non-global attribute). |
| `option`  | string  | Selected attribute term name.                           |

## Create a product
This API helps you to create a new product.

```http
POST /wp-json/wc/v1/products
```

> Example of how to create a `simple` product:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Premium Quality",
  "type": "simple",
  "regular_price": "21.99",
  "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "categories": [
    {
      "id": 9
    },
    {
      "id": 14
    }
  ],
  "images": [
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
      "position": 0
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
      "position": 1
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Premium Quality",
  type: "simple",
  regular_price: "21.99",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
      position: 0
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
      position: 1
    }
  ]
};

WooCommerce.post("products", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Premium Quality',
    'type' => 'simple',
    'regular_price' => '21.99',
    'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
    'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
    'categories' => [
        [
            'id' => 9
        ],
        [
            'id' => 14
        ]
    ],
    'images' => [
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg',
            'position' => 0
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg',
            'position' => 1
        ]
    ]
];

print_r($woocommerce->post('products', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Premium Quality",
    "type": "simple",
    "regular_price": "21.99",
    "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
    "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
    "categories": [
        {
            "id": 9
        },
        {
            "id": 14
        }
    ],
    "images": [
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
            "position": 0
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
            "position": 1
        }
    ]
}

print(wcapi.post("products", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Premium Quality",
  type: "simple",
  regular_price: "21.99",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
      position: 0
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
      position: 1
    }
  ]
}

woocommerce.post("products", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 162,
  "name": "Premium Quality",
  "slug": "premium-quality-3",
  "permalink": "https://example.com/product/premium-quality-3/",
  "date_created": "2016-05-31T23:40:07",
  "date_modified": "2016-05-31T23:40:07",
  "type": "simple",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "21.99",
  "regular_price": "21.99",
  "sale_price": "",
  "date_on_sale_from": "",
  "date_on_sale_to": "",
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>21,99</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "download_type": "standard",
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 163,
      "date_created": "2016-05-31T23:40:07",
      "date_modified": "2016-05-31T23:40:07",
      "src": "https://example.com/wp-content/uploads/2016/05/T_2_front.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 164,
      "date_created": "2016-05-31T23:40:10",
      "date_modified": "2016-05-31T23:40:10",
      "src": "https://example.com/wp-content/uploads/2016/05/T_2_back.jpg",
      "name": "",
      "alt": "",
      "position": 1
    }
  ],
  "attributes": [],
  "default_attributes": [],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/162"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

> Example of how to create a `variable` product with global and non-global attributes:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Ship Your Idea",
  "type": "variable",
  "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "categories": [
    {
      "id": 9
    },
    {
      "id": 14
    }
  ],
  "images": [
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
      "position": 0
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg",
      "position": 1
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
      "position": 2
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg",
      "position": 3
    }
  ],
  "attributes": [
    {
      "id": 6,
      "position": 0,
      "visible": false,
      "variation": true,
      "options": [
        "Black",
        "Green"
      ]
    },
    {
      "name": "Size",
      "position": 0,
      "visible": true,
      "variation": true,
      "options": [
        "S",
        "M"
      ]
    }
  ],
  "default_attributes": [
    {
      "id": 6,
      "option": "Black"
    },
    {
      "name": "Size",
      "option": "S"
    }
  ],
  "variations": [
    {
      "regular_price": "19.99",
      "image": [
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
          "position": 0
        }
      ],
      "attributes": [
        {
          "id": 6,
          "option": "black"
        },
        {
          "name": "Size",
          "option": "S"
        }
      ]
    },
    {
      "regular_price": "19.99",
      "image": [
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
          "position": 0
        }
      ],
      "attributes": [
        {
          "id": 6,
          "option": "green"
        },
        {
          "name": "Size",
          "option": "M"
        }
      ]
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Ship Your Idea",
  type: "variable",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
      position: 0
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg",
      position: 1
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
      position: 2
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg",
      position: 3
    }
  ],
  attributes: [
    {
      id: 6,
      position: 0,
      visible: true,
      variation: true,
      options: [
        "Black",
        "Green"
      ]
    }
    {
      name: "Size",
      position: 0,
      visible: false,
      variation: true,
      options: [
        "S",
        "M"
      ]
    }
  ],
  default_attributes: [
    {
      id: 6,
      option: "Black"
    },
    {
      name: "Size",
      option: "S"
    }
  ],
  variations: [
    {
      regular_price: "19.99",
      image: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
          position: 0
        }
      ],
      attributes: [
        {
          id: 6,
          option: "black"
        },
        {
          name: "Size",
          option: "S"
        }
      ]
    },
    {
      regular_price: "19.99",
      image: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
          position: 0
        }
      ],
      attributes: [
        {
          id: 6,
          option: "green"
        },
        {
          name: "Size",
          option: "M"
        }
      ]
    }
  ]
};

WooCommerce.post("products", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Ship Your Idea',
    'type' => 'variable',
    'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
    'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
    'categories' => [
        [
            'id' => 9
        ],
        [
            'id' => 14
        ]
    ],
    'images' => [
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg',
            'position' => 0
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg',
            'position' => 1
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg',
            'position' => 2
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg',
            'position' => 3
        ]
    ],
    'attributes' => [
        [
            'id' => 6,
            'position' => 0,
            'visible' => false,
            'variation' => true,
            'options' => [
                'Black',
                'Green'
            ]
        ],
        [
            'name' => 'Size',
            'position' => 0,
            'visible' => true,
            'variation' => true,
            'options' => [
                'S',
                'M'
            ]
        ]
    ],
    'default_attributes' => [
        [
            'id' => 6,
            'option' => 'Black'
        ],
        [
            'name' => 'Size',
            'option' => 'S'
        ]
    ],
    'variations' => [
        [
            'regular_price' => '19.99',
            'image' => [
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg',
                    'position' => 0
                ]
            ],
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'black'
                ],
                [
                    'name' => 'Size',
                    'option' => 'S'
                ]
            ]
        ],
        [
            'regular_price' => '19.99',
            'image' => [
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg',
                    'position' => 0
                ]
            ],
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'green'
                ],
                [
                    'name' => 'Size',
                    'option' => 'M'
                ]
            ]
        ]
    ]
];

print_r($woocommerce->post('products', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Ship Your Idea",
    "type": "variable",
    "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
    "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
    "categories": [
        {
            "id": 9
        },
        {
            "id": 14
        }
    ],
    "images": [
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
            "position": 0
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg",
            "position": 1
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
            "position": 2
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg",
            "position": 3
        }
    ],
    "attributes": [
        {
            "id": 6,
            "position": 0,
            "visible": False,
            "variation": True,
            "options": [
                "Black",
                "Green"
            ]
        },
        {
            "name": "Size",
            "position": 0,
            "visible": True,
            "variation": True,
            "options": [
                "S",
                "M"
            ]
        }
    ],
    "default_attributes": [
        {
            "id": 6,
            "option": "Black"
        },
        {
            "name": "Size",
            "option": "S"
        }
    ],
    "variations": [
        {
            "regular_price": "19.99",
            "image": [
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
                    "position": 0
                }
            ],
            "attributes": [
                {
                    "id": 6,
                    "option": "black"
                },
                {
                    "name": "Size",
                    "option": "S"
                }
            ]
        },
        {
            "regular_price": "19.99",
            "image": [
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
                    "position": 0
                }
            ],
            "attributes": [
                {
                    "id": 6,
                    "option": "green"
                },
                {
                    "name": "Size",
                    "option": "M"
                }
            ]
        }
    ]
}

print(wcapi.post("products", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Ship Your Idea",
  type: "variable",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
      position: 0
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg",
      position: 1
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
      position: 2
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg",
      position: 3
    }
  ],
  attributes: [
    {
      id: 6,
      position: 0,
      visible: false,
      variation: true,
      options: [
        "Black",
        "Green"
      ]
    },
    {
      name: "Size",
      position: 0,
      visible: true,
      variation: true,
      options: [
        "S",
        "M"
      ]
    }
  ],
  default_attributes: [
    {
      id: 6,
      option: "Black"
    },
    {
      name: "Size",
      option: "S"
    }
  ],
  variations: [
    {
      regular_price: "19.99",
      image: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
          position: 0
        }
      ],
      attributes: [
        {
          id: 6,
          option: "black"
        },
        {
          name: "Size",
          option: "S"
        }
      ]
    },
    {
      regular_price: "19.99",
      image: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
          position: 0
        }
      ],
      attributes: [
        {
          id: 6,
          option: "green"
        },
        {
          name: "Size",
          option: "M"
        }
      ]
    }
  ]
}

woocommerce.post("products", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 165,
  "name": "Ship Your Idea",
  "slug": "ship-your-idea-4",
  "permalink": "https://example.com/product/ship-your-idea-4/",
  "date_created": "2016-05-31T23:50:56",
  "date_modified": "2016-06-02T23:11:41",
  "type": "variable",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "19.99",
  "regular_price": "",
  "sale_price": "",
  "date_on_sale_from": "",
  "date_on_sale_to": "",
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>19,99</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "download_type": "standard",
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [
    34,
    37,
    187,
    205,
    31
  ],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 166,
      "date_created": "2016-05-31T23:50:57",
      "date_modified": "2016-05-31T23:50:57",
      "src": "https://example.com/wp-content/uploads/2016/05/T_4_front.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 167,
      "date_created": "2016-05-31T23:50:57",
      "date_modified": "2016-05-31T23:50:57",
      "src": "https://example.com/wp-content/uploads/2016/05/T_4_back.jpg",
      "name": "",
      "alt": "",
      "position": 1
    },
    {
      "id": 168,
      "date_created": "2016-05-31T23:50:58",
      "date_modified": "2016-05-31T23:50:58",
      "src": "https://example.com/wp-content/uploads/2016/05/T_3_front.jpg",
      "name": "",
      "alt": "",
      "position": 2
    },
    {
      "id": 169,
      "date_created": "2016-05-31T23:50:59",
      "date_modified": "2016-05-31T23:50:59",
      "src": "https://example.com/wp-content/uploads/2016/05/T_3_back.jpg",
      "name": "",
      "alt": "",
      "position": 3
    }
  ],
  "attributes": [
    {
      "id": 6,
      "name": "Color",
      "position": 0,
      "visible": false,
      "variation": true,
      "options": [
        "Black",
        "Green"
      ]
    },
    {
      "id": 0,
      "name": "Size",
      "position": 1,
      "visible": true,
      "variation": true,
      "options": [
        "S",
        "M"
      ]
    }
  ],
  "default_attributes": [
    {
      "id": 6,
      "name": "Color",
      "option": "black"
    },
    {
      "id": 0,
      "name": "size",
      "option": "S"
    }
  ],
  "variations": [
    {
      "id": 170,
      "date_created": "2016-05-31T23:50:56",
      "date_modified": "2016-06-02T23:11:41",
      "permalink": "https://example.com/product/ship-your-idea-4/?attribute_pa_color=black&attribute_size=S",
      "sku": "",
      "price": "19.99",
      "regular_price": "19.99",
      "sale_price": "",
      "date_on_sale_from": "",
      "date_on_sale_to": "",
      "on_sale": false,
      "purchasable": true,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_class": "",
      "shipping_class_id": 0,
      "image": [
        {
          "id": 171,
          "date_created": "2016-05-31T23:51:01",
          "date_modified": "2016-05-31T23:51:01",
          "src": "https://example.com/wp-content/uploads/2016/05/T_4_front-1.jpg",
          "name": "",
          "alt": "",
          "position": 0
        }
      ],
      "attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "black"
        },
        {
          "id": 0,
          "name": "size",
          "option": "S"
        }
      ]
    },
    {
      "id": 172,
      "date_created": "2016-05-31T23:50:56",
      "date_modified": "2016-06-02T23:11:41",
      "permalink": "https://example.com/product/ship-your-idea-4/?attribute_pa_color=green&attribute_size=M",
      "sku": "",
      "price": "19.99",
      "regular_price": "19.99",
      "sale_price": "",
      "date_on_sale_from": "",
      "date_on_sale_to": "",
      "on_sale": false,
      "purchasable": true,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_class": "",
      "shipping_class_id": 0,
      "image": [
        {
          "id": 173,
          "date_created": "2016-05-31T23:51:03",
          "date_modified": "2016-05-31T23:51:03",
          "src": "https://example.com/wp-content/uploads/2016/05/T_3_front-1.jpg",
          "name": "",
          "alt": "",
          "position": 0
        }
      ],
      "attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "green"
        },
        {
          "id": 0,
          "name": "size",
          "option": "M"
        }
      ]
    }
  ],
  "grouped_products": [],
  "menu_order": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/165"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product
This API lets you retrieve and view a specific product by ID.

```http
GET /wp-json/wc/v1/products/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/162 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/162")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/162')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/162").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/162").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 162,
  "name": "Premium Quality",
  "slug": "premium-quality-3",
  "permalink": "https://example.com/product/premium-quality-3/",
  "date_created": "2016-05-31T23:40:07",
  "date_modified": "2016-05-31T23:40:07",
  "type": "simple",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "21.99",
  "regular_price": "21.99",
  "sale_price": "",
  "date_on_sale_from": "",
  "date_on_sale_to": "",
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>21,99</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "download_type": "standard",
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 163,
      "date_created": "2016-05-31T23:40:07",
      "date_modified": "2016-05-31T23:40:07",
      "src": "https://example.com/wp-content/uploads/2016/05/T_2_front.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 164,
      "date_created": "2016-05-31T23:40:10",
      "date_modified": "2016-05-31T23:40:10",
      "src": "https://example.com/wp-content/uploads/2016/05/T_2_back.jpg",
      "name": "",
      "alt": "",
      "position": 1
    }
  ],
  "attributes": [],
  "default_attributes": [],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/162"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all products
This API helps you to view all the products.

```http
GET /wp-json/wc/v1/products
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 165,
    "name": "Ship Your Idea",
    "slug": "ship-your-idea-4",
    "permalink": "https://example.com/product/ship-your-idea-4/",
    "date_created": "2016-05-31T23:50:56",
    "date_modified": "2016-06-02T23:11:41",
    "type": "variable",
    "status": "publish",
    "featured": false,
    "catalog_visibility": "visible",
    "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
    "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
    "sku": "",
    "price": "19.99",
    "regular_price": "",
    "sale_price": "",
    "date_on_sale_from": "",
    "date_on_sale_to": "",
    "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>19,99</span>",
    "on_sale": false,
    "purchasable": true,
    "total_sales": 0,
    "virtual": false,
    "downloadable": false,
    "downloads": [],
    "download_limit": -1,
    "download_expiry": -1,
    "download_type": "standard",
    "external_url": "",
    "button_text": "",
    "tax_status": "taxable",
    "tax_class": "",
    "manage_stock": false,
    "stock_quantity": null,
    "in_stock": true,
    "backorders": "no",
    "backorders_allowed": false,
    "backordered": false,
    "sold_individually": false,
    "weight": "",
    "dimensions": {
      "length": "",
      "width": "",
      "height": ""
    },
    "shipping_required": true,
    "shipping_taxable": true,
    "shipping_class": "",
    "shipping_class_id": 0,
    "reviews_allowed": true,
    "average_rating": "0.00",
    "rating_count": 0,
    "related_ids": [
      34,
      37,
      187,
      205,
      31
    ],
    "upsell_ids": [],
    "cross_sell_ids": [],
    "parent_id": 0,
    "purchase_note": "",
    "categories": [
      {
        "id": 9,
        "name": "Clothing",
        "slug": "clothing"
      },
      {
        "id": 14,
        "name": "T-shirts",
        "slug": "t-shirts"
      }
    ],
    "tags": [],
    "images": [
      {
        "id": 166,
        "date_created": "2016-05-31T23:50:57",
        "date_modified": "2016-05-31T23:50:57",
        "src": "https://example.com/wp-content/uploads/2016/05/T_4_front.jpg",
        "name": "",
        "alt": "",
        "position": 0
      },
      {
        "id": 167,
        "date_created": "2016-05-31T23:50:57",
        "date_modified": "2016-05-31T23:50:57",
        "src": "https://example.com/wp-content/uploads/2016/05/T_4_back.jpg",
        "name": "",
        "alt": "",
        "position": 1
      },
      {
        "id": 168,
        "date_created": "2016-05-31T23:50:58",
        "date_modified": "2016-05-31T23:50:58",
        "src": "https://example.com/wp-content/uploads/2016/05/T_3_front.jpg",
        "name": "",
        "alt": "",
        "position": 2
      },
      {
        "id": 169,
        "date_created": "2016-05-31T23:50:59",
        "date_modified": "2016-05-31T23:50:59",
        "src": "https://example.com/wp-content/uploads/2016/05/T_3_back.jpg",
        "name": "",
        "alt": "",
        "position": 3
      }
    ],
    "attributes": [
      {
        "id": 6,
        "name": "Color",
        "position": 0,
        "visible": false,
        "variation": true,
        "options": [
          "Black",
          "Green"
        ]
      },
      {
        "id": 0,
        "name": "Size",
        "position": 1,
        "visible": true,
        "variation": true,
        "options": [
          "S",
          "M"
        ]
      }
    ],
    "default_attributes": [
      {
        "id": 6,
        "name": "Color",
        "option": "black"
      },
      {
        "id": 0,
        "name": "size",
        "option": "S"
      }
    ],
    "variations": [
      {
        "id": 170,
        "date_created": "2016-05-31T23:50:56",
        "date_modified": "2016-06-02T23:11:41",
        "permalink": "https://example.com/product/ship-your-idea-4/?attribute_pa_color=black&attribute_size=S",
        "sku": "",
        "price": "19.99",
        "regular_price": "19.99",
        "sale_price": "",
        "date_on_sale_from": "",
        "date_on_sale_to": "",
        "on_sale": false,
        "purchasable": true,
        "virtual": false,
        "downloadable": false,
        "downloads": [],
        "download_limit": -1,
        "download_expiry": -1,
        "tax_status": "taxable",
        "tax_class": "",
        "manage_stock": false,
        "stock_quantity": null,
        "in_stock": true,
        "backorders": "no",
        "backorders_allowed": false,
        "backordered": false,
        "weight": "",
        "dimensions": {
          "length": "",
          "width": "",
          "height": ""
        },
        "shipping_class": "",
        "shipping_class_id": 0,
        "image": [
          {
            "id": 171,
            "date_created": "2016-05-31T23:51:01",
            "date_modified": "2016-05-31T23:51:01",
            "src": "https://example.com/wp-content/uploads/2016/05/T_4_front-1.jpg",
            "name": "",
            "alt": "",
            "position": 0
          }
        ],
        "attributes": [
          {
            "id": 6,
            "name": "Color",
            "option": "black"
          },
          {
            "id": 0,
            "name": "size",
            "option": "S"
          }
        ]
      },
      {
        "id": 172,
        "date_created": "2016-05-31T23:50:56",
        "date_modified": "2016-06-02T23:11:41",
        "permalink": "https://example.com/product/ship-your-idea-4/?attribute_pa_color=green&attribute_size=M",
        "sku": "",
        "price": "19.99",
        "regular_price": "19.99",
        "sale_price": "",
        "date_on_sale_from": "",
        "date_on_sale_to": "",
        "on_sale": false,
        "purchasable": true,
        "virtual": false,
        "downloadable": false,
        "downloads": [],
        "download_limit": -1,
        "download_expiry": -1,
        "tax_status": "taxable",
        "tax_class": "",
        "manage_stock": false,
        "stock_quantity": null,
        "in_stock": true,
        "backorders": "no",
        "backorders_allowed": false,
        "backordered": false,
        "weight": "",
        "dimensions": {
          "length": "",
          "width": "",
          "height": ""
        },
        "shipping_class": "",
        "shipping_class_id": 0,
        "image": [
          {
            "id": 173,
            "date_created": "2016-05-31T23:51:03",
            "date_modified": "2016-05-31T23:51:03",
            "src": "https://example.com/wp-content/uploads/2016/05/T_3_front-1.jpg",
            "name": "",
            "alt": "",
            "position": 0
          }
        ],
        "attributes": [
          {
            "id": 6,
            "name": "Color",
            "option": "green"
          },
          {
            "id": 0,
            "name": "size",
            "option": "M"
          }
        ]
      }
    ],
    "grouped_products": [],
    "menu_order": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/165"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products"
        }
      ]
    }
  },
  {
    "id": 162,
    "name": "Premium Quality",
    "slug": "premium-quality-3",
    "permalink": "https://example.com/product/premium-quality-3/",
    "date_created": "2016-05-31T23:40:07",
    "date_modified": "2016-05-31T23:40:07",
    "type": "simple",
    "status": "publish",
    "featured": false,
    "catalog_visibility": "visible",
    "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
    "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
    "sku": "",
    "price": "21.99",
    "regular_price": "21.99",
    "sale_price": "",
    "date_on_sale_from": "",
    "date_on_sale_to": "",
    "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>21,99</span>",
    "on_sale": false,
    "purchasable": true,
    "total_sales": 0,
    "virtual": false,
    "downloadable": false,
    "downloads": [],
    "download_limit": -1,
    "download_expiry": -1,
    "download_type": "standard",
    "external_url": "",
    "button_text": "",
    "tax_status": "taxable",
    "tax_class": "",
    "manage_stock": false,
    "stock_quantity": null,
    "in_stock": true,
    "backorders": "no",
    "backorders_allowed": false,
    "backordered": false,
    "sold_individually": false,
    "weight": "",
    "dimensions": {
      "length": "",
      "width": "",
      "height": ""
    },
    "shipping_required": true,
    "shipping_taxable": true,
    "shipping_class": "",
    "shipping_class_id": 0,
    "reviews_allowed": true,
    "average_rating": "0.00",
    "rating_count": 0,
    "related_ids": [],
    "upsell_ids": [],
    "cross_sell_ids": [],
    "parent_id": 0,
    "purchase_note": "",
    "categories": [
      {
        "id": 9,
        "name": "Clothing",
        "slug": "clothing"
      },
      {
        "id": 14,
        "name": "T-shirts",
        "slug": "t-shirts"
      }
    ],
    "tags": [],
    "images": [
      {
        "id": 163,
        "date_created": "2016-05-31T23:40:07",
        "date_modified": "2016-05-31T23:40:07",
        "src": "https://example.com/wp-content/uploads/2016/05/T_2_front.jpg",
        "name": "",
        "alt": "",
        "position": 0
      },
      {
        "id": 164,
        "date_created": "2016-05-31T23:40:10",
        "date_modified": "2016-05-31T23:40:10",
        "src": "https://example.com/wp-content/uploads/2016/05/T_2_back.jpg",
        "name": "",
        "alt": "",
        "position": 1
      }
    ],
    "attributes": [],
    "default_attributes": [],
    "variations": [],
    "grouped_products": [],
    "menu_order": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/162"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter        | Type    | Description                                                                                                                                     |
|------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `context`        | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                       |
| `page`           | integer | Current page of the collection.                                                                                                                 |
| `per_page`       | integer | Maximum number of items to be returned in result set.                                                                                           |
| `search`         | string  | Limit results to those matching a string.                                                                                                       |
| `after`          | string  | Limit response to resources published after a given ISO8601 compliant date.                                                                     |
| `before`         | string  | Limit response to resources published before a given ISO8601 compliant date.                                                                    |
| `dates_are_gmt`  | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                                        |
| `exclude`        | string  | Ensure result set excludes specific ids.                                                                                                        |
| `include`        | string  | Limit result set to specific ids.                                                                                                               |
| `offset`         | integer | Offset the result set by a specific number of items.                                                                                            |
| `order`          | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                                      |
| `orderby`        | string  | Sort collection by object attribute. Default is `date`, Options: `date`, `id`, `include`, `title` and `slug`.                                   |
| `slug`           | string  | Limit result set to products with a specific slug.                                                                                              |
| `status`         | string  | Limit result set to products assigned a specific status. Default is `any`. Options: `any`, `draft`, `pending`, `private` and `publish`.         |
| `customer`       | string  | Limit result set to orders assigned a specific customer.                                                                                        |
| `category`       | string  | Limit result set to products assigned a specific category, e.g. `?category=9,14`.                                                               |
| `tag`            | string  | Limit result set to products assigned a specific tag, e.g. `?tag=9,14`.                                                                         |
| `shipping_class` | string  | Limit result set to products assigned a specific shipping class, e.g. `?shipping_class=9,14`.                                                   |
| `attribute`      | string  | Limit result set to products with a specific attribute, e.g. `?attribute=pa_color`.                                                             |
| `attribute_term` | string  | Limit result set to products with a specific attribute term (required an assigned `attribute`), e.g. `?attribute=pa_color&attribute_term=9,14`. |
| `sku`            | string  | Limit result set to products with a specific SKU.                                                                                               |

## Update a product
This API lets you make changes to a product.

```http
PUT /wp-json/wc/v1/products/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/products/162 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "24.54"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  regular_price: "24.54"
};

WooCommerce.put("products/162", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'regular_price' => '24.54'
];

print_r($woocommerce->put('products/162', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "regular_price": "24.54"
}

print(wcapi.put("products/162", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  regular_price: "24.54"
}

woocommerce.put("products/162", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 162,
  "name": "Premium Quality",
  "slug": "premium-quality-3",
  "permalink": "https://example.com/product/premium-quality-3/",
  "date_created": "2016-05-31T23:40:07",
  "date_modified": "2016-05-31T23:40:07",
  "type": "simple",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "24.54",
  "regular_price": "24.54",
  "sale_price": "",
  "date_on_sale_from": "",
  "date_on_sale_to": "",
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>24,54</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "download_type": "standard",
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 163,
      "date_created": "2016-05-31T23:40:07",
      "date_modified": "2016-05-31T23:40:07",
      "src": "https://example.com/wp-content/uploads/2016/05/T_2_front.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 164,
      "date_created": "2016-05-31T23:40:10",
      "date_modified": "2016-05-31T23:40:10",
      "src": "https://example.com/wp-content/uploads/2016/05/T_2_back.jpg",
      "name": "",
      "alt": "",
      "position": 1
    }
  ],
  "attributes": [],
  "default_attributes": [],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/162"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product
This API helps you delete a product.

```http
DELETE /wp-json/wc/v1/products/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/products/162?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/162", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/162', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/162", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/162", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 162,
  "name": "Premium Quality",
  "slug": "premium-quality-3",
  "permalink": "https://example.com/product/premium-quality-3/",
  "date_created": "2016-05-31T23:40:07",
  "date_modified": "2016-05-31T23:40:07",
  "type": "simple",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "24.54",
  "regular_price": "24.54",
  "sale_price": "",
  "date_on_sale_from": "",
  "date_on_sale_to": "",
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>24,54</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "download_type": "standard",
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 163,
      "date_created": "2016-05-31T23:40:07",
      "date_modified": "2016-05-31T23:40:07",
      "src": "https://example.com/wp-content/uploads/2016/05/T_2_front.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 164,
      "date_created": "2016-05-31T23:40:10",
      "date_modified": "2016-05-31T23:40:10",
      "src": "https://example.com/wp-content/uploads/2016/05/T_2_back.jpg",
      "name": "",
      "alt": "",
      "position": 1
    }
  ],
  "attributes": [],
  "default_attributes": [],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/162"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter | Type   | Description                                                               |
|-----------|--------|---------------------------------------------------------------------------|
| `force`   | string | Use `true` whether to permanently delete the product, Default is `false`. |

## Batch update products
This API helps you to batch create, update and delete multiple products.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/products/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/products/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Woo Single #1",
      "type": "simple",
      "regular_price": "21.99",
      "virtual": true,
      "downloadable": true,
      "downloads": [
        {
          "name": "Woo Single",
          "file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      "categories": [
        {
          "id": 11
        },
        {
          "id": 13
        }
      ],
      "images": [
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg",
          "position": 0
        }
      ]
    },
    {
      "name": "New Premium Quality",
      "type": "simple",
      "regular_price": "21.99",
      "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      "categories": [
        {
          "id": 9
        },
        {
          "id": 14
        }
      ],
      "images": [
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
          "position": 0
        },
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
          "position": 1
        }
      ]
    }
  ],
  "update": [
    {
      "id": 165,
      "variations": [
        {
          "id": 170,
          "regular_price": "29.99"
        },
        {
          "id": 172,
          "regular_price": "29.99"
        }
      ]
    }
  ],
  "delete": [
    162
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Woo Single #1",
      type: "simple",
      regular_price: "21.99",
      virtual: true,
      downloadable: true,
      downloads: [
        {
          name: "Woo Single",
          file: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      categories: [
        {
          id: 11
        },
        {
          id: 13
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg",
          position: 0
        }
      ]
    },
    {
      name: "New Premium Quality",
      type: "simple",
      regular_price: "21.99",
      description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      categories: [
        {
          id: 9
        },
        {
          id: 14
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
          position: 0
        },
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
          position: 1
        }
      ]
    }
  ],
  update: [
    {
      id: 165,
      variations: [
        {
          id: 170,
          regular_price: "29.99"
        },
        {
          id: 172,
          regular_price: "29.99"
        }
      ]
    }
  ],
  delete: [
    162
  ]
};

WooCommerce.post("products/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Woo Single #1',
            'type' => 'simple',
            'regular_price' => '21.99',
            'virtual' => true,
            'downloadable' => true,
            'downloads' => [
                [
                    'name' => 'Woo Single',
                    'file' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg'
                ]
            ],
            'categories' => [
                [
                    'id' => 11
                ],
                [
                    'id' => 13
                ]
            ],
            'images' => [
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg',
                    'position' => 0
                ]
            ]
        ],
        [
            'name' => 'New Premium Quality',
            'type' => 'simple',
            'regular_price' => '21.99',
            'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
            'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
            'categories' => [
                [
                    'id' => 9
                ],
                [
                    'id' => 14
                ]
            ],
            'images' => [
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg',
                    'position' => 0
                ],
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg',
                    'position' => 1
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 165,
            'variations' => [
                [
                    'id' => 170,
                    'regular_price' => '29.99'
                ],
                [
                    'id' => 172,
                    'regular_price' => '29.99'
                ]
            ]
        ]
    ],
    'delete' => [
        162
    ]
];

print_r($woocommerce->post('products/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Woo Single #1",
            "type": "simple",
            "regular_price": "21.99",
            "virtual": True,
            "downloadable": True,
            "downloads": [
                {
                    "name": "Woo Single",
                    "file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
                }
            ],
            "categories": [
                {
                    "id": 11
                },
                {
                    "id": 13
                }
            ],
            "images": [
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg",
                    "position": 0
                }
            ]
        },
        {
            "name": "New Premium Quality",
            "type": "simple",
            "regular_price": "21.99",
            "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
            "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
            "categories": [
                {
                    "id": 9
                },
                {
                    "id": 14
                }
            ],
            "images": [
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
                    "position": 0
                },
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
                    "position": 1
                }
            ]
        }
    ],
    "update": [
        {
            "id": 165,
            "variations": [
                {
                    "id": 170,
                    "regular_price": "29.99"
                },
                {
                    "id": 172,
                    "regular_price": "29.99"
                }
            ]
        }
    ],
    "delete": [
        162
    ]
}

print(wcapi.post("products/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Woo Single #1",
      type: "simple",
      regular_price: "21.99",
      virtual: true,
      downloadable: true,
      downloads: [
        {
          name: "Woo Single",
          file: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      categories: [
        {
          id: 11
        },
        {
          id: 13
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg",
          position: 0
        }
      ]
    },
    {
      name: "New Premium Quality",
      type: "simple",
      regular_price: "21.99",
      description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      categories: [
        {
          id: 9
        },
        {
          id: 14
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
          position: 0
        },
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
          position: 1
        }
      ]
    }
  ],
  update: [
    {
      id: 165,
      variations: [
        {
          id: 170,
          regular_price: "29.99"
        },
        {
          id: 172,
          regular_price: "29.99"
        }
      ]
    }
  ],
  delete: [
    162
  ]
}

woocommerce.post("products/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 174,
      "name": "Woo Single #1",
      "slug": "woo-single-1-2",
      "permalink": "https://example.com/product/woo-single-1-2/",
      "date_created": "2016-06-01T00:21:30",
      "date_modified": "2016-06-01T00:21:30",
      "type": "simple",
      "status": "publish",
      "featured": false,
      "catalog_visibility": "visible",
      "description": "",
      "short_description": "",
      "sku": "",
      "price": "21.99",
      "regular_price": "21.99",
      "sale_price": "",
      "date_on_sale_from": "",
      "date_on_sale_to": "",
      "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>21,99</span>",
      "on_sale": false,
      "purchasable": true,
      "total_sales": 0,
      "virtual": true,
      "downloadable": true,
      "downloads": [
        {
          "id": "7b5a304f737cfa35dc527c9e790399bf",
          "name": "Woo Single",
          "file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      "download_limit": -1,
      "download_expiry": -1,
      "download_type": "standard",
      "external_url": "",
      "button_text": "",
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "sold_individually": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_required": false,
      "shipping_taxable": true,
      "shipping_class": "",
      "shipping_class_id": 0,
      "reviews_allowed": true,
      "average_rating": "0.00",
      "rating_count": 0,
      "related_ids": [],
      "upsell_ids": [],
      "cross_sell_ids": [],
      "parent_id": 0,
      "purchase_note": "",
      "categories": [
        {
          "id": 11,
          "name": "Music",
          "slug": "music"
        },
        {
          "id": 13,
          "name": "Singles",
          "slug": "singles"
        }
      ],
      "tags": [],
      "images": [
        {
          "id": 175,
          "date_created": "2016-06-01T00:21:31",
          "date_modified": "2016-06-01T00:21:31",
          "src": "https://example.com/wp-content/uploads/2016/05/cd_4_angle.jpg",
          "name": "",
          "alt": "",
          "position": 0
        }
      ],
      "attributes": [],
      "default_attributes": [],
      "variations": [],
      "grouped_products": [],
      "menu_order": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/174"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products"
          }
        ]
      }
    },
    {
      "id": 176,
      "name": "New Premium Quality",
      "slug": "new-premium-quality",
      "permalink": "https://example.com/product/new-premium-quality/",
      "date_created": "2016-06-01T00:21:33",
      "date_modified": "2016-06-01T00:21:33",
      "type": "simple",
      "status": "publish",
      "featured": false,
      "catalog_visibility": "visible",
      "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
      "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
      "sku": "",
      "price": "21.99",
      "regular_price": "21.99",
      "sale_price": "",
      "date_on_sale_from": "",
      "date_on_sale_to": "",
      "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>21,99</span>",
      "on_sale": false,
      "purchasable": true,
      "total_sales": 0,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "download_type": "standard",
      "external_url": "",
      "button_text": "",
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "sold_individually": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_required": true,
      "shipping_taxable": true,
      "shipping_class": "",
      "shipping_class_id": 0,
      "reviews_allowed": true,
      "average_rating": "0.00",
      "rating_count": 0,
      "related_ids": [],
      "upsell_ids": [],
      "cross_sell_ids": [],
      "parent_id": 0,
      "purchase_note": "",
      "categories": [
        {
          "id": 9,
          "name": "Clothing",
          "slug": "clothing"
        },
        {
          "id": 14,
          "name": "T-shirts",
          "slug": "t-shirts"
        }
      ],
      "tags": [],
      "images": [
        {
          "id": 177,
          "date_created": "2016-06-01T00:21:33",
          "date_modified": "2016-06-01T00:21:33",
          "src": "https://example.com/wp-content/uploads/2016/05/T_2_front-1.jpg",
          "name": "",
          "alt": "",
          "position": 0
        },
        {
          "id": 178,
          "date_created": "2016-06-01T00:21:34",
          "date_modified": "2016-06-01T00:21:34",
          "src": "https://example.com/wp-content/uploads/2016/05/T_2_back-1.jpg",
          "name": "",
          "alt": "",
          "position": 1
        }
      ],
      "attributes": [],
      "default_attributes": [],
      "variations": [],
      "grouped_products": [],
      "menu_order": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/176"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 165,
      "name": "Ship Your Idea",
      "slug": "ship-your-idea-4",
      "permalink": "https://example.com/product/ship-your-idea-4/",
      "date_created": "2016-05-31T23:50:56",
      "date_modified": "2016-06-02T23:11:41",
      "type": "variable",
      "status": "publish",
      "featured": false,
      "catalog_visibility": "visible",
      "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
      "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
      "sku": "",
      "price": "29.99",
      "regular_price": "",
      "sale_price": "",
      "date_on_sale_from": "",
      "date_on_sale_to": "",
      "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>29,99</span>",
      "on_sale": false,
      "purchasable": true,
      "total_sales": 0,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "download_type": "standard",
      "external_url": "",
      "button_text": "",
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "sold_individually": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_required": true,
      "shipping_taxable": true,
      "shipping_class": "",
      "shipping_class_id": 0,
      "reviews_allowed": true,
      "average_rating": "0.00",
      "rating_count": 0,
      "related_ids": [
        34,
        37,
        187,
        205,
        31
      ],
      "upsell_ids": [],
      "cross_sell_ids": [],
      "parent_id": 0,
      "purchase_note": "",
      "categories": [
        {
          "id": 9,
          "name": "Clothing",
          "slug": "clothing"
        },
        {
          "id": 14,
          "name": "T-shirts",
          "slug": "t-shirts"
        }
      ],
      "tags": [],
      "images": [
        {
          "id": 166,
          "date_created": "2016-05-31T23:50:57",
          "date_modified": "2016-05-31T23:50:57",
          "src": "https://example.com/wp-content/uploads/2016/05/T_4_front.jpg",
          "name": "",
          "alt": "",
          "position": 0
        },
        {
          "id": 167,
          "date_created": "2016-05-31T23:50:57",
          "date_modified": "2016-05-31T23:50:57",
          "src": "https://example.com/wp-content/uploads/2016/05/T_4_back.jpg",
          "name": "",
          "alt": "",
          "position": 1
        },
        {
          "id": 168,
          "date_created": "2016-05-31T23:50:58",
          "date_modified": "2016-05-31T23:50:58",
          "src": "https://example.com/wp-content/uploads/2016/05/T_3_front.jpg",
          "name": "",
          "alt": "",
          "position": 2
        },
        {
          "id": 169,
          "date_created": "2016-05-31T23:50:59",
          "date_modified": "2016-05-31T23:50:59",
          "src": "https://example.com/wp-content/uploads/2016/05/T_3_back.jpg",
          "name": "",
          "alt": "",
          "position": 3
        }
      ],
      "attributes": [
        {
          "id": 6,
          "name": "Color",
          "position": 0,
          "visible": false,
          "variation": true,
          "options": [
            "Black",
            "Green"
          ]
        },
        {
          "id": 0,
          "name": "Size",
          "position": 1,
          "visible": true,
          "variation": true,
          "options": [
            "S",
            "M"
          ]
        }
      ],
      "default_attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "black"
        },
        {
          "id": 0,
          "name": "size",
          "option": "S"
        }
      ],
      "variations": [
        {
          "id": 170,
          "date_created": "2016-05-31T23:50:56",
          "date_modified": "2016-06-02T23:11:41",
          "permalink": "https://example.com/product/ship-your-idea-4/?attribute_pa_color=black&attribute_size=S",
          "sku": "",
          "price": "29.99",
          "regular_price": "29.99",
          "sale_price": "",
          "date_on_sale_from": "",
          "date_on_sale_to": "",
          "on_sale": false,
          "purchasable": true,
          "virtual": false,
          "downloadable": false,
          "downloads": [],
          "download_limit": -1,
          "download_expiry": -1,
          "tax_status": "taxable",
          "tax_class": "",
          "manage_stock": false,
          "stock_quantity": null,
          "in_stock": true,
          "backorders": "no",
          "backorders_allowed": false,
          "backordered": false,
          "weight": "",
          "dimensions": {
            "length": "",
            "width": "",
            "height": ""
          },
          "shipping_class": "",
          "shipping_class_id": 0,
          "image": [
            {
              "id": 171,
              "date_created": "2016-05-31T23:51:01",
              "date_modified": "2016-05-31T23:51:01",
              "src": "https://example.com/wp-content/uploads/2016/05/T_4_front-1.jpg",
              "name": "",
              "alt": "",
              "position": 0
            }
          ],
          "attributes": [
            {
              "id": 6,
              "name": "Color",
              "option": "black"
            },
            {
              "id": 0,
              "name": "size",
              "option": "S"
            }
          ]
        },
        {
          "id": 172,
          "date_created": "2016-05-31T23:50:56",
          "date_modified": "2016-06-02T23:11:41",
          "permalink": "https://example.com/product/ship-your-idea-4/?attribute_pa_color=green&attribute_size=M",
          "sku": "",
          "price": "29.99",
          "regular_price": "29.99",
          "sale_price": "",
          "date_on_sale_from": "",
          "date_on_sale_to": "",
          "on_sale": false,
          "purchasable": true,
          "virtual": false,
          "downloadable": false,
          "downloads": [],
          "download_limit": -1,
          "download_expiry": -1,
          "tax_status": "taxable",
          "tax_class": "",
          "manage_stock": false,
          "stock_quantity": null,
          "in_stock": true,
          "backorders": "no",
          "backorders_allowed": false,
          "backordered": false,
          "weight": "",
          "dimensions": {
            "length": "",
            "width": "",
            "height": ""
          },
          "shipping_class": "",
          "shipping_class_id": 0,
          "image": [
            {
              "id": 173,
              "date_created": "2016-05-31T23:51:03",
              "date_modified": "2016-05-31T23:51:03",
              "src": "https://example.com/wp-content/uploads/2016/05/T_3_front-1.jpg",
              "name": "",
              "alt": "",
              "position": 0
            }
          ],
          "attributes": [
            {
              "id": 6,
              "name": "Color",
              "option": "green"
            },
            {
              "id": 0,
              "name": "size",
              "option": "M"
            }
          ]
        }
      ],
      "grouped_products": [],
      "menu_order": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/165"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 162,
      "name": "Premium Quality",
      "slug": "premium-quality-3",
      "permalink": "https://example.com/product/premium-quality-3/",
      "date_created": "2016-05-31T23:40:07",
      "date_modified": "2016-06-01T00:13:45",
      "type": "simple",
      "status": "publish",
      "featured": false,
      "catalog_visibility": "visible",
      "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
      "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
      "sku": "",
      "price": "24.54",
      "regular_price": "24.54",
      "sale_price": "",
      "date_on_sale_from": "",
      "date_on_sale_to": "",
      "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#82;&#36;</span>24,54</span>",
      "on_sale": false,
      "purchasable": true,
      "total_sales": 0,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "download_type": "standard",
      "external_url": "",
      "button_text": "",
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "sold_individually": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_required": true,
      "shipping_taxable": true,
      "shipping_class": "",
      "shipping_class_id": 0,
      "reviews_allowed": true,
      "average_rating": "0.00",
      "rating_count": 0,
      "related_ids": [],
      "upsell_ids": [],
      "cross_sell_ids": [],
      "parent_id": 0,
      "purchase_note": "",
      "categories": [
        {
          "id": 9,
          "name": "Clothing",
          "slug": "clothing"
        },
        {
          "id": 14,
          "name": "T-shirts",
          "slug": "t-shirts"
        }
      ],
      "tags": [],
      "images": [
        {
          "id": 163,
          "date_created": "2016-05-31T23:40:07",
          "date_modified": "2016-05-31T23:40:07",
          "src": "https://example.com/wp-content/uploads/2016/05/T_2_front.jpg",
          "name": "",
          "alt": "",
          "position": 0
        },
        {
          "id": 164,
          "date_created": "2016-05-31T23:40:10",
          "date_modified": "2016-05-31T23:40:10",
          "src": "https://example.com/wp-content/uploads/2016/05/T_2_back.jpg",
          "name": "",
          "alt": "",
          "position": 1
        }
      ],
      "attributes": [],
      "default_attributes": [],
      "variations": [],
      "grouped_products": [],
      "menu_order": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/products/162"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/products"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>

## Retrieve product reviews
This API lets you retrieve and view a specific product review by ID.

```http
GET /wp-json/wc/v1/products/<product_id>/reviews/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/162/reviews/9 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/162/reviews/9")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/162')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/162/reviews/9").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/162/reviews/9").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "date_created": "2015-05-07T13:01:25",
  "review": "This will go great with my Hoodie that I ordered a few weeks ago.",
  "rating": 5,
  "name": "Stuart",
  "email": "stuart@example.com",
  "verified": false,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/162/reviews/9"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/162/reviews"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v1/products/162"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

### Product review properties
| Attribute      | Type    | Description                                                                                        |
|----------------|---------|----------------------------------------------------------------------------------------------------|
| `id`           | integer | Unique identifier for the resource. `READ-ONLY`                      |
| `date_created` | string  | The date the review was created, in the site's timezone. `READ-ONLY` |
| `rating`       | integer | Review rating (0 to 5). `READ-ONLY`                                  |
| `name`         | string  | Reviewer name. `READ-ONLY`                                           |
| `email`        | string  | Reviewer email. `READ-ONLY`                                          |
| `verified`     | boolean | Shows if the reviewer bought the product or not. `READ-ONLY`         |

## List all product reviews
This API lets you retrieve all reviews of a product.

```http
GET /wp-json/wc/v1/products/<product_id>/reviews
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/products/162/reviews \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/162/reviews")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/162/reviews')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/162/reviews").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/162/reviews").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 9,
    "date_created": "2015-05-07T13:01:25",
    "review": "This will go great with my Hoodie that I ordered a few weeks ago.",
    "rating": 5,
    "name": "Stuart",
    "email": "stuart@example.com",
    "verified": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/162/reviews/9"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/162/reviews"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/162"
        }
      ]
    }
  },
  {
    "id": 10,
    "date_created": "2015-05-07T15:49:53",
    "review": "Love this shirt! The ninja near and dear to my heart. &lt;3",
    "rating": 5,
    "name": "Maria",
    "email": "maria@example.com",
    "verified": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/162/reviews/10"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/162/reviews"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/162"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>


---

## Reports

*Source: apis/rest-api/v1/reports.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Reports
The reports API allows you to view all types of reports available.

## List all reports
This API lets you retrieve and view a simple list of available reports.

```http
GET /wp-json/wc/v1/reports
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/reports \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("reports")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('reports')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("reports").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "slug": "sales",
    "description": "List of sales reports.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/reports/sales"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/reports"
        }
      ]
    }
  },
  {
    "slug": "top_sellers",
    "description": "List of top sellers products.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/reports/top_sellers"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/reports"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Retrieve sales report
This API lets you retrieve and view a sales report.

```http
GET /wp-json/wc/v1/reports/sales
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/reports/sales?date_min=2016-05-03&date_max=2016-05-04 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("reports/sales", {
  date_min: "2016-05-03",
  date_max: "2016-05-04"
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$query = [
    'date_min' => '2016-05-03', 
    'date_max' => '2016-05-04'
];

print_r($woocommerce->get('reports/sales', $query));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/sales?date_min=2016-05-03&date_max=2016-05-04").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
query = {
  date_min: "2016-05-03",
  date_max: "2016-05-04"
}

woocommerce.get("reports/sales", query).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "total_sales": "14.00",
    "net_sales": "4.00",
    "average_sales": "2.00",
    "total_orders": 3,
    "total_items": 6,
    "total_tax": "0.00",
    "total_shipping": "10.00",
    "total_refunds": 0,
    "total_discount": "0.00",
    "totals_grouped_by": "day",
    "totals": {
      "2016-05-03": {
        "sales": "14.00",
        "orders": 3,
        "items": 6,
        "tax": "0.00",
        "shipping": "10.00",
        "discount": "0.00",
        "customers": 0
      },
      "2016-05-04": {
        "sales": "0.00",
        "orders": 0,
        "items": 0,
        "tax": "0.00",
        "shipping": "0.00",
        "discount": "0.00",
        "customers": 0
      }
    },
    "total_customers": 0,
    "_links": {
      "about": [
        {
          "href": "https://example.com/wp-json/wc/v1/reports"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Sales report properties
|      Attribute      |   Type  |                              Description                              |
|---------------------|---------|-----------------------------------------------------------------------|
| `total_sales`       | string  | Gross sales in the period. `READ-ONLY`  |
| `net_sales`         | string  | Net sales in the period. `READ-ONLY`    |
| `average_sales`     | string  | Average net daily sales. `READ-ONLY`    |
| `total_orders`      | integer | Total of orders placed. `READ-ONLY`     |
| `total_items`       | integer | Total of items purchased. `READ-ONLY`   |
| `total_tax`         | string  | Total charged for taxes. `READ-ONLY`    |
| `total_shipping`    | string  | Total charged for shipping. `READ-ONLY` |
| `total_refunds`     | number  | Total of refunded orders. `READ-ONLY`   |
| `total_discount`    | integer | Total of coupons used. `READ-ONLY`      |
| `totals_grouped_by` | string  | Group type. `READ-ONLY`                 |
| `totals`            | array   | Totals. `READ-ONLY`                     |

#### Available parameters
| Parameter  |  Type  |                                                    Description                                                    |
|------------|--------|-------------------------------------------------------------------------------------------------------------------|
| `context`  | string | Scope under which the request is made; determines fields present in response. Default is `view`. Options: `view`. |
| `period`   | string | Report period. Default is today's date. Options: `week`, `month`, `last_month` and `year`                         |
| `date_min` | string | Return sales for a specific start date, the date need to be in the YYYY-MM-DD format.                             |
| `date_max` | string | Return sales for a specific end date, the date need to be in the YYYY-MM-DD format.                               |

## Retrieve top sellers report
This API lets you retrieve and view a list of top sellers report.

```http
GET /wp-json/wc/v1/reports/top_sellers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/reports/top_sellers?period=last_month \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("reports/top_sellers", {
  period: "last_month",
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$query = [
    'period' => 'last_month'
];

print_r($woocommerce->get('reports/top_sellers', $query));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/top_sellers?period=last_month").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
query = {
  period: "last_month"
}

woocommerce.get("reports/top_sellers", query).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "title": "Happy Ninja",
    "product_id": 37,
    "quantity": 1,
    "_links": {
      "about": [
        {
          "href": "https://example.com/wp-json/wc/v1/reports"
        }
      ],
      "product": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/37"
        }
      ]
    }
  },
  {
    "title": "Woo Album #4",
    "product_id": 96,
    "quantity": 1,
    "_links": {
      "about": [
        {
          "href": "https://example.com/wp-json/wc/v1/reports"
        }
      ],
      "product": [
        {
          "href": "https://example.com/wp-json/wc/v1/products/96"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Top sellers report properties
|      Attribute      |   Type  |                              Description                              |
|---------------------|---------|-----------------------------------------------------------------------|
| `title`             | string  | Product title. `READ-ONLY`              |
| `product_id`        | integer | Product ID. `READ-ONLY`                 |
| `quantity`          | integer | Total number of purchases. `READ-ONLY`  |

#### Available parameters
| Parameter  |  Type  |                                                    Description                                                    |
|------------|--------|-------------------------------------------------------------------------------------------------------------------|
| `context`  | string | Scope under which the request is made; determines fields present in response. Default is `view`. Options: `view`. |
| `period`   | string | Report period. Default is `week`. Options: `week`, `month`, `last_month` and `year`                               |
| `date_min` | string | Return sales for a specific start date, the date need to be in the YYYY-MM-DD format.                             |
| `date_max` | string | Return sales for a specific end date, the date need to be in the YYYY-MM-DD format.                               |


---

## Tax classes

*Source: apis/rest-api/v1/tax-classes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Tax classes
The tax classes API allows you to create, view, and delete individual tax classes.

## Tax class properties
| Attribute |  Type  |                                  Description                                  |
|-----------|--------|-------------------------------------------------------------------------------|
| `slug`    | string | Unique identifier for the resource. `READ-ONLY` |
| `name`    | string | Tax class name. `REQUIRED`                      |

## Create a tax class
This API helps you to create a new tax class.

```http
POST /wp-json/wc/v1/taxes/classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/taxes/classes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "Zero Rate"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Zero Rate"
};

WooCommerce.post("taxes/classes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Zero Rate'
];

print_r($woocommerce->post('taxes/classes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Zero Rate"
}

print(wcapi.post("taxes/classes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Zero Rate"
}

woocommerce.post("taxes/classes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "slug": "zero-rate",
  "name": "Zero Rate",
  "_links": {
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes/classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all tax classes
This API helps you to view all tax classes.

```http
GET /wp-json/wc/v1/taxes/classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/taxes/classes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("taxes/classes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes/classes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes/classes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes/classes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "slug": "standard",
    "name": "Standard Rate",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/classes"
        }
      ]
    }
  },
  {
    "slug": "reduced-rate",
    "name": "Reduced Rate",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/classes"
        }
      ]
    }
  },
  {
    "slug": "zero-rate",
    "name": "Zero Rate",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/classes"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Delete a tax class
This API helps you delete a tax class.

:::warning
This also will delete all tax rates from the selected class.
:::

```http
DELETE /wp-json/wc/v1/taxes/classes/<slug>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/taxes/classes/zero-rate?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("taxes/classes/zero-rate", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('taxes/classes/zero-rate', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("taxes/classes/zero-rate", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("taxes/classes/zero-rate", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "slug": "zero-rate",
  "name": "Zero Rate",
  "_links": {
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes/classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, since this resource does not support trashing. |


---

## Tax rates

*Source: apis/rest-api/v1/taxes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Tax rates
The taxes API allows you to create, view, update, and delete individual tax rates, or a batch of tax rates.

## Tax rate properties
| Attribute  |   Type  |                                                                                   Description                                                                                   |
|------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`       | integer | Unique identifier for the resource. `READ-ONLY`                                                                                                   |
| `country`  | string  | Country ISO 3166 code. See [ISO 3166 Codes (Countries)](http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html) for more details                                              |
| `state`    | string  | State code.                                                                                                                                                                     |
| `postcode` | string  | Postcode/ZIP.                                                                                                                                                                   |
| `city`     | string  | City name.                                                                                                                                                                      |
| `rate`     | string  | Tax rate.                                                                                                                                                                       |
| `name`     | string  | Tax rate name.                                                                                                                                                                  |
| `priority` | integer | Tax priority. Only 1 matching rate per priority will be used. To define multiple tax rates for a single area you need to specify a different priority per rate. Default is `1`. |
| `compound` | boolean | Whether or not this is a compound rate. Compound tax rates are applied on top of other tax rates. Default is `false`.                                                           |
| `shipping` | boolean | Whether or not this tax rate also gets applied to shipping. Default is `true`.                                                                                                  |
| `order`    | integer | Indicates the order that will appear in queries.                                                                                                                                |
| `class`    | string  | Tax class. Default is `standard`.                                                                                                                                               |

## Create a tax rate
This API helps you to create a new tax rate.

```http
POST /wp-json/wc/v1/taxes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/taxes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "country": "US",
  "state": "AL",
  "rate": "4",
  "name": "State Tax",
  "shipping": false
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  country: "US",
  state: "AL",
  rate: "4",
  name: "State Tax",
  shipping: false
};

WooCommerce.post("taxes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'country' => 'US',
    'state' => 'AL',
    'rate' => '4',
    'name' => 'State Tax',
    'shipping' => false
];

print_r($woocommerce->post('taxes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "country": "US",
    "state": "AL",
    "rate": "4",
    "name": "State Tax",
    "shipping": False
}

print(wcapi.post("taxes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  country: "US",
  state: "AL",
  rate: "4",
  name: "State Tax",
  shipping: false
}

woocommerce.post("taxes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 72,
  "country": "US",
  "state": "AL",
  "postcode": "",
  "city": "",
  "rate": "4.0000",
  "name": "State Tax",
  "priority": 0,
  "compound": false,
  "shipping": false,
  "order": 1,
  "class": "standard",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes/72"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a tax rate
This API lets you retrieve and view a specific tax rate by ID.

```http
GET /wp-json/wc/v1/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/taxes/72 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("taxes/72")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes/72')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes/72").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes/72").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 72,
  "country": "US",
  "state": "AL",
  "postcode": "",
  "city": "",
  "rate": "4.0000",
  "name": "State Tax",
  "priority": 0,
  "compound": false,
  "shipping": false,
  "order": 1,
  "class": "standard",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes/72"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all tax rates
This API helps you to view all the tax rates.

```http
GET /wp-json/wc/v1/taxes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/taxes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("taxes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 72,
    "country": "US",
    "state": "AL",
    "postcode": "",
    "city": "",
    "rate": "4.0000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 1,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/72"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 73,
    "country": "US",
    "state": "AZ",
    "postcode": "",
    "city": "",
    "rate": "5.6000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 2,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/73"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 74,
    "country": "US",
    "state": "AR",
    "postcode": "",
    "city": "",
    "rate": "6.5000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 3,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/74"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 75,
    "country": "US",
    "state": "CA",
    "postcode": "",
    "city": "",
    "rate": "7.5000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 4,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/75"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 76,
    "country": "US",
    "state": "CO",
    "postcode": "",
    "city": "",
    "rate": "2.9000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 5,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/76"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 77,
    "country": "US",
    "state": "CT",
    "postcode": "",
    "city": "",
    "rate": "6.3500",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 6,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/77"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 78,
    "country": "US",
    "state": "DC",
    "postcode": "",
    "city": "",
    "rate": "5.7500",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 7,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/78"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 79,
    "country": "US",
    "state": "FL",
    "postcode": "",
    "city": "",
    "rate": "6.0000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 8,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/79"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 80,
    "country": "US",
    "state": "GA",
    "postcode": "",
    "city": "",
    "rate": "4.0000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 9,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/80"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  },
  {
    "id": 81,
    "country": "US",
    "state": "GU",
    "postcode": "",
    "city": "",
    "rate": "4.0000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 10,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes/81"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/taxes"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter  |   Type  |                                                                Description                                                                 |
|------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `context`  | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                  |
| `page`     | integer | Current page of the collection.                                                                                                            |
| `per_page` | integer | Maximum number of items to be returned in result set.                                                                                      |
| `offset`   | integer | Offset the result set by a specific number of items.                                                                                       |
| `order`    | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                                 |
| `orderby`  | string  | Sort collection by object attribute. Default is `name`. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. |
| `class`    | string  | Sort by tax class.                                                                                                                         |

## Update a tax rate
This API lets you make changes to a tax rate.

```http
PUT /wp-json/wc/v1/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/taxes/72 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "US Tax"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "US Tax"
};

WooCommerce.put("taxes/72", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'US Tax'
];

print_r($woocommerce->put('taxes/72', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "US Tax"
}

print(wcapi.put("taxes/72", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "US Tax"
}

woocommerce.put("taxes/72", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 72,
  "country": "US",
  "state": "AL",
  "postcode": "",
  "city": "",
  "rate": "4.0000",
  "name": "US Tax",
  "priority": 0,
  "compound": false,
  "shipping": false,
  "order": 1,
  "class": "standard",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes/72"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a tax rate
This API helps you delete a tax rate.

```http
DELETE /wp-json/wc/v1/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/taxes/72?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("taxes/72", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('taxes/72', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("taxes/72", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("taxes/72", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 72,
  "country": "US",
  "state": "AL",
  "postcode": "",
  "city": "",
  "rate": "4.0000",
  "name": "US Tax",
  "priority": 0,
  "compound": false,
  "shipping": false,
  "order": 1,
  "class": "standard",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes/72"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/taxes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update tax rates
This API helps you to batch create, update and delete multiple tax rates.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/taxes/batch
```

> Example batch creating all US taxes:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/taxes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "country": "US",
      "state": "AL",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 1
    },
    {
      "country": "US",
      "state": "AZ",
      "rate": "5.6000",
      "name": "State Tax",
      "shipping": false,
      "order": 2
    },
    {
      "country": "US",
      "state": "AR",
      "rate": "6.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 3
    },
    {
      "country": "US",
      "state": "CA",
      "rate": "7.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 4
    },
    {
      "country": "US",
      "state": "CO",
      "rate": "2.9000",
      "name": "State Tax",
      "shipping": false,
      "order": 5
    },
    {
      "country": "US",
      "state": "CT",
      "rate": "6.3500",
      "name": "State Tax",
      "shipping": true,
      "order": 6
    },
    {
      "country": "US",
      "state": "DC",
      "rate": "5.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 7
    },
    {
      "country": "US",
      "state": "FL",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 8
    },
    {
      "country": "US",
      "state": "GA",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 9
    },
    {
      "country": "US",
      "state": "GU",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 10
    },
    {
      "country": "US",
      "state": "HI",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 11
    },
    {
      "country": "US",
      "state": "ID",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 12
    },
    {
      "country": "US",
      "state": "IL",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": false,
      "order": 13
    },
    {
      "country": "US",
      "state": "IN",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 14
    },
    {
      "country": "US",
      "state": "IA",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 15
    },
    {
      "country": "US",
      "state": "KS",
      "rate": "6.1500",
      "name": "State Tax",
      "shipping": true,
      "order": 16
    },
    {
      "country": "US",
      "state": "KY",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 17
    },
    {
      "country": "US",
      "state": "LA",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 18
    },
    {
      "country": "US",
      "state": "ME",
      "rate": "5.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 19
    },
    {
      "country": "US",
      "state": "MD",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 20
    },
    {
      "country": "US",
      "state": "MA",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": false,
      "order": 21
    },
    {
      "country": "US",
      "state": "MI",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 22
    },
    {
      "country": "US",
      "state": "MN",
      "rate": "6.8750",
      "name": "State Tax",
      "shipping": true,
      "order": 23
    },
    {
      "country": "US",
      "state": "MS",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 24
    },
    {
      "country": "US",
      "state": "MO",
      "rate": "4.2250",
      "name": "State Tax",
      "shipping": false,
      "order": 25
    },
    {
      "country": "US",
      "state": "NE",
      "rate": "5.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 26
    },
    {
      "country": "US",
      "state": "NV",
      "rate": "6.8500",
      "name": "State Tax",
      "shipping": false,
      "order": 27
    },
    {
      "country": "US",
      "state": "NJ",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 28
    },
    {
      "country": "US",
      "state": "NM",
      "rate": "5.1250",
      "name": "State Tax",
      "shipping": true,
      "order": 29
    },
    {
      "country": "US",
      "state": "NY",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 30
    },
    {
      "country": "US",
      "state": "NC",
      "rate": "4.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 31
    },
    {
      "country": "US",
      "state": "ND",
      "rate": "5.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 32
    },
    {
      "country": "US",
      "state": "OH",
      "rate": "5.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 33
    },
    {
      "country": "US",
      "state": "OK",
      "rate": "4.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 34
    },
    {
      "country": "US",
      "state": "PA",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 35
    },
    {
      "country": "US",
      "state": "PR",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 36
    },
    {
      "country": "US",
      "state": "RI",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 37
    },
    {
      "country": "US",
      "state": "SC",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 38
    },
    {
      "country": "US",
      "state": "SD",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 39
    },
    {
      "country": "US",
      "state": "TN",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 40
    },
    {
      "country": "US",
      "state": "TX",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": true,
      "order": 41
    },
    {
      "country": "US",
      "state": "UT",
      "rate": "5.9500",
      "name": "State Tax",
      "shipping": false,
      "order": 42
    },
    {
      "country": "US",
      "state": "VT",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 43
    },
    {
      "country": "US",
      "state": "VA",
      "rate": "5.3000",
      "name": "State Tax",
      "shipping": false,
      "order": 44
    },
    {
      "country": "US",
      "state": "WA",
      "rate": "6.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 45
    },
    {
      "country": "US",
      "state": "WV",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 46
    },
    {
      "country": "US",
      "state": "WI",
      "rate": "5.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 47
    },
    {
      "country": "US",
      "state": "WY",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 48
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      country: "US",
      state: "AL",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 1
    },
    {
      country: "US",
      state: "AZ",
      rate: "5.6000",
      name: "State Tax",
      shipping: false,
      order: 2
    },
    {
      country: "US",
      state: "AR",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 3
    },
    {
      country: "US",
      state: "CA",
      rate: "7.5000",
      name: "State Tax",
      shipping: false,
      order: 4
    },
    {
      country: "US",
      state: "CO",
      rate: "2.9000",
      name: "State Tax",
      shipping: false,
      order: 5
    },
    {
      country: "US",
      state: "CT",
      rate: "6.3500",
      name: "State Tax",
      shipping: true,
      order: 6
    },
    {
      country: "US",
      state: "DC",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 7
    },
    {
      country: "US",
      state: "FL",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 8
    },
    {
      country: "US",
      state: "GA",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 9
    },
    {
      country: "US",
      state: "GU",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 10
    },
    {
      country: "US",
      state: "HI",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 11
    },
    {
      country: "US",
      state: "ID",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 12
    },
    {
      country: "US",
      state: "IL",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 13
    },
    {
      country: "US",
      state: "IN",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 14
    },
    {
      country: "US",
      state: "IA",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 15
    },
    {
      country: "US",
      state: "KS",
      rate: "6.1500",
      name: "State Tax",
      shipping: true,
      order: 16
    },
    {
      country: "US",
      state: "KY",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 17
    },
    {
      country: "US",
      state: "LA",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 18
    },
    {
      country: "US",
      state: "ME",
      rate: "5.5000",
      name: "State Tax",
      shipping: false,
      order: 19
    },
    {
      country: "US",
      state: "MD",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 20
    },
    {
      country: "US",
      state: "MA",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 21
    },
    {
      country: "US",
      state: "MI",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 22
    },
    {
      country: "US",
      state: "MN",
      rate: "6.8750",
      name: "State Tax",
      shipping: true,
      order: 23
    },
    {
      country: "US",
      state: "MS",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 24
    },
    {
      country: "US",
      state: "MO",
      rate: "4.2250",
      name: "State Tax",
      shipping: false,
      order: 25
    },
    {
      country: "US",
      state: "NE",
      rate: "5.5000",
      name: "State Tax",
      shipping: true,
      order: 26
    },
    {
      country: "US",
      state: "NV",
      rate: "6.8500",
      name: "State Tax",
      shipping: false,
      order: 27
    },
    {
      country: "US",
      state: "NJ",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 28
    },
    {
      country: "US",
      state: "NM",
      rate: "5.1250",
      name: "State Tax",
      shipping: true,
      order: 29
    },
    {
      country: "US",
      state: "NY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 30
    },
    {
      country: "US",
      state: "NC",
      rate: "4.7500",
      name: "State Tax",
      shipping: true,
      order: 31
    },
    {
      country: "US",
      state: "ND",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 32
    },
    {
      country: "US",
      state: "OH",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 33
    },
    {
      country: "US",
      state: "OK",
      rate: "4.5000",
      name: "State Tax",
      shipping: false,
      order: 34
    },
    {
      country: "US",
      state: "PA",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 35
    },
    {
      country: "US",
      state: "PR",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 36
    },
    {
      country: "US",
      state: "RI",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 37
    },
    {
      country: "US",
      state: "SC",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 38
    },
    {
      country: "US",
      state: "SD",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 39
    },
    {
      country: "US",
      state: "TN",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 40
    },
    {
      country: "US",
      state: "TX",
      rate: "6.2500",
      name: "State Tax",
      shipping: true,
      order: 41
    },
    {
      country: "US",
      state: "UT",
      rate: "5.9500",
      name: "State Tax",
      shipping: false,
      order: 42
    },
    {
      country: "US",
      state: "VT",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 43
    },
    {
      country: "US",
      state: "VA",
      rate: "5.3000",
      name: "State Tax",
      shipping: false,
      order: 44
    },
    {
      country: "US",
      state: "WA",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 45
    },
    {
      country: "US",
      state: "WV",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 46
    },
    {
      country: "US",
      state: "WI",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 47
    },
    {
      country: "US",
      state: "WY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 48
    }
  ]
};

WooCommerce.post("taxes/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'country' => 'US',
            'state' => 'AL',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 1
        ],
        [
            'country' => 'US',
            'state' => 'AZ',
            'rate' => '5.6000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 2
        ],
        [
            'country' => 'US',
            'state' => 'AR',
            'rate' => '6.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 3
        ],
        [
            'country' => 'US',
            'state' => 'CA',
            'rate' => '7.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 4
        ],
        [
            'country' => 'US',
            'state' => 'CO',
            'rate' => '2.9000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 5
        ],
        [
            'country' => 'US',
            'state' => 'CT',
            'rate' => '6.3500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 6
        ],
        [
            'country' => 'US',
            'state' => 'DC',
            'rate' => '5.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 7
        ],
        [
            'country' => 'US',
            'state' => 'FL',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 8
        ],
        [
            'country' => 'US',
            'state' => 'GA',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 9
        ],
        [
            'country' => 'US',
            'state' => 'GU',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 10
        ],
        [
            'country' => 'US',
            'state' => 'HI',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 11
        ],
        [
            'country' => 'US',
            'state' => 'ID',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 12
        ],
        [
            'country' => 'US',
            'state' => 'IL',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 13
        ],
        [
            'country' => 'US',
            'state' => 'IN',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 14
        ],
        [
            'country' => 'US',
            'state' => 'IA',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 15
        ],
        [
            'country' => 'US',
            'state' => 'KS',
            'rate' => '6.1500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 16
        ],
        [
            'country' => 'US',
            'state' => 'KY',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 17
        ],
        [
            'country' => 'US',
            'state' => 'LA',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 18
        ],
        [
            'country' => 'US',
            'state' => 'ME',
            'rate' => '5.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 19
        ],
        [
            'country' => 'US',
            'state' => 'MD',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 20
        ],
        [
            'country' => 'US',
            'state' => 'MA',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 21
        ],
        [
            'country' => 'US',
            'state' => 'MI',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 22
        ],
        [
            'country' => 'US',
            'state' => 'MN',
            'rate' => '6.8750',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 23
        ],
        [
            'country' => 'US',
            'state' => 'MS',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 24
        ],
        [
            'country' => 'US',
            'state' => 'MO',
            'rate' => '4.2250',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 25
        ],
        [
            'country' => 'US',
            'state' => 'NE',
            'rate' => '5.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 26
        ],
        [
            'country' => 'US',
            'state' => 'NV',
            'rate' => '6.8500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 27
        ],
        [
            'country' => 'US',
            'state' => 'NJ',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 28
        ],
        [
            'country' => 'US',
            'state' => 'NM',
            'rate' => '5.1250',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 29
        ],
        [
            'country' => 'US',
            'state' => 'NY',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 30
        ],
        [
            'country' => 'US',
            'state' => 'NC',
            'rate' => '4.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 31
        ],
        [
            'country' => 'US',
            'state' => 'ND',
            'rate' => '5.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 32
        ],
        [
            'country' => 'US',
            'state' => 'OH',
            'rate' => '5.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 33
        ],
        [
            'country' => 'US',
            'state' => 'OK',
            'rate' => '4.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 34
        ],
        [
            'country' => 'US',
            'state' => 'PA',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 35
        ],
        [
            'country' => 'US',
            'state' => 'PR',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 36
        ],
        [
            'country' => 'US',
            'state' => 'RI',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 37
        ],
        [
            'country' => 'US',
            'state' => 'SC',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 38
        ],
        [
            'country' => 'US',
            'state' => 'SD',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 39
        ],
        [
            'country' => 'US',
            'state' => 'TN',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 40
        ],
        [
            'country' => 'US',
            'state' => 'TX',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 41
        ],
        [
            'country' => 'US',
            'state' => 'UT',
            'rate' => '5.9500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 42
        ],
        [
            'country' => 'US',
            'state' => 'VT',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 43
        ],
        [
            'country' => 'US',
            'state' => 'VA',
            'rate' => '5.3000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 44
        ],
        [
            'country' => 'US',
            'state' => 'WA',
            'rate' => '6.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 45
        ],
        [
            'country' => 'US',
            'state' => 'WV',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 46
        ],
        [
            'country' => 'US',
            'state' => 'WI',
            'rate' => '5.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 47
        ],
        [
            'country' => 'US',
            'state' => 'WY',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 48
        ]
    ]
];

print_r($woocommerce->post('taxes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "country": "US",
            "state": "AL",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 1
        },
        {
            "country": "US",
            "state": "AZ",
            "rate": "5.6000",
            "name": "State Tax",
            "shipping": False,
            "order": 2
        },
        {
            "country": "US",
            "state": "AR",
            "rate": "6.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 3
        },
        {
            "country": "US",
            "state": "CA",
            "rate": "7.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 4
        },
        {
            "country": "US",
            "state": "CO",
            "rate": "2.9000",
            "name": "State Tax",
            "shipping": False,
            "order": 5
        },
        {
            "country": "US",
            "state": "CT",
            "rate": "6.3500",
            "name": "State Tax",
            "shipping": True,
            "order": 6
        },
        {
            "country": "US",
            "state": "DC",
            "rate": "5.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 7
        },
        {
            "country": "US",
            "state": "FL",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 8
        },
        {
            "country": "US",
            "state": "GA",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 9
        },
        {
            "country": "US",
            "state": "GU",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 10
        },
        {
            "country": "US",
            "state": "HI",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 11
        },
        {
            "country": "US",
            "state": "ID",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 12
        },
        {
            "country": "US",
            "state": "IL",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": False,
            "order": 13
        },
        {
            "country": "US",
            "state": "IN",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 14
        },
        {
            "country": "US",
            "state": "IA",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 15
        },
        {
            "country": "US",
            "state": "KS",
            "rate": "6.1500",
            "name": "State Tax",
            "shipping": True,
            "order": 16
        },
        {
            "country": "US",
            "state": "KY",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 17
        },
        {
            "country": "US",
            "state": "LA",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 18
        },
        {
            "country": "US",
            "state": "ME",
            "rate": "5.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 19
        },
        {
            "country": "US",
            "state": "MD",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 20
        },
        {
            "country": "US",
            "state": "MA",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": False,
            "order": 21
        },
        {
            "country": "US",
            "state": "MI",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 22
        },
        {
            "country": "US",
            "state": "MN",
            "rate": "6.8750",
            "name": "State Tax",
            "shipping": True,
            "order": 23
        },
        {
            "country": "US",
            "state": "MS",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 24
        },
        {
            "country": "US",
            "state": "MO",
            "rate": "4.2250",
            "name": "State Tax",
            "shipping": False,
            "order": 25
        },
        {
            "country": "US",
            "state": "NE",
            "rate": "5.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 26
        },
        {
            "country": "US",
            "state": "NV",
            "rate": "6.8500",
            "name": "State Tax",
            "shipping": False,
            "order": 27
        },
        {
            "country": "US",
            "state": "NJ",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 28
        },
        {
            "country": "US",
            "state": "NM",
            "rate": "5.1250",
            "name": "State Tax",
            "shipping": True,
            "order": 29
        },
        {
            "country": "US",
            "state": "NY",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 30
        },
        {
            "country": "US",
            "state": "NC",
            "rate": "4.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 31
        },
        {
            "country": "US",
            "state": "ND",
            "rate": "5.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 32
        },
        {
            "country": "US",
            "state": "OH",
            "rate": "5.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 33
        },
        {
            "country": "US",
            "state": "OK",
            "rate": "4.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 34
        },
        {
            "country": "US",
            "state": "PA",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 35
        },
        {
            "country": "US",
            "state": "PR",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 36
        },
        {
            "country": "US",
            "state": "RI",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 37
        },
        {
            "country": "US",
            "state": "SC",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 38
        },
        {
            "country": "US",
            "state": "SD",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 39
        },
        {
            "country": "US",
            "state": "TN",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 40
        },
        {
            "country": "US",
            "state": "TX",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": True,
            "order": 41
        },
        {
            "country": "US",
            "state": "UT",
            "rate": "5.9500",
            "name": "State Tax",
            "shipping": False,
            "order": 42
        },
        {
            "country": "US",
            "state": "VT",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 43
        },
        {
            "country": "US",
            "state": "VA",
            "rate": "5.3000",
            "name": "State Tax",
            "shipping": False,
            "order": 44
        },
        {
            "country": "US",
            "state": "WA",
            "rate": "6.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 45
        },
        {
            "country": "US",
            "state": "WV",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 46
        },
        {
            "country": "US",
            "state": "WI",
            "rate": "5.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 47
        },
        {
            "country": "US",
            "state": "WY",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 48
        }
    ]
}

print(wcapi.post("taxes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      country: "US",
      state: "AL",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 1
    },
    {
      country: "US",
      state: "AZ",
      rate: "5.6000",
      name: "State Tax",
      shipping: false,
      order: 2
    },
    {
      country: "US",
      state: "AR",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 3
    },
    {
      country: "US",
      state: "CA",
      rate: "7.5000",
      name: "State Tax",
      shipping: false,
      order: 4
    },
    {
      country: "US",
      state: "CO",
      rate: "2.9000",
      name: "State Tax",
      shipping: false,
      order: 5
    },
    {
      country: "US",
      state: "CT",
      rate: "6.3500",
      name: "State Tax",
      shipping: true,
      order: 6
    },
    {
      country: "US",
      state: "DC",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 7
    },
    {
      country: "US",
      state: "FL",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 8
    },
    {
      country: "US",
      state: "GA",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 9
    },
    {
      country: "US",
      state: "GU",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 10
    },
    {
      country: "US",
      state: "HI",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 11
    },
    {
      country: "US",
      state: "ID",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 12
    },
    {
      country: "US",
      state: "IL",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 13
    },
    {
      country: "US",
      state: "IN",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 14
    },
    {
      country: "US",
      state: "IA",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 15
    },
    {
      country: "US",
      state: "KS",
      rate: "6.1500",
      name: "State Tax",
      shipping: true,
      order: 16
    },
    {
      country: "US",
      state: "KY",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 17
    },
    {
      country: "US",
      state: "LA",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 18
    },
    {
      country: "US",
      state: "ME",
      rate: "5.5000",
      name: "State Tax",
      shipping: false,
      order: 19
    },
    {
      country: "US",
      state: "MD",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 20
    },
    {
      country: "US",
      state: "MA",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 21
    },
    {
      country: "US",
      state: "MI",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 22
    },
    {
      country: "US",
      state: "MN",
      rate: "6.8750",
      name: "State Tax",
      shipping: true,
      order: 23
    },
    {
      country: "US",
      state: "MS",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 24
    },
    {
      country: "US",
      state: "MO",
      rate: "4.2250",
      name: "State Tax",
      shipping: false,
      order: 25
    },
    {
      country: "US",
      state: "NE",
      rate: "5.5000",
      name: "State Tax",
      shipping: true,
      order: 26
    },
    {
      country: "US",
      state: "NV",
      rate: "6.8500",
      name: "State Tax",
      shipping: false,
      order: 27
    },
    {
      country: "US",
      state: "NJ",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 28
    },
    {
      country: "US",
      state: "NM",
      rate: "5.1250",
      name: "State Tax",
      shipping: true,
      order: 29
    },
    {
      country: "US",
      state: "NY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 30
    },
    {
      country: "US",
      state: "NC",
      rate: "4.7500",
      name: "State Tax",
      shipping: true,
      order: 31
    },
    {
      country: "US",
      state: "ND",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 32
    },
    {
      country: "US",
      state: "OH",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 33
    },
    {
      country: "US",
      state: "OK",
      rate: "4.5000",
      name: "State Tax",
      shipping: false,
      order: 34
    },
    {
      country: "US",
      state: "PA",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 35
    },
    {
      country: "US",
      state: "PR",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 36
    },
    {
      country: "US",
      state: "RI",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 37
    },
    {
      country: "US",
      state: "SC",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 38
    },
    {
      country: "US",
      state: "SD",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 39
    },
    {
      country: "US",
      state: "TN",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 40
    },
    {
      country: "US",
      state: "TX",
      rate: "6.2500",
      name: "State Tax",
      shipping: true,
      order: 41
    },
    {
      country: "US",
      state: "UT",
      rate: "5.9500",
      name: "State Tax",
      shipping: false,
      order: 42
    },
    {
      country: "US",
      state: "VT",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 43
    },
    {
      country: "US",
      state: "VA",
      rate: "5.3000",
      name: "State Tax",
      shipping: false,
      order: 44
    },
    {
      country: "US",
      state: "WA",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 45
    },
    {
      country: "US",
      state: "WV",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 46
    },
    {
      country: "US",
      state: "WI",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 47
    },
    {
      country: "US",
      state: "WY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 48
    }
  ]
}

woocommerce.post("taxes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 72,
      "country": "US",
      "state": "AL",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 1,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/72"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 73,
      "country": "US",
      "state": "AZ",
      "postcode": "",
      "city": "",
      "rate": "5.6000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 2,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/73"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 74,
      "country": "US",
      "state": "AR",
      "postcode": "",
      "city": "",
      "rate": "6.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 3,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/74"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 75,
      "country": "US",
      "state": "CA",
      "postcode": "",
      "city": "",
      "rate": "7.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 4,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/75"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 76,
      "country": "US",
      "state": "CO",
      "postcode": "",
      "city": "",
      "rate": "2.9000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 5,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/76"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 77,
      "country": "US",
      "state": "CT",
      "postcode": "",
      "city": "",
      "rate": "6.3500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 6,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/77"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 78,
      "country": "US",
      "state": "DC",
      "postcode": "",
      "city": "",
      "rate": "5.7500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 7,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/78"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 79,
      "country": "US",
      "state": "FL",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 8,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/79"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 80,
      "country": "US",
      "state": "GA",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 9,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/80"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 81,
      "country": "US",
      "state": "GU",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 10,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/81"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 82,
      "country": "US",
      "state": "HI",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 11,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/82"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 83,
      "country": "US",
      "state": "ID",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 12,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/83"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 84,
      "country": "US",
      "state": "IL",
      "postcode": "",
      "city": "",
      "rate": "6.2500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 13,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/84"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 85,
      "country": "US",
      "state": "IN",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 14,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/85"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 86,
      "country": "US",
      "state": "IA",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 15,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/86"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 87,
      "country": "US",
      "state": "KS",
      "postcode": "",
      "city": "",
      "rate": "6.1500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 16,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/87"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 88,
      "country": "US",
      "state": "KY",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 17,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/88"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 89,
      "country": "US",
      "state": "LA",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 18,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/89"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 90,
      "country": "US",
      "state": "ME",
      "postcode": "",
      "city": "",
      "rate": "5.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 19,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/90"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 91,
      "country": "US",
      "state": "MD",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 20,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/91"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 92,
      "country": "US",
      "state": "MA",
      "postcode": "",
      "city": "",
      "rate": "6.2500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 21,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/92"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 93,
      "country": "US",
      "state": "MI",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 22,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/93"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 94,
      "country": "US",
      "state": "MN",
      "postcode": "",
      "city": "",
      "rate": "6.8750",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 23,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/94"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 95,
      "country": "US",
      "state": "MS",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 24,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/95"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 96,
      "country": "US",
      "state": "MO",
      "postcode": "",
      "city": "",
      "rate": "4.2250",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 25,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/96"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 97,
      "country": "US",
      "state": "NE",
      "postcode": "",
      "city": "",
      "rate": "5.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 26,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/97"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 98,
      "country": "US",
      "state": "NV",
      "postcode": "",
      "city": "",
      "rate": "6.8500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 27,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/98"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 99,
      "country": "US",
      "state": "NJ",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 28,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/99"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 100,
      "country": "US",
      "state": "NM",
      "postcode": "",
      "city": "",
      "rate": "5.1250",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 29,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/100"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 101,
      "country": "US",
      "state": "NY",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 30,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/101"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 102,
      "country": "US",
      "state": "NC",
      "postcode": "",
      "city": "",
      "rate": "4.7500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 31,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/102"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 103,
      "country": "US",
      "state": "ND",
      "postcode": "",
      "city": "",
      "rate": "5.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 32,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/103"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 104,
      "country": "US",
      "state": "OH",
      "postcode": "",
      "city": "",
      "rate": "5.7500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 33,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/104"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 105,
      "country": "US",
      "state": "OK",
      "postcode": "",
      "city": "",
      "rate": "4.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 34,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/105"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 106,
      "country": "US",
      "state": "PA",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 35,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/106"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 107,
      "country": "US",
      "state": "PR",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 36,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/107"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 108,
      "country": "US",
      "state": "RI",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 37,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/108"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 109,
      "country": "US",
      "state": "SC",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 38,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/109"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 110,
      "country": "US",
      "state": "SD",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 39,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/110"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 111,
      "country": "US",
      "state": "TN",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 40,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/111"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 112,
      "country": "US",
      "state": "TX",
      "postcode": "",
      "city": "",
      "rate": "6.2500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 41,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/112"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 113,
      "country": "US",
      "state": "UT",
      "postcode": "",
      "city": "",
      "rate": "5.9500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 42,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/113"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 114,
      "country": "US",
      "state": "VT",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 43,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/114"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 115,
      "country": "US",
      "state": "VA",
      "postcode": "",
      "city": "",
      "rate": "5.3000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 44,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/115"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 116,
      "country": "US",
      "state": "WA",
      "postcode": "",
      "city": "",
      "rate": "6.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 45,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/116"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 117,
      "country": "US",
      "state": "WV",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 46,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/117"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 118,
      "country": "US",
      "state": "WI",
      "postcode": "",
      "city": "",
      "rate": "5.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 47,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/118"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    },
    {
      "id": 119,
      "country": "US",
      "state": "WY",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 48,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes/119"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/taxes"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Webhooks

*Source: apis/rest-api/v1/webhooks.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Webhooks
The webhooks API allows you to create, view, update, and delete individual, or a batch, of webhooks.

Webhooks can be managed via the WooCommerce settings screen or by using the REST API endpoints. The `WC_Webhook` class manages all data storage and retrieval of the webhook custom post type, as well as enqueuing webhook actions and processing/delivering/logging webhooks. On `woocommerce_init`, active webhooks are loaded.

Each webhook has:

* `status`: active (delivers payload), paused (delivery paused by admin), disabled (delivery paused by failure).
* `topic`: determines which resource events the webhook is triggered for.
* `delivery URL`: URL where the payload is delivered, must be HTTP or HTTPS.
* `secret`: an optional secret key that is used to generate a HMAC-SHA256 hash of the request body so the receiver can verify authenticity of the webhook.
* `hooks`: an array of hook names that are added and bound to the webhook for processing.

### Topics
The topic is a combination resource (e.g. order) and event (e.g. created) and maps to one or more hook names (e.g. `woocommerce_checkout_order_processed`). Webhooks can be created using the topic name and the appropriate hooks are automatically added.

Core topics are:

* Coupons: `coupon.created`, `coupon.updated` and `coupon.deleted`.
* Customers: `customer.created`, `customer.updated` and `customer.deleted`.
* Orders: `order.created`, `order.updated` and `order.deleted`.
* Products: `product.created`, `product.updated` and `product.deleted`.

Custom topics can also be used which map to a single hook name, for example you could add a webhook with topic `action.woocommerce_add_to_cart` that is triggered on that event. Custom topics pass the first hook argument to the payload, so in this example the `cart_item_key` would be included in the payload.

### Delivery/payload
Delivery is performed using `wp_remote_post()` (HTTP POST) and processed in the background by default using wp-cron. A few custom headers are added to the request to help the receiver process the webhook:

* `X-WC-Webhook-Topic` - e.g. `order.updated`.
* `X-WC-Webhook-Resource` - e.g. `order`.
* `X-WC-Webhook-Event` - e.g. `updated`.
* `X-WC-Webhook-Signature` - a base64 encoded HMAC-SHA256 hash of the payload.
* `X-WC-Webhook-ID` - webhook's post ID.
* `X-WC-Webhook-Delivery-ID` - delivery log ID (a comment).

The payload is JSON encoded and for API resources (coupons, customers, orders, products), the response is exactly the same as if requested via the REST API.

### Logging
Requests/responses are logged as comments on the webhook custom post type. Each delivery log includes:

* Request duration.
* Request URL, method, headers, and body.
* Response Code, message, headers, and body.

Only the 25 most recent delivery logs are kept in order to reduce comment table bloat.

After 5 consecutive failed deliveries (as defined by a non HTTP 2xx response code), the webhook is disabled and must be edited via the REST API to re-enable.

Delivery logs can be fetched through the REST API endpoint or in code using `WC_Webhook::get_delivery_logs()`.

### Visual interface
You can find the Webhooks interface going to "WooCommerce" > "Settings" > "API" > "Webhooks", see our [Visual Webhooks docs](https://docs.woocommerce.com/document/webhooks/) for more details.

## Webhook properties
|    Attribute    |    Type   |                                                                                     Description                                                                                      |
|-----------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`            | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                                        |
| `name`          | string    | A friendly name for the webhook. Default is `Webhook created on <date>`.                                                                                                             |
| `status`        | string    | Webhook status. Default is `active`. Options `active` (delivers payload), `paused` (does not deliver), or `disabled` (does not deliver due delivery failures).                       |
| `topic`         | string    | Webhook topic, e.g. `coupon.updated`. [See the complete list](#topics). `REQUIRED`                                                                     |
| `resource`      | string    | Webhook resource, e.g. `coupon` `READ-ONLY`                                                                                                            |
| `event`         | string    | Webhook event, e.g. `updated` `READ-ONLY`                                                                                                              |
| `hooks`         | array     | WooCommerce action names associated with the webhook. `READ-ONLY`                                                                                      |
| `delivery_url`  | string    | The URL where the webhook payload is delivered. `REQUIRED`                                                                                             |
| `secret`        | string    | Secret key used to generate a hash of the delivered webhook and provided in the request headers. `REQUIRED` `WRITE-ONLY` |
| `date_created`  | date-time | UTC DateTime when the webhook was created `READ-ONLY`                                                                                                  |
| `date_modified` | date-time | UTC DateTime when the webhook was last updated `READ-ONLY`                                                                                             |

### Webhooks delivery properties
|     Attribute      |    Type   |                                                                Description                                                                 |
|--------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `id`               | integer   | Unique identifier for the resource. `READ-ONLY`                                                              |
| `duration`         | string    | The delivery duration, in seconds. `READ-ONLY`                                                               |
| `summary`          | string    | A friendly summary of the response including the HTTP response code, message, and body. `READ-ONLY`          |
| `request_url`      | string    | The URL where the webhook was delivered. `READ-ONLY`                                                         |
| `request_headers`  | object    | Request headers. See [Request Headers Attributes](#request-header-properties) for more details. `READ-ONLY`  |
| `request_body`     | string    | Request body. `READ-ONLY`                                                                                    |
| `response_code`    | string    | The HTTP response code from the receiving server. `READ-ONLY`                                                |
| `response_message` | string    | The HTTP response message from the receiving server. `READ-ONLY`                                             |
| `response_headers` | object    | Response headers from the receiving server. `READ-ONLY`                                                      |
| `response_body`    | string    | The response body from the receiving server. `READ-ONLY`                                                     |
| `date_created`     | date-time | The date the webhook delivery was logged, in the site's timezone. `READ-ONLY`                                |

#### Request header properties
|         Attribute          |   Type  |                                                              Description                                                              |
|----------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------|
| `User-Agent`               | string  | The request user agent, default is "WooCommerce/\{version\} Hookshot (WordPress/\{version\})". `READ-ONLY`  |
| `Content-Type`             | string  | The request content-type, default is "application/json". `READ-ONLY`                                    |
| `X-WC-Webhook-Source`      | string  | The webhook source URL. `READ-ONLY`                                                                     |
| `X-WC-Webhook-Topic`       | string  | The webhook topic. `READ-ONLY`                                                                          |
| `X-WC-Webhook-Resource`    | string  | The webhook resource. `READ-ONLY`                                                                       |
| `X-WC-Webhook-Event`       | string  | The webhook event. `READ-ONLY`                                                                          |
| `X-WC-Webhook-Signature`   | string  | A base64 encoded HMAC-SHA256 hash of the payload. `READ-ONLY`                                           |
| `X-WC-Webhook-ID`          | integer | The webhook's ID. `READ-ONLY`                                                                           |
| `X-WC-Webhook-Delivery-ID` | integer | The delivery ID. `READ-ONLY`                                                                            |

## Create a webhook
This API helps you to create a new webhook.

```http
POST /wp-json/wc/v1/webhooks
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/webhooks \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Order updated",
  "topic": "order.updated",
  "delivery_url": "http://requestb.in/1g0sxmo1"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Order updated",
  topic: "order.updated",
  delivery_url: "http://requestb.in/1g0sxmo1"
};

WooCommerce.post("webhooks", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Order updated',
    'topic' => 'order.updated',
    'delivery_url' => 'http://requestb.in/1g0sxmo1'
];

print_r($woocommerce->post('webhooks', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Order updated",
    "topic": "order.updated",
    "delivery_url": "http://requestb.in/1g0sxmo1"
}

print(wcapi.post("webhooks", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Order updated",
  topic: "order.updated",
  delivery_url: "http://requestb.in/1g0sxmo1"
}

woocommerce.post("webhooks", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 142,
  "name": "Order updated",
  "status": "active",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T20:17:52",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a webhook
This API lets you retrieve and view a specific webhook.

```http
GET /wp-json/wc/v1/webhooks/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/webhooks/142 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("webhooks/142")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks/142')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks/142").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks/142").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 142,
  "name": "Order updated",
  "status": "active",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T20:17:52",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all webhooks
This API helps you to view all the webhooks.

```http
GET /wp-json/wc/v1/webhooks
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/webhooks \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("webhooks")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 143,
    "name": "Customer created",
    "status": "active",
    "topic": "customer.created",
    "resource": "customer",
    "event": "created",
    "hooks": [
      "user_register",
      "woocommerce_created_customer",
      "woocommerce_api_create_customer"
    ],
    "delivery_url": "http://requestb.in/1g0sxmo1",
    "date_created": "2016-05-15T20:17:52",
    "date_modified": "2016-05-15T20:17:52",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks/143"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks"
        }
      ]
    }
  },
  {
    "id": 142,
    "name": "Order updated",
    "status": "active",
    "topic": "order.updated",
    "resource": "order",
    "event": "updated",
    "hooks": [
      "woocommerce_process_shop_order_meta",
      "woocommerce_api_edit_order",
      "woocommerce_order_edit_status",
      "woocommerce_order_status_changed"
    ],
    "delivery_url": "http://requestb.in/1g0sxmo1",
    "date_created": "2016-05-15T20:17:52",
    "date_modified": "2016-05-15T20:17:52",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks/142"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter       |   Type  |                                                          Description                                                          |
|-----------------|---------|-------------------------------------------------------------------------------------------------------------------------------|
| `context`       | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                     |
| `page`          | integer | Current page of the collection.                                                                                               |
| `per_page`      | integer | Maximum number of items to be returned in result set.                                                                         |
| `search`        | string  | Limit results to those matching a string.                                                                                     |
| `after`         | string  | Limit response to resources published after a given ISO8601 compliant date.                                                   |
| `before`        | string  | Limit response to resources published before a given ISO8601 compliant date.                                                  |
| `dates_are_gmt` | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                      |
| `exclude`       | string  | Ensure result set excludes specific ids.                                                                                      |
| `include`       | string  | Limit result set to specific ids.                                                                                             |
| `offset`        | integer | Offset the result set by a specific number of items.                                                                          |
| `order`         | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                    |
| `orderby`       | string  | Sort collection by object attribute. Default is `date`, Options: `date`, `id`, `include`, `title` and `slug`.                 |
| `slug`          | string  | Limit result set to posts with a specific slug.                                                                               |
| `status`        | string  | Limit result set to webhooks assigned a specific status. Default is `all`. Options: `all`, `active`, `paused` and `disabled`. |

## Update a webhook
This API lets you make changes to a webhook.

```http
PUT /wp-json/wc/v1/webhooks/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v1/webhooks/142 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "status": "paused"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  status: "paused"
}

WooCommerce.put("webhooks/142", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'status' => 'paused'
];

print_r($woocommerce->put('webhooks/142', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "status": "paused"
}

print(wcapi.put("webhooks/142", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  status: "paused"
}

woocommerce.put("webhooks/142", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 142,
  "name": "Order updated",
  "status": "paused",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T20:30:12",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a webhook
This API helps you delete a webhook.

```http
DELETE /wp-json/wc/v1/webhooks/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v1/webhooks/142 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("webhooks/142")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('webhooks/142')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("webhooks/142").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("webhooks/142").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 142,
  "name": "Order updated",
  "status": "paused",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T20:30:12",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                                Description                                 |
|-----------|--------|----------------------------------------------------------------------------|
| `force`   | boolean | Whether to permanently delete the webhook. Default is `false`. |

## Batch update webhooks
This API helps you to batch create, update and delete multiple webhooks.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v1/webhooks/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v1/webhooks/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Coupon created",
      "topic": "coupon.created",
      "delivery_url": "http://requestb.in/1g0sxmo1"
    },
    {
      "name": "Customer deleted",
      "topic": "customer.deleted",
      "delivery_url": "http://requestb.in/1g0sxmo1"
    }
  ],
  "delete": [
    143
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Round toe",
      topic: "coupon.created",
      delivery_url: "http://requestb.in/1g0sxmo1"
    },
    {
      name: "Customer deleted",
      topic: "customer.deleted",
      delivery_url: "http://requestb.in/1g0sxmo1"
    }
  ],
  delete: [
    143
  ]
};

WooCommerce.post("webhooks/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Round toe',
            'topic' => 'coupon.created',
            'delivery_url' => 'http://requestb.in/1g0sxmo1'
        ],
        [
            'name' => 'Customer deleted',
            'topic' => 'customer.deleted',
            'delivery_url' => 'http://requestb.in/1g0sxmo1'
        ]
    ],
    'delete' => [
        143
    ]
];

print_r($woocommerce->post('webhooks/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Round toe",
            "topic": "coupon.created",
            "delivery_url": "http://requestb.in/1g0sxmo1"
        },
        {
            "name": "Customer deleted",
            "topic": "customer.deleted",
            "delivery_url": "http://requestb.in/1g0sxmo1"
        }
    ],
    "delete": [
        143
    ]
}

print(wcapi.post("webhooks/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Round toe",
      topic: "coupon.created",
      delivery_url: "http://requestb.in/1g0sxmo1"
    },
    {
      name: "Customer deleted",
      topic: "customer.deleted",
      delivery_url: "http://requestb.in/1g0sxmo1"
    }
  ],
  delete: [
    143
  ]
}

woocommerce.post("webhooks/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 146,
      "name": "Coupon created",
      "status": "active",
      "topic": "coupon.created",
      "resource": "coupon",
      "event": "created",
      "hooks": [
        "woocommerce_process_shop_coupon_meta",
        "woocommerce_api_create_coupon"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-24T22:56:26",
      "date_modified": "2016-05-24T22:56:26",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/webhooks/146"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/webhooks"
          }
        ]
      }
    },
    {
      "id": 147,
      "name": "Customer deleted",
      "status": "active",
      "topic": "customer.deleted",
      "resource": "customer",
      "event": "deleted",
      "hooks": [
        "delete_user"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-24T22:56:30",
      "date_modified": "2016-05-24T22:56:30",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/webhooks/147"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/webhooks"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 143,
      "name": "Webhook created on May 24, 2016 @ 03:20 AM",
      "status": "active",
      "topic": "customer.created",
      "resource": "customer",
      "event": "created",
      "hooks": [
        "user_register",
        "woocommerce_created_customer",
        "woocommerce_api_create_customer"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-15T20:17:52",
      "date_modified": "2016-05-15T20:17:52",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/webhooks/143"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/webhooks"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>

## Retrieve webhook delivery
This API lets you retrieve and view a specific webhook delivery.

```http
GET /wp-json/wc/v1/webhooks/<id>/deliveries/<delivery_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/webhooks/142/deliveries/54 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("webhooks/142/deliveries/54")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks/142/deliveries/54')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks/142/deliveries/54").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks/142/deliveries/54").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 54,
  "duration": "0.40888",
  "summary": "HTTP 200 OK: ok",
  "request_method": "POST",
  "request_url": "http://requestb.in/1g0sxmo1",
  "request_headers": {
    "User-Agent": "WooCommerce/2.6.0 Hookshot (WordPress/4.5.2)",
    "Content-Type": "application/json",
    "X-WC-Webhook-Source": "http://example.com/",
    "X-WC-Webhook-Topic": "order.updated",
    "X-WC-Webhook-Resource": "order",
    "X-WC-Webhook-Event": "updated",
    "X-WC-Webhook-Signature": "J72iu7hL93aUt2dFnyOBoBypwbmP6nt6Aor33nnOHxU=",
    "X-WC-Webhook-ID": 142,
    "X-WC-Webhook-Delivery-ID": 54
  },
  "request_body": "{\"order\":{\"id\":118,\"order_number\":118,\"order_key\":\"wc_order_5728e9a347a2d\",\"created_at\":\"2016-05-03T18:10:00Z\",\"updated_at\":\"2016-05-16T03:30:30Z\",\"completed_at\":\"2016-05-16T03:29:19Z\",\"status\":\"completed\",\"currency\":\"BRL\",\"total\":\"14.00\",\"subtotal\":\"4.00\",\"total_line_items_quantity\":2,\"total_tax\":\"0.00\",\"total_shipping\":\"10.00\",\"cart_tax\":\"0.00\",\"shipping_tax\":\"0.00\",\"total_discount\":\"0.00\",\"shipping_methods\":\"Flat Rate\",\"payment_details\":{\"method_id\":\"bacs\",\"method_title\":\"Direct Bank Transfer\",\"paid\":true},\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"},\"note\":\"\",\"customer_ip\":\"127.0.0.1\",\"customer_user_agent\":\"curl/7.47.0\",\"customer_id\":0,\"view_order_url\":\"http://example.com/my-account/view-order/118\",\"line_items\":[{\"id\":8,\"subtotal\":\"4.00\",\"subtotal_tax\":\"0.00\",\"total\":\"4.00\",\"total_tax\":\"0.00\",\"price\":\"2.00\",\"quantity\":2,\"tax_class\":null,\"name\":\"Woo Single #2\",\"product_id\":99,\"sku\":\"12345\",\"meta\":[]}],\"shipping_lines\":[{\"id\":9,\"method_id\":\"flat_rate\",\"method_title\":\"Flat Rate\",\"total\":\"10.00\"}],\"tax_lines\":[],\"fee_lines\":[],\"coupon_lines\":[],\"is_vat_exempt\":false,\"customer\":{\"id\":0,\"email\":\"john.doe@claudiosmweb.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"}}}}",
  "response_code": "200",
  "response_message": "OK",
  "response_headers": {
    "connection": "close",
    "server": "gunicorn/19.3.0",
    "date": "Tue, 16 May 2016 03:30:31 GMT",
    "content-type": "text/html; charset=utf-8",
    "content-length": "2",
    "sponsored-by": "https://www.runscope.com",
    "via": "1.1 vegur"
  },
  "response_body": "ok",
  "date_created": "2016-05-16T03:30:31",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks/142/deliveries/54"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks/142/deliveries"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v1/webhooks/142"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

:::note
View the <a href="#webhooks-delivery-properties">Webhooks Delivery properties</a> for more details on this response.
:::

## List all webhook deliveries
This API helps you view all deliveries from a specific webhook.

```http
GET /wp-json/wc/v1/webhooks/<id>/deliveries
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v1/webhooks/142/deliveries \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("webhooks/142/deliveries")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks/142/deliveries')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks/142/deliveries").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks/142/deliveries").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 54,
    "duration": "0.40888",
    "summary": "HTTP 200 OK: ok",
    "request_method": "POST",
    "request_url": "http://requestb.in/1g0sxmo1",
    "request_headers": {
      "User-Agent": "WooCommerce/2.6.0 Hookshot (WordPress/4.5.2)",
      "Content-Type": "application/json",
      "X-WC-Webhook-Source": "http://example.com/",
      "X-WC-Webhook-Topic": "order.updated",
      "X-WC-Webhook-Resource": "order",
      "X-WC-Webhook-Event": "updated",
      "X-WC-Webhook-Signature": "J72iu7hL93aUt2dFnyOBoBypwbmP6nt6Aor33nnOHxU=",
      "X-WC-Webhook-ID": 142,
      "X-WC-Webhook-Delivery-ID": 54
    },
    "request_body": "{\"order\":{\"id\":118,\"order_number\":118,\"order_key\":\"wc_order_5728e9a347a2d\",\"created_at\":\"2016-05-03T18:10:00Z\",\"updated_at\":\"2016-05-16T03:30:30Z\",\"completed_at\":\"2016-05-16T03:29:19Z\",\"status\":\"completed\",\"currency\":\"BRL\",\"total\":\"14.00\",\"subtotal\":\"4.00\",\"total_line_items_quantity\":2,\"total_tax\":\"0.00\",\"total_shipping\":\"10.00\",\"cart_tax\":\"0.00\",\"shipping_tax\":\"0.00\",\"total_discount\":\"0.00\",\"shipping_methods\":\"Flat Rate\",\"payment_details\":{\"method_id\":\"bacs\",\"method_title\":\"Direct Bank Transfer\",\"paid\":true},\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"},\"note\":\"\",\"customer_ip\":\"127.0.0.1\",\"customer_user_agent\":\"curl/7.47.0\",\"customer_id\":0,\"view_order_url\":\"http://example.com/my-account/view-order/118\",\"line_items\":[{\"id\":8,\"subtotal\":\"4.00\",\"subtotal_tax\":\"0.00\",\"total\":\"4.00\",\"total_tax\":\"0.00\",\"price\":\"2.00\",\"quantity\":2,\"tax_class\":null,\"name\":\"Woo Single #2\",\"product_id\":99,\"sku\":\"12345\",\"meta\":[]}],\"shipping_lines\":[{\"id\":9,\"method_id\":\"flat_rate\",\"method_title\":\"Flat Rate\",\"total\":\"10.00\"}],\"tax_lines\":[],\"fee_lines\":[],\"coupon_lines\":[],\"is_vat_exempt\":false,\"customer\":{\"id\":0,\"email\":\"john.doe@claudiosmweb.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"}}}}",
    "response_code": "200",
    "response_message": "OK",
    "response_headers": {
      "connection": "close",
      "server": "gunicorn/19.3.0",
      "date": "Tue, 16 May 2016 03:30:31 GMT",
      "content-type": "text/html; charset=utf-8",
      "content-length": "2",
      "sponsored-by": "https://www.runscope.com",
      "via": "1.1 vegur"
    },
    "response_body": "ok",
    "date_created": "2016-05-16T03:30:31",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks/142/deliveries/54"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks/142/deliveries"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks/142"
        }
      ]
    }
  },
  {
    "id": 53,
    "duration": "0.7615",
    "summary": "HTTP 200 OK: ok",
    "request_method": "POST",
    "request_url": "http://requestb.in/1g0sxmo1",
    "request_headers": {
      "User-Agent": "WooCommerce/2.6.0 Hookshot (WordPress/4.5.2)",
      "Content-Type": "application/json",
      "X-WC-Webhook-Source": "http://example.com/",
      "X-WC-Webhook-Topic": "order.updated",
      "X-WC-Webhook-Resource": "order",
      "X-WC-Webhook-Event": "updated",
      "X-WC-Webhook-Signature": "Z996ccyueeoqdXZFq2ND2ETpsPGrXmWKj+yvQ0c2N1w=",
      "X-WC-Webhook-ID": 142,
      "X-WC-Webhook-Delivery-ID": 53
    },
    "request_body": "{\"order\":{\"id\":118,\"order_number\":118,\"order_key\":\"wc_order_5728e9a347a2d\",\"created_at\":\"2016-05-03T18:10:00Z\",\"updated_at\":\"2016-05-16T03:29:13Z\",\"completed_at\":\"2016-05-16T03:29:19Z\",\"status\":\"completed\",\"currency\":\"BRL\",\"total\":\"14.00\",\"subtotal\":\"4.00\",\"total_line_items_quantity\":2,\"total_tax\":\"0.00\",\"total_shipping\":\"10.00\",\"cart_tax\":\"0.00\",\"shipping_tax\":\"0.00\",\"total_discount\":\"0.00\",\"shipping_methods\":\"Flat Rate\",\"payment_details\":{\"method_id\":\"bacs\",\"method_title\":\"Direct Bank Transfer\",\"paid\":true},\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"},\"note\":\"\",\"customer_ip\":\"127.0.0.1\",\"customer_user_agent\":\"curl/7.47.0\",\"customer_id\":0,\"view_order_url\":\"http://example.com/my-account/view-order/118\",\"line_items\":[{\"id\":8,\"subtotal\":\"4.00\",\"subtotal_tax\":\"0.00\",\"total\":\"4.00\",\"total_tax\":\"0.00\",\"price\":\"2.00\",\"quantity\":2,\"tax_class\":null,\"name\":\"Woo Single #2\",\"product_id\":99,\"sku\":\"12345\",\"meta\":[]}],\"shipping_lines\":[{\"id\":9,\"method_id\":\"flat_rate\",\"method_title\":\"Flat Rate\",\"total\":\"10.00\"}],\"tax_lines\":[],\"fee_lines\":[],\"coupon_lines\":[],\"is_vat_exempt\":false,\"customer\":{\"id\":0,\"email\":\"john.doe@claudiosmweb.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"}}}}",
    "response_code": "200",
    "response_message": "OK",
    "response_headers": {
      "connection": "close",
      "server": "gunicorn/19.3.0",
      "date": "Tue, 16 May 2016 03:29:20 GMT",
      "content-type": "text/html; charset=utf-8",
      "content-length": "2",
      "sponsored-by": "https://www.runscope.com",
      "via": "1.1 vegur"
    },
    "response_body": "ok",
    "date_created": "2016-05-16T03:29:19",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks/142/deliveries/53"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks/142/deliveries"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v1/webhooks/142"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>


---

## Coupons

*Source: apis/rest-api/v2/coupons.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Coupons
The coupons API allows you to create, view, update, and delete individual, or a batch, of coupon codes.

## Coupon properties
| Attribute                     | Type      | Description                                                                                                                          |
| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                          | integer   | Unique identifier for the object. `READ-ONLY`                                                          |
| `code`                        | string    | Coupon code. `MANDATORY`                                                                               |
| `amount`                      | string    | The amount of discount. Should always be numeric, even if setting a percentage.                                                      |
| `date_created`                | date-time | The date the coupon was created, in the site's timezone. `READ-ONLY`                                   |
| `date_created_gmt`            | date-time | The date the coupon was created, as GMT. `READ-ONLY`                                                   |
| `date_modified`               | date-time | The date the coupon was last modified, in the site's timezone. `READ-ONLY`                             |
| `date_modified_gmt`           | date-time | The date the coupon was last modified, as GMT. `READ-ONLY`                                             |
| `discount_type`               | string    | Determines the type of discount that will be applied. Options: `percent`, `fixed_cart` and `fixed_product`. Default is `fixed_cart`. |
| `description`                 | string    | Coupon description.                                                                                                                  |
| `date_expires`                | string    | The date the coupon expires, in the site's timezone.                                                                                 |
| `date_expires_gmt`            | string    | The date the coupon expires, as GMT.                                                                                                 |
| `usage_count`                 | integer   | Number of times the coupon has been used already. `READ-ONLY`                                          |
| `individual_use`              | boolean   | If true, the coupon can only be used individually. Other applied coupons will be removed from the cart. Default is `false`.          |
| `product_ids`                 | array     | List of product IDs the coupon can be used on.                                                                                       |
| `excluded_product_ids`        | array     | List of product IDs the coupon cannot be used on.                                                                                    |
| `usage_limit`                 | integer   | How many times the coupon can be used in total.                                                                                      |
| `usage_limit_per_user`        | integer   | How many times the coupon can be used per customer.                                                                                  |
| `limit_usage_to_x_items`      | integer   | Max number of items in the cart the coupon can be applied to.                                                                        |
| `free_shipping`               | boolean   | If true and if the free shipping method requires a coupon, this coupon will enable free shipping. Default is `false`.                |
| `product_categories`          | array     | List of category IDs the coupon applies to.                                                                                          |
| `excluded_product_categories` | array     | List of category IDs the coupon does not apply to.                                                                                   |
| `exclude_sale_items`          | boolean   | If true, this coupon will not be applied to items that have sale prices. Default is `false`.                                         |
| `minimum_amount`              | string    | Minimum order amount that needs to be in the cart before coupon applies.                                                             |
| `maximum_amount`              | string    | Maximum order amount allowed when using the coupon.                                                                                  |
| `email_restrictions`          | array     | List of email addresses that can use this coupon.                                                                                    |
| `used_by`                     | array     | List of user IDs (or guest email addresses) that have used the coupon. `READ-ONLY`                     |
| `meta_data`                   | array     | Meta data. See [Coupon - Meta data properties](#coupon---meta-data-properties)                                                         |

### Coupon - Meta data properties
| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

## Create a coupon
This API helps you to create a new coupon.

```http
POST /wp-json/wc/v2/coupons
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/coupons \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "code": "10off",
  "discount_type": "percent",
  "amount": "10",
  "individual_use": true,
  "exclude_sale_items": true,
  "minimum_amount": "100.00"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  code: "10off",
  discount_type: "percent",
  amount: "10",
  individual_use: true,
  exclude_sale_items: true,
  minimum_amount: "100.00"
};

WooCommerce.post("coupons", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'code' => '10off',
    'discount_type' => 'percent',
    'amount' => '10',
    'individual_use' => true,
    'exclude_sale_items' => true,
    'minimum_amount' => '100.00'
];

print_r($woocommerce->post('coupons', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "code": "10off",
    "discount_type": "percent",
    "amount": "10",
    "individual_use": True,
    "exclude_sale_items": True,
    "minimum_amount": "100.00"
}

print(wcapi.post("coupons", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  code: "10off",
  discount_type: "percent",
  amount: "10",
  individual_use: true,
  exclude_sale_items: true,
  minimum_amount: "100.00"
}

woocommerce.post("coupons", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 719,
  "code": "10off",
  "amount": "10.00",
  "date_created": "2017-03-21T15:23:00",
  "date_created_gmt": "2017-03-21T18:23:00",
  "date_modified": "2017-03-21T15:23:00",
  "date_modified_gmt": "2017-03-21T18:23:00",
  "discount_type": "percent",
  "description": "",
  "date_expires": null,
  "date_expires_gmt": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "excluded_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": null,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/coupons/719"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/coupons"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a coupon
This API lets you retrieve and view a specific coupon by ID.

```http
GET /wp-json/wc/v2/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/coupons/719 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("coupons/719")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('coupons/719')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("coupons/719").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("coupons/719").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 719,
  "code": "10off",
  "amount": "10.00",
  "date_created": "2017-03-21T15:23:00",
  "date_created_gmt": "2017-03-21T18:23:00",
  "date_modified": "2017-03-21T15:23:00",
  "date_modified_gmt": "2017-03-21T18:23:00",
  "discount_type": "percent",
  "description": "",
  "date_expires": null,
  "date_expires_gmt": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "excluded_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": null,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/coupons/719"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/coupons"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all coupons
This API helps you to list all the coupons that have been created.

```http
GET /wp-json/wc/v2/coupons
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/coupons \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("coupons")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('coupons')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("coupons").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("coupons").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 720,
    "code": "free shipping",
    "amount": "0.00",
    "date_created": "2017-03-21T15:25:02",
    "date_created_gmt": "2017-03-21T18:25:02",
    "date_modified": "2017-03-21T15:25:02",
    "date_modified_gmt": "2017-03-21T18:25:02",
    "discount_type": "fixed_cart",
    "description": "",
    "date_expires": null,
    "date_expires_gmt": null,
    "usage_count": 0,
    "individual_use": true,
    "product_ids": [],
    "excluded_product_ids": [],
    "usage_limit": null,
    "usage_limit_per_user": null,
    "limit_usage_to_x_items": null,
    "free_shipping": true,
    "product_categories": [],
    "excluded_product_categories": [],
    "exclude_sale_items": false,
    "minimum_amount": "0.00",
    "maximum_amount": "0.00",
    "email_restrictions": [],
    "used_by": [],
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/coupons/720"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/coupons"
        }
      ]
    }
  },
  {
    "id": 719,
    "code": "10off",
    "amount": "10.00",
    "date_created": "2017-03-21T15:23:00",
    "date_created_gmt": "2017-03-21T18:23:00",
    "date_modified": "2017-03-21T15:23:00",
    "date_modified_gmt": "2017-03-21T18:23:00",
    "discount_type": "percent",
    "description": "",
    "date_expires": null,
    "date_expires_gmt": null,
    "usage_count": 0,
    "individual_use": true,
    "product_ids": [],
    "excluded_product_ids": [],
    "usage_limit": null,
    "usage_limit_per_user": null,
    "limit_usage_to_x_items": null,
    "free_shipping": false,
    "product_categories": [],
    "excluded_product_categories": [],
    "exclude_sale_items": true,
    "minimum_amount": "100.00",
    "maximum_amount": "0.00",
    "email_restrictions": [],
    "used_by": [],
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/coupons/719"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/coupons"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter       | Type    | Description                                                                                                                  |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `context`       | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |
| `page`          | integer | Current page of the collection. Default is `1`.                                                                              |
| `per_page`      | integer | Maximum number of items to be returned in result set. Default is `10`.                                                       |
| `search`        | string  | Limit results to those matching a string.                                                                                    |
| `after`         | string  | Limit response to resources published after a given ISO8601 compliant date.                                                  |
| `before`        | string  | Limit response to resources published before a given ISO8601 compliant date.                                                 |
| `dates_are_gmt` | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                      |
| `exclude`       | array   | Ensure result set excludes specific IDs.                                                                                     |
| `include`       | array   | Limit result set to specific ids.                                                                                            |
| `offset`        | integer | Offset the result set by a specific number of items.                                                                         |
| `order`         | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                  |
| `orderby`       | string  | Sort collection by object attribute. Options: `date`, `id`, `include`, `title` and `slug`. Default is `date`.                |
| `code`          | string  | Limit result set to resources with a specific code.                                                                          |

## Update a coupon
This API lets you make changes to a coupon.

```http
PUT /wp-json/wc/v2/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/coupons/719 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "amount": "5"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  amount: "5"
};

WooCommerce.put("coupons/719", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php 
$data = [
    'amount' => '5'
];

print_r($woocommerce->put('coupons/719', $data)); 
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "amount": "5"
}

print(wcapi.put("coupons/719", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  amount: "5"
}

woocommerce.put("coupons/719", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 719,
  "code": "10off",
  "amount": "5.00",
  "date_created": "2017-03-21T15:23:00",
  "date_created_gmt": "2017-03-21T18:23:00",
  "date_modified": "2017-03-21T15:26:16",
  "date_modified_gmt": "2017-03-21T18:26:16",
  "discount_type": "percent",
  "description": "",
  "date_expires": null,
  "date_expires_gmt": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "excluded_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": null,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/coupons/719"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/coupons"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a coupon
This API helps you delete a coupon.

```http
DELETE /wp-json/wc/v2/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/coupons/719?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("coupons/719", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('coupons/719', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("coupons/719", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("coupons/719", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 719,
  "code": "10off",
  "amount": "5.00",
  "date_created": "2017-03-21T15:23:00",
  "date_created_gmt": "2017-03-21T18:23:00",
  "date_modified": "2017-03-21T15:26:16",
  "date_modified_gmt": "2017-03-21T18:26:16",
  "discount_type": "percent",
  "description": "",
  "date_expires": null,
  "date_expires_gmt": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "excluded_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": null,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/coupons/719"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/coupons"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                               Description                                |
|-----------|--------|--------------------------------------------------------------------------|
| `force`   | boolean | Use `true` to permanently delete the coupon. Default is `false`. |

## Batch update coupons
This API helps you to batch create, update and delete multiple coupons.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/coupons/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/coupons/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "code": "20off",
      "discount_type": "percent",
      "amount": "20",
      "individual_use": true,
      "exclude_sale_items": true,
      "minimum_amount": "100.00"
    },
    {
      "code": "30off",
      "discount_type": "percent",
      "amount": "30",
      "individual_use": true,
      "exclude_sale_items": true,
      "minimum_amount": "100.00"
    }
  ],
  "update": [
    {
      "id": 719,
      "minimum_amount": "50.00"
    }
  ],
  "delete": [
    720
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      code: "20off",
      discount_type: "percent",
      amount: "20",
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    },
    {
      code: "30off",
      discount_type: "percent",
      amount: "30",
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    }
  ],
  update: [
    {
      id: 719,
      minimum_amount: "50.00"
    }
  ],
  delete: [
    720
  ]
};

WooCommerce.post("coupons/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'code' => '20off',
            'discount_type' => 'percent',
            'amount' => '20',
            'individual_use' => true,
            'exclude_sale_items' => true,
            'minimum_amount' => '100.00'
        ],
        [
            'code' => '30off',
            'discount_type' => 'percent',
            'amount' => '30',
            'individual_use' => true,
            'exclude_sale_items' => true,
            'minimum_amount' => '100.00'
        ]
    ],
    'update' => [
        [
            'id' => 719,
            'minimum_amount' => '50.00'
        ]
    ],
    'delete' => [
        720
    ]
];

print_r($woocommerce->post('coupons/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "code": "20off",
            "discount_type": "percent",
            "amount": "20",
            "individual_use": True,
            "exclude_sale_items": True,
            "minimum_amount": "100.00"
        },
        {
            "code": "30off",
            "discount_type": "percent",
            "amount": "30",
            "individual_use": True,
            "exclude_sale_items": True,
            "minimum_amount": "100.00"
        }
    ],
    "update": [
        {
            "id": 719,
            "minimum_amount": "50.00"
        }
    ],
    "delete": [
        720
    ]
}

print(wcapi.post("coupons/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      code: "20off",
      discount_type: "percent",
      amount: "20",
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    },
    {
      code: "30off",
      discount_type: "percent",
      amount: "30",
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    }
  ],
  update: [
    {
      id: 719,
      minimum_amount: "50.00"
    }
  ],
  delete: [
    720
  ]
}

woocommerce.post("coupons/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 721,
      "code": "20off",
      "amount": "20.00",
      "date_created": "2017-03-21T15:27:29",
      "date_created_gmt": "2017-03-21T18:27:29",
      "date_modified": "2017-03-21T15:27:29",
      "date_modified_gmt": "2017-03-21T18:27:29",
      "discount_type": "percent",
      "description": "",
      "date_expires": null,
      "date_expires_gmt": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "excluded_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": null,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "100.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/coupons/721"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/coupons"
          }
        ]
      }
    },
    {
      "id": 722,
      "code": "30off",
      "amount": "30.00",
      "date_created": "2017-03-21T15:27:31",
      "date_created_gmt": "2017-03-21T18:27:31",
      "date_modified": "2017-03-21T15:27:31",
      "date_modified_gmt": "2017-03-21T18:27:31",
      "discount_type": "percent",
      "description": "",
      "date_expires": null,
      "date_expires_gmt": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "excluded_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": null,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "100.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/coupons/722"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/coupons"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 719,
      "code": "10off",
      "amount": "5.00",
      "date_created": "2017-03-21T15:23:00",
      "date_created_gmt": "2017-03-21T18:23:00",
      "date_modified": "2017-03-21T15:27:32",
      "date_modified_gmt": "2017-03-21T18:27:32",
      "discount_type": "percent",
      "description": "",
      "date_expires": null,
      "date_expires_gmt": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "excluded_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": null,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "50.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/coupons/719"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/coupons"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 720,
      "code": "free shipping",
      "amount": "0.00",
      "date_created": "2017-03-21T15:25:02",
      "date_created_gmt": "2017-03-21T18:25:02",
      "date_modified": "2017-03-21T15:25:02",
      "date_modified_gmt": "2017-03-21T18:25:02",
      "discount_type": "fixed_cart",
      "description": "",
      "date_expires": null,
      "date_expires_gmt": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "excluded_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": null,
      "free_shipping": true,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": false,
      "minimum_amount": "0.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/coupons/720"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/coupons"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Customers

*Source: apis/rest-api/v2/customers.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Customers
The customer API allows you to create, view, update, and delete individual, or a batch, of customers.

## Customer properties
| Attribute            | Type      | Description                                                                                                |
| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
| `id`                 | integer   | Unique identifier for the resource. `READ-ONLY`                              |
| `date_created`       | date-time | The date the customer was created, in the site's timezone. `READ-ONLY`       |
| `date_created_gmt`   | date-time | The date the customer was created, as GMT. `READ-ONLY`                       |
| `date_modified`      | date-time | The date the customer was last modified, in the site's timezone. `READ-ONLY` |
| `date_modified_gmt`  | date-time | The date the customer was last modified, as GMT. `READ-ONLY`                 |
| `email`              | string    | The email address for the customer. `MANDATORY`                              |
| `first_name`         | string    | Customer first name.                                                                                       |
| `last_name`          | string    | Customer last name.                                                                                        |
| `role`               | string    | Customer role. `READ-ONLY`                                                   |
| `username`           | string    | Customer login name.                                                                                       |
| `password`           | string    | Customer password. `WRITE-ONLY`                                              |
| `billing`            | object    | List of billing address data. See [Customer - Billing properties](#customer---billing-properties)            |
| `shipping`           | object    | List of shipping address data. See [Customer - Shipping properties](#customer---shipping-properties)         |
| `is_paying_customer` | bool      | Is the customer a paying customer? `READ-ONLY`                               |
| `orders_count`       | integer   | Quantity of orders made by the customer. `READ-ONLY`                         |
| `total_spent`        | string    | Total amount spent. `READ-ONLY`                                              |
| `avatar_url`         | string    | Avatar URL. `READ-ONLY`                                                      |
| `meta_data`          | array     | Meta data. See [Customer - Meta data properties](#customer---meta-data-properties)                           |

### Customer - Billing properties
| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1                                       |
| `address_2`  | string | Address line 2                                       |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | ISO code of the country.                             |
| `email`      | string | Email address.                                       |
| `phone`      | string | Phone number.                                        |

### Customer - Shipping properties
| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1                                       |
| `address_2`  | string | Address line 2                                       |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | ISO code of the country.                             |

### Customer - Meta data properties
| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

## Create a customer
This API helps you to create a new customer.

```http
POST /wp-json/wc/v2/customers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/customers \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "username": "john.doe",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  email: "john.doe@example.com",
  first_name: "John",
  last_name: "Doe",
  username: "john.doe",
  billing: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  }
};

WooCommerce.post("customers", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'email' => 'john.doe@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'username' => 'john.doe',
    'billing' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'company' => '',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US',
        'email' => 'john.doe@example.com',
        'phone' => '(555) 555-5555'
    ],
    'shipping' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'company' => '',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US'
    ]
];

print_r($woocommerce->post('customers', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe",
    "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
    },
    "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
    }
}

print(wcapi.post("customers", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  email: "john.doe@example.com",
  first_name: "John",
  last_name: "Doe",
  username: "john.doe",
  billing: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  }
}

woocommerce.post("customers", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 25,
  "date_created": "2017-03-21T16:09:28",
  "date_created_gmt": "2017-03-21T19:09:28",
  "date_modified": "2017-03-21T16:09:30",
  "date_modified_gmt": "2017-03-21T19:09:30",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "role": "customer",
  "username": "john.doe",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "is_paying_customer": false,
  "orders_count": 0,
  "total_spent": "0.00",
  "avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/customers/25"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/customers"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a customer
This API lets you retrieve and view a specific customer by ID.

```http
GET /wp-json/wc/v2/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/customers/25 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("customers/25")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers/25')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers/25").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers/25").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 25,
  "date_created": "2017-03-21T16:09:28",
  "date_created_gmt": "2017-03-21T19:09:28",
  "date_modified": "2017-03-21T16:09:30",
  "date_modified_gmt": "2017-03-21T19:09:30",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "role": "customer",
  "username": "john.doe",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "is_paying_customer": false,
  "orders_count": 0,
  "total_spent": "0.00",
  "avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/customers/25"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/customers"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all customers
This API helps you to view all the customers.

```http
GET /wp-json/wc/v2/customers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/customers \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("customers")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 26,
    "date_created": "2017-03-21T16:11:14",
    "date_created_gmt": "2017-03-21T19:11:14",
    "date_modified": "2017-03-21T16:11:16",
    "date_modified_gmt": "2017-03-21T19:11:16",
    "email": "joao.silva@example.com",
    "first_name": "João",
    "last_name": "Silva",
    "role": "customer",
    "username": "joao.silva",
    "billing": {
      "first_name": "João",
      "last_name": "Silva",
      "company": "",
      "address_1": "Av. Brasil, 432",
      "address_2": "",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postcode": "12345-000",
      "country": "BR",
      "email": "joao.silva@example.com",
      "phone": "(55) 5555-5555"
    },
    "shipping": {
      "first_name": "João",
      "last_name": "Silva",
      "company": "",
      "address_1": "Av. Brasil, 432",
      "address_2": "",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postcode": "12345-000",
      "country": "BR"
    },
    "is_paying_customer": false,
    "orders_count": 0,
    "total_spent": "0.00",
    "avatar_url": "https://secure.gravatar.com/avatar/be7b5febff88a2d947c3289e90cdf017?s=96",
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/customers/26"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/customers"
        }
      ]
    }
  },
  {
    "id": 25,
    "date_created": "2017-03-21T16:09:28",
    "date_created_gmt": "2017-03-21T19:09:28",
    "date_modified": "2017-03-21T16:09:30",
    "date_modified_gmt": "2017-03-21T19:09:30",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "customer",
    "username": "john.doe",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 555-5555"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    },
    "is_paying_customer": false,
    "orders_count": 0,
    "total_spent": "0.00",
    "avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/customers/25"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/customers"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter  | Type    | Description                                                                                                                                                                                 |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`  | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                                                                |
| `page`     | integer | Current page of the collection. Default is `1`.                                                                                                                                             |
| `per_page` | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                                                                      |
| `search`   | string  | Limit results to those matching a string.                                                                                                                                                   |
| `exclude`  | array   | Ensure result set excludes specific IDs.                                                                                                                                                    |
| `include`  | array   | Limit result set to specific IDs.                                                                                                                                                           |
| `offset`   | integer | Offset the result set by a specific number of items.                                                                                                                                        |
| `order`    | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                                                                  |
| `orderby`  | string  | Sort collection by object attribute. Options: `id`, `include`, `name` and `registered_date`. Default is `name`.                                                                             |
| `email`    | string  | Limit result set to resources with a specific email.                                                                                                                                        |
| `role`     | string  | Limit result set to resources with a specific role. Options: `all`, `administrator`, `editor`, `author`, `contributor`, `subscriber`, `customer` and `shop_manager`. Default is `customer`. |

## Update a customer
This API lets you make changes to a customer.

```http
PUT /wp-json/wc/v2/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/customers/25 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "first_name": "James",
  "billing": {
    "first_name": "James"
  },
  "shipping": {
    "first_name": "James"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  first_name: "James",
  billing: {
    first_name: "James"
  },
  shipping: {
    first_name: "James"
  }
};

WooCommerce.put("customers/25", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php 
$data = [
    'first_name' => 'James',
    'billing' => [
        'first_name' => 'James'
    ],
    'shipping' => [
        'first_name' => 'James'
    ]
];

print_r($woocommerce->put('customers/25', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "first_name": "James",
    "billing": {
        "first_name": "James"
    },
    "shipping": {
        "first_name": "James"
    }
}

print(wcapi.put("customers/25", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  first_name: "James",
  billing: {
    first_name: "James"
  },
  shipping: {
    first_name: "James"
  }
}

woocommerce.put("customers/25", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 25,
  "date_created": "2017-03-21T16:09:28",
  "date_created_gmt": "2017-03-21T19:09:28",
  "date_modified": "2017-03-21T16:12:28",
  "date_modified_gmt": "2017-03-21T19:12:28",
  "email": "john.doe@example.com",
  "first_name": "James",
  "last_name": "Doe",
  "role": "customer",
  "username": "john.doe",
  "billing": {
    "first_name": "James",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "James",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "is_paying_customer": false,
  "orders_count": 0,
  "total_spent": "0.00",
  "avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/customers/25"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/customers"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a customer
This API helps you delete a customer.

```http
DELETE /wp-json/wc/v2/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/customers/25?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("customers/25", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('customers/25', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("customers/25", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("customers/25", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 25,
  "date_created": "2017-03-21T16:09:28",
  "date_created_gmt": "2017-03-21T19:09:28",
  "date_modified": "2017-03-21T16:12:28",
  "date_modified_gmt": "2017-03-21T19:12:28",
  "email": "john.doe@example.com",
  "first_name": "James",
  "last_name": "Doe",
  "role": "customer",
  "username": "john.doe",
  "billing": {
    "first_name": "James",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "James",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "is_paying_customer": false,
  "orders_count": 0,
  "total_spent": "0.00",
  "avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/customers/25"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/customers"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter  |   Type  |                          Description                          |
|------------|---------|---------------------------------------------------------------|
| `force`    | boolean | Required to be `true`, as resource does not support trashing. |
| `reassign` | integer | User ID to reassign posts to.                                 |

## Batch update customers
This API helps you to batch create, update and delete multiple customers.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/customers/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/customers/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "email": "john.doe2@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "username": "john.doe2",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      }
    },
    {
      "email": "joao.silva2@example.com",
      "first_name": "João",
      "last_name": "Silva",
      "username": "joao.silva2",
      "billing": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(55) 5555-5555"
      },
      "shipping": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      }
    }
  ],
  "update": [
    {
      "id": 26,
      "billing": {
        "phone": "(11) 1111-1111"
      }
    }
  ],
  "delete": [
    25
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      email: "john.doe2@example.com",
      first_name: "John",
      last_name: "Doe",
      username: "john.doe2",
      billing: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      }
    },
    {
      email: "joao.silva2@example.com",
      first_name: "João",
      last_name: "Silva",
      username: "joao.silva2",
      billing: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR",
        email: "joao.silva@example.com",
        phone: "(55) 5555-5555"
      },
      shipping: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR"
      }
    }
  ],
  update: [
    {
      id: 26,
      billing: {
        phone: "(11) 1111-1111"
      }
    }
  ],
  delete: [
    25
  ]
};

WooCommerce.post("customers/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php 
$data = [
    'create' => [
        [
            'email' => 'john.doe2@example.com',
            'first_name' => 'John',
            'last_name' => 'Doe',
            'username' => 'john.doe2',
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'company' => '',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'company' => '',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ]
        ],
        [
            'email' => 'joao.silva2@example.com',
            'first_name' => 'João',
            'last_name' => 'Silva',
            'username' => 'joao.silva2',
            'billing' => [
                'first_name' => 'João',
                'last_name' => 'Silva',
                'company' => '',
                'address_1' => 'Av. Brasil, 432',
                'address_2' => '',
                'city' => 'Rio de Janeiro',
                'state' => 'RJ',
                'postcode' => '12345-000',
                'country' => 'BR',
                'email' => 'joao.silva@example.com',
                'phone' => '(55) 5555-5555'
            ],
            'shipping' => [
                'first_name' => 'João',
                'last_name' => 'Silva',
                'company' => '',
                'address_1' => 'Av. Brasil, 432',
                'address_2' => '',
                'city' => 'Rio de Janeiro',
                'state' => 'RJ',
                'postcode' => '12345-000',
                'country' => 'BR'
            ]
        ]
    ],
    'update' => [
        [
            'id' => 26,
            'billing' => [
                'phone' => '(11) 1111-1111'
            ]
        ]
    ],
    'delete' => [
        25
    ]
];

print_r($woocommerce->post('customers/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "email": "john.doe2@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "username": "john.doe2",
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "company": "",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "company": "",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            }
        },
        {
            "email": "joao.silva2@example.com",
            "first_name": "João",
            "last_name": "Silva",
            "username": "joao.silva2",
            "billing": {
                "first_name": "João",
                "last_name": "Silva",
                "company": "",
                "address_1": "Av. Brasil, 432",
                "address_2": "",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "postcode": "12345-000",
                "country": "BR",
                "email": "joao.silva@example.com",
                "phone": "(55) 5555-5555"
            },
            "shipping": {
                "first_name": "João",
                "last_name": "Silva",
                "company": "",
                "address_1": "Av. Brasil, 432",
                "address_2": "",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "postcode": "12345-000",
                "country": "BR"
            }
        }
    ],
    "update": [
        {
            "id": 26,
            "billing": {
                "phone": "(11) 1111-1111"
            }
        }
    ],
    "delete": [
        25
    ]
}

print(wcapi.post("customers/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      email: "john.doe2@example.com",
      first_name: "John",
      last_name: "Doe",
      username: "john.doe2",
      billing: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      }
    },
    {
      email: "joao.silva2@example.com",
      first_name: "João",
      last_name: "Silva",
      username: "joao.silva2",
      billing: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR",
        email: "joao.silva@example.com",
        phone: "(55) 5555-5555"
      },
      shipping: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR"
      }
    }
  ],
  update: [
    {
      id: 26,
      billing: {
        phone: "(11) 1111-1111"
      }
    }
  ],
  delete: [
    25
  ]
}

woocommerce.post("customers/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 27,
      "date_created": "2017-03-21T16:13:58",
      "date_created_gmt": "2017-03-21T19:13:58",
      "date_modified": "2017-03-21T16:13:59",
      "date_modified_gmt": "2017-03-21T19:13:59",
      "email": "john.doe2@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "role": "customer",
      "username": "john.doe2",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "is_paying_customer": false,
      "orders_count": 0,
      "total_spent": "0.00",
      "avatar_url": "https://secure.gravatar.com/avatar/6ad0b094bac53a85bb282ccdb3958279?s=96",
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers/27"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers"
          }
        ]
      }
    },
    {
      "id": 28,
      "date_created": "2017-03-21T16:14:00",
      "date_created_gmt": "2017-03-21T19:14:00",
      "date_modified": "2017-03-21T16:14:01",
      "date_modified_gmt": "2017-03-21T19:14:01",
      "email": "joao.silva2@example.com",
      "first_name": "João",
      "last_name": "Silva",
      "role": "customer",
      "username": "joao.silva2",
      "billing": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(55) 5555-5555"
      },
      "shipping": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      },
      "is_paying_customer": false,
      "orders_count": 0,
      "total_spent": "0.00",
      "avatar_url": "https://secure.gravatar.com/avatar/ea9ad095f2970f27cbff07e7f5e99453?s=96",
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers/28"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 26,
      "date_created": "2017-03-21T16:11:14",
      "date_created_gmt": "2017-03-21T19:11:14",
      "date_modified": "2017-03-21T16:14:03",
      "date_modified_gmt": "2017-03-21T19:14:03",
      "email": "joao.silva@example.com",
      "first_name": "João",
      "last_name": "Silva",
      "role": "customer",
      "username": "joao.silva",
      "billing": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(11) 1111-1111"
      },
      "shipping": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      },
      "is_paying_customer": false,
      "orders_count": 0,
      "total_spent": "0.00",
      "avatar_url": "https://secure.gravatar.com/avatar/be7b5febff88a2d947c3289e90cdf017?s=96",
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers/26"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 25,
      "date_created": "2017-03-21T16:09:28",
      "date_created_gmt": "2017-03-21T19:09:28",
      "date_modified": "2017-03-21T16:12:28",
      "date_modified_gmt": "2017-03-21T19:12:28",
      "email": "john.doe@example.com",
      "first_name": "James",
      "last_name": "Doe",
      "role": "customer",
      "username": "john.doe",
      "billing": {
        "first_name": "James",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "James",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "is_paying_customer": false,
      "orders_count": 0,
      "total_spent": "0.00",
      "avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers/25"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>

## Retrieve customer downloads
This API lets you retrieve customer downloads permissions.

```http
GET /wp-json/wc/v2/customers/<id>/downloads
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/customers/26/downloads \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("customers/26/downloads")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers/26/downloads')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers/26/downloads").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers/26/downloads").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "download_id": "91447fd1849316bbc89dfb7e986a6006",
    "download_url": "https://example.com/?download_file=87&order=wc_order_58d17c18352&email=joao.silva%40example.com&key=91447fd1849316bbc89dfb7e986a6006",
    "product_id": 87,
    "product_name": "Woo Album #2",
    "download_name": "Woo Album #2 &ndash; Song 2",
    "order_id": 723,
    "order_key": "wc_order_58d17c18352",
    "downloads_remaining": "3",
    "access_expires": "never",
    "access_expires_gmt": "never",
    "file": {
      "name": "Song 2",
      "file": "http://example.com/wp-content/uploads/woocommerce_uploads/2013/06/Song.mp3"
    },
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/customers/26/downloads"
        }
      ],
      "product": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/87"
        }
      ],
      "order": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

### Customer downloads properties
| Attribute             | Type    | Description                                                                                                                               |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `download_id`         | string  | Download ID (MD5). `READ-ONLY`                                                                              |
| `download_url`        | string  | Download file URL. `READ-ONLY`                                                                              |
| `product_id`          | integer | Downloadable product ID. `READ-ONLY`                                                                        |
| `product_name`        | string  | Product name. `READ-ONLY`                                                                                   |
| `download_name`       | string  | Downloadable file name. `READ-ONLY`                                                                         |
| `order_id`            | integer | Order ID. `READ-ONLY`                                                                                       |
| `order_key`           | string  | Order key. `READ-ONLY`                                                                                      |
| `downloads_remaining` | string  | Number of downloads remaining. `READ-ONLY`                                                                  |
| `access_expires`      | string  | The date when download access expires, in the site's timezone. `READ-ONLY`                                  |
| `access_expires_gmt`  | string  | The date when download access expires, as GMT. `READ-ONLY`                                                  |
| `file`                | object  | File details. `READ-ONLY` See [Customers downloads - File properties](#customer-downloads---file-properties) |

### Customer downloads - File properties
| Attribute | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `name`    | string | File name. `READ-ONLY` |
| `file`    | string | File URL. `READ-ONLY`  |


---

## REST API v2

*Source: apis/rest-api/v2/index.mdx*

import DocCardList from '@theme/DocCardList';

Legacy version of the WooCommerce REST API. Use `/wp-json/wc/v2/` endpoints. Consider migrating to v3 for new integrations.

<DocCardList />


---

## Order notes

*Source: apis/rest-api/v2/order-notes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Order notes
The order notes API allows you to create, view, and delete individual order notes.  
Order notes are added by administrators and programmatically to store data about an order, or order events.

## Order note properties
| Attribute          | Type      | Description                                                                                                                                      |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`               | integer   | Unique identifier for the resource. `READ-ONLY`                                                                    |
| `date_created`     | date-time | The date the order note was created, in the site's timezone. `READ-ONLY`                                           |
| `date_created_gmt` | date-time | The date the order note was created, as GMT. `READ-ONLY`                                                           |
| `note`             | string    | Order note content. `MANDATORY`                                                                                    |
| `customer_note`    | boolean   | If true, the note will be shown to customers and they will be notified. If false, the note will be for admin reference only. Default is `false`. |

## Create an order note
This API helps you to create a new note for an order.

```http
POST /wp-json/wc/v2/orders/<id>/notes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/orders/723/notes \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "note": "Order ok!!!"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  note: "Order ok!!!"
};

WooCommerce.post("orders/723/notes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'note' => 'Order ok!!!'
];

print_r($woocommerce->post('orders/723/notes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "note": "Order ok!!!"
}

print(wcapi.post("orders/723/notes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  note: "Order ok!!!"
}

woocommerce.post("orders/723/notes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 281,
  "date_created": "2017-03-21T16:46:41",
  "date_created_gmt": "2017-03-21T19:46:41",
  "note": "Order ok!!!",
  "customer_note": false,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/notes/281"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/notes"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve an order note
This API lets you retrieve and view a specific note from an order.

```http
GET /wp-json/wc/v2/orders/<id>/notes/<note_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/orders/723/notes/281 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/723/notes/281")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/723/notes/281')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/notes/281").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/723/notes/281").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 281,
  "date_created": "2017-03-21T16:46:41",
  "date_created_gmt": "2017-03-21T19:46:41",
  "note": "Order ok!!!",
  "customer_note": false,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/notes/281"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/notes"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all order notes
This API helps you to view all the notes from an order.

```http
GET /wp-json/wc/v2/orders/<id>/notes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/orders/723/notes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/723/notes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/723/notes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/notes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/723/notes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 281,
    "date_created": "2017-03-21T16:46:41",
    "date_created_gmt": "2017-03-21T19:46:41",
    "note": "Order ok!!!",
    "customer_note": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/notes/281"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/notes"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723"
        }
      ]
    }
  },
  {
    "id": 280,
    "date_created": "2017-03-21T16:16:58",
    "date_created_gmt": "2017-03-21T19:16:58",
    "note": "Order status changed from On hold to Completed.",
    "customer_note": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/notes/280"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/notes"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723"
        }
      ]
    }
  },
  {
    "id": 279,
    "date_created": "2017-03-21T16:16:46",
    "date_created_gmt": "2017-03-21T19:16:46",
    "note": "Awaiting BACS payment Order status changed from Pending payment to On hold.",
    "customer_note": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/notes/279"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/notes"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter  | Type    | Description                                                                                                                  |
| ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `context`  | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |
| `type`     | string  | Limit result to customers or internal notes. Options: `any`, `customer` and `internal`. Default is `any`.                    |

## Delete an order note
This API helps you delete an order note.

```http
DELETE /wp-json/wc/v2/orders/<id>/notes/<note_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/orders/723/notes/281?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("orders/723/notes/281", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/723/notes/281', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/723/notes/281", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/723/notes/281", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 281,
  "date_created": "2017-03-21T16:46:41",
  "date_created_gmt": "2017-03-21T19:46:41",
  "note": "Order ok!!!",
  "customer_note": false,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/notes/281"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/notes"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>
#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## Refunds

*Source: apis/rest-api/v2/order-refunds.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Refunds
The refunds API allows you to create, view, and delete individual refunds.

## Order refund properties
| Attribute          | Type      | Description                                                                                                                      |
|--------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------|
| `id`               | integer   | Unique identifier for the resource. `READ-ONLY`                                                    |
| `date_created`     | date-time | The date the order refund was created, in the site's timezone. `READ-ONLY`                         |
| `date_created_gmt` | date-time | The date the order refund was created, as GMT. `READ-ONLY`                                         |
| `amount`           | string    | Refund amount.                                                                                                                   |
| `reason`           | string    | Reason for refund.                                                                                                               |
| `refunded_by`      | integer   | User ID of user who created the refund.                                                                                          |
| `meta_data`        | array     | Meta data. See [Order refund - Meta data properties](#order-refund---meta-data-properties)                                         |
| `line_items`       | array     | Line items data. See [Order refund - Line items properties](#order-refund---line-items-properties)                                 |
| `api_refund`       | boolean   | When true, the payment gateway API is used to generate the refund. Default is `true`. `WRITE-ONLY` |

### Order refund - Meta data properties
| Attribute | Type    | Description                                        |
|-----------|---------|----------------------------------------------------|
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

### Order refund - Line items properties
| Attribute      | Type    | Description                                                                                                                                     |
|----------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`           | integer | Item ID. `READ-ONLY`                                                                                              |
| `name`         | string  | Product name.                                                                                                                                   |
| `product_id`   | integer | Product ID.                                                                                                                                     |
| `variation_id` | integer | Variation ID, if applicable.                                                                                                                    |
| `quantity`     | integer | Quantity ordered.                                                                                                                               |
| `tax_class`    | string  | Tax class of product.                                                                                                                           |
| `subtotal`     | string  | Line subtotal (before discounts).                                                                                                               |
| `subtotal_tax` | string  | Line subtotal tax (before discounts). `READ-ONLY`                                                                 |
| `total`        | string  | Line total (after discounts).                                                                                                                   |
| `total_tax`    | string  | Line total tax (after discounts). `READ-ONLY`                                                                     |
| `taxes`        | array   | Line taxes. See [Order refund line item - Taxes properties](#order-refund-line-item---taxes-properties) `READ-ONLY` |
| `meta_data`    | array   | Meta data. See [Order refund - Meta data properties](#order-refund---meta-data-properties)                                                        |
| `sku`          | string  | Product SKU. `READ-ONLY`                                                                                          |
| `price`        | string  | Product price. `READ-ONLY`                                                                                        |

#### Order refund line item - Taxes properties
| Attribute  | Type    | Description                                             |
|------------|---------|---------------------------------------------------------|
| `id`       | integer | Tax rate ID. `READ-ONLY`  |
| `total`    | string  | Tax total. `READ-ONLY`    |
| `subtotal` | string  | Tax subtotal. `READ-ONLY` |

## Create a refund
This API helps you to create a new refund for an order.

```http
POST /wp-json/wc/v2/orders/<id>/refunds
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/orders/723/refunds \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "amount": "10"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  amount: "10"
};

WooCommerce.post("orders/723/refunds", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'amount' => '10'
];

print_r($woocommerce->post('orders/723/refunds', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "amount": "10"
}

print(wcapi.post("orders/723/refunds", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  amount: "10"
}

woocommerce.post("orders/723/refunds", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 726,
  "date_created": "2017-03-21T17:07:11",
  "date_created_gmt": "2017-03-21T20:07:11",
  "amount": "10.00",
  "reason": "",
  "meta_data": [],
  "line_items": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/refunds/726"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/refunds"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a refund
This API lets you retrieve and view a specific refund from an order.

```http
GET /wp-json/wc/v2/orders/<id>/refunds/<refund_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/orders/723/refunds/726 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/723/refunds/726")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/723/refunds/726')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/refunds/726").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/723/refunds/726").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 726,
  "date_created": "2017-03-21T17:07:11",
  "date_created_gmt": "2017-03-21T20:07:11",
  "amount": "10.00",
  "reason": "",
  "meta_data": [],
  "line_items": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/refunds/726"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/refunds"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter | Type   | Description                                       |
|-----------|--------|---------------------------------------------------|
| `dp`      | integer | Number of decimal points to use in each resource. |

## List all refunds
This API helps you to view all the refunds from an order.

```http
GET /wp-json/wc/v2/orders/<id>/refunds
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/orders/723/refunds \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/723/refunds")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/723/refunds')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/refunds").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/723/refunds").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 726,
    "date_created": "2017-03-21T17:07:11",
    "date_created_gmt": "2017-03-21T20:07:11",
    "amount": "10.00",
    "reason": "",
    "refunded_by": 1,
    "meta_data": [],
    "line_items": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/refunds/726"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/refunds"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723"
        }
      ]
    }
  },
  {
    "id": 724,
    "date_created": "2017-03-21T16:55:37",
    "date_created_gmt": "2017-03-21T19:55:37",
    "amount": "9.00",
    "reason": "",
    "refunded_by": 1,
    "meta_data": [],
    "line_items": [
      {
        "id": 314,
        "name": "Woo Album #2",
        "product_id": 87,
        "variation_id": 0,
        "quantity": -1,
        "tax_class": "",
        "subtotal": "-9.00",
        "subtotal_tax": "0.00",
        "total": "-9.00",
        "total_tax": "0.00",
        "taxes": [],
        "meta_data": [
          {
            "id": 2076,
            "key": "_refunded_item_id",
            "value": "311"
          }
        ],
        "sku": "",
        "price": -9
      }
    ],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/refunds/724"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723/refunds"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter        | Type    | Description                                                                                                                  |
|------------------|---------|------------------------------------------------------------------------------------------------------------------------------|
| `context`        | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |
| `page`           | integer | Current page of the collection. Default is `1`.                                                                              |
| `per_page`       | integer | Maximum number of items to be returned in result set. Default is `10`.                                                       |
| `search`         | string  | Limit results to those matching a string.                                                                                    |
| `after`          | string  | Limit response to resources published after a given ISO8601 compliant date.                                                  |
| `before`         | string  | Limit response to resources published before a given ISO8601 compliant date.                                                 |
| `dates_are_gmt`  | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                     |
| `exclude`        | array   | Ensure result set excludes specific IDs.                                                                                     |
| `include`        | array   | Limit result set to specific ids.                                                                                            |
| `offset`         | integer | Offset the result set by a specific number of items.                                                                         |
| `order`          | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                  |
| `orderby`        | string  | Sort collection by object attribute. Options: `date`, `id`, `include`, `title` and `slug`. Default is `date`.                |
| `parent`         | array   | Limit result set to those of particular parent IDs.                                                                          |
| `parent_exclude` | array   | Limit result set to all items except those of a particular parent ID.                                                        |
| `dp`             | integer | Number of decimal points to use in each resource. Default is `2`.                                                            |

## Delete a refund
This API helps you delete an order refund.

```http
DELETE /wp-json/wc/v2/orders/<id>/refunds/<refund_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/orders/723/refunds/726?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("orders/723/refunds/726", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/723/refunds/726', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/723/refunds/726", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/723/refunds/726", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 726,
  "date_created": "2017-03-21T17:07:11",
  "date_created_gmt": "2017-03-21T20:07:11",
  "amount": "10.00",
  "reason": "",
  "meta_data": [],
  "line_items": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/refunds/726"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723/refunds"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/723"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter | Type   | Description                                                   |
|-----------|--------|---------------------------------------------------------------|
| `force`   | boolean | Required to be `true`, as resource does not support trashing. |


---

## Orders

*Source: apis/rest-api/v2/orders.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Orders
The orders API allows you to create, view, update, and delete individual, or a batch, of orders.

## Order properties
| Attribute              | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                   | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `parent_id`            | integer   | Parent order ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `number`               | string    | Order number. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `order_key`            | string    | Order key. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `created_via`          | string    | Shows where the order was created. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `version`              | string    | Version of WooCommerce which last updated the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `status`               | string    | Order status. Options: `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded`, `failed` and `trash`. Default is `pending`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `currency`             | string    | Currency the order was created with, in ISO format. Options: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BRL`, `BSD`, `BTC`, `BTN`, `BWP`, `BYR`, `BZD`, `CAD`, `CDF`, `CHF`, `CLP`, `CNY`, `COP`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GGP`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `IMP`, `INR`, `IQD`, `IRR`, `IRT`, `ISK`, `JEP`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRO`, `MUR`, `MVR`, `MWK`, `MXN`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PRB`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `STD`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `UYU`, `UZS`, `VEF`, `VND`, `VUV`, `WST`, `XAF`, `XCD`, `XOF`, `XPF`, `YER`, `ZAR` and `ZMW`. Default is `USD`. |
| `date_created`         | date-time | The date the order was created, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `date_created_gmt`     | date-time | The date the order was created, as GMT. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `date_modified`        | date-time | The date the order was last modified, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `date_modified_gmt`    | date-time | The date the order was last modified, as GMT. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `discount_total`       | string    | Total discount amount for the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `discount_tax`         | string    | Total discount tax amount for the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `shipping_total`       | string    | Total shipping amount for the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `shipping_tax`         | string    | Total shipping tax amount for the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `cart_tax`             | string    | Sum of line item taxes only. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `total`                | string    | Grand total. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `total_tax`            | string    | Sum of all taxes. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `prices_include_tax`   | boolean   | True the prices included tax during checkout. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `customer_id`          | integer   | User ID who owns the order. 0 for guests. Default is `0`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `customer_ip_address`  | string    | Customer's IP address. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `customer_user_agent`  | string    | User agent of the customer. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `customer_note`        | string    | Note left by customer during checkout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `billing`              | object    | Billing address. See [Order - Billing properties](#order---billing-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `shipping`             | object    | Shipping address. See [Order - Shipping properties](#order---shipping-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `payment_method`       | string    | Payment method ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `payment_method_title` | string    | Payment method title.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `transaction_id`       | string    | Unique transaction ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `date_paid`            | date-time | The date the order was paid, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `date_paid_gmt`        | date-time | The date the order was paid, as GMT. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `date_completed`       | date-time | The date the order was completed, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `date_completed_gmt`   | date-time | The date the order was completed, as GMT. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `cart_hash`            | string    | MD5 hash of cart items to ensure orders are not modified. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `meta_data`            | array     | Meta data. See [Order - Meta data properties](#order---meta-data-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `line_items`           | array     | Line items data. See [Order - Line items properties](#order---line-items-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `tax_lines`            | array     | Tax lines data. See [Order - Tax lines properties](#order---tax-lines-properties) `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `shipping_lines`       | array     | Shipping lines data. See [Order - Shipping lines properties](#order---shipping-lines-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `fee_lines`            | array     | Fee lines data. See [Order - Fee lines properties](#order---fee-lines-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `coupon_lines`         | array     | Coupons line data. See [Order - Coupon lines properties](#order---coupon-lines-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `refunds`              | array     | List of refunds. See [Order - Refunds properties](#order---refunds-properties) `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `set_paid`             | boolean   | Define if the order is paid. It will set the status to processing and reduce stock items. Default is `false`. `WRITE-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Order - Billing properties
| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1                                       |
| `address_2`  | string | Address line 2                                       |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | Country code in ISO 3166-1 alpha-2 format.           |
| `email`      | string | Email address.                                       |
| `phone`      | string | Phone number.                                        |

### Order - Shipping properties
| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1                                       |
| `address_2`  | string | Address line 2                                       |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | Country code in ISO 3166-1 alpha-2 format.           |

### Order - Meta data properties
| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

### Order - Line items properties

| Attribute      | Type    | Description                                                                                                   |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `id`           | integer | Item ID. `READ-ONLY`                                                            |
| `name`         | string  | Product name.                                                                                                 |
| `parent_name`  | string or null | Parent product name if the product is a variation; otherwise `null`.                                      |
| `product_id`   | integer | Product ID.                                                                                                   |
| `variation_id` | integer | Variation ID, if applicable.                                                                                  |
| `quantity`     | integer | Quantity ordered.                                                                                             |
| `tax_class`    | integer | Tax class of product.                                                                                         |
| `subtotal`     | string  | Line subtotal (before discounts).                                                                             |
| `subtotal_tax` | string  | Line subtotal tax (before discounts). `READ-ONLY`                               |
| `total`        | string  | Line total (after discounts).                                                                                 |
| `total_tax`    | string  | Line total tax (after discounts). `READ-ONLY`                                   |
| `taxes`        | array   | Line taxes. See [Order - Taxes properties](#order---taxes-properties) `READ-ONLY` |
| `meta_data`    | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)                                    |
| `sku`          | string  | Product SKU. `READ-ONLY`                                                        |
| `global_unique_id` | string or null | Product GTIN, UPC, EAN or ISBN. An empty string if not set, or `null` if the product no longer exists. `READ-ONLY` |
| `price`        | string  | Product price. `READ-ONLY`                                                      |
| `image`        | object  | Main product image. See [Order - Line item image properties](#order---line-item-image-properties). `READ-ONLY` |

### Order - Line item image properties

| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | integer or string | Image attachment ID, returned as an integer or numeric string. An empty string or `0` if no image is set; `0` if the product no longer exists. `READ-ONLY` |
| `src` | string or boolean | Full-size image URL. An empty string if no image is set or the product no longer exists, or `false` if the attachment cannot be resolved. `READ-ONLY` |

### Order - Tax lines properties
| Attribute            | Type    | Description                                                                         |
| -------------------- | ------- | ----------------------------------------------------------------------------------- |
| `id`                 | integer | Item ID. `READ-ONLY`                                  |
| `rate_code`          | string  | Tax rate code. `READ-ONLY`                            |
| `rate_id`            | string  | Tax rate ID. `READ-ONLY`                              |
| `label`              | string  | Tax rate label. `READ-ONLY`                           |
| `compound`           | boolean | Show if is a compound tax rate. `READ-ONLY`           |
| `tax_total`          | string  | Tax total (not including shipping taxes). `READ-ONLY` |
| `shipping_tax_total` | string  | Shipping tax total. `READ-ONLY`                       |
| `meta_data`          | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)          |

### Order - Shipping lines properties
| Attribute      | Type    | Description                                                                                                   |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `id`           | integer | Item ID. `READ-ONLY`                                                            |
| `method_title` | string  | Shipping method name.                                                                                         |
| `method_id`    | string  | Shipping method ID.                                                                                           |
| `total`        | string  | Line total (after discounts).                                                                                 |
| `total_tax`    | string  | Line total tax (after discounts). `READ-ONLY`                                   |
| `taxes`        | array   | Line taxes. See [Order - Taxes properties](#order---taxes-properties) `READ-ONLY` |
| `meta_data`    | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)                                    |

### Order - Fee lines properties
| Attribute    | Type    | Description                                                                                                   |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------- |
| `id`         | integer | Item ID. `READ-ONLY`                                                            |
| `name`       | string  | Fee name.                                                                                                     |
| `tax_class`  | string  | Tax class of fee.                                                                                             |
| `tax_status` | string  | Tax status of fee. Options: `taxable` and `none`.                                                             |
| `total`      | string  | Line total (after discounts).                                                                                 |
| `total_tax`  | string  | Line total tax (after discounts). `READ-ONLY`                                   |
| `taxes`      | array   | Line taxes. See [Order - Taxes properties](#order---taxes-properties) `READ-ONLY` |
| `meta_data`  | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)                                    |

### Order - Coupon lines properties
| Attribute      | Type    | Description                                                                |
| -------------- | ------- | -------------------------------------------------------------------------- |
| `id`           | integer | Item ID. `READ-ONLY`                         |
| `code`         | string  | Coupon code.                                                               |
| `discount`     | string  | Discount total.                                                            |
| `discount_tax` | string  | Discount total tax. `READ-ONLY`              |
| `meta_data`    | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties) |

### Order - Refunds properties
| Attribute | Type    | Description                                              |
| --------- | ------- | -------------------------------------------------------- |
| `id`      | integer | Refund ID. `READ-ONLY`     |
| `reason`  | string  | Refund reason. `READ-ONLY` |
| `total`   | string  | Refund total. `READ-ONLY`  |

### Order - Taxes properties
| Attribute            | Type    | Description                                                                         |
|----------------------|---------|-------------------------------------------------------------------------------------|
| `id`                 | integer | Item ID. `READ-ONLY`                                  |
| `rate_code`          | string  | Tax rate code. `READ-ONLY`                            |
| `rate_id`            | string  | Tax rate ID. `READ-ONLY`                              |
| `label`              | string  | Tax rate label. `READ-ONLY`                           |
| `compound`           | boolean | Show if is a compound tax rate. `READ-ONLY`           |
| `tax_total`          | string  | Tax total (not including shipping taxes). `READ-ONLY` |
| `shipping_tax_total` | string  | Shipping tax total. `READ-ONLY`                       |
| `meta_data`          | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)          |

## Create an order
This API helps you to create a new order.

```http
POST /wp-json/wc/v2/orders
```

> Example of create a paid order:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/orders \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "line_items": [
    {
      "product_id": 93,
      "quantity": 2
    },
    {
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1
    }
  ],
  "shipping_lines": [
    {
      "method_id": "flat_rate",
      "method_title": "Flat Rate",
      "total": "10.00"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  payment_method: "bacs",
  payment_method_title: "Direct Bank Transfer",
  set_paid: true,
  billing: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  },
  line_items: [
    {
      product_id: 93,
      quantity: 2
    },
    {
      product_id: 22,
      variation_id: 23,
      quantity: 1
    }
  ],
  shipping_lines: [
    {
      method_id: "flat_rate",
      method_title: "Flat Rate",
      total: "10.00"
    }
  ]
};

WooCommerce.post("orders", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'payment_method' => 'bacs',
    'payment_method_title' => 'Direct Bank Transfer',
    'set_paid' => true,
    'billing' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US',
        'email' => 'john.doe@example.com',
        'phone' => '(555) 555-5555'
    ],
    'shipping' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US'
    ],
    'line_items' => [
        [
            'product_id' => 93,
            'quantity' => 2
        ],
        [
            'product_id' => 22,
            'variation_id' => 23,
            'quantity' => 1
        ]
    ],
    'shipping_lines' => [
        [
            'method_id' => 'flat_rate',
            'method_title' => 'Flat Rate',
            'total' => '10.00'
        ]
    ]
];

print_r($woocommerce->post('orders', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "payment_method": "bacs",
    "payment_method_title": "Direct Bank Transfer",
    "set_paid": True,
    "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
    },
    "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
    },
    "line_items": [
        {
            "product_id": 93,
            "quantity": 2
        },
        {
            "product_id": 22,
            "variation_id": 23,
            "quantity": 1
        }
    ],
    "shipping_lines": [
        {
            "method_id": "flat_rate",
            "method_title": "Flat Rate",
            "total": '10.00'
        }
    ]
}

print(wcapi.post("orders", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  payment_method: "bacs",
  payment_method_title: "Direct Bank Transfer",
  set_paid: true,
  billing: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  },
  line_items: [
    {
      product_id: 93,
      quantity: 2
    },
    {
      product_id: 22,
      variation_id: 23,
      quantity: 1
    }
  ],
  shipping_lines: [
    {
      method_id: "flat_rate",
      method_title: "Flat Rate",
      total: '10.00'
    }
  ]
}

woocommerce.post("orders", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 727,
  "parent_id": 0,
  "number": "727",
  "order_key": "wc_order_58d2d042d1d",
  "created_via": "rest-api",
  "version": "3.0.0",
  "status": "processing",
  "currency": "USD",
  "date_created": "2017-03-22T16:28:02",
  "date_created_gmt": "2017-03-22T19:28:02",
  "date_modified": "2017-03-22T16:28:08",
  "date_modified_gmt": "2017-03-22T19:28:08",
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "10.00",
  "shipping_tax": "0.00",
  "cart_tax": "1.35",
  "total": "29.35",
  "total_tax": "1.35",
  "prices_include_tax": false,
  "customer_id": 0,
  "customer_ip_address": "",
  "customer_user_agent": "",
  "customer_note": "",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "transaction_id": "",
  "date_paid": "2017-03-22T16:28:08",
  "date_paid_gmt": "2017-03-22T19:28:08",
  "date_completed": null,
  "date_completed_gmt": null,
  "cart_hash": "",
  "meta_data": [
    {
      "id": 13106,
      "key": "_download_permissions_granted",
      "value": "yes"
    }
  ],
  "line_items": [
    {
      "id": 315,
      "name": "Woo Single #1",
      "product_id": 93,
      "variation_id": 0,
      "quantity": 2,
      "tax_class": "",
      "subtotal": "6.00",
      "subtotal_tax": "0.45",
      "total": "6.00",
      "total_tax": "0.45",
      "taxes": [
        {
          "id": 75,
          "total": "0.45",
          "subtotal": "0.45"
        }
      ],
      "meta_data": [],
      "sku": "",
      "price": 3
    },
    {
      "id": 316,
      "name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1,
      "tax_class": "",
      "subtotal": "12.00",
      "subtotal_tax": "0.90",
      "total": "12.00",
      "total_tax": "0.90",
      "taxes": [
        {
          "id": 75,
          "total": "0.9",
          "subtotal": "0.9"
        }
      ],
      "meta_data": [
        {
          "id": 2095,
          "key": "pa_color",
          "value": "black"
        },
        {
          "id": 2096,
          "key": "size",
          "value": "M Test"
        }
      ],
      "sku": "Bar3",
      "price": 12
    }
  ],
  "tax_lines": [
    {
      "id": 318,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": 75,
      "label": "State Tax",
      "compound": false,
      "tax_total": "1.35",
      "shipping_tax_total": "0.00",
      "meta_data": []
    }
  ],
  "shipping_lines": [
    {
      "id": 317,
      "method_title": "Flat Rate",
      "method_id": "flat_rate",
      "total": "10.00",
      "total_tax": "0.00",
      "taxes": [],
      "meta_data": []
    }
  ],
  "fee_lines": [],
  "coupon_lines": [],
  "refunds": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/727"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve an order
This API lets you retrieve and view a specific order.

```http
GET /wp-json/wc/v2/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/orders/727 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders/727")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/727')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/727").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/727").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 727,
  "parent_id": 0,
  "number": "727",
  "order_key": "wc_order_58d2d042d1d",
  "created_via": "rest-api",
  "version": "3.0.0",
  "status": "processing",
  "currency": "USD",
  "date_created": "2017-03-22T16:28:02",
  "date_created_gmt": "2017-03-22T19:28:02",
  "date_modified": "2017-03-22T16:28:08",
  "date_modified_gmt": "2017-03-22T19:28:08",
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "10.00",
  "shipping_tax": "0.00",
  "cart_tax": "1.35",
  "total": "29.35",
  "total_tax": "1.35",
  "prices_include_tax": false,
  "customer_id": 0,
  "customer_ip_address": "",
  "customer_user_agent": "",
  "customer_note": "",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "transaction_id": "",
  "date_paid": "2017-03-22T16:28:08",
  "date_paid_gmt": "2017-03-22T19:28:08",
  "date_completed": null,
  "date_completed_gmt": null,
  "cart_hash": "",
  "meta_data": [
    {
      "id": 13106,
      "key": "_download_permissions_granted",
      "value": "yes"
    }
  ],
  "line_items": [
    {
      "id": 315,
      "name": "Woo Single #1",
      "product_id": 93,
      "variation_id": 0,
      "quantity": 2,
      "tax_class": "",
      "subtotal": "6.00",
      "subtotal_tax": "0.45",
      "total": "6.00",
      "total_tax": "0.45",
      "taxes": [
        {
          "id": 75,
          "total": "0.45",
          "subtotal": "0.45"
        }
      ],
      "meta_data": [],
      "sku": "",
      "price": 3
    },
    {
      "id": 316,
      "name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1,
      "tax_class": "",
      "subtotal": "12.00",
      "subtotal_tax": "0.90",
      "total": "12.00",
      "total_tax": "0.90",
      "taxes": [
        {
          "id": 75,
          "total": "0.9",
          "subtotal": "0.9"
        }
      ],
      "meta_data": [
        {
          "id": 2095,
          "key": "pa_color",
          "value": "black"
        },
        {
          "id": 2096,
          "key": "size",
          "value": "M Test"
        }
      ],
      "sku": "Bar3",
      "price": 12
    }
  ],
  "tax_lines": [
    {
      "id": 318,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": 75,
      "label": "State Tax",
      "compound": false,
      "tax_total": "1.35",
      "shipping_tax_total": "0.00",
      "meta_data": []
    }
  ],
  "shipping_lines": [
    {
      "id": 317,
      "method_title": "Flat Rate",
      "method_id": "flat_rate",
      "total": "10.00",
      "total_tax": "0.00",
      "taxes": [],
      "meta_data": []
    }
  ],
  "fee_lines": [],
  "coupon_lines": [],
  "refunds": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/727"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                    Description                    |
|-----------|--------|---------------------------------------------------|
| `dp`      | string | Number of decimal points to use in each resource. |

## List all orders
This API helps you to view all the orders.

```http
GET /wp-json/wc/v2/orders
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/orders \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("orders")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 727,
    "parent_id": 0,
    "number": "727",
    "order_key": "wc_order_58d2d042d1d",
    "created_via": "rest-api",
    "version": "3.0.0",
    "status": "processing",
    "currency": "USD",
    "date_created": "2017-03-22T16:28:02",
    "date_created_gmt": "2017-03-22T19:28:02",
    "date_modified": "2017-03-22T16:28:08",
    "date_modified_gmt": "2017-03-22T19:28:08",
    "discount_total": "0.00",
    "discount_tax": "0.00",
    "shipping_total": "10.00",
    "shipping_tax": "0.00",
    "cart_tax": "1.35",
    "total": "29.35",
    "total_tax": "1.35",
    "prices_include_tax": false,
    "customer_id": 0,
    "customer_ip_address": "",
    "customer_user_agent": "",
    "customer_note": "",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 555-5555"
    },
    "shipping": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    },
    "payment_method": "bacs",
    "payment_method_title": "Direct Bank Transfer",
    "transaction_id": "",
    "date_paid": "2017-03-22T16:28:08",
    "date_paid_gmt": "2017-03-22T19:28:08",
    "date_completed": null,
    "date_completed_gmt": null,
    "cart_hash": "",
    "meta_data": [
      {
        "id": 13106,
        "key": "_download_permissions_granted",
        "value": "yes"
      },
      {
        "id": 13109,
        "key": "_order_stock_reduced",
        "value": "yes"
      }
    ],
    "line_items": [
      {
        "id": 315,
        "name": "Woo Single #1",
        "product_id": 93,
        "variation_id": 0,
        "quantity": 2,
        "tax_class": "",
        "subtotal": "6.00",
        "subtotal_tax": "0.45",
        "total": "6.00",
        "total_tax": "0.45",
        "taxes": [
          {
            "id": 75,
            "total": "0.45",
            "subtotal": "0.45"
          }
        ],
        "meta_data": [],
        "sku": "",
        "price": 3
      },
      {
        "id": 316,
        "name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
        "product_id": 22,
        "variation_id": 23,
        "quantity": 1,
        "tax_class": "",
        "subtotal": "12.00",
        "subtotal_tax": "0.90",
        "total": "12.00",
        "total_tax": "0.90",
        "taxes": [
          {
            "id": 75,
            "total": "0.9",
            "subtotal": "0.9"
          }
        ],
        "meta_data": [
          {
            "id": 2095,
            "key": "pa_color",
            "value": "black"
          },
          {
            "id": 2096,
            "key": "size",
            "value": "M Test"
          }
        ],
        "sku": "Bar3",
        "price": 12
      }
    ],
    "tax_lines": [
      {
        "id": 318,
        "rate_code": "US-CA-STATE TAX",
        "rate_id": 75,
        "label": "State Tax",
        "compound": false,
        "tax_total": "1.35",
        "shipping_tax_total": "0.00",
        "meta_data": []
      }
    ],
    "shipping_lines": [
      {
        "id": 317,
        "method_title": "Flat Rate",
        "method_id": "flat_rate",
        "total": "10.00",
        "total_tax": "0.00",
        "taxes": [],
        "meta_data": []
      }
    ],
    "fee_lines": [],
    "coupon_lines": [],
    "refunds": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/727"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders"
        }
      ]
    }
  },
  {
    "id": 723,
    "parent_id": 0,
    "number": "723",
    "order_key": "wc_order_58d17c18352",
    "created_via": "checkout",
    "version": "3.0.0",
    "status": "completed",
    "currency": "USD",
    "date_created": "2017-03-21T16:16:00",
    "date_created_gmt": "2017-03-21T19:16:00",
    "date_modified": "2017-03-21T16:54:51",
    "date_modified_gmt": "2017-03-21T19:54:51",
    "discount_total": "0.00",
    "discount_tax": "0.00",
    "shipping_total": "10.00",
    "shipping_tax": "0.00",
    "cart_tax": "0.00",
    "total": "39.00",
    "total_tax": "0.00",
    "prices_include_tax": false,
    "customer_id": 26,
    "customer_ip_address": "127.0.0.1",
    "customer_user_agent": "mozilla/5.0 (x11; ubuntu; linux x86_64; rv:52.0) gecko/20100101 firefox/52.0",
    "customer_note": "",
    "billing": {
      "first_name": "João",
      "last_name": "Silva",
      "company": "",
      "address_1": "Av. Brasil, 432",
      "address_2": "",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postcode": "12345-000",
      "country": "BR",
      "email": "joao.silva@example.com",
      "phone": "(11) 1111-1111"
    },
    "shipping": {
      "first_name": "João",
      "last_name": "Silva",
      "company": "",
      "address_1": "Av. Brasil, 432",
      "address_2": "",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postcode": "12345-000",
      "country": "BR"
    },
    "payment_method": "bacs",
    "payment_method_title": "Direct bank transfer",
    "transaction_id": "",
    "date_paid": null,
    "date_paid_gmt": null,
    "date_completed": "2017-03-21T16:54:51",
    "date_completed_gmt": "2017-03-21T19:54:51",
    "cart_hash": "5040ce7273261e31d8bcf79f9be3d279",
    "meta_data": [
      {
        "id": 13023,
        "key": "_download_permissions_granted",
        "value": "yes"
      }
    ],
    "line_items": [
      {
        "id": 311,
        "name": "Woo Album #2",
        "product_id": 87,
        "variation_id": 0,
        "quantity": 1,
        "tax_class": "",
        "subtotal": "9.00",
        "subtotal_tax": "0.00",
        "total": "9.00",
        "total_tax": "0.00",
        "taxes": [],
        "meta_data": [],
        "sku": "",
        "price": 9
      },
      {
        "id": 313,
        "name": "Woo Ninja",
        "product_id": 34,
        "variation_id": 0,
        "quantity": 1,
        "tax_class": "",
        "subtotal": "20.00",
        "subtotal_tax": "0.00",
        "total": "20.00",
        "total_tax": "0.00",
        "taxes": [],
        "meta_data": [],
        "sku": "",
        "price": 20
      }
    ],
    "tax_lines": [],
    "shipping_lines": [
      {
        "id": 312,
        "method_title": "Flat rate",
        "method_id": "flat_rate:25",
        "total": "10.00",
        "total_tax": "0.00",
        "taxes": [],
        "meta_data": [
          {
            "id": 2057,
            "key": "Items",
            "value": "Woo Album #2 &times; 1"
          }
        ]
      }
    ],
    "fee_lines": [],
    "coupon_lines": [],
    "refunds": [
      {
        "id": 726,
        "refund": "",
        "total": "-10.00"
      },
      {
        "id": 724,
        "refund": "",
        "total": "-9.00"
      }
    ],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders/723"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/orders"
        }
      ],
      "customer": [
        {
          "href": "https://example.com/wp-json/wc/v2/customers/26"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter        | Type    | Description                                                                                                                                                                     |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`        | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                                                    |
| `page`           | integer | Current page of the collection. Default is `1`.                                                                                                                                 |
| `per_page`       | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                                                          |
| `search`         | string  | Limit results to those matching a string.                                                                                                                                       |
| `after`          | string  | Limit response to resources published after a given ISO8601 compliant date.                                                                                                     |
| `before`         | string  | Limit response to resources published before a given ISO8601 compliant date.                                                                                                    |
| `dates_are_gmt`  | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                                                                        |
| `exclude`        | array   | Ensure result set excludes specific IDs.                                                                                                                                        |
| `include`        | array   | Limit result set to specific ids.                                                                                                                                               |
| `offset`         | integer | Offset the result set by a specific number of items.                                                                                                                            |
| `order`          | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                                                                     |
| `orderby`        | string  | Sort collection by object attribute. Options: `date`, `id`, `include`, `title` and `slug`. Default is `date`.                                                                   |
| `parent`         | array   | Limit result set to those of particular parent IDs.                                                                                                                             |
| `parent_exclude` | array   | Limit result set to all items except those of a particular parent ID.                                                                                                           |
| `status`         | string  | Limit result set to orders assigned a specific status. Options: `any`, `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded` and `failed`. Default is `any`. |
| `customer`       | integer | Limit result set to orders assigned a specific customer.                                                                                                                        |
| `product`        | integer | Limit result set to orders assigned a specific product.                                                                                                                         |
| `dp`             | integer | Number of decimal points to use in each resource. Default is `2`.                                                                                                               |

## Update an Order
This API lets you make changes to an order.

### HTTP Request
```http
PUT /wp-json/wc/v2/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/orders/727 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "status": "completed"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  status: "completed"
};

WooCommerce.put("orders/727", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'status' => 'completed'
];

print_r($woocommerce->put('orders/727', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "status": "completed"
}

print(wcapi.put("orders/727", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  status: "completed"
}

woocommerce.put("orders/727", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 727,
  "parent_id": 0,
  "number": "727",
  "order_key": "wc_order_58d2d042d1d",
  "created_via": "rest-api",
  "version": "3.0.0",
  "status": "completed",
  "currency": "USD",
  "date_created": "2017-03-22T16:28:02",
  "date_created_gmt": "2017-03-22T19:28:02",
  "date_modified": "2017-03-22T16:30:35",
  "date_modified_gmt": "2017-03-22T19:30:35",
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "10.00",
  "shipping_tax": "0.00",
  "cart_tax": "1.35",
  "total": "29.35",
  "total_tax": "1.35",
  "prices_include_tax": false,
  "customer_id": 0,
  "customer_ip_address": "",
  "customer_user_agent": "",
  "customer_note": "",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "transaction_id": "",
  "date_paid": "2017-03-22T16:28:08",
  "date_paid_gmt": "2017-03-22T19:28:08",
  "date_completed": "2017-03-22T16:30:35",
  "date_completed_gmt": "2017-03-22T19:30:35",
  "cart_hash": "",
  "meta_data": [
    {
      "id": 13106,
      "key": "_download_permissions_granted",
      "value": "yes"
    },
    {
      "id": 13109,
      "key": "_order_stock_reduced",
      "value": "yes"
    }
  ],
  "line_items": [
    {
      "id": 315,
      "name": "Woo Single #1",
      "product_id": 93,
      "variation_id": 0,
      "quantity": 2,
      "tax_class": "",
      "subtotal": "6.00",
      "subtotal_tax": "0.45",
      "total": "6.00",
      "total_tax": "0.45",
      "taxes": [
        {
          "id": 75,
          "total": "0.45",
          "subtotal": "0.45"
        }
      ],
      "meta_data": [],
      "sku": "",
      "price": 3
    },
    {
      "id": 316,
      "name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1,
      "tax_class": "",
      "subtotal": "12.00",
      "subtotal_tax": "0.90",
      "total": "12.00",
      "total_tax": "0.90",
      "taxes": [
        {
          "id": 75,
          "total": "0.9",
          "subtotal": "0.9"
        }
      ],
      "meta_data": [
        {
          "id": 2095,
          "key": "pa_color",
          "value": "black"
        },
        {
          "id": 2096,
          "key": "size",
          "value": "M Test"
        }
      ],
      "sku": "Bar3",
      "price": 12
    }
  ],
  "tax_lines": [
    {
      "id": 318,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": 75,
      "label": "State Tax",
      "compound": false,
      "tax_total": "1.35",
      "shipping_tax_total": "0.00",
      "meta_data": []
    }
  ],
  "shipping_lines": [
    {
      "id": 317,
      "method_title": "Flat Rate",
      "method_id": "flat_rate",
      "total": "10.00",
      "total_tax": "0.00",
      "taxes": [],
      "meta_data": []
    }
  ],
  "fee_lines": [],
  "coupon_lines": [],
  "refunds": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/727"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete an order
This API helps you delete an order.

```http
DELETE /wp-json/wc/v2/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/orders/727?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("orders/727", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/727', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/727", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/727", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 727,
  "parent_id": 0,
  "number": "727",
  "order_key": "wc_order_58d2d042d1d",
  "created_via": "rest-api",
  "version": "3.0.0",
  "status": "completed",
  "currency": "USD",
  "date_created": "2017-03-22T16:28:02",
  "date_created_gmt": "2017-03-22T19:28:02",
  "date_modified": "2017-03-22T16:30:35",
  "date_modified_gmt": "2017-03-22T19:30:35",
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "10.00",
  "shipping_tax": "0.00",
  "cart_tax": "1.35",
  "total": "29.35",
  "total_tax": "1.35",
  "prices_include_tax": false,
  "customer_id": 0,
  "customer_ip_address": "",
  "customer_user_agent": "",
  "customer_note": "",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "transaction_id": "",
  "date_paid": "2017-03-22T16:28:08",
  "date_paid_gmt": "2017-03-22T19:28:08",
  "date_completed": "2017-03-22T16:30:35",
  "date_completed_gmt": "2017-03-22T19:30:35",
  "cart_hash": "",
  "meta_data": [
    {
      "id": 13106,
      "key": "_download_permissions_granted",
      "value": "yes"
    },
    {
      "id": 13109,
      "key": "_order_stock_reduced",
      "value": "yes"
    }
  ],
  "line_items": [
    {
      "id": 315,
      "name": "Woo Single #1",
      "product_id": 93,
      "variation_id": 0,
      "quantity": 2,
      "tax_class": "",
      "subtotal": "6.00",
      "subtotal_tax": "0.45",
      "total": "6.00",
      "total_tax": "0.45",
      "taxes": [
        {
          "id": 75,
          "total": "0.45",
          "subtotal": "0.45"
        }
      ],
      "meta_data": [],
      "sku": "",
      "price": 3
    },
    {
      "id": 316,
      "name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1,
      "tax_class": "",
      "subtotal": "12.00",
      "subtotal_tax": "0.90",
      "total": "12.00",
      "total_tax": "0.90",
      "taxes": [
        {
          "id": 75,
          "total": "0.9",
          "subtotal": "0.9"
        }
      ],
      "meta_data": [
        {
          "id": 2095,
          "key": "pa_color",
          "value": "black"
        },
        {
          "id": 2096,
          "key": "size",
          "value": "M Test"
        }
      ],
      "sku": "Bar3",
      "price": 12
    }
  ],
  "tax_lines": [
    {
      "id": 318,
      "rate_code": "US-CA-STATE TAX",
      "rate_id": 75,
      "label": "State Tax",
      "compound": false,
      "tax_total": "1.35",
      "shipping_tax_total": "0.00",
      "meta_data": []
    }
  ],
  "shipping_lines": [
    {
      "id": 317,
      "method_title": "Flat Rate",
      "method_id": "flat_rate",
      "total": "10.00",
      "total_tax": "0.00",
      "taxes": [],
      "meta_data": []
    }
  ],
  "fee_lines": [],
  "coupon_lines": [],
  "refunds": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders/727"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/orders"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                               Description                               |
|-----------|--------|-------------------------------------------------------------------------|
| `force`   | string | Use `true` whether to permanently delete the order, Default is `false`. |

## Batch update orders
This API helps you to batch create, update and delete multiple orders.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/orders/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/orders/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "line_items": [
        {
          "product_id": 79,
          "quantity": 1
        },
        {
          "product_id": 93,
          "quantity": 1
        },
        {
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1
        }
      ],
      "shipping_lines": [
        {
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "30.00"
        }
      ]
    },
    {
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "set_paid": true,
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "line_items": [
        {
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1
        },
        {
          "product_id": 22,
          "variation_id": 24,
          "quantity": 1
        }
      ],
      "shipping_lines": [
        {
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "20.00"
        }
      ]
    }
  ],
  "update": [
    {
      "id": 727,
      "shipping_methods": "Local Delivery"
    }
  ],
  "delete": [
    723
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 79,
          quantity: 1
        },
        {
          product_id: 93,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "30.00"
        }
      ]
    },
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      set_paid: true,
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 24,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "20.00"
        }
      ]
    }
  ],
  update: [
    {
      id: 727,
      shipping_methods: "Local Delivery"
    }
  ],
  delete: [
    723
  ]
};

WooCommerce.post("orders/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'payment_method' => 'bacs',
            'payment_method_title' => 'Direct Bank Transfer',
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ],
            'line_items' => [
                [
                    'product_id' => 79,
                    'quantity' => 1
                ],
                [
                    'product_id' => 93,
                    'quantity' => 1
                ],
                [
                    'product_id' => 22,
                    'variation_id' => 23,
                    'quantity' => 1
                ]
            ],
            'shipping_lines' => [
                [
                    'method_id' => 'flat_rate',
                    'method_title' => 'Flat Rate',
                    'total' => '30.00'
                ]
            ]
        ],
        [
            'payment_method' => 'bacs',
            'payment_method_title' => 'Direct Bank Transfer',
            'set_paid' => true,
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ],
            'line_items' => [
                [
                    'product_id' => 22,
                    'variation_id' => 23,
                    'quantity' => 1
                ],
                [
                    'product_id' => 22,
                    'variation_id' => 24,
                    'quantity' => 1
                ]
            ],
            'shipping_lines' => [
                [
                    'method_id' => 'flat_rate',
                    'method_title' => 'Flat Rate',
                    'total' => '20.00'
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 727,
            'shipping_methods' => 'Local Delivery'
        ]
    ],
    'delete' => [
        723
    ]
];

print_r($woocommerce->post('orders/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "payment_method": "bacs",
            "payment_method_title": "Direct Bank Transfer",
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            },
            "line_items": [
                {
                    "product_id": 79,
                    "quantity": 1
                },
                {
                    "product_id": 93,
                    "quantity": 1
                },
                {
                    "product_id": 22,
                    "variation_id": 23,
                    "quantity": 1
                }
            ],
            "shipping_lines": [
                {
                    "method_id": "flat_rate",
                    "method_title": "Flat Rate",
                    "total": "30.00"
                }
            ]
        },
        {
            "payment_method": "bacs",
            "payment_method_title": "Direct Bank Transfer",
            "set_paid": True,
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            },
            "line_items": [
                {
                    "product_id": 22,
                    "variation_id": 23,
                    "quantity": 1
                },
                {
                    "product_id": 22,
                    "variation_id": 24,
                    "quantity": 1
                }
            ],
            "shipping_lines": [
                {
                    "method_id": "flat_rate",
                    "method_title": "Flat Rate",
                    "total": "20.00"
                }
            ]
        }
    ],
    "update": [
        {
            "id": 727,
            "shipping_methods": "Local Delivery"
        }
    ],
    "delete": [
        723
    ]
}

print(wcapi.post("orders/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 79,
          quantity: 1
        },
        {
          product_id: 93,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "30.00"
        }
      ]
    },
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      set_paid: true,
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 24,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "20.00"
        }
      ]
    }
  ],
  update: [
    {
      id: 727,
      shipping_methods: "Local Delivery"
    }
  ],
  delete: [
    723
  ]
}

woocommerce.post("orders/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 728,
      "parent_id": 0,
      "number": "728",
      "order_key": "wc_order_58d2d18e580",
      "created_via": "rest-api",
      "version": "3.0.0",
      "status": "pending",
      "currency": "USD",
      "date_created": "2017-03-22T16:33:34",
      "date_created_gmt": "2017-03-22T19:33:34",
      "date_modified": "2017-03-22T16:33:34",
      "date_modified_gmt": "2017-03-22T19:33:34",
      "discount_total": "0.00",
      "discount_tax": "0.00",
      "shipping_total": "30.00",
      "shipping_tax": "0.00",
      "cart_tax": "2.25",
      "total": "62.25",
      "total_tax": "2.25",
      "prices_include_tax": false,
      "customer_id": 0,
      "customer_ip_address": "",
      "customer_user_agent": "",
      "customer_note": "",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "transaction_id": "",
      "date_paid": null,
      "date_paid_gmt": null,
      "date_completed": null,
      "date_completed_gmt": null,
      "cart_hash": "",
      "meta_data": [],
      "line_items": [
        {
          "id": 319,
          "name": "Woo Logo",
          "product_id": 79,
          "variation_id": 0,
          "quantity": 1,
          "tax_class": "",
          "subtotal": "15.00",
          "subtotal_tax": "1.13",
          "total": "15.00",
          "total_tax": "1.13",
          "taxes": [
            {
              "id": 75,
              "total": "1.125",
              "subtotal": "1.125"
            }
          ],
          "meta_data": [],
          "sku": "",
          "price": 15
        },
        {
          "id": 320,
          "name": "Woo Single #1",
          "product_id": 93,
          "variation_id": 0,
          "quantity": 1,
          "tax_class": "",
          "subtotal": "3.00",
          "subtotal_tax": "0.23",
          "total": "3.00",
          "total_tax": "0.23",
          "taxes": [
            {
              "id": 75,
              "total": "0.225",
              "subtotal": "0.225"
            }
          ],
          "meta_data": [],
          "sku": "",
          "price": 3
        },
        {
          "id": 321,
          "name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1,
          "tax_class": "",
          "subtotal": "12.00",
          "subtotal_tax": "0.90",
          "total": "12.00",
          "total_tax": "0.90",
          "taxes": [
            {
              "id": 75,
              "total": "0.9",
              "subtotal": "0.9"
            }
          ],
          "meta_data": [
            {
              "id": 2133,
              "key": "pa_color",
              "value": "black"
            },
            {
              "id": 2134,
              "key": "size",
              "value": "M Test"
            }
          ],
          "sku": "Bar3",
          "price": 12
        }
      ],
      "tax_lines": [
        {
          "id": 323,
          "rate_code": "US-CA-STATE TAX",
          "rate_id": 75,
          "label": "State Tax",
          "compound": false,
          "tax_total": "2.25",
          "shipping_tax_total": "0.00",
          "meta_data": []
        }
      ],
      "shipping_lines": [
        {
          "id": 322,
          "method_title": "Flat Rate",
          "method_id": "flat_rate",
          "total": "30.00",
          "total_tax": "0.00",
          "taxes": [],
          "meta_data": []
        }
      ],
      "fee_lines": [],
      "coupon_lines": [],
      "refunds": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/orders/728"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/orders"
          }
        ]
      }
    },
    {
      "id": 729,
      "parent_id": 0,
      "number": "729",
      "order_key": "wc_order_58d2d196171",
      "created_via": "rest-api",
      "version": "3.0.0",
      "status": "processing",
      "currency": "USD",
      "date_created": "2017-03-22T16:33:42",
      "date_created_gmt": "2017-03-22T19:33:42",
      "date_modified": "2017-03-22T16:33:47",
      "date_modified_gmt": "2017-03-22T19:33:47",
      "discount_total": "0.00",
      "discount_tax": "0.00",
      "shipping_total": "20.00",
      "shipping_tax": "0.00",
      "cart_tax": "2.40",
      "total": "54.40",
      "total_tax": "2.40",
      "prices_include_tax": false,
      "customer_id": 0,
      "customer_ip_address": "",
      "customer_user_agent": "",
      "customer_note": "",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "transaction_id": "",
      "date_paid": "2017-03-22T16:33:47",
      "date_paid_gmt": "2017-03-22T19:33:47",
      "date_completed": null,
      "date_completed_gmt": null,
      "cart_hash": "",
      "meta_data": [
        {
          "id": 13198,
          "key": "_download_permissions_granted",
          "value": "yes"
        }
      ],
      "line_items": [
        {
          "id": 324,
          "name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1,
          "tax_class": "",
          "subtotal": "12.00",
          "subtotal_tax": "0.90",
          "total": "12.00",
          "total_tax": "0.90",
          "taxes": [
            {
              "id": 75,
              "total": "0.9",
              "subtotal": "0.9"
            }
          ],
          "meta_data": [
            {
              "id": 2153,
              "key": "pa_color",
              "value": "black"
            },
            {
              "id": 2154,
              "key": "size",
              "value": "M Test"
            }
          ],
          "sku": "Bar3",
          "price": 12
        },
        {
          "id": 325,
          "name": "Ship Your Idea &ndash; Color: Green, Size: S Test",
          "product_id": 22,
          "variation_id": 24,
          "quantity": 1,
          "tax_class": "",
          "subtotal": "20.00",
          "subtotal_tax": "1.50",
          "total": "20.00",
          "total_tax": "1.50",
          "taxes": [
            {
              "id": 75,
              "total": "1.5",
              "subtotal": "1.5"
            }
          ],
          "meta_data": [
            {
              "id": 2164,
              "key": "pa_color",
              "value": "green"
            },
            {
              "id": 2165,
              "key": "size",
              "value": "S Test"
            }
          ],
          "sku": "",
          "price": 20
        }
      ],
      "tax_lines": [
        {
          "id": 327,
          "rate_code": "US-CA-STATE TAX",
          "rate_id": 75,
          "label": "State Tax",
          "compound": false,
          "tax_total": "2.40",
          "shipping_tax_total": "0.00",
          "meta_data": []
        }
      ],
      "shipping_lines": [
        {
          "id": 326,
          "method_title": "Flat Rate",
          "method_id": "flat_rate",
          "total": "20.00",
          "total_tax": "0.00",
          "taxes": [],
          "meta_data": []
        }
      ],
      "fee_lines": [],
      "coupon_lines": [],
      "refunds": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/orders/729"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/orders"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 727,
      "parent_id": 0,
      "number": "727",
      "order_key": "wc_order_58d2d042d1d",
      "created_via": "rest-api",
      "version": "3.0.0",
      "status": "completed",
      "currency": "USD",
      "date_created": "2017-03-22T16:28:02",
      "date_created_gmt": "2017-03-22T19:28:02",
      "date_modified": "2017-03-22T16:30:35",
      "date_modified_gmt": "2017-03-22T19:30:35",
      "discount_total": "0.00",
      "discount_tax": "0.00",
      "shipping_total": "10.00",
      "shipping_tax": "0.00",
      "cart_tax": "1.35",
      "total": "29.35",
      "total_tax": "1.35",
      "prices_include_tax": false,
      "customer_id": 0,
      "customer_ip_address": "",
      "customer_user_agent": "",
      "customer_note": "",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "transaction_id": "",
      "date_paid": "2017-03-22T16:28:08",
      "date_paid_gmt": "2017-03-22T19:28:08",
      "date_completed": "2017-03-22T16:30:35",
      "date_completed_gmt": "2017-03-22T19:30:35",
      "cart_hash": "",
      "meta_data": [
        {
          "id": 13106,
          "key": "_download_permissions_granted",
          "value": "yes"
        },
        {
          "id": 13109,
          "key": "_order_stock_reduced",
          "value": "yes"
        }
      ],
      "line_items": [
        {
          "id": 315,
          "name": "Woo Single #1",
          "product_id": 93,
          "variation_id": 0,
          "quantity": 2,
          "tax_class": "",
          "subtotal": "6.00",
          "subtotal_tax": "0.45",
          "total": "6.00",
          "total_tax": "0.45",
          "taxes": [
            {
              "id": 75,
              "total": "0.45",
              "subtotal": "0.45"
            }
          ],
          "meta_data": [],
          "sku": "",
          "price": 3
        },
        {
          "id": 316,
          "name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1,
          "tax_class": "",
          "subtotal": "12.00",
          "subtotal_tax": "0.90",
          "total": "12.00",
          "total_tax": "0.90",
          "taxes": [
            {
              "id": 75,
              "total": "0.9",
              "subtotal": "0.9"
            }
          ],
          "meta_data": [
            {
              "id": 2095,
              "key": "pa_color",
              "value": "black"
            },
            {
              "id": 2096,
              "key": "size",
              "value": "M Test"
            }
          ],
          "sku": "Bar3",
          "price": 12
        }
      ],
      "tax_lines": [
        {
          "id": 318,
          "rate_code": "US-CA-STATE TAX",
          "rate_id": 75,
          "label": "State Tax",
          "compound": false,
          "tax_total": "1.35",
          "shipping_tax_total": "0.00",
          "meta_data": []
        }
      ],
      "shipping_lines": [
        {
          "id": 317,
          "method_title": "Flat Rate",
          "method_id": "flat_rate",
          "total": "10.00",
          "total_tax": "0.00",
          "taxes": [],
          "meta_data": []
        }
      ],
      "fee_lines": [],
      "coupon_lines": [],
      "refunds": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/orders/727"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/orders"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 723,
      "parent_id": 0,
      "number": "723",
      "order_key": "wc_order_58d17c18352",
      "created_via": "checkout",
      "version": "3.0.0",
      "status": "completed",
      "currency": "USD",
      "date_created": "2017-03-21T16:16:00",
      "date_created_gmt": "2017-03-21T19:16:00",
      "date_modified": "2017-03-21T16:54:51",
      "date_modified_gmt": "2017-03-21T19:54:51",
      "discount_total": "0.00",
      "discount_tax": "0.00",
      "shipping_total": "10.00",
      "shipping_tax": "0.00",
      "cart_tax": "0.00",
      "total": "39.00",
      "total_tax": "0.00",
      "prices_include_tax": false,
      "customer_id": 26,
      "customer_ip_address": "127.0.0.1",
      "customer_user_agent": "mozilla/5.0 (x11; ubuntu; linux x86_64; rv:52.0) gecko/20100101 firefox/52.0",
      "customer_note": "",
      "billing": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(11) 1111-1111"
      },
      "shipping": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      },
      "payment_method": "bacs",
      "payment_method_title": "Direct bank transfer",
      "transaction_id": "",
      "date_paid": null,
      "date_paid_gmt": null,
      "date_completed": "2017-03-21T16:54:51",
      "date_completed_gmt": "2017-03-21T19:54:51",
      "cart_hash": "5040ce7273261e31d8bcf79f9be3d279",
      "meta_data": [
        {
          "id": 13023,
          "key": "_download_permissions_granted",
          "value": "yes"
        }
      ],
      "line_items": [
        {
          "id": 311,
          "name": "Woo Album #2",
          "product_id": 87,
          "variation_id": 0,
          "quantity": 1,
          "tax_class": "",
          "subtotal": "9.00",
          "subtotal_tax": "0.00",
          "total": "9.00",
          "total_tax": "0.00",
          "taxes": [],
          "meta_data": [],
          "sku": "",
          "price": 9
        },
        {
          "id": 313,
          "name": "Woo Ninja",
          "product_id": 34,
          "variation_id": 0,
          "quantity": 1,
          "tax_class": "",
          "subtotal": "20.00",
          "subtotal_tax": "0.00",
          "total": "20.00",
          "total_tax": "0.00",
          "taxes": [],
          "meta_data": [],
          "sku": "",
          "price": 20
        }
      ],
      "tax_lines": [],
      "shipping_lines": [
        {
          "id": 312,
          "method_title": "Flat rate",
          "method_id": "flat_rate:25",
          "total": "10.00",
          "total_tax": "0.00",
          "taxes": [],
          "meta_data": [
            {
              "id": 2057,
              "key": "Items",
              "value": "Woo Album #2 &times; 1"
            }
          ]
        }
      ],
      "fee_lines": [],
      "coupon_lines": [],
      "refunds": [
        {
          "id": 726,
          "refund": "",
          "total": "-10.00"
        },
        {
          "id": 724,
          "refund": "",
          "total": "-9.00"
        }
      ],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/orders/723"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/orders"
          }
        ],
        "customer": [
          {
            "href": "https://example.com/wp-json/wc/v2/customers/26"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Payment gateways

*Source: apis/rest-api/v2/payment-gateways.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Payment gateways
The payment gateways API allows you to view, and update individual payment gateways. Results are not paginated - all gateways will be returned.

## Payment gateway properties
| Attribute            | Type    | Description                                                                                                 |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `id`                 | string  | Payment gateway ID. `READ-ONLY`                                               |
| `title`              | string  | Payment gateway title on checkout.                                                                          |
| `description`        | string  | Payment gateway description on checkout.                                                                    |
| `order`              | integer | Payment gateway sort order.                                                                                 |
| `enabled`            | boolean | Payment gateway enabled status.                                                                             |
| `method_title`       | string  | Payment gateway method title. `READ-ONLY`                                     |
| `method_description` | string  | Payment gateway method description. `READ-ONLY`                               |
| `settings`           | object  | Payment gateway settings. See [Payment gateway - Settings properties](#payment-gateway---settings-properties) |

### Payment gateway - Settings properties
| Attribute     | Type   | Description                                                                                                                                                                                     |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string | A unique identifier for the setting. `READ-ONLY`                                                                                                                  |
| `label`       | string | A human readable label for the setting used in interfaces. `READ-ONLY`                                                                                            |
| `description` | string | A human readable description for the setting used in interfaces. `READ-ONLY`                                                                                      |
| `type`        | string | Type of setting. Options: `text`, `email`, `number`, `color`, `password`, `textarea`, `select`, `multiselect`, `radio`, `image_width` and `checkbox`. `READ-ONLY` |
| `value`       | string | Setting value.                                                                                                                                                                                  |
| `default`     | string | Default value for the setting. `READ-ONLY`                                                                                                                        |
| `tip`         | string | Additional help text shown to the user about the setting. `READ-ONLY`                                                                                             |
| `placeholder` | string | Placeholder text to be displayed in text inputs. `READ-ONLY`                                                                                                      |

## Retrieve a payment gateway
This API lets you retrieve and view a specific payment gateway.

```http
GET /wp-json/wc/v2/payment_gateways/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/payment_gateways/bacs \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("payment_gateways/bacs")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('payment_gateways/bacs')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("payment_gateways/bacs").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("payment_gateways/bacs").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": "bacs",
  "title": "Direct bank transfer",
  "description": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
  "order": 0,
  "enabled": true,
  "method_title": "BACS",
  "method_description": "Allows payments by BACS, more commonly known as direct bank/wire transfer.",
  "settings": {
    "title": {
      "id": "title",
      "label": "Title",
      "description": "This controls the title which the user sees during checkout.",
      "type": "text",
      "value": "Direct bank transfer",
      "default": "Direct bank transfer",
      "tip": "This controls the title which the user sees during checkout.",
      "placeholder": ""
    },
    "instructions": {
      "id": "instructions",
      "label": "Instructions",
      "description": "Instructions that will be added to the thank you page and emails.",
      "type": "textarea",
      "value": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
      "default": "",
      "tip": "Instructions that will be added to the thank you page and emails.",
      "placeholder": ""
    }
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/payment_gateways/bacs"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/payment_gateways"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all payment gateways
This API helps you to view all the payment gateways.

```http
GET /wp-json/wc/v2/payment_gateways
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/payment_gateways \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("payment_gateways")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('payment_gateways')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("payment_gateways").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("payment_gateways").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": "bacs",
    "title": "Direct bank transfer",
    "description": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
    "order": 0,
    "enabled": true,
    "method_title": "BACS",
    "method_description": "Allows payments by BACS, more commonly known as direct bank/wire transfer.",
    "settings": {
      "title": {
        "id": "title",
        "label": "Title",
        "description": "This controls the title which the user sees during checkout.",
        "type": "text",
        "value": "Direct bank transfer",
        "default": "Direct bank transfer",
        "tip": "This controls the title which the user sees during checkout.",
        "placeholder": ""
      },
      "instructions": {
        "id": "instructions",
        "label": "Instructions",
        "description": "Instructions that will be added to the thank you page and emails.",
        "type": "textarea",
        "value": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
        "default": "",
        "tip": "Instructions that will be added to the thank you page and emails.",
        "placeholder": ""
      }
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/payment_gateways/bacs"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/payment_gateways"
        }
      ]
    }
  },
  {
    "id": "cheque",
    "title": "Check payments",
    "description": "Please send a check to Store Name, Store Street, Store Town, Store State / County, Store Postcode.",
    "order": 1,
    "enabled": false,
    "method_title": "Check payments",
    "method_description": "Allows check payments. Why would you take checks in this day and age? Well you probably wouldn't but it does allow you to make test purchases for testing order emails and the 'success' pages etc.",
    "settings": {
      "title": {
        "id": "title",
        "label": "Title",
        "description": "This controls the title which the user sees during checkout.",
        "type": "text",
        "value": "Check payments",
        "default": "Check payments",
        "tip": "This controls the title which the user sees during checkout.",
        "placeholder": ""
      },
      "instructions": {
        "id": "instructions",
        "label": "Instructions",
        "description": "Instructions that will be added to the thank you page and emails.",
        "type": "textarea",
        "value": "",
        "default": "",
        "tip": "Instructions that will be added to the thank you page and emails.",
        "placeholder": ""
      }
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/payment_gateways/cheque"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/payment_gateways"
        }
      ]
    }
  },
  {
    "id": "cod",
    "title": "Cash on delivery",
    "description": "Pay with cash upon delivery.",
    "order": 2,
    "enabled": false,
    "method_title": "Cash on delivery",
    "method_description": "Have your customers pay with cash (or by other means) upon delivery.",
    "settings": {
      "title": {
        "id": "title",
        "label": "Title",
        "description": "Payment method description that the customer will see on your checkout.",
        "type": "text",
        "value": "Cash on delivery",
        "default": "Cash on delivery",
        "tip": "Payment method description that the customer will see on your checkout.",
        "placeholder": ""
      },
      "instructions": {
        "id": "instructions",
        "label": "Instructions",
        "description": "Instructions that will be added to the thank you page.",
        "type": "textarea",
        "value": "",
        "default": "Pay with cash upon delivery.",
        "tip": "Instructions that will be added to the thank you page.",
        "placeholder": ""
      },
      "enable_for_methods": {
        "id": "enable_for_methods",
        "label": "Enable for shipping methods",
        "description": "If COD is only available for certain methods, set it up here. Leave blank to enable for all methods.",
        "type": "multiselect",
        "value": "",
        "default": "",
        "tip": "If COD is only available for certain methods, set it up here. Leave blank to enable for all methods.",
        "placeholder": "",
        "options": {
          "flat_rate": "Flat rate",
          "free_shipping": "Free shipping",
          "local_pickup": "Local pickup"
        }
      },
      "enable_for_virtual": {
        "id": "enable_for_virtual",
        "label": "Accept COD if the order is virtual",
        "description": "",
        "type": "checkbox",
        "value": "yes",
        "default": "yes",
        "tip": "",
        "placeholder": ""
      }
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/payment_gateways/cod"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/payment_gateways"
        }
      ]
    }
  },
  {
    "id": "paypal",
    "title": "PayPal",
    "description": "Pay via PayPal; you can pay with your credit card if you don't have a PayPal account.",
    "order": 3,
    "enabled": true,
    "method_title": "PayPal",
    "method_description": "PayPal Standard sends customers to PayPal to enter their payment information. PayPal IPN requires fsockopen/cURL support to update order statuses after payment. Check the <a href=\"https://example.com/wp-admin/admin.php?page=wc-status\">system status</a> page for more details.",
    "settings": {
      "title": {
        "id": "title",
        "label": "Title",
        "description": "This controls the title which the user sees during checkout.",
        "type": "text",
        "value": "PayPal",
        "default": "PayPal",
        "tip": "This controls the title which the user sees during checkout.",
        "placeholder": ""
      },
      "email": {
        "id": "email",
        "label": "PayPal email",
        "description": "Please enter your PayPal email address; this is needed in order to take payment.",
        "type": "email",
        "value": "me@example.com",
        "default": "me@example.com",
        "tip": "Please enter your PayPal email address; this is needed in order to take payment.",
        "placeholder": "you@youremail.com"
      },
      "testmode": {
        "id": "testmode",
        "label": "Enable PayPal sandbox",
        "description": "PayPal sandbox can be used to test payments. Sign up for a <a href=\"https://developer.paypal.com/\">developer account</a>.",
        "type": "checkbox",
        "value": "yes",
        "default": "no",
        "tip": "PayPal sandbox can be used to test payments. Sign up for a <a href=\"https://developer.paypal.com/\">developer account</a>.",
        "placeholder": ""
      },
      "debug": {
        "id": "debug",
        "label": "Enable logging",
        "description": "Log PayPal events, such as IPN requests, inside <code>/var/www/woocommerce/wp-content/uploads/wc-logs/paypal-de01f7c6894774e7ac8e4207bb8bac2f.log</code>",
        "type": "checkbox",
        "value": "yes",
        "default": "no",
        "tip": "Log PayPal events, such as IPN requests, inside <code>/var/www/woocommerce/wp-content/uploads/wc-logs/paypal-de01f7c6894774e7ac8e4207bb8bac2f.log</code>",
        "placeholder": ""
      },
      "receiver_email": {
        "id": "receiver_email",
        "label": "Receiver email",
        "description": "If your main PayPal email differs from the PayPal email entered above, input your main receiver email for your PayPal account here. This is used to validate IPN requests.",
        "type": "email",
        "value": "me@example.com",
        "default": "",
        "tip": "If your main PayPal email differs from the PayPal email entered above, input your main receiver email for your PayPal account here. This is used to validate IPN requests.",
        "placeholder": "you@youremail.com"
      },
      "identity_token": {
        "id": "identity_token",
        "label": "PayPal identity token",
        "description": "Optionally enable \"Payment Data Transfer\" (Profile > Profile and Settings > My Selling Tools > Website Preferences) and then copy your identity token here. This will allow payments to be verified without the need for PayPal IPN.",
        "type": "text",
        "value": "",
        "default": "",
        "tip": "Optionally enable \"Payment Data Transfer\" (Profile > Profile and Settings > My Selling Tools > Website Preferences) and then copy your identity token here. This will allow payments to be verified without the need for PayPal IPN.",
        "placeholder": ""
      },
      "invoice_prefix": {
        "id": "invoice_prefix",
        "label": "Invoice prefix",
        "description": "Please enter a prefix for your invoice numbers. If you use your PayPal account for multiple stores ensure this prefix is unique as PayPal will not allow orders with the same invoice number.",
        "type": "text",
        "value": "WC-",
        "default": "WC-",
        "tip": "Please enter a prefix for your invoice numbers. If you use your PayPal account for multiple stores ensure this prefix is unique as PayPal will not allow orders with the same invoice number.",
        "placeholder": ""
      },
      "send_shipping": {
        "id": "send_shipping",
        "label": "Send shipping details to PayPal instead of billing.",
        "description": "PayPal allows us to send one address. If you are using PayPal for shipping labels you may prefer to send the shipping address rather than billing.",
        "type": "checkbox",
        "value": "no",
        "default": "no",
        "tip": "PayPal allows us to send one address. If you are using PayPal for shipping labels you may prefer to send the shipping address rather than billing.",
        "placeholder": ""
      },
      "address_override": {
        "id": "address_override",
        "label": "Enable \"address_override\" to prevent address information from being changed.",
        "description": "PayPal verifies addresses therefore this setting can cause errors (we recommend keeping it disabled).",
        "type": "checkbox",
        "value": "no",
        "default": "no",
        "tip": "PayPal verifies addresses therefore this setting can cause errors (we recommend keeping it disabled).",
        "placeholder": ""
      },
      "paymentaction": {
        "id": "paymentaction",
        "label": "Payment action",
        "description": "Choose whether you wish to capture funds immediately or authorize payment only.",
        "type": "select",
        "value": "sale",
        "default": "sale",
        "tip": "Choose whether you wish to capture funds immediately or authorize payment only.",
        "placeholder": "",
        "options": {
          "sale": "Capture",
          "authorization": "Authorize"
        }
      },
      "page_style": {
        "id": "page_style",
        "label": "Page style",
        "description": "Optionally enter the name of the page style you wish to use. These are defined within your PayPal account. This affects classic PayPal checkout screens.",
        "type": "text",
        "value": "",
        "default": "",
        "tip": "Optionally enter the name of the page style you wish to use. These are defined within your PayPal account. This affects classic PayPal checkout screens.",
        "placeholder": "Optional"
      },
      "image_url": {
        "id": "image_url",
        "label": "Image url",
        "description": "Optionally enter the URL to a 150x50px image displayed as your logo in the upper left corner of the PayPal checkout pages.",
        "type": "text",
        "value": "",
        "default": "",
        "tip": "Optionally enter the URL to a 150x50px image displayed as your logo in the upper left corner of the PayPal checkout pages.",
        "placeholder": "Optional"
      },
      "api_username": {
        "id": "api_username",
        "label": "API username",
        "description": "Get your API credentials from PayPal.",
        "type": "text",
        "value": "",
        "default": "",
        "tip": "Get your API credentials from PayPal.",
        "placeholder": "Optional"
      },
      "api_password": {
        "id": "api_password",
        "label": "API password",
        "description": "Get your API credentials from PayPal.",
        "type": "password",
        "value": "",
        "default": "",
        "tip": "Get your API credentials from PayPal.",
        "placeholder": "Optional"
      },
      "api_signature": {
        "id": "api_signature",
        "label": "API signature",
        "description": "Get your API credentials from PayPal.",
        "type": "text",
        "value": "",
        "default": "",
        "tip": "Get your API credentials from PayPal.",
        "placeholder": "Optional"
      }
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/payment_gateways/paypal"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/payment_gateways"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Update a payment gateway
This API lets you make changes to a payment gateway.

```http
PUT /wp-json/wc/v2/payment_gateways/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/payment_gateways/bacs \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "enabled": false
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  enabled: false
};

WooCommerce.put("payment_gateways/bacs", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'enabled' => false
];

print_r($woocommerce->put('payment_gateways/bacs', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "enabled": False
}

print(wcapi.put("payment_gateways/bacs", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  enabled: false
}

woocommerce.put("payment_gateways/bacs", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": "bacs",
  "title": "Direct bank transfer",
  "description": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
  "order": 0,
  "enabled": false,
  "method_title": "BACS",
  "method_description": "Allows payments by BACS, more commonly known as direct bank/wire transfer.",
  "settings": {
    "title": {
      "id": "title",
      "label": "Title",
      "description": "This controls the title which the user sees during checkout.",
      "type": "text",
      "value": "Direct bank transfer",
      "default": "Direct bank transfer",
      "tip": "This controls the title which the user sees during checkout.",
      "placeholder": ""
    },
    "instructions": {
      "id": "instructions",
      "label": "Instructions",
      "description": "Instructions that will be added to the thank you page and emails.",
      "type": "textarea",
      "value": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
      "default": "",
      "tip": "Instructions that will be added to the thank you page and emails.",
      "placeholder": ""
    }
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/payment_gateways/bacs"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/payment_gateways"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>


---

## Product attribute terms

*Source: apis/rest-api/v2/product-attribute-terms.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product attribute terms
The product attribute terms API allows you to create, view, update, and delete individual, or a batch, of attribute terms.

## Product attribute term properties
| Attribute     | Type    | Description                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Term name. `MANDATORY`                                     |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `menu_order`  | integer | Menu order, used to custom sort the resource.                                            |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create an attribute term
This API helps you to create a new product attribute term.

```http
POST /wp-json/wc/v2/products/attributes/<attribute_id>/terms
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/attributes/2/terms \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "XXS"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "XXS"
};

WooCommerce.post("products/attributes/2/terms", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'XXS'
];

print_r($woocommerce->post('products/attributes/2/terms', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "XXS"
}

print(wcapi.post("products/attributes/2/terms", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "XXS"
}

woocommerce.post("products/attributes/2/terms", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 23,
  "name": "XXS",
  "slug": "xxs",
  "description": "",
  "menu_order": 1,
  "count": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/23"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve an attribute term
This API lets you retrieve a product attribute term by ID.

```http
GET /wp-json/wc/v2/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/attributes/2/terms/23 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/attributes/2/terms/23")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/2/terms/23')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/2/terms/23").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/2/terms/23").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 23,
  "name": "XXS",
  "slug": "xxs",
  "description": "",
  "menu_order": 1,
  "count": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/23"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all attribute terms
This API lets you retrieve all terms from a product attribute.

```http
GET /wp-json/wc/v2/products/attributes/<attribute_id>/terms
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/attributes/2/terms \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/attributes/2/terms")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/2/terms')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/2/terms").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/2/terms").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 23,
    "name": "XXS",
    "slug": "xxs",
    "description": "",
    "menu_order": 1,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/23"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 22,
    "name": "XS",
    "slug": "xs",
    "description": "",
    "menu_order": 2,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/22"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 17,
    "name": "S",
    "slug": "s",
    "description": "",
    "menu_order": 3,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/17"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 18,
    "name": "M",
    "slug": "m",
    "description": "",
    "menu_order": 4,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/18"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 19,
    "name": "L",
    "slug": "l",
    "description": "",
    "menu_order": 5,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/19"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 20,
    "name": "XL",
    "slug": "xl",
    "description": "",
    "menu_order": 6,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/20"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
        }
      ]
    }
  },
  {
    "id": 21,
    "name": "XXL",
    "slug": "xxl",
    "description": "",
    "menu_order": 7,
    "count": 1,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/21"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter      | Type    | Description                                                                                                                                  |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`      | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                 |
| `page`         | integer | Current page of the collection. Default is `1`.                                                                                              |
| `per_page`     | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                       |
| `search`       | string  | Limit results to those matching a string.                                                                                                    |
| `exclude`      | array   | Ensure result set excludes specific ids.                                                                                                     |
| `include`      | array   | Limit result set to specific ids.                                                                                                            |
| `order`        | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                   |
| `orderby`      | string  | Sort collection by resource attribute. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. Default is `name`. |
| `hide_empty`   | boolean | Whether to hide resources not assigned to any products. Default is `false`.                                                                  |
| `parent`       | integer | Limit result set to resources assigned to a specific parent.                                                                                 |
| `product`      | integer | Limit result set to resources assigned to a specific product.                                                                                |
| `slug`         | string  | Limit result set to resources with a specific slug.                                                                                          |

## Update an attribute term
This API lets you make changes to a product attribute term.

```http
PUT /wp-json/wc/v2/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/products/attributes/2/terms/23 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "XXS"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "XXS"
};

WooCommerce.put("products/attributes/2/terms/23", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'XXS'
];

print_r($woocommerce->put('products/attributes/2/terms/23', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "XXS"
}

print(wcapi.put("products/attributes/2/terms/23", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "XXS"
}

woocommerce.put("products/attributes/2/terms/23", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 23,
  "name": "XXS",
  "slug": "xxs",
  "description": "",
  "menu_order": 1,
  "count": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/23"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete an attribute term
This API helps you delete a product attribute term.

```http
DELETE /wp-json/wc/v2/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/products/attributes/2/terms/23?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/attributes/2/terms/23", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/attributes/2/terms/23', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/attributes/2/terms/23", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/attributes/2/terms/23", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 23,
  "name": "XXS",
  "slug": "xxs",
  "description": "",
  "menu_order": 1,
  "count": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/23"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type   |                          Description                          |
|-----------|---------|---------------------------------------------------------------|
| `force`   | boolean | Required to be `true`, as resource does not support trashing. |

## Batch update attribute terms
This API helps you to batch create, update and delete multiple product attribute terms.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/products/attributes/<attribute_id>/terms/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/attributes/<attribute_id>/terms/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "XXS"
    },
    {
      "name": "S"
    }
  ],
  "update": [
    {
      "id": 19,
      "menu_order": 6
    }
  ],
  "delete": [
    21,
    20
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "XXS"
    },
    {
      name: "S"
    }
  ],
  update: [
    {
      id: 19,
      menu_order: 6
    }
  ],
  delete: [
    21,
    20
  ]
};

WooCommerce.post("products/attributes/2/terms/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'XXS'
        ],
        [
            'name' => 'S'
        ]
    ],
    'update' => [
        [
            'id' => 19,
            'menu_order' => 6
        ]
    ],
    'delete' => [
        21,
        20
    ]
];

print_r($woocommerce->post('products/attributes/2/terms/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "XXS"
        },
        {
            "name": "S"
        }
    ],
    "update": [
        {
            "id": 19,
            "menu_order": 6
        }
    ],
    "delete": [
        21,
        20
    ]
}

print(wcapi.post("products/attributes/2/terms/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "XXS"
    },
    {
      name: "S"
    }
  ],
  update: [
    {
      id: 19,
      menu_order: 6
    }
  ],
  delete: [
    21,
    20
  ]
}

woocommerce.post("products/attributes/2/terms/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 23,
      "name": "XXS",
      "slug": "xxs",
      "description": "",
      "menu_order": 1,
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/23"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
          }
        ]
      }
    },
    {
      "id": 17,
      "name": "S",
      "slug": "s",
      "description": "",
      "menu_order": 3,
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/17"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 19,
      "name": "L",
      "slug": "l",
      "description": "",
      "menu_order": 6,
      "count": 1,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/19"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 21,
      "name": "XXL",
      "slug": "xxl",
      "description": "",
      "menu_order": 7,
      "count": 1,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/21"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
          }
        ]
      }
    },
    {
      "id": 20,
      "name": "XL",
      "slug": "xl",
      "description": "",
      "menu_order": 6,
      "count": 1,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms/20"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2/terms"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product attributes

*Source: apis/rest-api/v2/product-attributes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product attributes
The product attributes API allows you to create, view, update, and delete individual, or a batch, of product attributes.

## Product attribute properties
| Attribute      | Type    | Description                                                                                      |
| -------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `id`           | integer | Unique identifier for the resource. `READ-ONLY`                    |
| `name`         | string  | Attribute name. `MANDATORY`                                        |
| `slug`         | string  | An alphanumeric identifier for the resource unique to its type.                                  |
| `type`         | string  | Type of attribute. By default only `select` is supported.                           |
| `order_by`     | string  | Default sort order. Options: `menu_order`, `name`, `name_num` and `id`. Default is `menu_order`. |
| `has_archives` | boolean | Enable/Disable attribute archives. Default is `false`.                                           |

## Create a product attribute
This API helps you to create a new product attribute.

```http
POST /wp-json/wc/v2/products/attributes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/attributes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Color",
  slug: "pa_color",
  type: "select",
  order_by: "menu_order",
  has_archives: true
};

WooCommerce.post("products/attributes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Color',
    'slug' => 'pa_color',
    'type' => 'select',
    'order_by' => 'menu_order',
    'has_archives' => true
];

print_r($woocommerce->post('products/attributes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Color",
    "slug": "pa_color",
    "type": "select",
    "order_by": "menu_order",
    "has_archives": True
}

print(wcapi.post("products/attributes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Color",
  slug: "pa_color",
  type: "select",
  order_by: "menu_order",
  has_archives: true
}

woocommerce.post("products/attributes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 1,
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/1"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product attribute
This API lets you retrieve and view a specific product attribute by ID.

```http
GET /wp-json/wc/v2/products/attributes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/attributes/1 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/attributes/1")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/1')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/1").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/1").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 1,
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/1"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all product attributes
This API helps you to view all the product attributes.

```http
GET /wp-json/wc/v2/products/attributes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/attributes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/attributes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 1,
    "name": "Color",
    "slug": "pa_color",
    "type": "select",
    "order_by": "menu_order",
    "has_archives": true,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/1"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes"
        }
      ]
    }
  },
  {
    "id": 2,
    "name": "Size",
    "slug": "pa_size",
    "type": "select",
    "order_by": "menu_order",
    "has_archives": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes/2"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/attributes"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter | Type   | Description                                                                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `context` | string | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |

## Update a product attribute
This API lets you make changes to a product attribute.

```http
PUT /wp-json/wc/v2/products/attributes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/products/attributes/1 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "order_by": "name"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  order_by: "name"
};

WooCommerce.put("products/attributes/1", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'order_by' => 'name'
];

print_r($woocommerce->put('products/attributes/1', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "order_by": "name"
}

print(wcapi.put("products/attributes/1", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  order_by: "name"
}

woocommerce.put("products/attributes/1", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 1,
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "name",
  "has_archives": true,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/1"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product attribute
This API helps you delete a product attribute.

```http
DELETE /wp-json/wc/v2/products/attributes/<id>
```

:::warning
This also will delete all terms from the selected attribute.
:::

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/products/attributes/1?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/attributes/1", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/attributes/1', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/attributes/1", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/attributes/1", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 1,
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes/1"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/attributes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type   |                          Description                          |
|-----------|---------|---------------------------------------------------------------|
| `force`   | boolean | Required to be `true`, as resource does not support trashing. |

## Batch update product attributes
This API helps you to batch create, update and delete multiple product attributes.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/products/attributes/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/attributes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Brand"
    },
    {
      "name": "Publisher"
    }
  ],
  "update": [
    {
      "id": 2,
      "order_by": "name"
    }
  ],
  "delete": [
    1
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Brand"
    },
    {
      name: "Publisher"
    }
  ],
  update: [
    {
      id: 2,
      order_by: "name"
    }
  ],
  delete: [
    1
  ]
};

WooCommerce.post("products/attributes/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Brand'
        ],
        [
            'name' => 'Publisher'
        ]
    ],
    'update' => [
        [
            'id' => 2,
            'order_by' => 'name'
        ]
    ],
    'delete' => [
        1
    ]
];

print_r($woocommerce->post('products/attributes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Brand"
        },
        {
            "name": "Publisher"
        }
    ],
    "update": [
        {
            "id": 2,
            "order_by": "name"
        }
    ],
    "delete": [
        1
    ]
}

print(wcapi.post("products/attributes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Brand"
    },
    {
      name: "Publisher"
    }
  ],
  update: [
    {
      id: 2,
      order_by: "name"
    }
  ],
  delete: [
    1
  ]
}

woocommerce.post("products/attributes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 7,
      "name": "Brand",
      "slug": "pa_brand",
      "type": "select",
      "order_by": "menu_order",
      "has_archives": false,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/7"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes"
          }
        ]
      }
    },
    {
      "id": 8,
      "name": "Publisher",
      "slug": "pa_publisher",
      "type": "select",
      "order_by": "menu_order",
      "has_archives": false,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/8"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 2,
      "name": "Size",
      "slug": "pa_size",
      "type": "select",
      "order_by": "menu_order",
      "has_archives": false,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/2"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 1,
      "name": "Color",
      "slug": "pa_color",
      "type": "select",
      "order_by": "menu_order",
      "has_archives": true,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes/1"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/attributes"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product categories

*Source: apis/rest-api/v2/product-categories.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product categories
The product categories API allows you to create, view, update, and delete individual, or a batch, of categories.

## Product category properties
| Attribute     | Type    | Description                                                                                                      |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`                                    |
| `name`        | string  | Category name. `MANDATORY`                                                         |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                                                  |
| `parent`      | integer | The ID for the parent of the resource.                                                                           |
| `description` | string  | HTML description of the resource.                                                                                |
| `display`     | string  | Category archive display type. Options: `default`, `products`, `subcategories` and `both`. Default is `default`. |
| `image`       | object  | Image data. See [Product category - Image properties](#product-category---image-properties)                        |
| `menu_order`  | integer | Menu order, used to custom sort the resource.                                                                    |
| `count`       | integer | Number of published products for the resource. `READ-ONLY`                         |

### Product category - Image properties
| Attribute           | Type      | Description                                                                                             |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `id`                | integer   | Image ID.                                                                                               |
| `date_created`      | date-time | The date the image was created, in the site's timezone. `READ-ONLY`       |
| `date_created_gmt`  | date-time | The date the image was created, as GMT `READ-ONLY`                        |
| `date_modified`     | date-time | The date the image was last modified, in the site's timezone. `READ-ONLY` |
| `date_modified_gmt` | date-time | The date the image was last modified, as GMT. `READ-ONLY`                 |
| `src`               | string    | Image URL.                                                                                              |
| `title`             | string    | Image name.                                                                                             |
| `alt`               | string    | Image alternative text.                                                                                 |

## Create a product category
This API helps you to create a new product category.

```http
POST /wp-json/wc/v2/products/categories
```

> Example of how to create a product category:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/categories \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Clothing",
  "image": {
    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Clothing",
  image: {
    src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
  }
};

WooCommerce.post("products/categories", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Clothing',
    'image' => [
        'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg'
    ]
];

print_r($woocommerce->post('products/categories', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Clothing",
    "image": {
        "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
    }
}

print(wcapi.post("products/categories", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Clothing",
  image: {
    src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
  }
}

woocommerce.post("products/categories", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "name": "Clothing",
  "slug": "clothing",
  "parent": 0,
  "description": "",
  "display": "default",
  "image": {
    "id": 730,
    "date_created": "2017-03-23T00:01:07",
    "date_created_gmt": "2017-03-23T03:01:07",
    "date_modified": "2017-03-23T00:01:07",
    "date_modified_gmt": "2017-03-23T03:01:07",
    "src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
    "title": "",
    "alt": ""
  },
  "menu_order": 0,
  "count": 36,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/categories/9"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/categories"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product category
This API lets you retrieve a product category by ID.

```http
GET /wp-json/wc/v2/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/categories/9 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/categories/9")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/categories/9')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/categories/9").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/categories/9").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "name": "Clothing",
  "slug": "clothing",
  "parent": 0,
  "description": "",
  "display": "default",
  "image": {
    "id": 730,
    "date_created": "2017-03-23T00:01:07",
    "date_created_gmt": "2017-03-23T03:01:07",
    "date_modified": "2017-03-23T00:01:07",
    "date_modified_gmt": "2017-03-23T03:01:07",
    "src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
    "title": "",
    "alt": ""
  },
  "menu_order": 0,
  "count": 36,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/categories/9"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/categories"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all product categories
This API lets you retrieve all product categories.

```http
GET /wp-json/wc/v2/products/categories
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/categories \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/categories")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/categories')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/categories").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/categories").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 15,
    "name": "Albums",
    "slug": "albums",
    "parent": 11,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 4,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/15"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/11"
        }
      ]
    }
  },
  {
    "id": 9,
    "name": "Clothing",
    "slug": "clothing",
    "parent": 0,
    "description": "",
    "display": "default",
    "image": {
      "id": 730,
      "date_created": "2017-03-23T00:01:07",
      "date_created_gmt": "2017-03-23T03:01:07",
      "date_modified": "2017-03-23T00:01:07",
      "date_modified_gmt": "2017-03-23T03:01:07",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
      "title": "",
      "alt": ""
    },
    "menu_order": 0,
    "count": 36,
    "_links": {
      "self": [
        {
          "href": "https://example/wp-json/wc/v2/products/categories/9"
        }
      ],
      "collection": [
        {
          "href": "https://example/wp-json/wc/v2/products/categories"
        }
      ]
    }
  },
  {
    "id": 10,
    "name": "Hoodies",
    "slug": "hoodies",
    "parent": 9,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 6,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/10"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/9"
        }
      ]
    }
  },
  {
    "id": 11,
    "name": "Music",
    "slug": "music",
    "parent": 0,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 7,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/11"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories"
        }
      ]
    }
  },
  {
    "id": 12,
    "name": "Posters",
    "slug": "posters",
    "parent": 0,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 5,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/12"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories"
        }
      ]
    }
  },
  {
    "id": 13,
    "name": "Singles",
    "slug": "singles",
    "parent": 11,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 3,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/13"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/11"
        }
      ]
    }
  },
  {
    "id": 14,
    "name": "T-shirts",
    "slug": "t-shirts",
    "parent": 9,
    "description": "",
    "display": "default",
    "image": [],
    "menu_order": 0,
    "count": 6,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/14"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/categories/9"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter    | Type    | Description                                                                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                 |
| `page`       | integer | Current page of the collection. Default is `1`.                                                                                              |
| `per_page`   | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                       |
| `search`     | string  | Limit results to those matching a string.                                                                                                    |
| `exclude`    | array   | Ensure result set excludes specific ids.                                                                                                     |
| `include`    | array   | Limit result set to specific ids.                                                                                                            |
| `order`      | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                   |
| `orderby`    | string  | Sort collection by resource attribute. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. Default is `name`. |
| `hide_empty` | boolean | Whether to hide resources not assigned to any products. Default is `false`.                                                                  |
| `parent`     | integer | Limit result set to resources assigned to a specific parent.                                                                                 |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                                |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                          |

## Update a product category
This API lets you make changes to a product category.

```http
PUT /wp-json/wc/v2/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/products/categories/9 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "All kinds of clothes."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  description: "All kinds of clothes."
};

WooCommerce.put("products/categories/9", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description' => 'All kinds of clothes.'
];

print_r($woocommerce->put('products/categories/9', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "All kinds of clothes."
}

print(wcapi.put("products/categories/9", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "All kinds of clothes."
}

woocommerce.put("products/categories/9", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "name": "Clothing",
  "slug": "clothing",
  "parent": 0,
  "description": "All kinds of clothes.",
  "display": "default",
  "image": {
    "id": 730,
    "date_created": "2017-03-23T00:01:07",
    "date_created_gmt": "2017-03-23T03:01:07",
    "date_modified": "2017-03-23T00:01:07",
    "date_modified_gmt": "2017-03-23T03:01:07",
    "src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
    "title": "",
    "alt": ""
  },
  "menu_order": 0,
  "count": 36,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/categories/9"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/categories"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product category
This API helps you delete a product category.

```http
DELETE /wp-json/wc/v2/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/products/categories/9?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/categories/9", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/categories/9', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/categories/9", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/categories/9", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 9,
  "name": "Clothing",
  "slug": "clothing",
  "parent": 0,
  "description": "All kinds of clothes.",
  "display": "default",
  "image": {
    "id": 730,
    "date_created": "2017-03-23T00:01:07",
    "date_created_gmt": "2017-03-23T03:01:07",
    "date_modified": "2017-03-23T00:01:07",
    "date_modified_gmt": "2017-03-23T03:01:07",
    "src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
    "title": "",
    "alt": ""
  },
  "menu_order": 0,
  "count": 36,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/categories/9"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/categories"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product categories
This API helps you to batch create, update and delete multiple product categories.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/products/categories/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/categories/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Albums"
    },
    {
      "name": "Clothing"
    }
  ],
  "update": [
    {
      "id": 10,
      "description": "Nice hoodies"
    }
  ],
  "delete": [
    11,
    12
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Albums"
    },
    {
      name: "Clothing"
    }
  ],
  update: [
    {
      id: 10,
      description: "Nice hoodies"
    }
  ],
  delete: [
    11,
    12
  ]
};

WooCommerce.post("products/categories/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Albums'
        ],
        [
            'name' => 'Clothing'
        ]
    ],
    'update' => [
        [
            'id' => 10,
            'description' => 'Nice hoodies'
        ]
    ],
    'delete' => [
        11,
        12
    ]
];

print_r($woocommerce->post('products/categories/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Albums"
        },
        {
            "name": "Clothing"
        }
    ],
    "update": [
        {
            "id": 10,
            "description": "Nice hoodies"
        }
    ],
    "delete": [
        11,
        12
    ]
}

print(wcapi.post("products/categories/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Albums"
    },
    {
      name: "Clothing"
    }
  ],
  update: [
    {
      id: 10,
      description: "Nice hoodies"
    }
  ],
  delete: [
    11,
    12
  ]
}

woocommerce.post("products/categories/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 15,
      "name": "Albums",
      "slug": "albums",
      "parent": 11,
      "description": "",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories/15"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories"
          }
        ],
        "up": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories/11"
          }
        ]
      }
    },
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing",
      "parent": 0,
      "description": "",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories/9"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 10,
      "name": "Hoodies",
      "slug": "hoodies",
      "parent": 9,
      "description": "Nice hoodies",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 6,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories/10"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories"
          }
        ],
        "up": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories/9"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 11,
      "name": "Music",
      "slug": "music",
      "parent": 0,
      "description": "",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 7,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories/11"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories"
          }
        ]
      }
    },
    {
      "id": 12,
      "name": "Posters",
      "slug": "posters",
      "parent": 0,
      "description": "",
      "display": "default",
      "image": [],
      "menu_order": 0,
      "count": 5,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories/12"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/categories"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product shipping classes

*Source: apis/rest-api/v2/product-shipping-classes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product shipping classes
The product shipping class API allows you to create, view, update, and delete individual, or a batch, of shipping classes.

## Product shipping class properties
| Attribute     | Type    | Description                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Shipping class name. `MANDATORY`                           |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create a shipping class
This API helps you to create a new product shipping class.

```http
POST /wp-json/wc/v2/products/shipping_classes
```

> Example of how to create a product shipping class:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/shipping_classes \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Priority"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Priority"
};

WooCommerce.post("products/shipping_classes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Priority'
];

print_r($woocommerce->post('products/shipping_classes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Priority"
}

print(wcapi.post("products/shipping_classes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Priority"
}

woocommerce.post("products/shipping_classes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 32,
  "name": "Priority",
  "slug": "priority",
  "description": "",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/32"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a shipping class
This API lets you retrieve a product shipping class by ID.

```http
GET /wp-json/wc/v2/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/shipping_classes/32 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/shipping_classes/32")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/shipping_classes/32')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/shipping_classes/32").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/shipping_classes/32").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 32,
  "name": "Priority",
  "slug": "priority",
  "description": "",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/32"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all shipping classes
This API lets you retrieve all product shipping classes.

```http
GET /wp-json/wc/v2/products/shipping_classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/shipping_classes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/shipping_classes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/shipping_classes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/shipping_classes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/shipping_classes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 33,
    "name": "Express",
    "slug": "express",
    "description": "",
    "count": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/33"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
        }
      ]
    }
  },
  {
    "id": 32,
    "name": "Priority",
    "slug": "priority",
    "description": "",
    "count": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/32"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter    | Type    | Description                                                                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                 |
| `page`       | integer | Current page of the collection. Default is `1`.                                                                                              |
| `per_page`   | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                       |
| `search`     | string  | Limit results to those matching a string.                                                                                                    |
| `exclude`    | array   | Ensure result set excludes specific ids.                                                                                                     |
| `include`    | array   | Limit result set to specific ids.                                                                                                            |
| `offset`     | integer | Offset the result set by a specific number of items.                                                                                         |
| `order`      | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                   |
| `orderby`    | string  | Sort collection by resource attribute. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. Default is `name`. |
| `hide_empty` | boolean | Whether to hide resources not assigned to any products. Default is `false`.                                                                  |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                                |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                          |

## Update a shipping class
This API lets you make changes to a product shipping class.

```http
PUT /wp-json/wc/v2/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/products/shipping_classes/32 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "Priority mail."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  description: "Priority mail."
};

WooCommerce.put("products/shipping_classes/32", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description' => 'Priority mail.'
];

print_r($woocommerce->put('products/shipping_classes/32', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "Priority mail."
}

print(wcapi.put("products/shipping_classes/32", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "Priority mail."
}

woocommerce.put("products/shipping_classes/32", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 32,
  "name": "Priority",
  "slug": "priority",
  "description": "Priority mail.",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/32"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a shipping class
This API helps you delete a product shipping class.

```http
DELETE /wp-json/wc/v2/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/products/shipping_classes/32?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/shipping_classes/32", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/shipping_classes/32', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/shipping_classes/32", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/shipping_classes/32", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 32,
  "name": "Priority",
  "slug": "priority",
  "description": "Priority mail.",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/32"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update shipping classes
This API helps you to batch create, update and delete multiple product shipping classes.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/products/shipping_classes/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/shipping_classes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Small items"
    },
    {
      "name": "Large items"
    }
  ],
  "update": [
    {
      "id": 33,
      "description": "Express shipping"
    }
  ],
  "delete": [
    32
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Small items"
    },
    {
      name: "Large items"
    }
  ],
  update: [
    {
      id: 33,
      description: "Express shipping"
    }
  ],
  delete: [
    32
  ]
};

WooCommerce.post("products/shipping_classes/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Small items'
        ],
        [
            'name' => 'Large items'
        ]
    ],
    'update' => [
        [
            'id' => 33,
            'description' => 'Express shipping'
        ]
    ],
    'delete' => [
        32
    ]
];

print_r($woocommerce->post('products/shipping_classes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Small items"
        },
        {
            "name": "Large items"
        }
    ],
    "update": [
        {
            "id": 33,
            "description": "Express shipping"
        }
    ],
    "delete": [
        32
    ]
}

print(wcapi.post("products/shipping_classes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Small items"
    },
    {
      name: "Large items"
    }
  ],
  update: [
    {
      id: 33,
      description: "Express shipping"
    }
  ],
  delete: [
    32
  ]
}

woocommerce.post("products/shipping_classes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 34,
      "name": "Small items",
      "slug": "small-items",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/34"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
          }
        ]
      }
    },
    {
      "id": 35,
      "name": "Large items",
      "slug": "large-items",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/35"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 33,
      "name": "Express",
      "slug": "express",
      "description": "Express shipping",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/33"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 32,
      "name": "Priority",
      "slug": "priority",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/shipping_classes/32"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/shipping_classes"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product tags

*Source: apis/rest-api/v2/product-tags.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product tags
The product tags API allows you to create, view, update, and delete individual, or a batch, of product tags.

## Product tag properties
| Attribute     | Type    | Description                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Tag name. `MANDATORY`                                      |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create a product tag
This API helps you to create a new product tag.

```http
POST /wp-json/wc/v2/products/tags
```

> Example of how to create a product tag:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/tags \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Leather Shoes"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Leather Shoes"
};

WooCommerce.post("products/tags", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Leather Shoes'
];

print_r($woocommerce->post('products/tags', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Leather Shoes"
}

print(wcapi.post("products/tags", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Leather Shoes"
}

woocommerce.post("products/tags", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 34,
  "name": "Leather Shoes",
  "slug": "leather-shoes",
  "description": "",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/tags/34"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/tags"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product tag
This API lets you retrieve a product tag by ID.

```http
GET /wp-json/wc/v2/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/tags/34 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/tags/34")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/tags/34')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/tags/34").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/tags/34").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 34,
  "name": "Leather Shoes",
  "slug": "leather-shoes",
  "description": "",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/tags/34"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/tags"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all product tags
This API lets you retrieve all product tag.

```http
GET /wp-json/wc/v2/products/tags
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/tags \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/tags")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/tags')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/tags").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/tags").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 34,
    "name": "Leather Shoes",
    "slug": "leather-shoes",
    "description": "",
    "count": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/tags/34"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/tags"
        }
      ]
    }
  },
  {
    "id": 35,
    "name": "Oxford Shoes",
    "slug": "oxford-shoes",
    "description": "",
    "count": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/tags/35"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/tags"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter    | Type    | Description                                                                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                 |
| `page`       | integer | Current page of the collection. Default is `1`.                                                                                              |
| `per_page`   | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                       |
| `search`     | string  | Limit results to those matching a string.                                                                                                    |
| `exclude`    | array   | Ensure result set excludes specific ids.                                                                                                     |
| `include`    | array   | Limit result set to specific ids.                                                                                                            |
| `offset`     | integer | Offset the result set by a specific number of items.                                                                                         |
| `order`      | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                   |
| `orderby`    | string  | Sort collection by resource attribute. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. Default is `name`. |
| `hide_empty` | boolean | Whether to hide resources not assigned to any products. Default is `false`.                                                                  |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                                |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                          |

## Update a product tag
This API lets you make changes to a product tag.

```http
PUT /wp-json/wc/v2/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/products/tags/34 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "Genuine leather."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  description: "Genuine leather."
};

WooCommerce.put("products/tags/34", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description': 'Genuine leather.'
];

print_r($woocommerce->put('products/tags/34', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "Genuine leather."
}

print(wcapi.put("products/tags/34", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "Genuine leather."
}

woocommerce.put("products/tags/34", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 34,
  "name": "Leather Shoes",
  "slug": "leather-shoes",
  "description": "Genuine leather.",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/tags/34"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/tags"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product tag
This API helps you delete a product tag.

```http
DELETE /wp-json/wc/v2/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/products/tags/34?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/tags/34", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/tags/34', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/tags/34", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/tags/34", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 34,
  "name": "Leather Shoes",
  "slug": "leather-shoes",
  "description": "Genuine leather.",
  "count": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/tags/34"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/tags"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product tags
This API helps you to batch create, update and delete multiple product tags.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/products/tags/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/tags/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Round toe"
    },
    {
      "name": "Flat"
    }
  ],
  "update": [
    {
      "id": 34,
      "description": "Genuine leather."
    }
  ],
  "delete": [
    35
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Round toe"
    },
    {
      name: "Flat"
    }
  ],
  update: [
    {
      id: 34,
      description: "Genuine leather."
    }
  ],
  delete: [
    35
  ]
};

WooCommerce.post("products/tags/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Round toe'
        ],
        [
            'name' => 'Flat'
        ]
    ],
    'update' => [
        [
            'id' => 34,
            'description' => 'Genuine leather.'
        ]
    ],
    'delete' => [
        35
    ]
];

print_r($woocommerce->post('products/tags/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Round toe"
        },
        {
            "name": "Flat"
        }
    ],
    "update": [
        {
            "id": 34,
            "description": "Genuine leather."
        }
    ],
    "delete": [
        35
    ]
}

print(wcapi.post("products/tags/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Round toe"
    },
    {
      name: "Flat"
    }
  ],
  update: [
    {
      id: 34,
      description: "Genuine leather."
    }
  ],
  delete: [
    35
  ]
}

woocommerce.post("products/tags/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 36,
      "name": "Round toe",
      "slug": "round-toe",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/tags/36"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/tags"
          }
        ]
      }
    },
    {
      "id": 37,
      "name": "Flat",
      "slug": "flat",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/tags/37"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/tags"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 34,
      "name": "Leather Shoes",
      "slug": "leather-shoes",
      "description": "Genuine leather.",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/tags/34"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/tags"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 35,
      "name": "Oxford Shoes",
      "slug": "oxford-shoes",
      "description": "",
      "count": 0,
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/tags/35"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/tags"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Product variations

*Source: apis/rest-api/v2/product-variations.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product variations
The product variations API allows you to create, view, update, and delete individual, or a batch, of product variations.

## Product variation properties
| Attribute               | Type      | Description                                                                                                         |
|-------------------------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `id`                    | integer   | Unique identifier for the resource. `READ-ONLY`                                       |
| `date_created`          | date-time | The date the variation was created, in the site's timezone. `READ-ONLY`               |
| `date_created_gmt`      | date-time | The date the variation was created, as GMT. `READ-ONLY`                               |
| `date_modified`         | date-time | The date the variation was last modified, in the site's timezone. `READ-ONLY`         |
| `date_modified_gmt`     | date-time | The date the variation was last modified, as GMT. `READ-ONLY`                         |
| `description`           | string    | Variation description.                                                                                              |
| `permalink`             | string    | Variation URL. `READ-ONLY`                                                            |
| `sku`                   | string    | Unique identifier.                                                                                                  |
| `price`                 | string    | Current variation price. `READ-ONLY`                                                  |
| `regular_price`         | string    | Variation regular price.                                                                                            |
| `sale_price`            | string    | Variation sale price.                                                                                               |
| `date_on_sale_from`     | date-time | Start date of sale price, in the site's timezone.                                                                   |
| `date_on_sale_from_gmt` | date-time | Start date of sale price, as GMT.                                                                                   |
| `date_on_sale_to`       | date-time | End date of sale price, in the site's timezone.                                                                     |
| `date_on_sale_to_gmt`   | date-time | End date of sale price, as GMT.                                                                                     |
| `on_sale`               | boolean   | Shows if the variation is on sale. `READ-ONLY`                                        |
| `visible`               | boolean   | Define if the attribute is visible on the "Additional information" tab in the product's page. Default is `true`.    |
| `purchasable`           | boolean   | Shows if the variation can be bought. `READ-ONLY`                                     |
| `virtual`               | boolean   | If the variation is virtual. Default is `false`.                                                                    |
| `downloadable`          | boolean   | If the variation is downloadable. Default is `false`.                                                               |
| `downloads`             | array     | List of downloadable files. See [Product variation - Downloads properties](#product-variation---downloads-properties) |
| `download_limit`        | integer   | Number of times downloadable files can be downloaded after purchase. Default is `-1`.                               |
| `download_expiry`       | integer   | Number of days until access to downloadable files expires. Default is `-1`.                                         |
| `tax_status`            | string    | Tax status. Options: `taxable`, `shipping` and `none`. Default is `taxable`.                                        |
| `tax_class`             | string    | Tax class.                                                                                                          |
| `manage_stock`          | boolean, string   | Stock management at variation level. Possible values are either a boolean or `parent`. Default is `false`.  |
| `stock_quantity`        | integer   | Stock quantity.                                                                                                     |
| `in_stock`              | boolean   | Controls whether or not the variation is listed as "in stock" or "out of stock" on the frontend. Default is `true`. |
| `backorders`            | string    | If managing stock, this controls if backorders are allowed. Options: `no`, `notify` and `yes`. Default is `no`.     |
| `backorders_allowed`    | boolean   | Shows if backorders are allowed. `READ-ONLY`                                          |
| `backordered`           | boolean   | Shows if the variation is on backordered. `READ-ONLY`                                 |
| `weight`                | string    | Variation weight.                                                                                                   |
| `dimensions`            | object    | Variation dimensions. See [Product variation - Dimensions properties](#product-variation---dimensions-properties)     |
| `shipping_class`        | string    | Shipping class slug.                                                                                                |
| `shipping_class_id`     | string    | Shipping class ID. `READ-ONLY`                                                        |
| `image`                 | object    | Variation image data. See [Product variation - Image properties](#product-variation---image-properties)               |
| `attributes`            | array     | List of attributes. See [Product variation - Attributes properties](#product-variation---attributes-properties)       |
| `menu_order`            | integer   | Menu order, used to custom sort products.                                                                           |
| `meta_data`             | array     | Meta data. See [Product variation - Meta data properties](#product-variation---meta-data-properties)                  |

### Product variation - Downloads properties
| Attribute | Type   | Description |
|-----------|--------|-------------|
| `id`      | string | File ID.    |
| `name`    | string | File name.  |
| `file`    | string | File URL.   |

### Product variation - Dimensions properties
| Attribute | Type   | Description       |
|-----------|--------|-------------------|
| `length`  | string | Variation length. |
| `width`   | string | Variation width.  |
| `height`  | string | Variation height. |

### Product variation - Image properties
| Attribute           | Type      | Description                                                                                             |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|
| `id`                | integer   | Image ID.                                                                                               |
| `date_created`      | date-time | The date the image was created, in the site's timezone. `READ-ONLY`       |
| `date_created_gmt`  | date-time | The date the image was created, as GMT. `READ-ONLY`                       |
| `date_modified`     | date-time | The date the image was last modified, in the site's timezone. `READ-ONLY` |
| `date_modified_gmt` | date-time | The date the image was last modified, as GMT. `READ-ONLY`                 |
| `src`               | string    | Image URL.                                                                                              |
| `name`              | string    | Image name.                                                                                             |
| `alt`               | string    | Image alternative text.                                                                                 |
| `position`          | integer   | Image position. 0 means that the image is featured.                                                     |

### Product variation - Attributes properties
| Attribute | Type    | Description                   |
|-----------|---------|-------------------------------|
| `id`      | integer | Attribute ID.                 |
| `name`    | string  | Attribute name.               |
| `option`  | string  | Selected attribute term name. |

### Product variation - Meta data properties
| Attribute | Type    | Description                                        |
|-----------|---------|----------------------------------------------------|
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

## Create a product variation
This API helps you to create a new product variation.

```http
POST /wp-json/wc/v2/products/<product_id>/variations
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/22/variations \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "9.00",
  "image": {
    "id": 423
  },
  "attributes": [
    {
      "id": 6,
      "option": "Black"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  regular_price: "9.00",
  image: {
    id: 423
  },
  attributes: [
    {
      id: 9,
      option: "Black"
    }
  ]
};

WooCommerce.post("products/22/variations", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'regular_price' => '9.00',
    'image' => [
        'id' => 423
    ],
    'attributes' => [
        [
            'id' => 9,
            'option' => 'Black'
        ]
    ]
];

print_r($woocommerce->post('products/22/variations', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "regular_price": "9.00",
    "image": {
        "id": 423
    },
    "attributes": [
        {
            "id": 9,
            "option": "Black"
        }
    ]
}

print(wcapi.post("products/22/variations", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  regular_price: "9.00",
  image: {
    id: 423
  },
  attributes: [
    {
      id: 9,
      position: "Black"
    }
  ]
}

woocommerce.post("products/22/variations", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 732,
  "date_created": "2017-03-23T00:36:38",
  "date_created_gmt": "2017-03-23T03:36:38",
  "date_modified": "2017-03-23T00:36:38",
  "date_modified_gmt": "2017-03-23T03:36:38",
  "description": "",
  "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=black",
  "sku": "",
  "price": "9.00",
  "regular_price": "9.00",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "on_sale": false,
  "visible": true,
  "purchasable": true,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_class": "",
  "shipping_class_id": 0,
  "image": {
    "id": 423,
    "date_created": "2016-10-19T12:21:14",
    "date_created_gmt": "2016-10-19T16:21:14",
    "date_modified": "2016-10-19T12:21:14",
    "date_modified_gmt": "2016-10-19T16:21:14",
    "src": "https://example.com/wp-content/uploads/2016/10/T_4_front-12.jpg",
    "name": "",
    "alt": "",
    "position": 0
  },
  "attributes": [
    {
      "id": 6,
      "name": "Color",
      "option": "Black"
    }
  ],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/variations/732"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/variations"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product variation
This API lets you retrieve and view a specific product variation by ID.

```http
GET /wp-json/wc/v2/products/<product_id>/variations/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/22/variations/732 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/22/variations/732")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/22/variations/732')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/22/variations/732").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/22/variations/732").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 732,
  "date_created": "2017-03-23T00:36:38",
  "date_created_gmt": "2017-03-23T03:36:38",
  "date_modified": "2017-03-23T00:36:38",
  "date_modified_gmt": "2017-03-23T03:36:38",
  "description": "",
  "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=black",
  "sku": "",
  "price": "9.00",
  "regular_price": "9.00",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "on_sale": false,
  "visible": true,
  "purchasable": true,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_class": "",
  "shipping_class_id": 0,
  "image": {
    "id": 423,
    "date_created": "2016-10-19T12:21:14",
    "date_created_gmt": "2016-10-19T16:21:14",
    "date_modified": "2016-10-19T12:21:14",
    "date_modified_gmt": "2016-10-19T16:21:14",
    "src": "https://example.com/wp-content/uploads/2016/10/T_4_front-12.jpg",
    "name": "",
    "alt": "",
    "position": 0
  },
  "attributes": [
    {
      "id": 6,
      "name": "Color",
      "option": "Black"
    }
  ],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/variations/732"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/variations"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all product variations
This API helps you to view all the product variations.

```http
GET /wp-json/wc/v2/products/<product_id>/variations
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/22/variations \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/22/variations")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/22/variations')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/22/variations").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/22/variations").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 733,
    "date_created": "2017-03-23T00:53:11",
    "date_created_gmt": "2017-03-23T03:53:11",
    "date_modified": "2017-03-23T00:53:11",
    "date_modified_gmt": "2017-03-23T03:53:11",
    "description": "",
    "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=green",
    "sku": "",
    "price": "9.00",
    "regular_price": "9.00",
    "sale_price": "",
    "date_on_sale_from": null,
    "date_on_sale_from_gmt": null,
    "date_on_sale_to": null,
    "date_on_sale_to_gmt": null,
    "on_sale": false,
    "visible": true,
    "purchasable": true,
    "virtual": false,
    "downloadable": false,
    "downloads": [],
    "download_limit": -1,
    "download_expiry": -1,
    "tax_status": "taxable",
    "tax_class": "",
    "manage_stock": false,
    "stock_quantity": null,
    "in_stock": true,
    "backorders": "no",
    "backorders_allowed": false,
    "backordered": false,
    "weight": "",
    "dimensions": {
      "length": "",
      "width": "",
      "height": ""
    },
    "shipping_class": "",
    "shipping_class_id": 0,
    "image": {
      "id": 425,
      "date_created": "2016-10-19T12:21:16",
      "date_created_gmt": "2016-10-19T16:21:16",
      "date_modified": "2016-10-19T12:21:16",
      "date_modified_gmt": "2016-10-19T16:21:16",
      "src": "https://example.com/wp-content/uploads/2016/10/T_3_front-12.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    "attributes": [
      {
        "id": 6,
        "name": "Color",
        "option": "Green"
      }
    ],
    "menu_order": 0,
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/variations/733"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/variations"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22"
        }
      ]
    }
  },
  {
    "id": 732,
    "date_created": "2017-03-23T00:36:38",
    "date_created_gmt": "2017-03-23T03:36:38",
    "date_modified": "2017-03-23T00:36:38",
    "date_modified_gmt": "2017-03-23T03:36:38",
    "description": "",
    "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=black",
    "sku": "",
    "price": "9.00",
    "regular_price": "9.00",
    "sale_price": "",
    "date_on_sale_from": null,
    "date_on_sale_from_gmt": null,
    "date_on_sale_to": null,
    "date_on_sale_to_gmt": null,
    "on_sale": false,
    "visible": true,
    "purchasable": true,
    "virtual": false,
    "downloadable": false,
    "downloads": [],
    "download_limit": -1,
    "download_expiry": -1,
    "tax_status": "taxable",
    "tax_class": "",
    "manage_stock": false,
    "stock_quantity": null,
    "in_stock": true,
    "backorders": "no",
    "backorders_allowed": false,
    "backordered": false,
    "weight": "",
    "dimensions": {
      "length": "",
      "width": "",
      "height": ""
    },
    "shipping_class": "",
    "shipping_class_id": 0,
    "image": {
      "id": 423,
      "date_created": "2016-10-19T12:21:14",
      "date_created_gmt": "2016-10-19T16:21:14",
      "date_modified": "2016-10-19T12:21:14",
      "date_modified_gmt": "2016-10-19T16:21:14",
      "src": "https://example.com/wp-content/uploads/2016/10/T_4_front-12.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    "attributes": [
      {
        "id": 6,
        "name": "Color",
        "option": "Black"
      }
    ],
    "menu_order": 0,
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/variations/732"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/variations"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter        | Type    | Description                                                                                                                             |
|------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `context`        | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.            |
| `page`           | integer | Current page of the collection. Default is `1`.                                                                                         |
| `per_page`       | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                  |
| `search`         | string  | Limit results to those matching a string.                                                                                               |
| `after`          | string  | Limit response to resources published after a given ISO8601 compliant date.                                                             |
| `before`         | string  | Limit response to resources published before a given ISO8601 compliant date.                                                            |
| `dates_are_gmt`  | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                                |
| `exclude`        | array   | Ensure result set excludes specific IDs.                                                                                                |
| `include`        | array   | Limit result set to specific ids.                                                                                                       |
| `offset`         | integer | Offset the result set by a specific number of items.                                                                                    |
| `order`          | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                             |
| `orderby`        | string  | Sort collection by object attribute. Options: `date`, `id`, `include`, `title` and `slug`. Default is `date`.                           |
| `parent`         | array   | Limit result set to those of particular parent IDs.                                                                                     |
| `parent_exclude` | array   | Limit result set to all items except those of a particular parent ID.                                                                   |
| `slug`           | string  | Limit result set to products with a specific slug.                                                                                      |
| `status`         | string  | Limit result set to products assigned a specific status. Options: `any`, `draft`, `pending`, `private` and `publish`. Default is `any`. |
| `type`           | string  | Limit result set to products assigned a specific type. Options: `simple`, `grouped`, `external` and `variable`.                         |
| `sku`            | string  | Limit result set to products with a specific SKU.                                                                                       |
| `featured`       | boolean | Limit result set to featured products.                                                                                                  |
| `category`       | string  | Limit result set to products assigned a specific category ID.                                                                           |
| `tag`            | string  | Limit result set to products assigned a specific tag ID.                                                                                |
| `shipping_class` | string  | Limit result set to products assigned a specific shipping class ID.                                                                     |
| `attribute`      | string  | Limit result set to products with a specific attribute.                                                                                 |
| `attribute_term` | string  | Limit result set to products with a specific attribute term ID (required an assigned attribute).                                        |
| `tax_class`      | string  | Limit result set to products with a specific tax class. Default options: `standard`, `reduced-rate` and `zero-rate`.                    |
| `in_stock`       | boolean | Limit result set to products in stock or out of stock.                                                                                  |
| `on_sale`        | boolean | Limit result set to products on sale.                                                                                                   |
| `min_price`      | string  | Limit result set to products based on a minimum price.                                                                                  |
| `max_price`      | string  | Limit result set to products based on a maximum price.                                                                                  |
| `image_size`     | string  | Use a specific registered image size for the returned variation image `src`. Falls back to the full size if the requested size is not registered. Default is `full`. |

## Update a product variation
This API lets you make changes to a product variation.

```http
PUT /wp-json/wc/v2/products/<product_id>/variations/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/products/22/variations/733 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "10.00"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  regular_price: "10.00"
};

WooCommerce.put("products/22/variations/733", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'regular_price' => '10.00'
];

print_r($woocommerce->put('products/22/variations/733', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "regular_price": "10.00"
}

print(wcapi.put("products/22/variations/733", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  regular_price: "10.00"
}

woocommerce.put("products/22/variations/733", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 733,
  "date_created": "2017-03-23T00:53:11",
  "date_created_gmt": "2017-03-23T03:53:11",
  "date_modified": "2017-03-23T00:53:11",
  "date_modified_gmt": "2017-03-23T03:53:11",
  "description": "",
  "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=green",
  "sku": "",
  "price": "10.00",
  "regular_price": "10.00",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "on_sale": false,
  "visible": true,
  "purchasable": true,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_class": "",
  "shipping_class_id": 0,
  "image": {
    "id": 425,
    "date_created": "2016-10-19T12:21:16",
    "date_created_gmt": "2016-10-19T16:21:16",
    "date_modified": "2016-10-19T12:21:16",
    "date_modified_gmt": "2016-10-19T16:21:16",
    "src": "https://example.com/wp-content/uploads/2016/10/T_3_front-12.jpg",
    "name": "",
    "alt": "",
    "position": 0
  },
  "attributes": [
    {
      "id": 6,
      "name": "Color",
      "option": "Green"
    }
  ],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/variations/733"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/variations"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product variation
This API helps you delete a product variation.

```http
DELETE /wp-json/wc/v2/products/<product_id>/variations/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/products/22/variations/733?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/22/variations/733", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/22/variations/733', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/22/variations/733", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/22/variations/733", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 733,
  "date_created": "2017-03-23T00:53:11",
  "date_created_gmt": "2017-03-23T03:53:11",
  "date_modified": "2017-03-23T00:53:11",
  "date_modified_gmt": "2017-03-23T03:53:11",
  "description": "",
  "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=green",
  "sku": "",
  "price": "10.00",
  "regular_price": "10.00",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "on_sale": false,
  "visible": true,
  "purchasable": true,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_class": "",
  "shipping_class_id": 0,
  "image": {
    "id": 425,
    "date_created": "2016-10-19T12:21:16",
    "date_created_gmt": "2016-10-19T16:21:16",
    "date_modified": "2016-10-19T12:21:16",
    "date_modified_gmt": "2016-10-19T16:21:16",
    "src": "https://example.com/wp-content/uploads/2016/10/T_3_front-12.jpg",
    "name": "",
    "alt": "",
    "position": 0
  },
  "attributes": [
    {
      "id": 6,
      "name": "Color",
      "option": "Green"
    }
  ],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/variations/733"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/variations"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter | Type   | Description                                                   |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product variations
This API helps you to batch create, update and delete multiple product variations.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/products/<product_id>/variations/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/22/variations/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "regular_price": "10.00",
      "attributes": [
        {
          "id": 6,
          "option": "Blue"
        }
      ]
    },
    {
      "regular_price": "10.00",
      "attributes": [
        {
          "id": 6,
          "option": "White"
        }
      ]
    }
  ],
  "update": [
    {
      "id": 733,
      "regular_price": "10.00"
    }
  ],
  "delete": [
    732
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "Blue"
        }
      ]
    },
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "White"
        }
      ]
    }
  ],
  update: [
    {
      id: 733,
      regular_price: "10.00"
    }
  ],
  delete: [
    732
  ]
};

WooCommerce.post("products/22/variations/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'regular_price' => '10.00',
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'Blue'
                ]
            ]
        ],
        [
            'regular_price' => '10.00',
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'White'
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 733,
            'regular_price' => '10.00'
        ]
    ],
    'delete' => [
        732
    ]
];

print_r($woocommerce->post('products/22/variations/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "regular_price": "10.00",
            "attributes": [
                {
                    "id": 6,
                    "option": "Blue"
                }
            ]
        },
        {
            "regular_price": "10.00",
            "attributes": [
                {
                    "id": 6,
                    "option": "White"
                }
            ]
        }
    ],
    "update": [
        {
            "id": 733,
            "regular_price": "10.00"
        }
    ],
    "delete": [
        732
    ]
}

print(wcapi.post("products/22/variations/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "Blue"
        }
      ]
    },
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "White"
        }
      ]
    }
  ],
  update: [
    {
      id: 733,
      regular_price: "10.00"
    }
  ],
  delete: [
    732
  ]
}

woocommerce.post("products/22/variations/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 735,
      "date_created": "2017-03-23T01:19:37",
      "date_created_gmt": "2017-03-23T04:19:37",
      "date_modified": "2017-03-23T01:19:37",
      "date_modified_gmt": "2017-03-23T04:19:37",
      "description": "",
      "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=blue",
      "sku": "",
      "price": "10.00",
      "regular_price": "10.00",
      "sale_price": "",
      "date_on_sale_from": null,
      "date_on_sale_from_gmt": null,
      "date_on_sale_to": null,
      "date_on_sale_to_gmt": null,
      "on_sale": false,
      "visible": true,
      "purchasable": true,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_class": "",
      "shipping_class_id": 0,
      "image": {
        "id": 0,
        "date_created": "2017-03-22T22:19:40",
        "date_created_gmt": "2017-03-23T04:19:40",
        "date_modified": "2017-03-22T22:19:40",
        "date_modified_gmt": "2017-03-23T04:19:40",
        "src": "https://example.com/wp-content/plugins/woocommerce/assets/images/placeholder.png",
        "name": "Placeholder",
        "alt": "Placeholder",
        "position": 0
      },
      "attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "Blue"
        }
      ],
      "menu_order": 0,
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22/variations/735"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22/variations"
          }
        ],
        "up": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22"
          }
        ]
      }
    },
    {
      "id": 736,
      "date_created": "2017-03-23T01:19:40",
      "date_created_gmt": "2017-03-23T04:19:40",
      "date_modified": "2017-03-23T01:19:40",
      "date_modified_gmt": "2017-03-23T04:19:40",
      "description": "",
      "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=white",
      "sku": "",
      "price": "10.00",
      "regular_price": "10.00",
      "sale_price": "",
      "date_on_sale_from": null,
      "date_on_sale_from_gmt": null,
      "date_on_sale_to": null,
      "date_on_sale_to_gmt": null,
      "on_sale": false,
      "visible": true,
      "purchasable": true,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_class": "",
      "shipping_class_id": 0,
      "image": {
        "id": 0,
        "date_created": "2017-03-22T22:19:42",
        "date_created_gmt": "2017-03-23T04:19:42",
        "date_modified": "2017-03-22T22:19:42",
        "date_modified_gmt": "2017-03-23T04:19:42",
        "src": "https://example.com/wp-content/plugins/woocommerce/assets/images/placeholder.png",
        "name": "Placeholder",
        "alt": "Placeholder",
        "position": 0
      },
      "attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "White"
        }
      ],
      "menu_order": 0,
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22/variations/736"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22/variations"
          }
        ],
        "up": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 733,
      "date_created": "2017-03-23T00:53:11",
      "date_created_gmt": "2017-03-23T03:53:11",
      "date_modified": "2017-03-23T00:53:11",
      "date_modified_gmt": "2017-03-23T03:53:11",
      "description": "",
      "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=green",
      "sku": "",
      "price": "10.00",
      "regular_price": "10.00",
      "sale_price": "",
      "date_on_sale_from": null,
      "date_on_sale_from_gmt": null,
      "date_on_sale_to": null,
      "date_on_sale_to_gmt": null,
      "on_sale": false,
      "visible": true,
      "purchasable": true,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_class": "",
      "shipping_class_id": 0,
      "image": {
        "id": 425,
        "date_created": "2016-10-19T12:21:16",
        "date_created_gmt": "2016-10-19T16:21:16",
        "date_modified": "2016-10-19T12:21:16",
        "date_modified_gmt": "2016-10-19T16:21:16",
        "src": "https://example.com/wp-content/uploads/2016/10/T_3_front-12.jpg",
        "name": "",
        "alt": "",
        "position": 0
      },
      "attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "Green"
        }
      ],
      "menu_order": 0,
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22/variations/733"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22/variations"
          }
        ],
        "up": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 732,
      "date_created": "2017-03-23T00:36:38",
      "date_created_gmt": "2017-03-23T03:36:38",
      "date_modified": "2017-03-23T00:36:38",
      "date_modified_gmt": "2017-03-23T03:36:38",
      "description": "",
      "permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=black",
      "sku": "",
      "price": "9.00",
      "regular_price": "9.00",
      "sale_price": "",
      "date_on_sale_from": null,
      "date_on_sale_from_gmt": null,
      "date_on_sale_to": null,
      "date_on_sale_to_gmt": null,
      "on_sale": false,
      "visible": true,
      "purchasable": true,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_class": "",
      "shipping_class_id": 0,
      "image": {
        "id": 423,
        "date_created": "2016-10-19T12:21:14",
        "date_created_gmt": "2016-10-19T16:21:14",
        "date_modified": "2016-10-19T12:21:14",
        "date_modified_gmt": "2016-10-19T16:21:14",
        "src": "https://example.com/wp-content/uploads/2016/10/T_4_front-12.jpg",
        "name": "",
        "alt": "",
        "position": 0
      },
      "attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "Black"
        }
      ],
      "menu_order": 0,
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22/variations/732"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22/variations"
          }
        ],
        "up": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/22"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>

---

## Products

*Source: apis/rest-api/v2/products.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Products
The products API allows you to create, view, update, and delete individual, or a batch, of products.

## Product properties
| Attribute               | Type      | Description                                                                                                          |       |                                                                               |
|-------------------------|-----------|----------------------------------------------------------------------------------------------------------------------|-------|-------------------------------------------------------------------------------|
| `id`                    | integer   | Unique identifier for the resource. `READ-ONLY`                                        |       |                                                                               |
| `name`                  | string    | Product name.                                                                                                        |       |                                                                               |
| `slug`                  | string    | Product slug.                                                                                                        |       |                                                                               |
| `permalink`             | string    | Product URL. `READ-ONLY`                                                               |       |                                                                               |
| `date_created`          | date-time | The date the product was created, in the site's timezone. `READ-ONLY`                  |       |                                                                               |
| `date_created_gmt`      | date-time | The date the product was created, as GMT. `READ-ONLY`                                  |       |                                                                               |
| `date_modified`         | date-time | The date the product was last modified, in the site's timezone. `READ-ONLY`            |       |                                                                               |
| `date_modified_gmt`     | date-time | The date the product was last modified, as GMT. `READ-ONLY`                            |       |                                                                               |
| `type`                  | string    | Product type. Options: `simple`, `grouped`, `external` and `variable`. Default is `simple`.                          |       |                                                                               |
| `status`                | string    | Product status (post status). Options: `draft`, `pending`, `private` and `publish`. Default is `publish`.            |       |                                                                               |
| `featured`              | boolean   | Featured product. Default is `false`.                                                                                |       |                                                                               |
| `catalog_visibility`    | string    | Catalog visibility. Options: `visible`, `catalog`, `search` and `hidden`. Default is `visible`.                      |       |                                                                               |
| `description`           | string    | Product description.                                                                                                 |       |                                                                               |
| `short_description`     | string    | Product short description.                                                                                           |       |                                                                               |
| `sku`                   | string    | Unique identifier.                                                                                                   |       |                                                                               |
| `price`                 | string    | Current product price. `READ-ONLY`                                                     |       |                                                                               |
| `regular_price`         | string    | Product regular price.                                                                                               |       |                                                                               |
| `sale_price`            | string    | Product sale price.                                                                                                  |       |                                                                               |
| `date_on_sale_from`     | date-time | Start date of sale price, in the site's timezone.                                                                    |       |                                                                               |
| `date_on_sale_from_gmt` | date-time | Start date of sale price, as GMT.                                                                                    |       |                                                                               |
| `date_on_sale_to`       | date-time | End date of sale price, in the site's timezone.                                                                      |       |                                                                               |
| `date_on_sale_to_gmt`   | date-time | End date of sale price, as GMT.                                                                                      |       |                                                                               |
| `price_html`            | string    | Price formatted in HTML. `READ-ONLY`                                                   |       |                                                                               |
| `on_sale`               | boolean   | Shows if the product is on sale. `READ-ONLY`                                           |       |                                                                               |
| `purchasable`           | boolean   | Shows if the product can be bought. `READ-ONLY`                                        |       |                                                                               |
| `total_sales`           | integer   | Amount of sales. `READ-ONLY`                                                           |       |                                                                               |
| `virtual`               | boolean   | If the product is virtual. Default is `false`.                                                                       |       |                                                                               |
| `downloadable`          | boolean   | If the product is downloadable. Default is `false`.                                                                  |       |                                                                               |
| `downloads`             | array     | List of downloadable files. See [Product - Downloads properties](#product---downloads-properties)                      |       |                                                                               |
| `download_limit`        | integer   | Number of times downloadable files can be downloaded after purchase. Default is `-1`.                                |       |                                                                               |
| `download_expiry`       | integer   | Number of days until access to downloadable files expires. Default is `-1`.                                          |       |                                                                               |
| `external_url`          | string    | Product external URL. Only for external products.                                                                    |       |                                                                               |
| `button_text`           | string    | Product external button text. Only for external products.                                                            |       |                                                                               |
| `tax_status`            | string    | Tax status. Options: `taxable`, `shipping` and `none`. Default is `taxable`.                                         |       |                                                                               |
| `tax_class`             | string    | Tax class.                                                                                                           |       |                                                                               |
| `manage_stock`          | boolean   | Stock management at product level. Default is `false`.                                                               |       |                                                                               |
| `stock_quantity`        | integer   | Stock quantity.                                                                                                      |       |                                                                               |
| `in_stock`              | boolean   | Controls whether or not the product is listed as "in stock" or "out of stock" on the frontend. Default is `true`.    |       |                                                                               |
| `backorders`            | string    | If managing stock, this controls if backorders are allowed. Options: `no`, `notify` and `yes`. Default is `no`.      |       |                                                                               |
| `backorders_allowed`    | boolean   | Shows if backorders are allowed. `READ-ONLY`                                           |       |                                                                               |
| `backordered`           | boolean   | Shows if the product is on backordered. `READ-ONLY`                                    |       |                                                                               |
| `sold_individually`     | boolean   | Allow one item to be bought in a single order. Default is `false`.                                                   |       |                                                                               |
| `weight`                | string    | Product weight.                                                                                                      |       |                                                                               |
| `dimensions`            | object    | Product dimensions. See [Product - Dimensions properties](#product---dimensions-properties)                            |       |                                                                               |
| `shipping_required`     | boolean   | Shows if the product need to be shipped. `READ-ONLY`                                   |       |                                                                               |
| `shipping_taxable`      | boolean   | Shows whether or not the product shipping is taxable. `READ-ONLY`                      |       |                                                                               |
| `shipping_class`        | string    | Shipping class slug.                                                                                                 |       |                                                                               |
| `shipping_class_id`     | integer   | Shipping class ID. `READ-ONLY`                                                         |       |                                                                               |
| `reviews_allowed`       | boolean   | Allow reviews. Default is `true`.                                                                                    |       |                                                                               |
| `average_rating`        | string    | Reviews average rating. `READ-ONLY`                                                    |       |                                                                               |
| `rating_count`          | integer   | Amount of reviews that the product have. `READ-ONLY`                                   |       |                                                                               |
| `related_ids`           | array     | List of related products IDs. `READ-ONLY`                                              |       |                                                                               |
| `upsell_ids`            | array     | List of up-sell products IDs.                                                                                        |       |                                                                               |
| `cross_sell_ids`        | array     | List of cross-sell products IDs.                                                                                     |       |                                                                               |
| `parent_id`             | integer   | Product parent ID.                                                                                                   |       |                                                                               |
| `purchase_note`         | string    | Optional note to send the customer after purchase.                                                                   |       |                                                                               |
| `categories`            | array     | List of categories. See [Product - Categories properties](#product---categories-properties)                            |       |                                                                               |
| `tags`                  | array     | List of tags. See [Product - Tags properties](#product---tags-properties)                                              | array | List of images. See [Product - Images properties](#product---images-properties) |
| `attributes`            | array     | List of attributes. See [Product - Attributes properties](#product---attributes-properties)                            |       |                                                                               |
| `default_attributes`    | array     | Defaults variation attributes. See [Product - Default attributes properties](#product---default-attributes-properties) |       |                                                                               |
| `variations`            | array     | List of variations IDs. `READ-ONLY`                                                    |       |                                                                               |
| `grouped_products`      | array     | List of grouped products ID.                                                                                         |       |                                                                               |
| `menu_order`            | integer   | Menu order, used to custom sort products.                                                                            |       |                                                                               |
| `meta_data`             | array     | Meta data. See [Product - Meta data properties](#product---meta-data-properties)                                       |       |                                                                               |

### Product - Downloads properties
| Attribute | Type   | Description |
|-----------|--------|-------------|
| `id`      | string | File ID.    |
| `name`    | string | File name.  |
| `file`    | string | File URL.   |

### Product - Dimensions properties
| Attribute | Type   | Description     |
|-----------|--------|-----------------|
| `length`  | string | Product length. |
| `width`   | string | Product width.  |
| `height`  | string | Product height. |

### Product - Categories properties
| Attribute | Type    | Description                                              |
|-----------|---------|----------------------------------------------------------|
| `id`      | integer | Category ID.                                             |
| `name`    | string  | Category name. `READ-ONLY` |
| `slug`    | string  | Category slug. `READ-ONLY` |

### Product - Tags properties
| Attribute | Type    | Description                                         |
|-----------|---------|-----------------------------------------------------|
| `id`      | integer | Tag ID.                                             |
| `name`    | string  | Tag name. `READ-ONLY` |
| `slug`    | string  | Tag slug. `READ-ONLY` |

### Product - Images properties
| Attribute           | Type      | Description                                                                                             |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------|
| `id`                | integer   | Image ID.                                                                                               |
| `date_created`      | date-time | The date the image was created, in the site's timezone. `READ-ONLY`       |
| `date_created_gmt`  | date-time | The date the image was created, as GMT. `READ-ONLY`                       |
| `date_modified`     | date-time | The date the image was last modified, in the site's timezone. `READ-ONLY` |
| `date_modified_gmt` | date-time | The date the image was last modified, as GMT. `READ-ONLY`                 |
| `src`               | string    | Image URL.                                                                                              |
| `name`              | string    | Image name.                                                                                             |
| `alt`               | string    | Image alternative text.                                                                                 |
| `position`          | integer   | Image position. 0 means that the image is featured.                                                     |

### Product - Attributes properties
| Attribute   | Type    | Description                                                                                                       |
|-------------|---------|-------------------------------------------------------------------------------------------------------------------|
| `id`        | integer | Attribute ID.                                                                                                     |
| `name`      | string  | Attribute name.                                                                                                   |
| `position`  | integer | Attribute position.                                                                                               |
| `visible`   | boolean | Define if the attribute is visible on the "Additional information" tab in the product's page. Default is `false`. |
| `variation` | boolean | Define if the attribute can be used as variation. Default is `false`.                                             |
| `options`   | array   | List of available term names of the attribute.                                                                    |

### Product - Default attributes properties
| Attribute | Type    | Description                   |
|-----------|---------|-------------------------------|
| `id`      | integer | Attribute ID.                 |
| `name`    | string  | Attribute name.               |
| `option`  | string  | Selected attribute term name. |

### Product - Meta data properties
| Attribute | Type    | Description                                        |
|-----------|---------|----------------------------------------------------|
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

## Create a product
This API helps you to create a new product.

```http
POST /wp-json/wc/v2/products
```

> Example of how to create a `simple` product:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Premium Quality",
  "type": "simple",
  "regular_price": "21.99",
  "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "categories": [
    {
      "id": 9
    },
    {
      "id": 14
    }
  ],
  "images": [
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
      "position": 0
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
      "position": 1
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Premium Quality",
  type: "simple",
  regular_price: "21.99",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
      position: 0
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
      position: 1
    }
  ]
};

WooCommerce.post("products", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Premium Quality',
    'type' => 'simple',
    'regular_price' => '21.99',
    'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
    'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
    'categories' => [
        [
            'id' => 9
        ],
        [
            'id' => 14
        ]
    ],
    'images' => [
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg',
            'position' => 0
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg',
            'position' => 1
        ]
    ]
];

print_r($woocommerce->post('products', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Premium Quality",
    "type": "simple",
    "regular_price": "21.99",
    "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
    "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
    "categories": [
        {
            "id": 9
        },
        {
            "id": 14
        }
    ],
    "images": [
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
            "position": 0
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
            "position": 1
        }
    ]
}

print(wcapi.post("products", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Premium Quality",
  type: "simple",
  regular_price: "21.99",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
      position: 0
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
      position: 1
    }
  ]
}

woocommerce.post("products", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 794,
  "name": "Premium Quality",
  "slug": "premium-quality-19",
  "permalink": "https://example.com/product/premium-quality-19/",
  "date_created": "2017-03-23T17:01:14",
  "date_created_gmt": "2017-03-23T20:01:14",
  "date_modified": "2017-03-23T17:01:14",
  "date_modified_gmt": "2017-03-23T20:01:14",
  "type": "simple",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "21.99",
  "regular_price": "21.99",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [
    53,
    40,
    56,
    479,
    99
  ],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 792,
      "date_created": "2017-03-23T14:01:13",
      "date_created_gmt": "2017-03-23T20:01:13",
      "date_modified": "2017-03-23T14:01:13",
      "date_modified_gmt": "2017-03-23T20:01:13",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 793,
      "date_created": "2017-03-23T14:01:14",
      "date_created_gmt": "2017-03-23T20:01:14",
      "date_modified": "2017-03-23T14:01:14",
      "date_modified_gmt": "2017-03-23T20:01:14",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
      "name": "",
      "alt": "",
      "position": 1
    }
  ],
  "attributes": [],
  "default_attributes": [],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/794"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

> Example of how to create a `variable` product with global and non-global attributes:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Ship Your Idea",
  "type": "variable",
  "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "categories": [
    {
      "id": 9
    },
    {
      "id": 14
    }
  ],
  "images": [
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
      "position": 0
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg",
      "position": 1
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
      "position": 2
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg",
      "position": 3
    }
  ],
  "attributes": [
    {
      "id": 6,
      "position": 0,
      "visible": false,
      "variation": true,
      "options": [
        "Black",
        "Green"
      ]
    },
    {
      "name": "Size",
      "position": 0,
      "visible": true,
      "variation": true,
      "options": [
        "S",
        "M"
      ]
    }
  ],
  "default_attributes": [
    {
      "id": 6,
      "option": "Black"
    },
    {
      "name": "Size",
      "option": "S"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Ship Your Idea",
  type: "variable",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
      position: 0
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg",
      position: 1
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
      position: 2
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg",
      position: 3
    }
  ],
  attributes: [
    {
      id: 6,
      position: 0,
      visible: true,
      variation: true,
      options: [
        "Black",
        "Green"
      ]
    },
    {
      name: "Size",
      position: 0,
      visible: false,
      variation: true,
      options: [
        "S",
        "M"
      ]
    }
  ],
  default_attributes: [
    {
      id: 6,
      option: "Black"
    },
    {
      name: "Size",
      option: "S"
    }
  ]
};

WooCommerce.post("products", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Ship Your Idea',
    'type' => 'variable',
    'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
    'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
    'categories' => [
        [
            'id' => 9
        ],
        [
            'id' => 14
        ]
    ],
    'images' => [
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg',
            'position' => 0
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg',
            'position' => 1
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg',
            'position' => 2
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg',
            'position' => 3
        ]
    ],
    'attributes' => [
        [
            'id' => 6,
            'position' => 0,
            'visible' => false,
            'variation' => true,
            'options' => [
                'Black',
                'Green'
            ]
        ],
        [
            'name' => 'Size',
            'position' => 0,
            'visible' => true,
            'variation' => true,
            'options' => [
                'S',
                'M'
            ]
        ]
    ],
    'default_attributes' => [
        [
            'id' => 6,
            'option' => 'Black'
        ],
        [
            'name' => 'Size',
            'option' => 'S'
        ]
    ]
];

print_r($woocommerce->post('products', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Ship Your Idea",
    "type": "variable",
    "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
    "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
    "categories": [
        {
            "id": 9
        },
        {
            "id": 14
        }
    ],
    "images": [
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
            "position": 0
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg",
            "position": 1
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
            "position": 2
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg",
            "position": 3
        }
    ],
    "attributes": [
        {
            "id": 6,
            "position": 0,
            "visible": False,
            "variation": True,
            "options": [
                "Black",
                "Green"
            ]
        },
        {
            "name": "Size",
            "position": 0,
            "visible": True,
            "variation": True,
            "options": [
                "S",
                "M"
            ]
        }
    ],
    "default_attributes": [
        {
            "id": 6,
            "option": "Black"
        },
        {
            "name": "Size",
            "option": "S"
        }
    ]
}

print(wcapi.post("products", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Ship Your Idea",
  type: "variable",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg",
      position: 0
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg",
      position: 1
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg",
      position: 2
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg",
      position: 3
    }
  ],
  attributes: [
    {
      id: 6,
      position: 0,
      visible: false,
      variation: true,
      options: [
        "Black",
        "Green"
      ]
    },
    {
      name: "Size",
      position: 0,
      visible: true,
      variation: true,
      options: [
        "S",
        "M"
      ]
    }
  ],
  default_attributes: [
    {
      id: 6,
      option: "Black"
    },
    {
      name: "Size",
      option: "S"
    }
  ]
}

woocommerce.post("products", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 799,
  "name": "Ship Your Idea",
  "slug": "ship-your-idea-22",
  "permalink": "https://example.com/product/ship-your-idea-22/",
  "date_created": "2017-03-23T17:03:12",
  "date_created_gmt": "2017-03-23T20:03:12",
  "date_modified": "2017-03-23T17:03:12",
  "date_modified_gmt": "2017-03-23T20:03:12",
  "type": "variable",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "",
  "regular_price": "",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "price_html": "",
  "on_sale": false,
  "purchasable": false,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [
    472,
    387,
    19,
    53,
    396
  ],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 795,
      "date_created": "2017-03-23T14:03:08",
      "date_created_gmt": "2017-03-23T20:03:08",
      "date_modified": "2017-03-23T14:03:08",
      "date_modified_gmt": "2017-03-23T20:03:08",
      "src": "https://example.com/wp-content/uploads/2017/03/T_4_front-11.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 796,
      "date_created": "2017-03-23T14:03:09",
      "date_created_gmt": "2017-03-23T20:03:09",
      "date_modified": "2017-03-23T14:03:09",
      "date_modified_gmt": "2017-03-23T20:03:09",
      "src": "https://example.com/wp-content/uploads/2017/03/T_4_back-10.jpg",
      "name": "",
      "alt": "",
      "position": 1
    },
    {
      "id": 797,
      "date_created": "2017-03-23T14:03:10",
      "date_created_gmt": "2017-03-23T20:03:10",
      "date_modified": "2017-03-23T14:03:10",
      "date_modified_gmt": "2017-03-23T20:03:10",
      "src": "https://example.com/wp-content/uploads/2017/03/T_3_front-10.jpg",
      "name": "",
      "alt": "",
      "position": 2
    },
    {
      "id": 798,
      "date_created": "2017-03-23T14:03:11",
      "date_created_gmt": "2017-03-23T20:03:11",
      "date_modified": "2017-03-23T14:03:11",
      "date_modified_gmt": "2017-03-23T20:03:11",
      "src": "https://example.com/wp-content/uploads/2017/03/T_3_back-10.jpg",
      "name": "",
      "alt": "",
      "position": 3
    }
  ],
  "attributes": [
    {
      "id": 6,
      "name": "Color",
      "position": 0,
      "visible": false,
      "variation": true,
      "options": [
        "Black",
        "Green"
      ]
    },
    {
      "id": 0,
      "name": "Size",
      "position": 0,
      "visible": true,
      "variation": true,
      "options": [
        "S",
        "M"
      ]
    }
  ],
  "default_attributes": [
    {
      "id": 6,
      "name": "Color",
      "option": "black"
    },
    {
      "id": 0,
      "name": "Size",
      "option": "S"
    }
  ],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/799"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a product
This API lets you retrieve and view a specific product by ID.

```http
GET /wp-json/wc/v2/products/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/794 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/794")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/794')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/794").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/794").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 794,
  "name": "Premium Quality",
  "slug": "premium-quality-19",
  "permalink": "https://example.com/product/premium-quality-19/",
  "date_created": "2017-03-23T17:01:14",
  "date_created_gmt": "2017-03-23T20:01:14",
  "date_modified": "2017-03-23T17:01:14",
  "date_modified_gmt": "2017-03-23T20:01:14",
  "type": "simple",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "21.99",
  "regular_price": "21.99",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [
    53,
    40,
    56,
    479,
    99
  ],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 792,
      "date_created": "2017-03-23T14:01:13",
      "date_created_gmt": "2017-03-23T20:01:13",
      "date_modified": "2017-03-23T14:01:13",
      "date_modified_gmt": "2017-03-23T20:01:13",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 793,
      "date_created": "2017-03-23T14:01:14",
      "date_created_gmt": "2017-03-23T20:01:14",
      "date_modified": "2017-03-23T14:01:14",
      "date_modified_gmt": "2017-03-23T20:01:14",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
      "name": "",
      "alt": "",
      "position": 1
    }
  ],
  "attributes": [],
  "default_attributes": [],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/794"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all products
This API helps you to view all the products.

```http
GET /wp-json/wc/v2/products
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 799,
    "name": "Ship Your Idea",
    "slug": "ship-your-idea-22",
    "permalink": "https://example.com/product/ship-your-idea-22/",
    "date_created": "2017-03-23T17:03:12",
    "date_created_gmt": "2017-03-23T20:03:12",
    "date_modified": "2017-03-23T17:03:12",
    "date_modified_gmt": "2017-03-23T20:03:12",
    "type": "variable",
    "status": "publish",
    "featured": false,
    "catalog_visibility": "visible",
    "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
    "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
    "sku": "",
    "price": "",
    "regular_price": "",
    "sale_price": "",
    "date_on_sale_from": null,
    "date_on_sale_from_gmt": null,
    "date_on_sale_to": null,
    "date_on_sale_to_gmt": null,
    "price_html": "",
    "on_sale": false,
    "purchasable": false,
    "total_sales": 0,
    "virtual": false,
    "downloadable": false,
    "downloads": [],
    "download_limit": -1,
    "download_expiry": -1,
    "external_url": "",
    "button_text": "",
    "tax_status": "taxable",
    "tax_class": "",
    "manage_stock": false,
    "stock_quantity": null,
    "in_stock": true,
    "backorders": "no",
    "backorders_allowed": false,
    "backordered": false,
    "sold_individually": false,
    "weight": "",
    "dimensions": {
      "length": "",
      "width": "",
      "height": ""
    },
    "shipping_required": true,
    "shipping_taxable": true,
    "shipping_class": "",
    "shipping_class_id": 0,
    "reviews_allowed": true,
    "average_rating": "0.00",
    "rating_count": 0,
    "related_ids": [
      31,
      22,
      369,
      414,
      56
    ],
    "upsell_ids": [],
    "cross_sell_ids": [],
    "parent_id": 0,
    "purchase_note": "",
    "categories": [
      {
        "id": 9,
        "name": "Clothing",
        "slug": "clothing"
      },
      {
        "id": 14,
        "name": "T-shirts",
        "slug": "t-shirts"
      }
    ],
    "tags": [],
    "images": [
      {
        "id": 795,
        "date_created": "2017-03-23T14:03:08",
        "date_created_gmt": "2017-03-23T20:03:08",
        "date_modified": "2017-03-23T14:03:08",
        "date_modified_gmt": "2017-03-23T20:03:08",
        "src": "https://example.com/wp-content/uploads/2017/03/T_4_front-11.jpg",
        "name": "",
        "alt": "",
        "position": 0
      },
      {
        "id": 796,
        "date_created": "2017-03-23T14:03:09",
        "date_created_gmt": "2017-03-23T20:03:09",
        "date_modified": "2017-03-23T14:03:09",
        "date_modified_gmt": "2017-03-23T20:03:09",
        "src": "https://example.com/wp-content/uploads/2017/03/T_4_back-10.jpg",
        "name": "",
        "alt": "",
        "position": 1
      },
      {
        "id": 797,
        "date_created": "2017-03-23T14:03:10",
        "date_created_gmt": "2017-03-23T20:03:10",
        "date_modified": "2017-03-23T14:03:10",
        "date_modified_gmt": "2017-03-23T20:03:10",
        "src": "https://example.com/wp-content/uploads/2017/03/T_3_front-10.jpg",
        "name": "",
        "alt": "",
        "position": 2
      },
      {
        "id": 798,
        "date_created": "2017-03-23T14:03:11",
        "date_created_gmt": "2017-03-23T20:03:11",
        "date_modified": "2017-03-23T14:03:11",
        "date_modified_gmt": "2017-03-23T20:03:11",
        "src": "https://example.com/wp-content/uploads/2017/03/T_3_back-10.jpg",
        "name": "",
        "alt": "",
        "position": 3
      }
    ],
    "attributes": [
      {
        "id": 6,
        "name": "Color",
        "position": 0,
        "visible": false,
        "variation": true,
        "options": [
          "Black",
          "Green"
        ]
      },
      {
        "id": 0,
        "name": "Size",
        "position": 0,
        "visible": true,
        "variation": true,
        "options": [
          "S",
          "M"
        ]
      }
    ],
    "default_attributes": [],
    "variations": [],
    "grouped_products": [],
    "menu_order": 0,
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/799"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products"
        }
      ]
    }
  },
  {
    "id": 794,
    "name": "Premium Quality",
    "slug": "premium-quality-19",
    "permalink": "https://example.com/product/premium-quality-19/",
    "date_created": "2017-03-23T17:01:14",
    "date_created_gmt": "2017-03-23T20:01:14",
    "date_modified": "2017-03-23T17:01:14",
    "date_modified_gmt": "2017-03-23T20:01:14",
    "type": "simple",
    "status": "publish",
    "featured": false,
    "catalog_visibility": "visible",
    "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
    "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
    "sku": "",
    "price": "21.99",
    "regular_price": "21.99",
    "sale_price": "",
    "date_on_sale_from": null,
    "date_on_sale_from_gmt": null,
    "date_on_sale_to": null,
    "date_on_sale_to_gmt": null,
    "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
    "on_sale": false,
    "purchasable": true,
    "total_sales": 0,
    "virtual": false,
    "downloadable": false,
    "downloads": [],
    "download_limit": -1,
    "download_expiry": -1,
    "external_url": "",
    "button_text": "",
    "tax_status": "taxable",
    "tax_class": "",
    "manage_stock": false,
    "stock_quantity": null,
    "in_stock": true,
    "backorders": "no",
    "backorders_allowed": false,
    "backordered": false,
    "sold_individually": false,
    "weight": "",
    "dimensions": {
      "length": "",
      "width": "",
      "height": ""
    },
    "shipping_required": true,
    "shipping_taxable": true,
    "shipping_class": "",
    "shipping_class_id": 0,
    "reviews_allowed": true,
    "average_rating": "0.00",
    "rating_count": 0,
    "related_ids": [
      463,
      47,
      31,
      387,
      458
    ],
    "upsell_ids": [],
    "cross_sell_ids": [],
    "parent_id": 0,
    "purchase_note": "",
    "categories": [
      {
        "id": 9,
        "name": "Clothing",
        "slug": "clothing"
      },
      {
        "id": 14,
        "name": "T-shirts",
        "slug": "t-shirts"
      }
    ],
    "tags": [],
    "images": [
      {
        "id": 792,
        "date_created": "2017-03-23T14:01:13",
        "date_created_gmt": "2017-03-23T20:01:13",
        "date_modified": "2017-03-23T14:01:13",
        "date_modified_gmt": "2017-03-23T20:01:13",
        "src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
        "name": "",
        "alt": "",
        "position": 0
      },
      {
        "id": 793,
        "date_created": "2017-03-23T14:01:14",
        "date_created_gmt": "2017-03-23T20:01:14",
        "date_modified": "2017-03-23T14:01:14",
        "date_modified_gmt": "2017-03-23T20:01:14",
        "src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
        "name": "",
        "alt": "",
        "position": 1
      }
    ],
    "attributes": [],
    "default_attributes": [
      {
        "id": 6,
        "name": "Color",
        "option": "black"
      },
      {
        "id": 0,
        "name": "Size",
        "option": "S"
      }
    ],
    "variations": [],
    "grouped_products": [],
    "menu_order": 0,
    "meta_data": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/794"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter        | Type    | Description                                                                                                                             |
|------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `context`        | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.            |
| `page`           | integer | Current page of the collection. Default is `1`.                                                                                         |
| `per_page`       | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                  |
| `search`         | string  | Limit results to those matching a string.                                                                                               |
| `after`          | string  | Limit response to resources published after a given ISO8601 compliant date.                                                             |
| `before`         | string  | Limit response to resources published before a given ISO8601 compliant date.                                                            |
| `dates_are_gmt`  | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                                |
| `exclude`        | array   | Ensure result set excludes specific IDs.                                                                                                |
| `include`        | array   | Limit result set to specific ids.                                                                                                       |
| `offset`         | integer | Offset the result set by a specific number of items.                                                                                    |
| `order`          | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                             |
| `orderby`        | string  | Sort collection by object attribute. Options: `date`, `id`, `include`, `title` and `slug`. Default is `date`.                           |
| `parent`         | array   | Limit result set to those of particular parent IDs.                                                                                     |
| `parent_exclude` | array   | Limit result set to all items except those of a particular parent ID.                                                                   |
| `slug`           | string  | Limit result set to products with a specific slug.                                                                                      |
| `status`         | string  | Limit result set to products assigned a specific status. Options: `any`, `draft`, `pending`, `private` and `publish`. Default is `any`. |
| `type`           | string  | Limit result set to products assigned a specific type. Options: `simple`, `grouped`, `external` and `variable`.                         |
| `sku`            | string  | Limit result set to products with a specific SKU.                                                                                       |
| `featured`       | boolean | Limit result set to featured products.                                                                                                  |
| `category`       | string  | Limit result set to products assigned a specific category ID.                                                                           |
| `tag`            | string  | Limit result set to products assigned a specific tag ID.                                                                                |
| `shipping_class` | string  | Limit result set to products assigned a specific shipping class ID.                                                                     |
| `attribute`      | string  | Limit result set to products with a specific attribute.                                                                                 |
| `attribute_term` | string  | Limit result set to products with a specific attribute term ID (required an assigned attribute).                                        |
| `tax_class`      | string  | Limit result set to products with a specific tax class. Default options: `standard`, `reduced-rate` and `zero-rate`.                    |
| `in_stock`       | boolean | Limit result set to products in stock or out of stock.                                                                                  |
| `on_sale`        | boolean | Limit result set to products on sale.                                                                                                   |
| `min_price`      | string  | Limit result set to products based on a minimum price.                                                                                  |
| `max_price`      | string  | Limit result set to products based on a maximum price.                                                                                  |
| `image_size`     | string  | Use a specific registered image size for the returned image `src` values. Falls back to the full size if the requested size is not registered. Default is `full`. |

## Update a product
This API lets you make changes to a product.

```http
PUT /wp-json/wc/v2/products/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/products/794 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "24.54"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  regular_price: "24.54"
};

WooCommerce.put("products/794", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'regular_price' => '24.54'
];

print_r($woocommerce->put('products/794', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "regular_price": "24.54"
}

print(wcapi.put("products/794", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  regular_price: "24.54"
}

woocommerce.put("products/794", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 794,
  "name": "Premium Quality",
  "slug": "premium-quality-19",
  "permalink": "https://example.com/product/premium-quality-19/",
  "date_created": "2017-03-23T17:01:14",
  "date_created_gmt": "2017-03-23T20:01:14",
  "date_modified": "2017-03-23T17:01:14",
  "date_modified_gmt": "2017-03-23T20:01:14",
  "type": "simple",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "24.54",
  "regular_price": "24.54",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>24.54</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [
    479,
    387,
    22,
    463,
    396
  ],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 792,
      "date_created": "2017-03-23T14:01:13",
      "date_created_gmt": "2017-03-23T20:01:13",
      "date_modified": "2017-03-23T14:01:13",
      "date_modified_gmt": "2017-03-23T20:01:13",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 793,
      "date_created": "2017-03-23T14:01:14",
      "date_created_gmt": "2017-03-23T20:01:14",
      "date_modified": "2017-03-23T14:01:14",
      "date_modified_gmt": "2017-03-23T20:01:14",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
      "name": "",
      "alt": "",
      "position": 1
    }
  ],
  "attributes": [],
  "default_attributes": [],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/794"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a product
This API helps you delete a product.

```http
DELETE /wp-json/wc/v2/products/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/products/794?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("products/794", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/794', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/794", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/794", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 794,
  "name": "Premium Quality",
  "slug": "premium-quality-19",
  "permalink": "https://example.com/product/premium-quality-19/",
  "date_created": "2017-03-23T17:01:14",
  "date_created_gmt": "2017-03-23T20:01:14",
  "date_modified": "2017-03-23T17:01:14",
  "date_modified_gmt": "2017-03-23T20:01:14",
  "type": "simple",
  "status": "publish",
  "featured": false,
  "catalog_visibility": "visible",
  "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
  "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
  "sku": "",
  "price": "24.54",
  "regular_price": "24.54",
  "sale_price": "",
  "date_on_sale_from": null,
  "date_on_sale_from_gmt": null,
  "date_on_sale_to": null,
  "date_on_sale_to_gmt": null,
  "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>24.54</span>",
  "on_sale": false,
  "purchasable": true,
  "total_sales": 0,
  "virtual": false,
  "downloadable": false,
  "downloads": [],
  "download_limit": -1,
  "download_expiry": -1,
  "external_url": "",
  "button_text": "",
  "tax_status": "taxable",
  "tax_class": "",
  "manage_stock": false,
  "stock_quantity": null,
  "in_stock": true,
  "backorders": "no",
  "backorders_allowed": false,
  "backordered": false,
  "sold_individually": false,
  "weight": "",
  "dimensions": {
    "length": "",
    "width": "",
    "height": ""
  },
  "shipping_required": true,
  "shipping_taxable": true,
  "shipping_class": "",
  "shipping_class_id": 0,
  "reviews_allowed": true,
  "average_rating": "0.00",
  "rating_count": 0,
  "related_ids": [
    479,
    387,
    22,
    463,
    396
  ],
  "upsell_ids": [],
  "cross_sell_ids": [],
  "parent_id": 0,
  "purchase_note": "",
  "categories": [
    {
      "id": 9,
      "name": "Clothing",
      "slug": "clothing"
    },
    {
      "id": 14,
      "name": "T-shirts",
      "slug": "t-shirts"
    }
  ],
  "tags": [],
  "images": [
    {
      "id": 792,
      "date_created": "2017-03-23T14:01:13",
      "date_created_gmt": "2017-03-23T20:01:13",
      "date_modified": "2017-03-23T14:01:13",
      "date_modified_gmt": "2017-03-23T20:01:13",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
      "name": "",
      "alt": "",
      "position": 0
    },
    {
      "id": 793,
      "date_created": "2017-03-23T14:01:14",
      "date_created_gmt": "2017-03-23T20:01:14",
      "date_modified": "2017-03-23T14:01:14",
      "date_modified_gmt": "2017-03-23T20:01:14",
      "src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
      "name": "",
      "alt": "",
      "position": 1
    }
  ],
  "attributes": [],
  "default_attributes": [],
  "variations": [],
  "grouped_products": [],
  "menu_order": 0,
  "meta_data": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/794"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter | Type   | Description                                                               |
|-----------|--------|---------------------------------------------------------------------------|
| `force`   | string | Use `true` whether to permanently delete the product, Default is `false`. |

## Batch update products
This API helps you to batch create, update and delete multiple products.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/products/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/products/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Woo Single #1",
      "type": "simple",
      "regular_price": "21.99",
      "virtual": true,
      "downloadable": true,
      "downloads": [
        {
          "name": "Woo Single",
          "file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      "categories": [
        {
          "id": 11
        },
        {
          "id": 13
        }
      ],
      "images": [
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg",
          "position": 0
        }
      ]
    },
    {
      "name": "New Premium Quality",
      "type": "simple",
      "regular_price": "21.99",
      "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      "categories": [
        {
          "id": 9
        },
        {
          "id": 14
        }
      ],
      "images": [
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
          "position": 0
        },
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
          "position": 1
        }
      ]
    }
  ],
  "update": [
    {
      "id": 799,
      "default_attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "Green"
        },
        {
          "id": 0,
          "name": "Size",
          "option": "M"
        }
      ]
    }
  ],
  "delete": [
    794
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Woo Single #1",
      type: "simple",
      regular_price: "21.99",
      virtual: true,
      downloadable: true,
      downloads: [
        {
          name: "Woo Single",
          file: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      categories: [
        {
          id: 11
        },
        {
          id: 13
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg",
          position: 0
        }
      ]
    },
    {
      name: "New Premium Quality",
      type: "simple",
      regular_price: "21.99",
      description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      categories: [
        {
          id: 9
        },
        {
          id: 14
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
          position: 0
        },
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
          position: 1
        }
      ]
    }
  ],
  update: [
    {
      id: 799,
      default_attributes: [
        {
          id: 6,
          name: "Color",
          option: "Green"
        },
        {
          id: 0,
          name: "Size",
          option: "M"
        }
      ]
    }
  ],
  delete: [
    794
  ]
};

WooCommerce.post("products/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Woo Single #1',
            'type' => 'simple',
            'regular_price' => '21.99',
            'virtual' => true,
            'downloadable' => true,
            'downloads' => [
                [
                    'name' => 'Woo Single',
                    'file' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg'
                ]
            ],
            'categories' => [
                [
                    'id' => 11
                ],
                [
                    'id' => 13
                ]
            ],
            'images' => [
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg',
                    'position' => 0
                ]
            ]
        ],
        [
            'name' => 'New Premium Quality',
            'type' => 'simple',
            'regular_price' => '21.99',
            'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
            'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
            'categories' => [
                [
                    'id' => 9
                ],
                [
                    'id' => 14
                ]
            ],
            'images' => [
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg',
                    'position' => 0
                ],
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg',
                    'position' => 1
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 799,
            'default_attributes' => [
                [
                    'id' => 6,
                    'name' => 'Color',
                    'option' => 'Green'
                ],
                [
                    'id' => 0,
                    'name' => 'Size',
                    'option' => 'M'
                ]
            ]
        ]
    ],
    'delete' => [
        794
    ]
];

print_r($woocommerce->post('products/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Woo Single #1",
            "type": "simple",
            "regular_price": "21.99",
            "virtual": True,
            "downloadable": True,
            "downloads": [
                {
                    "name": "Woo Single",
                    "file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
                }
            ],
            "categories": [
                {
                    "id": 11
                },
                {
                    "id": 13
                }
            ],
            "images": [
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg",
                    "position": 0
                }
            ]
        },
        {
            "name": "New Premium Quality",
            "type": "simple",
            "regular_price": "21.99",
            "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
            "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
            "categories": [
                {
                    "id": 9
                },
                {
                    "id": 14
                }
            ],
            "images": [
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
                    "position": 0
                },
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
                    "position": 1
                }
            ]
        }
    ],
    "update": [
        {
            "id": 799,
            "default_attributes": [
                {
                    "id": 6,
                    "name": "Color",
                    "option": "Green"
                },
                {
                    "id": 0,
                    "name": "Size",
                    "option": "M"
                }
            ]
        }
    ],
    "delete": [
        794
    ]
}

print(wcapi.post("products/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Woo Single #1",
      type: "simple",
      regular_price: "21.99",
      virtual: true,
      downloadable: true,
      downloads: [
        {
          name: "Woo Single",
          file: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      categories: [
        {
          id: 11
        },
        {
          id: 13
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg",
          position: 0
        }
      ]
    },
    {
      name: "New Premium Quality",
      type: "simple",
      regular_price: "21.99",
      description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      categories: [
        {
          id: 9
        },
        {
          id: 14
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg",
          position: 0
        },
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
          position: 1
        }
      ]
    }
  ],
  update: [
    {
      id: 799,
      default_attributes: [
        {
          id: 6,
          name: "Color,
          option: "Green"
        },
        {
          id: 0,
          name: "Size",
          option: "M"
        }
      ]
    }
  ],
  delete: [
    794
  ]
}

woocommerce.post("products/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 801,
      "name": "Woo Single #1",
      "slug": "woo-single-1-4",
      "permalink": "https://example.com/product/woo-single-1-4/",
      "date_created": "2017-03-23T17:35:43",
      "date_created_gmt": "2017-03-23T20:35:43",
      "date_modified": "2017-03-23T17:35:43",
      "date_modified_gmt": "2017-03-23T20:35:43",
      "type": "simple",
      "status": "publish",
      "featured": false,
      "catalog_visibility": "visible",
      "description": "",
      "short_description": "",
      "sku": "",
      "price": "21.99",
      "regular_price": "21.99",
      "sale_price": "",
      "date_on_sale_from": null,
      "date_on_sale_from_gmt": null,
      "date_on_sale_to": null,
      "date_on_sale_to_gmt": null,
      "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
      "on_sale": false,
      "purchasable": true,
      "total_sales": 0,
      "virtual": true,
      "downloadable": true,
      "downloads": [
        {
          "id": 0,
          "name": "Woo Single",
          "file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      "download_limit": -1,
      "download_expiry": -1,
      "external_url": "",
      "button_text": "",
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "sold_individually": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_required": false,
      "shipping_taxable": true,
      "shipping_class": "",
      "shipping_class_id": 0,
      "reviews_allowed": true,
      "average_rating": "0.00",
      "rating_count": 0,
      "related_ids": [
        588,
        87,
        573,
        96,
        329
      ],
      "upsell_ids": [],
      "cross_sell_ids": [],
      "parent_id": 0,
      "purchase_note": "",
      "categories": [
        {
          "id": 11,
          "name": "Music",
          "slug": "music"
        },
        {
          "id": 13,
          "name": "Singles",
          "slug": "singles"
        }
      ],
      "tags": [],
      "images": [
        {
          "id": 800,
          "date_created": "2017-03-23T14:35:43",
          "date_created_gmt": "2017-03-23T20:35:43",
          "date_modified": "2017-03-23T14:35:43",
          "date_modified_gmt": "2017-03-23T20:35:43",
          "src": "https://example.com/wp-content/uploads/2017/03/cd_4_angle.jpg",
          "name": "",
          "alt": "",
          "position": 0
        }
      ],
      "attributes": [],
      "default_attributes": [],
      "variations": [],
      "grouped_products": [],
      "menu_order": 0,
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/801"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products"
          }
        ]
      }
    },
    {
      "id": 804,
      "name": "New Premium Quality",
      "slug": "new-premium-quality",
      "permalink": "https://example.com/product/new-premium-quality/",
      "date_created": "2017-03-23T17:35:48",
      "date_created_gmt": "2017-03-23T20:35:48",
      "date_modified": "2017-03-23T17:35:48",
      "date_modified_gmt": "2017-03-23T20:35:48",
      "type": "simple",
      "status": "publish",
      "featured": false,
      "catalog_visibility": "visible",
      "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
      "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
      "sku": "",
      "price": "21.99",
      "regular_price": "21.99",
      "sale_price": "",
      "date_on_sale_from": null,
      "date_on_sale_from_gmt": null,
      "date_on_sale_to": null,
      "date_on_sale_to_gmt": null,
      "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
      "on_sale": false,
      "purchasable": true,
      "total_sales": 0,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "external_url": "",
      "button_text": "",
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "sold_individually": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_required": true,
      "shipping_taxable": true,
      "shipping_class": "",
      "shipping_class_id": 0,
      "reviews_allowed": true,
      "average_rating": "0.00",
      "rating_count": 0,
      "related_ids": [
        458,
        56,
        99,
        34,
        378
      ],
      "upsell_ids": [],
      "cross_sell_ids": [],
      "parent_id": 0,
      "purchase_note": "",
      "categories": [
        {
          "id": 9,
          "name": "Clothing",
          "slug": "clothing"
        },
        {
          "id": 14,
          "name": "T-shirts",
          "slug": "t-shirts"
        }
      ],
      "tags": [],
      "images": [
        {
          "id": 802,
          "date_created": "2017-03-23T14:35:47",
          "date_created_gmt": "2017-03-23T20:35:47",
          "date_modified": "2017-03-23T14:35:47",
          "date_modified_gmt": "2017-03-23T20:35:47",
          "src": "https://example.com/wp-content/uploads/2017/03/T_2_front-5.jpg",
          "name": "",
          "alt": "",
          "position": 0
        },
        {
          "id": 803,
          "date_created": "2017-03-23T14:35:48",
          "date_created_gmt": "2017-03-23T20:35:48",
          "date_modified": "2017-03-23T14:35:48",
          "date_modified_gmt": "2017-03-23T20:35:48",
          "src": "https://example.com/wp-content/uploads/2017/03/T_2_back-3.jpg",
          "name": "",
          "alt": "",
          "position": 1
        }
      ],
      "attributes": [],
      "default_attributes": [],
      "variations": [],
      "grouped_products": [],
      "menu_order": 0,
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/804"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 799,
      "name": "Ship Your Idea",
      "slug": "ship-your-idea-22",
      "permalink": "https://example.com/product/ship-your-idea-22/",
      "date_created": "2017-03-23T17:03:12",
      "date_created_gmt": "2017-03-23T20:03:12",
      "date_modified": "2017-03-23T17:03:12",
      "date_modified_gmt": "2017-03-23T20:03:12",
      "type": "variable",
      "status": "publish",
      "featured": false,
      "catalog_visibility": "visible",
      "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
      "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
      "sku": "",
      "price": "",
      "regular_price": "",
      "sale_price": "",
      "date_on_sale_from": null,
      "date_on_sale_from_gmt": null,
      "date_on_sale_to": null,
      "date_on_sale_to_gmt": null,
      "price_html": "",
      "on_sale": false,
      "purchasable": false,
      "total_sales": 0,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "external_url": "",
      "button_text": "",
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "sold_individually": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_required": true,
      "shipping_taxable": true,
      "shipping_class": "",
      "shipping_class_id": 0,
      "reviews_allowed": true,
      "average_rating": "0.00",
      "rating_count": 0,
      "related_ids": [
        414,
        40,
        34,
        463,
        15
      ],
      "upsell_ids": [],
      "cross_sell_ids": [],
      "parent_id": 0,
      "purchase_note": "",
      "categories": [
        {
          "id": 9,
          "name": "Clothing",
          "slug": "clothing"
        },
        {
          "id": 14,
          "name": "T-shirts",
          "slug": "t-shirts"
        }
      ],
      "tags": [],
      "images": [
        {
          "id": 795,
          "date_created": "2017-03-23T14:03:08",
          "date_created_gmt": "2017-03-23T20:03:08",
          "date_modified": "2017-03-23T14:03:08",
          "date_modified_gmt": "2017-03-23T20:03:08",
          "src": "https://example.com/wp-content/uploads/2017/03/T_4_front-11.jpg",
          "name": "",
          "alt": "",
          "position": 0
        },
        {
          "id": 796,
          "date_created": "2017-03-23T14:03:09",
          "date_created_gmt": "2017-03-23T20:03:09",
          "date_modified": "2017-03-23T14:03:09",
          "date_modified_gmt": "2017-03-23T20:03:09",
          "src": "https://example.com/wp-content/uploads/2017/03/T_4_back-10.jpg",
          "name": "",
          "alt": "",
          "position": 1
        },
        {
          "id": 797,
          "date_created": "2017-03-23T14:03:10",
          "date_created_gmt": "2017-03-23T20:03:10",
          "date_modified": "2017-03-23T14:03:10",
          "date_modified_gmt": "2017-03-23T20:03:10",
          "src": "https://example.com/wp-content/uploads/2017/03/T_3_front-10.jpg",
          "name": "",
          "alt": "",
          "position": 2
        },
        {
          "id": 798,
          "date_created": "2017-03-23T14:03:11",
          "date_created_gmt": "2017-03-23T20:03:11",
          "date_modified": "2017-03-23T14:03:11",
          "date_modified_gmt": "2017-03-23T20:03:11",
          "src": "https://example.com/wp-content/uploads/2017/03/T_3_back-10.jpg",
          "name": "",
          "alt": "",
          "position": 3
        }
      ],
      "attributes": [
        {
          "id": 6,
          "name": "Color",
          "position": 0,
          "visible": false,
          "variation": true,
          "options": [
            "Black",
            "Green"
          ]
        },
        {
          "id": 0,
          "name": "Size",
          "position": 0,
          "visible": true,
          "variation": true,
          "options": [
            "S",
            "M"
          ]
        }
      ],
      "default_attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "green"
        },
        {
          "id": 0,
          "name": "Size",
          "option": "M"
        }
      ],
      "variations": [],
      "grouped_products": [],
      "menu_order": 0,
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/799"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 794,
      "name": "Premium Quality",
      "slug": "premium-quality-19",
      "permalink": "https://example.com/product/premium-quality-19/",
      "date_created": "2017-03-23T17:01:14",
      "date_created_gmt": "2017-03-23T20:01:14",
      "date_modified": "2017-03-23T17:01:14",
      "date_modified_gmt": "2017-03-23T20:01:14",
      "type": "simple",
      "status": "publish",
      "featured": false,
      "catalog_visibility": "visible",
      "description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
      "short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
      "sku": "",
      "price": "24.54",
      "regular_price": "24.54",
      "sale_price": "",
      "date_on_sale_from": null,
      "date_on_sale_from_gmt": null,
      "date_on_sale_to": null,
      "date_on_sale_to_gmt": null,
      "price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>24.54</span>",
      "on_sale": false,
      "purchasable": true,
      "total_sales": 0,
      "virtual": false,
      "downloadable": false,
      "downloads": [],
      "download_limit": -1,
      "download_expiry": -1,
      "external_url": "",
      "button_text": "",
      "tax_status": "taxable",
      "tax_class": "",
      "manage_stock": false,
      "stock_quantity": null,
      "in_stock": true,
      "backorders": "no",
      "backorders_allowed": false,
      "backordered": false,
      "sold_individually": false,
      "weight": "",
      "dimensions": {
        "length": "",
        "width": "",
        "height": ""
      },
      "shipping_required": true,
      "shipping_taxable": true,
      "shipping_class": "",
      "shipping_class_id": 0,
      "reviews_allowed": true,
      "average_rating": "0.00",
      "rating_count": 0,
      "related_ids": [
        369,
        56,
        378,
        31,
        22
      ],
      "upsell_ids": [],
      "cross_sell_ids": [],
      "parent_id": 0,
      "purchase_note": "",
      "categories": [
        {
          "id": 9,
          "name": "Clothing",
          "slug": "clothing"
        },
        {
          "id": 14,
          "name": "T-shirts",
          "slug": "t-shirts"
        }
      ],
      "tags": [],
      "images": [
        {
          "id": 792,
          "date_created": "2017-03-23T14:01:13",
          "date_created_gmt": "2017-03-23T20:01:13",
          "date_modified": "2017-03-23T14:01:13",
          "date_modified_gmt": "2017-03-23T20:01:13",
          "src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
          "name": "",
          "alt": "",
          "position": 0
        },
        {
          "id": 793,
          "date_created": "2017-03-23T14:01:14",
          "date_created_gmt": "2017-03-23T20:01:14",
          "date_modified": "2017-03-23T14:01:14",
          "date_modified_gmt": "2017-03-23T20:01:14",
          "src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
          "name": "",
          "alt": "",
          "position": 1
        }
      ],
      "attributes": [],
      "default_attributes": [],
      "variations": [],
      "grouped_products": [],
      "menu_order": 0,
      "meta_data": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/products/794"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/products"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>

## Retrieve product reviews
This API lets you retrieve and view a specific product review by ID.

```http
GET /wp-json/wc/v2/products/<product_id>/reviews/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/22/reviews/5 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/products/22/reviews/5")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/22/reviews/5')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/products/22/reviews/5").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/products/22/reviews/5").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 5,
  "date_created": "2013-06-07T11:43:13",
  "date_created_gmt": "2013-06-07T11:43:13",
  "review": "Nice T-shirt, I got one in black. Goes with anything!",
  "rating": 4,
  "name": "James Koster",
  "email": "james@example.com",
  "verified": false,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/reviews/5"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22/reviews"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/products/22"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Product review properties
| Attribute          | Type      | Description                                                                                |
|--------------------|-----------|--------------------------------------------------------------------------------------------|
| `id`               | integer   | Unique identifier for the resource. `READ-ONLY`              |
| `review`           | string    | The content of the review. `MANDATORY`                       |
| `date_created`     | date-time | The date the review was created, in the site's timezone.                                   |
| `date_created_gmt` | date-time | The date the review was created, as GMT.                                                   |
| `rating`           | integer   | Review rating (0 to 5).                                                                    |
| `name`             | string    | Reviewer name. `MANDATORY`                                   |
| `email`            | string    | Reviewer email. `MANDATORY`                                  |
| `verified`         | boolean   | Shows if the reviewer bought the product or not. `READ-ONLY` |

## List all product reviews
This API lets you retrieve all reviews of a product.

```http
GET /wp-json/wc/v2/products/<product_id>/reviews
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/products/22/reviews \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("products/22/reviews")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/22/reviews')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/22/reviews").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/22/reviews").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 5,
    "date_created": "2013-06-07T11:43:13",
    "date_created_gmt": "2013-06-07T11:43:13",
    "review": "Nice T-shirt, I got one in black. Goes with anything!",
    "rating": 4,
    "name": "James Koster",
    "email": "james@example.com",
    "verified": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/reviews/5"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/reviews"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22"
        }
      ]
    }
  },
  {
    "id": 6,
    "date_created": "2013-06-07T11:55:15",
    "date_created_gmt": "2013-06-07T11:55:15",
    "review": "Very comfortable shirt, and I love the graphic!",
    "rating": 4,
    "name": "Cobus Bester",
    "email": "bester@example.com",
    "verified": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/reviews/6"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/reviews"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22"
        }
      ]
    }
  },
  {
    "id": 7,
    "date_created": "2013-06-07T13:02:14",
    "date_created_gmt": "2013-06-07T13:02:14",
    "review": "Great T-shirt quality, Great Design and Great Service.",
    "rating": 5,
    "name": "Stuart",
    "email": "stuart@example.com",
    "verified": false,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/reviews/7"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22/reviews"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/22"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>


---

## Reports

*Source: apis/rest-api/v2/reports.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Reports
The reports API allows you to view all types of reports available.

## List all reports
This API lets you retrieve and view a simple list of available reports.

```http
GET /wp-json/wc/v2/reports
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/reports \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("reports")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('reports')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("reports").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "slug": "sales",
    "description": "List of sales reports.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/reports/sales"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/reports"
        }
      ]
    }
  },
  {
    "slug": "top_sellers",
    "description": "List of top sellers products.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/reports/top_sellers"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/reports"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Retrieve sales report
This API lets you retrieve and view a sales report.

```http
GET /wp-json/wc/v2/reports/sales
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/reports/sales?date_min=2016-05-03&date_max=2016-05-04 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("reports/sales", {
  date_min: "2016-05-03",
  date_max: "2016-05-04"
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$query = [
    'date_min' => '2016-05-03', 
    'date_max' => '2016-05-04'
];

print_r($woocommerce->get('reports/sales', $query));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/sales?date_min=2016-05-03&date_max=2016-05-04").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
query = {
  date_min: "2016-05-03",
  date_max: "2016-05-04"
}

woocommerce.get("reports/sales", query).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "total_sales": "14.00",
    "net_sales": "4.00",
    "average_sales": "2.00",
    "total_orders": 3,
    "total_items": 6,
    "total_tax": "0.00",
    "total_shipping": "10.00",
    "total_refunds": 0,
    "total_discount": "0.00",
    "totals_grouped_by": "day",
    "totals": {
      "2016-05-03": {
        "sales": "14.00",
        "orders": 3,
        "items": 6,
        "tax": "0.00",
        "shipping": "10.00",
        "discount": "0.00",
        "customers": 0
      },
      "2016-05-04": {
        "sales": "0.00",
        "orders": 0,
        "items": 0,
        "tax": "0.00",
        "shipping": "0.00",
        "discount": "0.00",
        "customers": 0
      }
    },
    "total_customers": 0,
    "_links": {
      "about": [
        {
          "href": "https://example.com/wp-json/wc/v2/reports"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Sales report properties
|      Attribute      |   Type  |                              Description                              |
|---------------------|---------|-----------------------------------------------------------------------|
| `total_sales`       | string  | Gross sales in the period. `READ-ONLY`  |
| `net_sales`         | string  | Net sales in the period. `READ-ONLY`    |
| `average_sales`     | string  | Average net daily sales. `READ-ONLY`    |
| `total_orders`      | integer | Total of orders placed. `READ-ONLY`     |
| `total_items`       | integer | Total of items purchased. `READ-ONLY`   |
| `total_tax`         | string  | Total charged for taxes. `READ-ONLY`    |
| `total_shipping`    | string  | Total charged for shipping. `READ-ONLY` |
| `total_refunds`     | number | Total of refunded orders. `READ-ONLY`   |
| `total_discount`    | integer | Total of coupons used. `READ-ONLY`      |
| `totals_grouped_by` | string  | Group type. `READ-ONLY`                 |
| `totals`            | array   | Totals. `READ-ONLY`                     |

#### Available parameters
| Parameter  |  Type  |                                                    Description                                                    |
|------------|--------|-------------------------------------------------------------------------------------------------------------------|
| `context`  | string | Scope under which the request is made; determines fields present in response. Default is `view`. Options: `view`. |
| `period`   | string | Report period. Default is today's date. Options: `week`, `month`, `last_month` and `year`                         |
| `date_min` | string | Return sales for a specific start date, the date need to be in the YYYY-MM-DD format.                             |
| `date_max` | string | Return sales for a specific end date, the date need to be in the YYYY-MM-DD format.                               |

## Retrieve top sellers report
This API lets you retrieve and view a list of top sellers report.

```http
GET /wp-json/wc/v2/reports/top_sellers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/reports/top_sellers?period=last_month \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("reports/top_sellers", {
  period: "last_month"
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$query = [
    'period' => 'last_month'
];

print_r($woocommerce->get('reports/top_sellers', $query));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/top_sellers?period=last_month").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
query = {
  period: "last_month"
}

woocommerce.get("reports/top_sellers", query).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "title": "Happy Ninja",
    "product_id": 37,
    "quantity": 1,
    "_links": {
      "about": [
        {
          "href": "https://example.com/wp-json/wc/v2/reports"
        }
      ],
      "product": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/37"
        }
      ]
    }
  },
  {
    "title": "Woo Album #4",
    "product_id": 96,
    "quantity": 1,
    "_links": {
      "about": [
        {
          "href": "https://example.com/wp-json/wc/v2/reports"
        }
      ],
      "product": [
        {
          "href": "https://example.com/wp-json/wc/v2/products/96"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Top sellers report properties
|      Attribute      |   Type  |                              Description                              |
|---------------------|---------|-----------------------------------------------------------------------|
| `title`             | string  | Product title. `READ-ONLY`              |
| `product_id`        | integer | Product ID. `READ-ONLY`                 |
| `quantity`          | integer | Total number of purchases. `READ-ONLY`  |

#### Available parameters
| Parameter  |  Type  |                                                    Description                                                    |
|------------|--------|-------------------------------------------------------------------------------------------------------------------|
| `context`  | string | Scope under which the request is made; determines fields present in response. Default is `view`. Options: `view`. |
| `period`   | string | Report period. Default is `week`. Options: `week`, `month`, `last_month` and `year`                               |
| `date_min` | string | Return sales for a specific start date, the date need to be in the YYYY-MM-DD format.                             |
| `date_max` | string | Return sales for a specific end date, the date need to be in the YYYY-MM-DD format.                               |


---

## Setting options

*Source: apis/rest-api/v2/setting-options.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Setting options
## Setting option properties
| Attribute     | Type   | Description                                                                                                                                                                                     |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string | A unique identifier for the setting. `READ-ONLY`                                                                                                                  |
| `label`       | string | A human readable label for the setting used in interfaces. `READ-ONLY`                                                                                            |
| `description` | string | A human readable description for the setting used in interfaces. `READ-ONLY`                                                                                      |
| `value`       | mixed  | Setting value.                                                                                                                                                                                  |
| `default`     | mixed  | Default value for the setting. `READ-ONLY`                                                                                                                        |
| `tip`         | string | Additional help text shown to the user about the setting. `READ-ONLY`                                                                                             |
| `placeholder` | string | Placeholder text to be displayed in text inputs. `READ-ONLY`                                                                                                      |
| `type`        | string | Type of setting. Options: `text`, `email`, `number`, `color`, `password`, `textarea`, `select`, `multiselect`, `radio`, `image_width` and `checkbox`. `READ-ONLY` |
| `options`     | object | Array of options (key value pairs) for inputs such as select, multiselect, and radio buttons. `READ-ONLY`                                                         |

## Retrieve an setting option
This API lets you retrieve and view a specific setting option.

```http
GET /wp-json/wc/v2/settings/<group_id>/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/settings/general/woocommerce_allowed_countries \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("settings/general/woocommerce_allowed_countries")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('settings/general/woocommerce_allowed_countries')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("settings/general/woocommerce_allowed_countries").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("settings/general/woocommerce_allowed_countries").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": "woocommerce_allowed_countries",
  "label": "Selling location(s)",
  "description": "This option lets you limit which countries you are willing to sell to.",
  "type": "select",
  "default": "all",
  "options": {
    "all": "Sell to all countries",
    "all_except": "Sell to all countries, except for&hellip;",
    "specific": "Sell to specific countries"
  },
  "tip": "This option lets you limit which countries you are willing to sell to.",
  "value": "all",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_allowed_countries"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/settings/general"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all setting options
This API helps you to view all the setting options.

```http
GET /wp-json/wc/v2/settings/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/settings/general \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("settings/general")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('settings/general')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("settings/general").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("settings/general").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": "woocommerce_allowed_countries",
    "label": "Selling location(s)",
    "description": "This option lets you limit which countries you are willing to sell to.",
    "type": "select",
    "default": "all",
    "options": {
      "all": "Sell to all countries",
      "all_except": "Sell to all countries, except for&hellip;",
      "specific": "Sell to specific countries"
    },
    "tip": "This option lets you limit which countries you are willing to sell to.",
    "value": "all",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_allowed_countries"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_all_except_countries",
    "label": "Sell to all countries, except for&hellip;",
    "description": "",
    "type": "multiselect",
    "default": "",
    "value": "",
    "options": {
      "AX": "&#197;land Islands",
      "AF": "Afghanistan",
      "AL": "Albania",
      "DZ": "Algeria",
      "AS": "American Samoa",
      "AD": "Andorra",
      "AO": "Angola",
      "AI": "Anguilla",
      "AQ": "Antarctica",
      "AG": "Antigua and Barbuda",
      "AR": "Argentina",
      "AM": "Armenia",
      "AW": "Aruba",
      "AU": "Australia",
      "AT": "Austria",
      "AZ": "Azerbaijan",
      "BS": "Bahamas",
      "BH": "Bahrain",
      "BD": "Bangladesh",
      "BB": "Barbados",
      "BY": "Belarus",
      "PW": "Belau",
      "BE": "Belgium",
      "BZ": "Belize",
      "BJ": "Benin",
      "BM": "Bermuda",
      "BT": "Bhutan",
      "BO": "Bolivia",
      "BQ": "Bonaire, Saint Eustatius and Saba",
      "BA": "Bosnia and Herzegovina",
      "BW": "Botswana",
      "BV": "Bouvet Island",
      "BR": "Brazil",
      "IO": "British Indian Ocean Territory",
      "VG": "British Virgin Islands",
      "BN": "Brunei",
      "BG": "Bulgaria",
      "BF": "Burkina Faso",
      "BI": "Burundi",
      "KH": "Cambodia",
      "CM": "Cameroon",
      "CA": "Canada",
      "CV": "Cape Verde",
      "KY": "Cayman Islands",
      "CF": "Central African Republic",
      "TD": "Chad",
      "CL": "Chile",
      "CN": "China",
      "CX": "Christmas Island",
      "CC": "Cocos (Keeling) Islands",
      "CO": "Colombia",
      "KM": "Comoros",
      "CG": "Congo (Brazzaville)",
      "CD": "Congo (Kinshasa)",
      "CK": "Cook Islands",
      "CR": "Costa Rica",
      "HR": "Croatia",
      "CU": "Cuba",
      "CW": "Cura&ccedil;ao",
      "CY": "Cyprus",
      "CZ": "Czech Republic",
      "DK": "Denmark",
      "DJ": "Djibouti",
      "DM": "Dominica",
      "DO": "Dominican Republic",
      "EC": "Ecuador",
      "EG": "Egypt",
      "SV": "El Salvador",
      "GQ": "Equatorial Guinea",
      "ER": "Eritrea",
      "EE": "Estonia",
      "ET": "Ethiopia",
      "FK": "Falkland Islands",
      "FO": "Faroe Islands",
      "FJ": "Fiji",
      "FI": "Finland",
      "FR": "France",
      "GF": "French Guiana",
      "PF": "French Polynesia",
      "TF": "French Southern Territories",
      "GA": "Gabon",
      "GM": "Gambia",
      "GE": "Georgia",
      "DE": "Germany",
      "GH": "Ghana",
      "GI": "Gibraltar",
      "GR": "Greece",
      "GL": "Greenland",
      "GD": "Grenada",
      "GP": "Guadeloupe",
      "GU": "Guam",
      "GT": "Guatemala",
      "GG": "Guernsey",
      "GN": "Guinea",
      "GW": "Guinea-Bissau",
      "GY": "Guyana",
      "HT": "Haiti",
      "HM": "Heard Island and McDonald Islands",
      "HN": "Honduras",
      "HK": "Hong Kong",
      "HU": "Hungary",
      "IS": "Iceland",
      "IN": "India",
      "ID": "Indonesia",
      "IR": "Iran",
      "IQ": "Iraq",
      "IE": "Ireland",
      "IM": "Isle of Man",
      "IL": "Israel",
      "IT": "Italy",
      "CI": "Ivory Coast",
      "JM": "Jamaica",
      "JP": "Japan",
      "JE": "Jersey",
      "JO": "Jordan",
      "KZ": "Kazakhstan",
      "KE": "Kenya",
      "KI": "Kiribati",
      "KW": "Kuwait",
      "KG": "Kyrgyzstan",
      "LA": "Laos",
      "LV": "Latvia",
      "LB": "Lebanon",
      "LS": "Lesotho",
      "LR": "Liberia",
      "LY": "Libya",
      "LI": "Liechtenstein",
      "LT": "Lithuania",
      "LU": "Luxembourg",
      "MO": "Macao S.A.R., China",
      "MK": "Macedonia",
      "MG": "Madagascar",
      "MW": "Malawi",
      "MY": "Malaysia",
      "MV": "Maldives",
      "ML": "Mali",
      "MT": "Malta",
      "MH": "Marshall Islands",
      "MQ": "Martinique",
      "MR": "Mauritania",
      "MU": "Mauritius",
      "YT": "Mayotte",
      "MX": "Mexico",
      "FM": "Micronesia",
      "MD": "Moldova",
      "MC": "Monaco",
      "MN": "Mongolia",
      "ME": "Montenegro",
      "MS": "Montserrat",
      "MA": "Morocco",
      "MZ": "Mozambique",
      "MM": "Myanmar",
      "NA": "Namibia",
      "NR": "Nauru",
      "NP": "Nepal",
      "NL": "Netherlands",
      "NC": "New Caledonia",
      "NZ": "New Zealand",
      "NI": "Nicaragua",
      "NE": "Niger",
      "NG": "Nigeria",
      "NU": "Niue",
      "NF": "Norfolk Island",
      "KP": "North Korea",
      "MP": "Northern Mariana Islands",
      "NO": "Norway",
      "OM": "Oman",
      "PK": "Pakistan",
      "PS": "Palestinian Territory",
      "PA": "Panama",
      "PG": "Papua New Guinea",
      "PY": "Paraguay",
      "PE": "Peru",
      "PH": "Philippines",
      "PN": "Pitcairn",
      "PL": "Poland",
      "PT": "Portugal",
      "PR": "Puerto Rico",
      "QA": "Qatar",
      "RE": "Reunion",
      "RO": "Romania",
      "RU": "Russia",
      "RW": "Rwanda",
      "ST": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe",
      "BL": "Saint Barth&eacute;lemy",
      "SH": "Saint Helena",
      "KN": "Saint Kitts and Nevis",
      "LC": "Saint Lucia",
      "SX": "Saint Martin (Dutch part)",
      "MF": "Saint Martin (French part)",
      "PM": "Saint Pierre and Miquelon",
      "VC": "Saint Vincent and the Grenadines",
      "WS": "Samoa",
      "SM": "San Marino",
      "SA": "Saudi Arabia",
      "SN": "Senegal",
      "RS": "Serbia",
      "SC": "Seychelles",
      "SL": "Sierra Leone",
      "SG": "Singapore",
      "SK": "Slovakia",
      "SI": "Slovenia",
      "SB": "Solomon Islands",
      "SO": "Somalia",
      "ZA": "South Africa",
      "GS": "South Georgia/Sandwich Islands",
      "KR": "South Korea",
      "SS": "South Sudan",
      "ES": "Spain",
      "LK": "Sri Lanka",
      "SD": "Sudan",
      "SR": "Suriname",
      "SJ": "Svalbard and Jan Mayen",
      "SZ": "Swaziland",
      "SE": "Sweden",
      "CH": "Switzerland",
      "SY": "Syria",
      "TW": "Taiwan",
      "TJ": "Tajikistan",
      "TZ": "Tanzania",
      "TH": "Thailand",
      "TL": "Timor-Leste",
      "TG": "Togo",
      "TK": "Tokelau",
      "TO": "Tonga",
      "TT": "Trinidad and Tobago",
      "TN": "Tunisia",
      "TR": "Turkey",
      "TM": "Turkmenistan",
      "TC": "Turks and Caicos Islands",
      "TV": "Tuvalu",
      "UG": "Uganda",
      "UA": "Ukraine",
      "AE": "United Arab Emirates",
      "GB": "United Kingdom (UK)",
      "US": "United States (US)",
      "UM": "United States (US) Minor Outlying Islands",
      "VI": "United States (US) Virgin Islands",
      "UY": "Uruguay",
      "UZ": "Uzbekistan",
      "VU": "Vanuatu",
      "VA": "Vatican",
      "VE": "Venezuela",
      "VN": "Vietnam",
      "WF": "Wallis and Futuna",
      "EH": "Western Sahara",
      "YE": "Yemen",
      "ZM": "Zambia",
      "ZW": "Zimbabwe"
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_all_except_countries"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_specific_allowed_countries",
    "label": "Sell to specific countries",
    "description": "",
    "type": "multiselect",
    "default": "",
    "value": "",
    "options": {
      "AX": "&#197;land Islands",
      "AF": "Afghanistan",
      "AL": "Albania",
      "DZ": "Algeria",
      "AS": "American Samoa",
      "AD": "Andorra",
      "AO": "Angola",
      "AI": "Anguilla",
      "AQ": "Antarctica",
      "AG": "Antigua and Barbuda",
      "AR": "Argentina",
      "AM": "Armenia",
      "AW": "Aruba",
      "AU": "Australia",
      "AT": "Austria",
      "AZ": "Azerbaijan",
      "BS": "Bahamas",
      "BH": "Bahrain",
      "BD": "Bangladesh",
      "BB": "Barbados",
      "BY": "Belarus",
      "PW": "Belau",
      "BE": "Belgium",
      "BZ": "Belize",
      "BJ": "Benin",
      "BM": "Bermuda",
      "BT": "Bhutan",
      "BO": "Bolivia",
      "BQ": "Bonaire, Saint Eustatius and Saba",
      "BA": "Bosnia and Herzegovina",
      "BW": "Botswana",
      "BV": "Bouvet Island",
      "BR": "Brazil",
      "IO": "British Indian Ocean Territory",
      "VG": "British Virgin Islands",
      "BN": "Brunei",
      "BG": "Bulgaria",
      "BF": "Burkina Faso",
      "BI": "Burundi",
      "KH": "Cambodia",
      "CM": "Cameroon",
      "CA": "Canada",
      "CV": "Cape Verde",
      "KY": "Cayman Islands",
      "CF": "Central African Republic",
      "TD": "Chad",
      "CL": "Chile",
      "CN": "China",
      "CX": "Christmas Island",
      "CC": "Cocos (Keeling) Islands",
      "CO": "Colombia",
      "KM": "Comoros",
      "CG": "Congo (Brazzaville)",
      "CD": "Congo (Kinshasa)",
      "CK": "Cook Islands",
      "CR": "Costa Rica",
      "HR": "Croatia",
      "CU": "Cuba",
      "CW": "Cura&ccedil;ao",
      "CY": "Cyprus",
      "CZ": "Czech Republic",
      "DK": "Denmark",
      "DJ": "Djibouti",
      "DM": "Dominica",
      "DO": "Dominican Republic",
      "EC": "Ecuador",
      "EG": "Egypt",
      "SV": "El Salvador",
      "GQ": "Equatorial Guinea",
      "ER": "Eritrea",
      "EE": "Estonia",
      "ET": "Ethiopia",
      "FK": "Falkland Islands",
      "FO": "Faroe Islands",
      "FJ": "Fiji",
      "FI": "Finland",
      "FR": "France",
      "GF": "French Guiana",
      "PF": "French Polynesia",
      "TF": "French Southern Territories",
      "GA": "Gabon",
      "GM": "Gambia",
      "GE": "Georgia",
      "DE": "Germany",
      "GH": "Ghana",
      "GI": "Gibraltar",
      "GR": "Greece",
      "GL": "Greenland",
      "GD": "Grenada",
      "GP": "Guadeloupe",
      "GU": "Guam",
      "GT": "Guatemala",
      "GG": "Guernsey",
      "GN": "Guinea",
      "GW": "Guinea-Bissau",
      "GY": "Guyana",
      "HT": "Haiti",
      "HM": "Heard Island and McDonald Islands",
      "HN": "Honduras",
      "HK": "Hong Kong",
      "HU": "Hungary",
      "IS": "Iceland",
      "IN": "India",
      "ID": "Indonesia",
      "IR": "Iran",
      "IQ": "Iraq",
      "IE": "Ireland",
      "IM": "Isle of Man",
      "IL": "Israel",
      "IT": "Italy",
      "CI": "Ivory Coast",
      "JM": "Jamaica",
      "JP": "Japan",
      "JE": "Jersey",
      "JO": "Jordan",
      "KZ": "Kazakhstan",
      "KE": "Kenya",
      "KI": "Kiribati",
      "KW": "Kuwait",
      "KG": "Kyrgyzstan",
      "LA": "Laos",
      "LV": "Latvia",
      "LB": "Lebanon",
      "LS": "Lesotho",
      "LR": "Liberia",
      "LY": "Libya",
      "LI": "Liechtenstein",
      "LT": "Lithuania",
      "LU": "Luxembourg",
      "MO": "Macao S.A.R., China",
      "MK": "Macedonia",
      "MG": "Madagascar",
      "MW": "Malawi",
      "MY": "Malaysia",
      "MV": "Maldives",
      "ML": "Mali",
      "MT": "Malta",
      "MH": "Marshall Islands",
      "MQ": "Martinique",
      "MR": "Mauritania",
      "MU": "Mauritius",
      "YT": "Mayotte",
      "MX": "Mexico",
      "FM": "Micronesia",
      "MD": "Moldova",
      "MC": "Monaco",
      "MN": "Mongolia",
      "ME": "Montenegro",
      "MS": "Montserrat",
      "MA": "Morocco",
      "MZ": "Mozambique",
      "MM": "Myanmar",
      "NA": "Namibia",
      "NR": "Nauru",
      "NP": "Nepal",
      "NL": "Netherlands",
      "NC": "New Caledonia",
      "NZ": "New Zealand",
      "NI": "Nicaragua",
      "NE": "Niger",
      "NG": "Nigeria",
      "NU": "Niue",
      "NF": "Norfolk Island",
      "KP": "North Korea",
      "MP": "Northern Mariana Islands",
      "NO": "Norway",
      "OM": "Oman",
      "PK": "Pakistan",
      "PS": "Palestinian Territory",
      "PA": "Panama",
      "PG": "Papua New Guinea",
      "PY": "Paraguay",
      "PE": "Peru",
      "PH": "Philippines",
      "PN": "Pitcairn",
      "PL": "Poland",
      "PT": "Portugal",
      "PR": "Puerto Rico",
      "QA": "Qatar",
      "RE": "Reunion",
      "RO": "Romania",
      "RU": "Russia",
      "RW": "Rwanda",
      "ST": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe",
      "BL": "Saint Barth&eacute;lemy",
      "SH": "Saint Helena",
      "KN": "Saint Kitts and Nevis",
      "LC": "Saint Lucia",
      "SX": "Saint Martin (Dutch part)",
      "MF": "Saint Martin (French part)",
      "PM": "Saint Pierre and Miquelon",
      "VC": "Saint Vincent and the Grenadines",
      "WS": "Samoa",
      "SM": "San Marino",
      "SA": "Saudi Arabia",
      "SN": "Senegal",
      "RS": "Serbia",
      "SC": "Seychelles",
      "SL": "Sierra Leone",
      "SG": "Singapore",
      "SK": "Slovakia",
      "SI": "Slovenia",
      "SB": "Solomon Islands",
      "SO": "Somalia",
      "ZA": "South Africa",
      "GS": "South Georgia/Sandwich Islands",
      "KR": "South Korea",
      "SS": "South Sudan",
      "ES": "Spain",
      "LK": "Sri Lanka",
      "SD": "Sudan",
      "SR": "Suriname",
      "SJ": "Svalbard and Jan Mayen",
      "SZ": "Swaziland",
      "SE": "Sweden",
      "CH": "Switzerland",
      "SY": "Syria",
      "TW": "Taiwan",
      "TJ": "Tajikistan",
      "TZ": "Tanzania",
      "TH": "Thailand",
      "TL": "Timor-Leste",
      "TG": "Togo",
      "TK": "Tokelau",
      "TO": "Tonga",
      "TT": "Trinidad and Tobago",
      "TN": "Tunisia",
      "TR": "Turkey",
      "TM": "Turkmenistan",
      "TC": "Turks and Caicos Islands",
      "TV": "Tuvalu",
      "UG": "Uganda",
      "UA": "Ukraine",
      "AE": "United Arab Emirates",
      "GB": "United Kingdom (UK)",
      "US": "United States (US)",
      "UM": "United States (US) Minor Outlying Islands",
      "VI": "United States (US) Virgin Islands",
      "UY": "Uruguay",
      "UZ": "Uzbekistan",
      "VU": "Vanuatu",
      "VA": "Vatican",
      "VE": "Venezuela",
      "VN": "Vietnam",
      "WF": "Wallis and Futuna",
      "EH": "Western Sahara",
      "YE": "Yemen",
      "ZM": "Zambia",
      "ZW": "Zimbabwe"
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_specific_allowed_countries"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_ship_to_countries",
    "label": "Shipping location(s)",
    "description": "Choose which countries you want to ship to, or choose to ship to all locations you sell to.",
    "type": "select",
    "default": "",
    "options": {
      "": "Ship to all countries you sell to",
      "all": "Ship to all countries",
      "specific": "Ship to specific countries only",
      "disabled": "Disable shipping &amp; shipping calculations"
    },
    "tip": "Choose which countries you want to ship to, or choose to ship to all locations you sell to.",
    "value": "",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_ship_to_countries"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_specific_ship_to_countries",
    "label": "Ship to specific countries",
    "description": "",
    "type": "multiselect",
    "default": "",
    "value": "",
    "options": {
      "AX": "&#197;land Islands",
      "AF": "Afghanistan",
      "AL": "Albania",
      "DZ": "Algeria",
      "AS": "American Samoa",
      "AD": "Andorra",
      "AO": "Angola",
      "AI": "Anguilla",
      "AQ": "Antarctica",
      "AG": "Antigua and Barbuda",
      "AR": "Argentina",
      "AM": "Armenia",
      "AW": "Aruba",
      "AU": "Australia",
      "AT": "Austria",
      "AZ": "Azerbaijan",
      "BS": "Bahamas",
      "BH": "Bahrain",
      "BD": "Bangladesh",
      "BB": "Barbados",
      "BY": "Belarus",
      "PW": "Belau",
      "BE": "Belgium",
      "BZ": "Belize",
      "BJ": "Benin",
      "BM": "Bermuda",
      "BT": "Bhutan",
      "BO": "Bolivia",
      "BQ": "Bonaire, Saint Eustatius and Saba",
      "BA": "Bosnia and Herzegovina",
      "BW": "Botswana",
      "BV": "Bouvet Island",
      "BR": "Brazil",
      "IO": "British Indian Ocean Territory",
      "VG": "British Virgin Islands",
      "BN": "Brunei",
      "BG": "Bulgaria",
      "BF": "Burkina Faso",
      "BI": "Burundi",
      "KH": "Cambodia",
      "CM": "Cameroon",
      "CA": "Canada",
      "CV": "Cape Verde",
      "KY": "Cayman Islands",
      "CF": "Central African Republic",
      "TD": "Chad",
      "CL": "Chile",
      "CN": "China",
      "CX": "Christmas Island",
      "CC": "Cocos (Keeling) Islands",
      "CO": "Colombia",
      "KM": "Comoros",
      "CG": "Congo (Brazzaville)",
      "CD": "Congo (Kinshasa)",
      "CK": "Cook Islands",
      "CR": "Costa Rica",
      "HR": "Croatia",
      "CU": "Cuba",
      "CW": "Cura&ccedil;ao",
      "CY": "Cyprus",
      "CZ": "Czech Republic",
      "DK": "Denmark",
      "DJ": "Djibouti",
      "DM": "Dominica",
      "DO": "Dominican Republic",
      "EC": "Ecuador",
      "EG": "Egypt",
      "SV": "El Salvador",
      "GQ": "Equatorial Guinea",
      "ER": "Eritrea",
      "EE": "Estonia",
      "ET": "Ethiopia",
      "FK": "Falkland Islands",
      "FO": "Faroe Islands",
      "FJ": "Fiji",
      "FI": "Finland",
      "FR": "France",
      "GF": "French Guiana",
      "PF": "French Polynesia",
      "TF": "French Southern Territories",
      "GA": "Gabon",
      "GM": "Gambia",
      "GE": "Georgia",
      "DE": "Germany",
      "GH": "Ghana",
      "GI": "Gibraltar",
      "GR": "Greece",
      "GL": "Greenland",
      "GD": "Grenada",
      "GP": "Guadeloupe",
      "GU": "Guam",
      "GT": "Guatemala",
      "GG": "Guernsey",
      "GN": "Guinea",
      "GW": "Guinea-Bissau",
      "GY": "Guyana",
      "HT": "Haiti",
      "HM": "Heard Island and McDonald Islands",
      "HN": "Honduras",
      "HK": "Hong Kong",
      "HU": "Hungary",
      "IS": "Iceland",
      "IN": "India",
      "ID": "Indonesia",
      "IR": "Iran",
      "IQ": "Iraq",
      "IE": "Ireland",
      "IM": "Isle of Man",
      "IL": "Israel",
      "IT": "Italy",
      "CI": "Ivory Coast",
      "JM": "Jamaica",
      "JP": "Japan",
      "JE": "Jersey",
      "JO": "Jordan",
      "KZ": "Kazakhstan",
      "KE": "Kenya",
      "KI": "Kiribati",
      "KW": "Kuwait",
      "KG": "Kyrgyzstan",
      "LA": "Laos",
      "LV": "Latvia",
      "LB": "Lebanon",
      "LS": "Lesotho",
      "LR": "Liberia",
      "LY": "Libya",
      "LI": "Liechtenstein",
      "LT": "Lithuania",
      "LU": "Luxembourg",
      "MO": "Macao S.A.R., China",
      "MK": "Macedonia",
      "MG": "Madagascar",
      "MW": "Malawi",
      "MY": "Malaysia",
      "MV": "Maldives",
      "ML": "Mali",
      "MT": "Malta",
      "MH": "Marshall Islands",
      "MQ": "Martinique",
      "MR": "Mauritania",
      "MU": "Mauritius",
      "YT": "Mayotte",
      "MX": "Mexico",
      "FM": "Micronesia",
      "MD": "Moldova",
      "MC": "Monaco",
      "MN": "Mongolia",
      "ME": "Montenegro",
      "MS": "Montserrat",
      "MA": "Morocco",
      "MZ": "Mozambique",
      "MM": "Myanmar",
      "NA": "Namibia",
      "NR": "Nauru",
      "NP": "Nepal",
      "NL": "Netherlands",
      "NC": "New Caledonia",
      "NZ": "New Zealand",
      "NI": "Nicaragua",
      "NE": "Niger",
      "NG": "Nigeria",
      "NU": "Niue",
      "NF": "Norfolk Island",
      "KP": "North Korea",
      "MP": "Northern Mariana Islands",
      "NO": "Norway",
      "OM": "Oman",
      "PK": "Pakistan",
      "PS": "Palestinian Territory",
      "PA": "Panama",
      "PG": "Papua New Guinea",
      "PY": "Paraguay",
      "PE": "Peru",
      "PH": "Philippines",
      "PN": "Pitcairn",
      "PL": "Poland",
      "PT": "Portugal",
      "PR": "Puerto Rico",
      "QA": "Qatar",
      "RE": "Reunion",
      "RO": "Romania",
      "RU": "Russia",
      "RW": "Rwanda",
      "ST": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe",
      "BL": "Saint Barth&eacute;lemy",
      "SH": "Saint Helena",
      "KN": "Saint Kitts and Nevis",
      "LC": "Saint Lucia",
      "SX": "Saint Martin (Dutch part)",
      "MF": "Saint Martin (French part)",
      "PM": "Saint Pierre and Miquelon",
      "VC": "Saint Vincent and the Grenadines",
      "WS": "Samoa",
      "SM": "San Marino",
      "SA": "Saudi Arabia",
      "SN": "Senegal",
      "RS": "Serbia",
      "SC": "Seychelles",
      "SL": "Sierra Leone",
      "SG": "Singapore",
      "SK": "Slovakia",
      "SI": "Slovenia",
      "SB": "Solomon Islands",
      "SO": "Somalia",
      "ZA": "South Africa",
      "GS": "South Georgia/Sandwich Islands",
      "KR": "South Korea",
      "SS": "South Sudan",
      "ES": "Spain",
      "LK": "Sri Lanka",
      "SD": "Sudan",
      "SR": "Suriname",
      "SJ": "Svalbard and Jan Mayen",
      "SZ": "Swaziland",
      "SE": "Sweden",
      "CH": "Switzerland",
      "SY": "Syria",
      "TW": "Taiwan",
      "TJ": "Tajikistan",
      "TZ": "Tanzania",
      "TH": "Thailand",
      "TL": "Timor-Leste",
      "TG": "Togo",
      "TK": "Tokelau",
      "TO": "Tonga",
      "TT": "Trinidad and Tobago",
      "TN": "Tunisia",
      "TR": "Turkey",
      "TM": "Turkmenistan",
      "TC": "Turks and Caicos Islands",
      "TV": "Tuvalu",
      "UG": "Uganda",
      "UA": "Ukraine",
      "AE": "United Arab Emirates",
      "GB": "United Kingdom (UK)",
      "US": "United States (US)",
      "UM": "United States (US) Minor Outlying Islands",
      "VI": "United States (US) Virgin Islands",
      "UY": "Uruguay",
      "UZ": "Uzbekistan",
      "VU": "Vanuatu",
      "VA": "Vatican",
      "VE": "Venezuela",
      "VN": "Vietnam",
      "WF": "Wallis and Futuna",
      "EH": "Western Sahara",
      "YE": "Yemen",
      "ZM": "Zambia",
      "ZW": "Zimbabwe"
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_specific_ship_to_countries"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_default_customer_address",
    "label": "Default customer location",
    "description": "",
    "type": "select",
    "default": "geolocation",
    "options": {
      "": "No location by default",
      "base": "Shop base address",
      "geolocation": "Geolocate",
      "geolocation_ajax": "Geolocate (with page caching support)"
    },
    "tip": "This option determines a customers default location. The MaxMind GeoLite Database will be periodically downloaded to your wp-content directory if using geolocation.",
    "value": "geolocation",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_default_customer_address"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_calc_taxes",
    "label": "Enable taxes",
    "description": "Enable taxes and tax calculations",
    "type": "checkbox",
    "default": "no",
    "value": "yes",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_calc_taxes"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_demo_store",
    "label": "Store notice",
    "description": "Enable site-wide store notice text",
    "type": "checkbox",
    "default": "no",
    "value": "no",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_demo_store"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_demo_store_notice",
    "label": "Store notice text",
    "description": "",
    "type": "textarea",
    "default": "This is a demo store for testing purposes &mdash; no orders shall be fulfilled.",
    "value": "This is a demo store for testing purposes &mdash; no orders shall be fulfilled.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_demo_store_notice"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_currency",
    "label": "Currency",
    "description": "This controls what currency prices are listed at in the catalog and which currency gateways will take payments in.",
    "type": "select",
    "default": "GBP",
    "options": {
      "AED": "United Arab Emirates dirham (&#x62f;.&#x625;)",
      "AFN": "Afghan afghani (&#x60b;)",
      "ALL": "Albanian lek (L)",
      "AMD": "Armenian dram (AMD)",
      "ANG": "Netherlands Antillean guilder (&fnof;)",
      "AOA": "Angolan kwanza (Kz)",
      "ARS": "Argentine peso (&#36;)",
      "AUD": "Australian dollar (&#36;)",
      "AWG": "Aruban florin (&fnof;)",
      "AZN": "Azerbaijani manat (AZN)",
      "BAM": "Bosnia and Herzegovina convertible mark (KM)",
      "BBD": "Barbadian dollar (&#36;)",
      "BDT": "Bangladeshi taka (&#2547;&nbsp;)",
      "BGN": "Bulgarian lev (&#1083;&#1074;.)",
      "BHD": "Bahraini dinar (.&#x62f;.&#x628;)",
      "BIF": "Burundian franc (Fr)",
      "BMD": "Bermudian dollar (&#36;)",
      "BND": "Brunei dollar (&#36;)",
      "BOB": "Bolivian boliviano (Bs.)",
      "BRL": "Brazilian real (&#82;&#36;)",
      "BSD": "Bahamian dollar (&#36;)",
      "BTC": "Bitcoin (&#3647;)",
      "BTN": "Bhutanese ngultrum (Nu.)",
      "BWP": "Botswana pula (P)",
      "BYR": "Belarusian ruble (Br)",
      "BZD": "Belize dollar (&#36;)",
      "CAD": "Canadian dollar (&#36;)",
      "CDF": "Congolese franc (Fr)",
      "CHF": "Swiss franc (&#67;&#72;&#70;)",
      "CLP": "Chilean peso (&#36;)",
      "CNY": "Chinese yuan (&yen;)",
      "COP": "Colombian peso (&#36;)",
      "CRC": "Costa Rican col&oacute;n (&#x20a1;)",
      "CUC": "Cuban convertible peso (&#36;)",
      "CUP": "Cuban peso (&#36;)",
      "CVE": "Cape Verdean escudo (&#36;)",
      "CZK": "Czech koruna (&#75;&#269;)",
      "DJF": "Djiboutian franc (Fr)",
      "DKK": "Danish krone (DKK)",
      "DOP": "Dominican peso (RD&#36;)",
      "DZD": "Algerian dinar (&#x62f;.&#x62c;)",
      "EGP": "Egyptian pound (EGP)",
      "ERN": "Eritrean nakfa (Nfk)",
      "ETB": "Ethiopian birr (Br)",
      "EUR": "Euro (&euro;)",
      "FJD": "Fijian dollar (&#36;)",
      "FKP": "Falkland Islands pound (&pound;)",
      "GBP": "Pound sterling (&pound;)",
      "GEL": "Georgian lari (&#x10da;)",
      "GGP": "Guernsey pound (&pound;)",
      "GHS": "Ghana cedi (&#x20b5;)",
      "GIP": "Gibraltar pound (&pound;)",
      "GMD": "Gambian dalasi (D)",
      "GNF": "Guinean franc (Fr)",
      "GTQ": "Guatemalan quetzal (Q)",
      "GYD": "Guyanese dollar (&#36;)",
      "HKD": "Hong Kong dollar (&#36;)",
      "HNL": "Honduran lempira (L)",
      "HRK": "Croatian kuna (Kn)",
      "HTG": "Haitian gourde (G)",
      "HUF": "Hungarian forint (&#70;&#116;)",
      "IDR": "Indonesian rupiah (Rp)",
      "ILS": "Israeli new shekel (&#8362;)",
      "IMP": "Manx pound (&pound;)",
      "INR": "Indian rupee (&#8377;)",
      "IQD": "Iraqi dinar (&#x639;.&#x62f;)",
      "IRR": "Iranian rial (&#xfdfc;)",
      "IRT": "Iranian toman (&#x062A;&#x0648;&#x0645;&#x0627;&#x0646;)",
      "ISK": "Icelandic kr&oacute;na (kr.)",
      "JEP": "Jersey pound (&pound;)",
      "JMD": "Jamaican dollar (&#36;)",
      "JOD": "Jordanian dinar (&#x62f;.&#x627;)",
      "JPY": "Japanese yen (&yen;)",
      "KES": "Kenyan shilling (KSh)",
      "KGS": "Kyrgyzstani som (&#x441;&#x43e;&#x43c;)",
      "KHR": "Cambodian riel (&#x17db;)",
      "KMF": "Comorian franc (Fr)",
      "KPW": "North Korean won (&#x20a9;)",
      "KRW": "South Korean won (&#8361;)",
      "KWD": "Kuwaiti dinar (&#x62f;.&#x643;)",
      "KYD": "Cayman Islands dollar (&#36;)",
      "KZT": "Kazakhstani tenge (KZT)",
      "LAK": "Lao kip (&#8365;)",
      "LBP": "Lebanese pound (&#x644;.&#x644;)",
      "LKR": "Sri Lankan rupee (&#xdbb;&#xdd4;)",
      "LRD": "Liberian dollar (&#36;)",
      "LSL": "Lesotho loti (L)",
      "LYD": "Libyan dinar (&#x644;.&#x62f;)",
      "MAD": "Moroccan dirham (&#x62f;.&#x645;.)",
      "MDL": "Moldovan leu (MDL)",
      "MGA": "Malagasy ariary (Ar)",
      "MKD": "Macedonian denar (&#x434;&#x435;&#x43d;)",
      "MMK": "Burmese kyat (Ks)",
      "MNT": "Mongolian t&ouml;gr&ouml;g (&#x20ae;)",
      "MOP": "Macanese pataca (P)",
      "MRO": "Mauritanian ouguiya (UM)",
      "MUR": "Mauritian rupee (&#x20a8;)",
      "MVR": "Maldivian rufiyaa (.&#x783;)",
      "MWK": "Malawian kwacha (MK)",
      "MXN": "Mexican peso (&#36;)",
      "MYR": "Malaysian ringgit (&#82;&#77;)",
      "MZN": "Mozambican metical (MT)",
      "NAD": "Namibian dollar (&#36;)",
      "NGN": "Nigerian naira (&#8358;)",
      "NIO": "Nicaraguan c&oacute;rdoba (C&#36;)",
      "NOK": "Norwegian krone (&#107;&#114;)",
      "NPR": "Nepalese rupee (&#8360;)",
      "NZD": "New Zealand dollar (&#36;)",
      "OMR": "Omani rial (&#x631;.&#x639;.)",
      "PAB": "Panamanian balboa (B/.)",
      "PEN": "Peruvian nuevo sol (S/.)",
      "PGK": "Papua New Guinean kina (K)",
      "PHP": "Philippine peso (&#8369;)",
      "PKR": "Pakistani rupee (&#8360;)",
      "PLN": "Polish z&#x142;oty (&#122;&#322;)",
      "PRB": "Transnistrian ruble (&#x440;.)",
      "PYG": "Paraguayan guaran&iacute; (&#8370;)",
      "QAR": "Qatari riyal (&#x631;.&#x642;)",
      "RON": "Romanian leu (lei)",
      "RSD": "Serbian dinar (&#x434;&#x438;&#x43d;.)",
      "RUB": "Russian ruble (&#8381;)",
      "RWF": "Rwandan franc (Fr)",
      "SAR": "Saudi riyal (&#x631;.&#x633;)",
      "SBD": "Solomon Islands dollar (&#36;)",
      "SCR": "Seychellois rupee (&#x20a8;)",
      "SDG": "Sudanese pound (&#x62c;.&#x633;.)",
      "SEK": "Swedish krona (&#107;&#114;)",
      "SGD": "Singapore dollar (&#36;)",
      "SHP": "Saint Helena pound (&pound;)",
      "SLL": "Sierra Leonean leone (Le)",
      "SOS": "Somali shilling (Sh)",
      "SRD": "Surinamese dollar (&#36;)",
      "SSP": "South Sudanese pound (&pound;)",
      "STD": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe dobra (Db)",
      "SYP": "Syrian pound (&#x644;.&#x633;)",
      "SZL": "Swazi lilangeni (L)",
      "THB": "Thai baht (&#3647;)",
      "TJS": "Tajikistani somoni (&#x405;&#x41c;)",
      "TMT": "Turkmenistan manat (m)",
      "TND": "Tunisian dinar (&#x62f;.&#x62a;)",
      "TOP": "Tongan pa&#x2bb;anga (T&#36;)",
      "TRY": "Turkish lira (&#8378;)",
      "TTD": "Trinidad and Tobago dollar (&#36;)",
      "TWD": "New Taiwan dollar (&#78;&#84;&#36;)",
      "TZS": "Tanzanian shilling (Sh)",
      "UAH": "Ukrainian hryvnia (&#8372;)",
      "UGX": "Ugandan shilling (UGX)",
      "USD": "United States dollar (&#36;)",
      "UYU": "Uruguayan peso (&#36;)",
      "UZS": "Uzbekistani som (UZS)",
      "VEF": "Venezuelan bol&iacute;var (Bs F)",
      "VND": "Vietnamese &#x111;&#x1ed3;ng (&#8363;)",
      "VUV": "Vanuatu vatu (Vt)",
      "WST": "Samoan t&#x101;l&#x101; (T)",
      "XAF": "Central African CFA franc (Fr)",
      "XCD": "East Caribbean dollar (&#36;)",
      "XOF": "West African CFA franc (Fr)",
      "XPF": "CFP franc (Fr)",
      "YER": "Yemeni rial (&#xfdfc;)",
      "ZAR": "South African rand (&#82;)",
      "ZMW": "Zambian kwacha (K)"
    },
    "tip": "This controls what currency prices are listed at in the catalog and which currency gateways will take payments in.",
    "value": "USD",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_currency"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_currency_pos",
    "label": "Currency position",
    "description": "This controls the position of the currency symbol.",
    "type": "select",
    "default": "left",
    "options": {
      "left": "Left (&#36;99.99)",
      "right": "Right (99.99&#36;)",
      "left_space": "Left with space (&#36; 99.99)",
      "right_space": "Right with space (99.99 &#36;)"
    },
    "tip": "This controls the position of the currency symbol.",
    "value": "left",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_currency_pos"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_price_thousand_sep",
    "label": "Thousand separator",
    "description": "This sets the thousand separator of displayed prices.",
    "type": "text",
    "default": ",",
    "tip": "This sets the thousand separator of displayed prices.",
    "value": ",",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_price_thousand_sep"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_price_decimal_sep",
    "label": "Decimal separator",
    "description": "This sets the decimal separator of displayed prices.",
    "type": "text",
    "default": ".",
    "tip": "This sets the decimal separator of displayed prices.",
    "value": ".",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_price_decimal_sep"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "woocommerce_price_num_decimals",
    "label": "Number of decimals",
    "description": "This sets the number of decimal points shown in displayed prices.",
    "type": "number",
    "default": "2",
    "tip": "This sets the number of decimal points shown in displayed prices.",
    "value": "2",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_price_num_decimals"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Update a setting option
This API lets you make changes to a setting option.

```http
PUT /wp-json/wc/v2/settings/<group_id>/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/settings/general/woocommerce_allowed_countries \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "value": "all_except"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  value: "all_except"
};

WooCommerce.put("settings/general/woocommerce_allowed_countries", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php 
$data = [
    'value' => 'all_except'
];

print_r($woocommerce->put('settings/general/woocommerce_allowed_countries', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "value": "all_except"
}

print(wcapi.put("settings/general/woocommerce_allowed_countries", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  value: "all_except"
}

woocommerce.put("settings/general/woocommerce_allowed_countries", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": "woocommerce_allowed_countries",
  "label": "Selling location(s)",
  "description": "This option lets you limit which countries you are willing to sell to.",
  "type": "select",
  "default": "all",
  "options": {
    "all": "Sell to all countries",
    "all_except": "Sell to all countries, except for&hellip;",
    "specific": "Sell to specific countries"
  },
  "tip": "This option lets you limit which countries you are willing to sell to.",
  "value": "all_except",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_allowed_countries"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/settings/general"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Batch update setting options
This API helps you to batch update multiple setting options.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/settings/<id>/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/settings/general/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "update": [
    {
      "id": "woocommerce_allowed_countries",
      "value": "all"
    },
    {
      "id": "woocommerce_demo_store",
      "value": "yes"
    },
    {
      "id": "woocommerce_currency",
      "value": "GBP"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "Blue"
        }
      ]
    },
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "White"
        }
      ]
    }
  ],
  update: [
    {
      id: 733,
      regular_price: "10.00"
    }
  ],
  delete: [
    732
  ]
};

WooCommerce.post("products/22/settings/general/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'regular_price' => '10.00',
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'Blue'
                ]
            ]
        ],
        [
            'regular_price' => '10.00',
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'White'
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 733,
            'regular_price' => '10.00'
        ]
    ],
    'delete' => [
        732
    ]
];

print_r($woocommerce->post('products/22/settings/general/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "regular_price": "10.00",
            "attributes": [
                {
                    "id": 6,
                    "option": "Blue"
                }
            ]
        },
        {
            "regular_price": "10.00",
            "attributes": [
                {
                    "id": 6,
                    "option": "White"
                }
            ]
        }
    ],
    "update": [
        {
            "id": 733,
            "regular_price": "10.00"
        }
    ],
    "delete": [
        732
    ]
}

print(wcapi.post("products/22/settings/general/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "Blue"
        }
      ]
    },
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "White"
        }
      ]
    }
  ],
  update: [
    {
      id: 733,
      regular_price: "10.00"
    }
  ],
  delete: [
    732
  ]
}

woocommerce.post("products/22/settings/general/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "update": [
    {
      "id": "woocommerce_allowed_countries",
      "label": "Selling location(s)",
      "description": "This option lets you limit which countries you are willing to sell to.",
      "type": "select",
      "default": "all",
      "options": {
        "all": "Sell to all countries",
        "all_except": "Sell to all countries, except for&hellip;",
        "specific": "Sell to specific countries"
      },
      "tip": "This option lets you limit which countries you are willing to sell to.",
      "value": "all",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_allowed_countries"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/settings/general"
          }
        ]
      }
    },
    {
      "id": "woocommerce_demo_store",
      "label": "Store notice",
      "description": "Enable site-wide store notice text",
      "type": "checkbox",
      "default": "no",
      "value": "yes",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_demo_store"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/settings/general"
          }
        ]
      }
    },
    {
      "id": "woocommerce_currency",
      "label": "Currency",
      "description": "This controls what currency prices are listed at in the catalog and which currency gateways will take payments in.",
      "type": "select",
      "default": "GBP",
      "options": {
        "AED": "United Arab Emirates dirham (&#x62f;.&#x625;)",
        "AFN": "Afghan afghani (&#x60b;)",
        "ALL": "Albanian lek (L)",
        "AMD": "Armenian dram (AMD)",
        "ANG": "Netherlands Antillean guilder (&fnof;)",
        "AOA": "Angolan kwanza (Kz)",
        "ARS": "Argentine peso (&#36;)",
        "AUD": "Australian dollar (&#36;)",
        "AWG": "Aruban florin (&fnof;)",
        "AZN": "Azerbaijani manat (AZN)",
        "BAM": "Bosnia and Herzegovina convertible mark (KM)",
        "BBD": "Barbadian dollar (&#36;)",
        "BDT": "Bangladeshi taka (&#2547;&nbsp;)",
        "BGN": "Bulgarian lev (&#1083;&#1074;.)",
        "BHD": "Bahraini dinar (.&#x62f;.&#x628;)",
        "BIF": "Burundian franc (Fr)",
        "BMD": "Bermudian dollar (&#36;)",
        "BND": "Brunei dollar (&#36;)",
        "BOB": "Bolivian boliviano (Bs.)",
        "BRL": "Brazilian real (&#82;&#36;)",
        "BSD": "Bahamian dollar (&#36;)",
        "BTC": "Bitcoin (&#3647;)",
        "BTN": "Bhutanese ngultrum (Nu.)",
        "BWP": "Botswana pula (P)",
        "BYR": "Belarusian ruble (Br)",
        "BZD": "Belize dollar (&#36;)",
        "CAD": "Canadian dollar (&#36;)",
        "CDF": "Congolese franc (Fr)",
        "CHF": "Swiss franc (&#67;&#72;&#70;)",
        "CLP": "Chilean peso (&#36;)",
        "CNY": "Chinese yuan (&yen;)",
        "COP": "Colombian peso (&#36;)",
        "CRC": "Costa Rican col&oacute;n (&#x20a1;)",
        "CUC": "Cuban convertible peso (&#36;)",
        "CUP": "Cuban peso (&#36;)",
        "CVE": "Cape Verdean escudo (&#36;)",
        "CZK": "Czech koruna (&#75;&#269;)",
        "DJF": "Djiboutian franc (Fr)",
        "DKK": "Danish krone (DKK)",
        "DOP": "Dominican peso (RD&#36;)",
        "DZD": "Algerian dinar (&#x62f;.&#x62c;)",
        "EGP": "Egyptian pound (EGP)",
        "ERN": "Eritrean nakfa (Nfk)",
        "ETB": "Ethiopian birr (Br)",
        "EUR": "Euro (&euro;)",
        "FJD": "Fijian dollar (&#36;)",
        "FKP": "Falkland Islands pound (&pound;)",
        "GBP": "Pound sterling (&pound;)",
        "GEL": "Georgian lari (&#x10da;)",
        "GGP": "Guernsey pound (&pound;)",
        "GHS": "Ghana cedi (&#x20b5;)",
        "GIP": "Gibraltar pound (&pound;)",
        "GMD": "Gambian dalasi (D)",
        "GNF": "Guinean franc (Fr)",
        "GTQ": "Guatemalan quetzal (Q)",
        "GYD": "Guyanese dollar (&#36;)",
        "HKD": "Hong Kong dollar (&#36;)",
        "HNL": "Honduran lempira (L)",
        "HRK": "Croatian kuna (Kn)",
        "HTG": "Haitian gourde (G)",
        "HUF": "Hungarian forint (&#70;&#116;)",
        "IDR": "Indonesian rupiah (Rp)",
        "ILS": "Israeli new shekel (&#8362;)",
        "IMP": "Manx pound (&pound;)",
        "INR": "Indian rupee (&#8377;)",
        "IQD": "Iraqi dinar (&#x639;.&#x62f;)",
        "IRR": "Iranian rial (&#xfdfc;)",
        "IRT": "Iranian toman (&#x062A;&#x0648;&#x0645;&#x0627;&#x0646;)",
        "ISK": "Icelandic kr&oacute;na (kr.)",
        "JEP": "Jersey pound (&pound;)",
        "JMD": "Jamaican dollar (&#36;)",
        "JOD": "Jordanian dinar (&#x62f;.&#x627;)",
        "JPY": "Japanese yen (&yen;)",
        "KES": "Kenyan shilling (KSh)",
        "KGS": "Kyrgyzstani som (&#x441;&#x43e;&#x43c;)",
        "KHR": "Cambodian riel (&#x17db;)",
        "KMF": "Comorian franc (Fr)",
        "KPW": "North Korean won (&#x20a9;)",
        "KRW": "South Korean won (&#8361;)",
        "KWD": "Kuwaiti dinar (&#x62f;.&#x643;)",
        "KYD": "Cayman Islands dollar (&#36;)",
        "KZT": "Kazakhstani tenge (KZT)",
        "LAK": "Lao kip (&#8365;)",
        "LBP": "Lebanese pound (&#x644;.&#x644;)",
        "LKR": "Sri Lankan rupee (&#xdbb;&#xdd4;)",
        "LRD": "Liberian dollar (&#36;)",
        "LSL": "Lesotho loti (L)",
        "LYD": "Libyan dinar (&#x644;.&#x62f;)",
        "MAD": "Moroccan dirham (&#x62f;.&#x645;.)",
        "MDL": "Moldovan leu (MDL)",
        "MGA": "Malagasy ariary (Ar)",
        "MKD": "Macedonian denar (&#x434;&#x435;&#x43d;)",
        "MMK": "Burmese kyat (Ks)",
        "MNT": "Mongolian t&ouml;gr&ouml;g (&#x20ae;)",
        "MOP": "Macanese pataca (P)",
        "MRO": "Mauritanian ouguiya (UM)",
        "MUR": "Mauritian rupee (&#x20a8;)",
        "MVR": "Maldivian rufiyaa (.&#x783;)",
        "MWK": "Malawian kwacha (MK)",
        "MXN": "Mexican peso (&#36;)",
        "MYR": "Malaysian ringgit (&#82;&#77;)",
        "MZN": "Mozambican metical (MT)",
        "NAD": "Namibian dollar (&#36;)",
        "NGN": "Nigerian naira (&#8358;)",
        "NIO": "Nicaraguan c&oacute;rdoba (C&#36;)",
        "NOK": "Norwegian krone (&#107;&#114;)",
        "NPR": "Nepalese rupee (&#8360;)",
        "NZD": "New Zealand dollar (&#36;)",
        "OMR": "Omani rial (&#x631;.&#x639;.)",
        "PAB": "Panamanian balboa (B/.)",
        "PEN": "Peruvian nuevo sol (S/.)",
        "PGK": "Papua New Guinean kina (K)",
        "PHP": "Philippine peso (&#8369;)",
        "PKR": "Pakistani rupee (&#8360;)",
        "PLN": "Polish z&#x142;oty (&#122;&#322;)",
        "PRB": "Transnistrian ruble (&#x440;.)",
        "PYG": "Paraguayan guaran&iacute; (&#8370;)",
        "QAR": "Qatari riyal (&#x631;.&#x642;)",
        "RON": "Romanian leu (lei)",
        "RSD": "Serbian dinar (&#x434;&#x438;&#x43d;.)",
        "RUB": "Russian ruble (&#8381;)",
        "RWF": "Rwandan franc (Fr)",
        "SAR": "Saudi riyal (&#x631;.&#x633;)",
        "SBD": "Solomon Islands dollar (&#36;)",
        "SCR": "Seychellois rupee (&#x20a8;)",
        "SDG": "Sudanese pound (&#x62c;.&#x633;.)",
        "SEK": "Swedish krona (&#107;&#114;)",
        "SGD": "Singapore dollar (&#36;)",
        "SHP": "Saint Helena pound (&pound;)",
        "SLL": "Sierra Leonean leone (Le)",
        "SOS": "Somali shilling (Sh)",
        "SRD": "Surinamese dollar (&#36;)",
        "SSP": "South Sudanese pound (&pound;)",
        "STD": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe dobra (Db)",
        "SYP": "Syrian pound (&#x644;.&#x633;)",
        "SZL": "Swazi lilangeni (L)",
        "THB": "Thai baht (&#3647;)",
        "TJS": "Tajikistani somoni (&#x405;&#x41c;)",
        "TMT": "Turkmenistan manat (m)",
        "TND": "Tunisian dinar (&#x62f;.&#x62a;)",
        "TOP": "Tongan pa&#x2bb;anga (T&#36;)",
        "TRY": "Turkish lira (&#8378;)",
        "TTD": "Trinidad and Tobago dollar (&#36;)",
        "TWD": "New Taiwan dollar (&#78;&#84;&#36;)",
        "TZS": "Tanzanian shilling (Sh)",
        "UAH": "Ukrainian hryvnia (&#8372;)",
        "UGX": "Ugandan shilling (UGX)",
        "USD": "United States dollar (&#36;)",
        "UYU": "Uruguayan peso (&#36;)",
        "UZS": "Uzbekistani som (UZS)",
        "VEF": "Venezuelan bol&iacute;var (Bs F)",
        "VND": "Vietnamese &#x111;&#x1ed3;ng (&#8363;)",
        "VUV": "Vanuatu vatu (Vt)",
        "WST": "Samoan t&#x101;l&#x101; (T)",
        "XAF": "Central African CFA franc (Fr)",
        "XCD": "East Caribbean dollar (&#36;)",
        "XOF": "West African CFA franc (Fr)",
        "XPF": "CFP franc (Fr)",
        "YER": "Yemeni rial (&#xfdfc;)",
        "ZAR": "South African rand (&#82;)",
        "ZMW": "Zambian kwacha (K)"
      },
      "tip": "This controls what currency prices are listed at in the catalog and which currency gateways will take payments in.",
      "value": "GBP",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/settings/general/woocommerce_currency"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/settings/general"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Settings

*Source: apis/rest-api/v2/settings.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Settings
The settings API allows you to view all groups of settings available.

## Setting group properties
| Attribute     | Type   | Description                                                                                                |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `id`          | string | A unique identifier that can be used to link settings together. `READ-ONLY`  |
| `label`       | string | A human readable label for the setting used in interfaces. `READ-ONLY`       |
| `description` | string | A human readable description for the setting used in interfaces. `READ-ONLY` |
| `parent_id`   | string | ID of parent grouping. `READ-ONLY`                                           |
| `sub_groups`  | string | IDs for settings sub groups. `READ-ONLY`                                     |

## List all settings groups
This API helps you to view all the settings groups.

```http
GET /wp-json/wc/v2/settings
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/settings \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("settings")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('settings')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("settings").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("settings").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": "general",
    "label": "General",
    "description": "",
    "parent_id": "",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/general"
        }
      ]
    }
  },
  {
    "id": "products",
    "label": "Products",
    "description": "",
    "parent_id": "",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/products"
        }
      ]
    }
  },
  {
    "id": "tax",
    "label": "Tax",
    "description": "",
    "parent_id": "",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/tax"
        }
      ]
    }
  },
  {
    "id": "shipping",
    "label": "Shipping",
    "description": "",
    "parent_id": "",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/shipping"
        }
      ]
    }
  },
  {
    "id": "checkout",
    "label": "Checkout",
    "description": "",
    "parent_id": "",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/checkout"
        }
      ]
    }
  },
  {
    "id": "account",
    "label": "Accounts",
    "description": "",
    "parent_id": "",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/account"
        }
      ]
    }
  },
  {
    "id": "email",
    "label": "Emails",
    "description": "",
    "parent_id": "",
    "sub_groups": [
      "email_new_order",
      "email_cancelled_order",
      "email_failed_order",
      "email_customer_on_hold_order",
      "email_customer_processing_order",
      "email_customer_completed_order",
      "email_customer_refunded_order",
      "email_customer_invoice",
      "email_customer_note",
      "email_customer_reset_password",
      "email_customer_new_account"
    ],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email"
        }
      ]
    }
  },
  {
    "id": "integration",
    "label": "Integration",
    "description": "",
    "parent_id": "",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/integration"
        }
      ]
    }
  },
  {
    "id": "api",
    "label": "API",
    "description": "",
    "parent_id": "",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/api"
        }
      ]
    }
  },
  {
    "id": "email_new_order",
    "label": "New order",
    "description": "New order emails are sent to chosen recipient(s) when a new order is received.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_new_order"
        }
      ]
    }
  },
  {
    "id": "email_cancelled_order",
    "label": "Cancelled order",
    "description": "Cancelled order emails are sent to chosen recipient(s) when orders have been marked cancelled (if they were previously processing or on-hold).",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_cancelled_order"
        }
      ]
    }
  },
  {
    "id": "email_failed_order",
    "label": "Failed order",
    "description": "Failed order emails are sent to chosen recipient(s) when orders have been marked failed (if they were previously processing or on-hold).",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_failed_order"
        }
      ]
    }
  },
  {
    "id": "email_customer_on_hold_order",
    "label": "Order on-hold",
    "description": "This is an order notification sent to customers containing order details after an order is placed on-hold.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_customer_on_hold_order"
        }
      ]
    }
  },
  {
    "id": "email_customer_processing_order",
    "label": "Processing order",
    "description": "This is an order notification sent to customers containing order details after payment.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_customer_processing_order"
        }
      ]
    }
  },
  {
    "id": "email_customer_completed_order",
    "label": "Completed order",
    "description": "Order complete emails are sent to customers when their orders are marked completed and usually indicate that their orders have been shipped.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_customer_completed_order"
        }
      ]
    }
  },
  {
    "id": "email_customer_refunded_order",
    "label": "Refunded order",
    "description": "Order refunded emails are sent to customers when their orders are marked refunded.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_customer_refunded_order"
        }
      ]
    }
  },
  {
    "id": "email_customer_invoice",
    "label": "Customer invoice",
    "description": "Customer invoice emails can be sent to customers containing their order information and payment links.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_customer_invoice"
        }
      ]
    }
  },
  {
    "id": "email_customer_note",
    "label": "Customer note",
    "description": "Customer note emails are sent when you add a note to an order.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_customer_note"
        }
      ]
    }
  },
  {
    "id": "email_customer_reset_password",
    "label": "Reset password",
    "description": "Customer \"reset password\" emails are sent when customers reset their passwords.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_customer_reset_password"
        }
      ]
    }
  },
  {
    "id": "email_customer_new_account",
    "label": "New account",
    "description": "Customer \"new account\" emails are sent to the customer when a customer signs up via checkout or account pages.",
    "parent_id": "email",
    "sub_groups": [],
    "_links": {
      "options": [
        {
          "href": "https://example.com/wp-json/wc/v2/settings/email_customer_new_account"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>


---

## Shipping methods

*Source: apis/rest-api/v2/shipping-methods.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Shipping methods
The shipping methods API allows you to view individual shipping methods.

## Shipping method properties
| Attribute     | Type   | Description                                                            |
| ------------- | ------ | ---------------------------------------------------------------------- |
| `id`          | string | Method ID. `READ-ONLY`                   |
| `title`       | string | Shipping method title. `READ-ONLY`       |
| `description` | string | Shipping method description. `READ-ONLY` |

## Retrieve a shipping method
This API lets you retrieve and view a specific shipping method.

```http
GET /wp-json/wc/v2/shipping_methods/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/shipping_methods/flat_rate \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("shipping_methods/flat_rate")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping_methods/flat_rate')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping_methods/flat_rate").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping_methods/flat_rate").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": "flat_rate",
  "title": "Flat rate",
  "description": "Lets you charge a fixed rate for shipping.",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping_methods/flat_rate"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping_methods"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all shipping methods
This API helps you to view all the shipping methods.

```http
GET /wp-json/wc/v2/shipping_methods
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/shipping_methods \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("shipping_methods")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping_methods')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping_methods").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping_methods").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": "flat_rate",
    "title": "Flat rate",
    "description": "Lets you charge a fixed rate for shipping.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping_methods/flat_rate"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping_methods"
        }
      ]
    }
  },
  {
    "id": "free_shipping",
    "title": "Free shipping",
    "description": "Free shipping is a special method which can be triggered with coupons and minimum spends.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping_methods/free_shipping"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping_methods"
        }
      ]
    }
  },
  {
    "id": "local_pickup",
    "title": "Local pickup",
    "description": "Allow customers to pick up orders themselves. By default, when using local pickup store base taxes will apply regardless of customer address.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping_methods/local_pickup"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping_methods"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>


---

## Shipping zone locations

*Source: apis/rest-api/v2/shipping-zone-locations.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Shipping zone locations
The shipping zone locations API allows you to view and batch update locations of a shipping zone.

## Shipping location properties
| Attribute | Type   | Description                                                                                                 |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `code`    | string | Shipping zone location code.                                                                                |
| `type`    | string | Shipping zone location type. Options: `postcode`, `state`, `country` and `continent`. Default is `country`. |

## List all locations of a shipping zone
This API helps you to view all the locations of a shipping zone.

```http
GET /wp-json/wc/v2/shipping/zones/<id>/locations
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/shipping/zones/5/locations \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("shipping/zones/5/locations")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones/5/locations')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones/5/locations").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones/5/locations").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "code": "BR",
    "type": "country",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/locations"
        }
      ],
      "describes": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Update a locations of a shipping zone
This API lets you make changes to locations of a shipping zone.

```http
PUT /wp-json/wc/v2/shipping/zones/<id>/locations
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/shipping/zones/5/locations \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '[
  {
    "code": "BR:SP",
    "type": "state"
  },
  {
    "code": "BR:RJ",
    "type": "state"
  }
]'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
var data = [
  {
    code: 'BR:SP',
    type: 'state'
  },
  {
    code: 'BR:RJ',
    type: 'state'
  }
];

WooCommerce.put("shipping/zones/5/locations", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    [
        'code' => 'BR:SP',
        'type' => 'state'
    ],
    [
        'code' => 'BR:RJ',
        'type' => 'state'
    ]
];

print_r($woocommerce->put('shipping/zones/5/locations', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = [
    {
        "code": "BR:SP",
        "type": "state"
    },
    {
        "code": "BR:RJ",
        "type": "state"
    }
]

print(wcapi.put("shipping/zones/5/locations", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = [
  {
    code: "BR:SP",
    type: "state"
  },
  {
    code: "BR:RJ",
    type: "state"
  }
]

woocommerce.put("shipping/zones/5/locations", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "code": "BR:SP",
    "type": "state",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/locations"
        }
      ],
      "describes": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
        }
      ]
    }
  },
  {
    "code": "BR:RJ",
    "type": "state",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/locations"
        }
      ],
      "describes": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>


---

## Shipping zone methods

*Source: apis/rest-api/v2/shipping-zone-methods.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Shipping zone methods
The shipping zone methods API allows you to create, view, update, and delete individual methods of a shipping zone.

## Shipping method properties
| Attribute            | Type    | Description                                                                                                 |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `instance_id`        | integer | Shipping method instance ID. `READ-ONLY`                                      |
| `title`              | string  | Shipping method customer facing title. `READ-ONLY`                            |
| `order`              | integer | Shipping method sort order.                                                                                 |
| `enabled`            | boolean | Shipping method enabled status.                                                                             |
| `method_id`          | string  | Shipping method ID. `READ-ONLY` `MANDATORY`     |
| `method_title`       | string  | Shipping method title. `READ-ONLY`                                            |
| `method_description` | string  | Shipping method description. `READ-ONLY`                                      |
| `settings`           | object  | Shipping method settings. See [Shipping method - Settings properties](#shipping-method---settings-properties) |

### Shipping method - Settings properties
| Attribute     | Type   | Description                                                                                                                                                                                     |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string | A unique identifier for the setting. `READ-ONLY`                                                                                                                  |
| `label`       | string | A human readable label for the setting used in interfaces. `READ-ONLY`                                                                                            |
| `description` | string | A human readable description for the setting used in interfaces. `READ-ONLY`                                                                                      |
| `type`        | string | Type of setting. Options: `text`, `email`, `number`, `color`, `password`, `textarea`, `select`, `multiselect`, `radio`, `image_width` and `checkbox`. `READ-ONLY` |
| `value`       | string | Setting value.                                                                                                                                                                                  |
| `default`     | string | Default value for the setting. `READ-ONLY`                                                                                                                        |
| `tip`         | string | Additional help text shown to the user about the setting. `READ-ONLY`                                                                                             |
| `placeholder` | string | Placeholder text to be displayed in text inputs. `READ-ONLY`                                                                                                      |

## Include a shipping method to a shipping zone
This API helps you to create a new shipping method to a shipping zone.

```http
POST /wp-json/wc/v2/shipping/zones/<id>/methods
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/shipping/zones/5/methods \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "method_id": "flat_rate"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  method_id: "flat_rate"
};

WooCommerce.post("shipping/zones/5/methods", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'method_id' => 'flat_rate'
];

print_r($woocommerce->post('shipping/zones/5/methods', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "method_id": "flat_rate"
}

print(wcapi.post("shipping/zones/5/methods", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  method_id: "flat_rate"
}

woocommerce.post("shipping/zones/5/methods", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "instance_id": 26,
  "title": "Flat rate",
  "order": 1,
  "enabled": true,
  "method_id": "flat_rate",
  "method_title": "Flat rate",
  "method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
  "settings": {
    "title": {
      "id": "title",
      "label": "Method title",
      "description": "This controls the title which the user sees during checkout.",
      "type": "text",
      "value": "Flat rate",
      "default": "Flat rate",
      "tip": "This controls the title which the user sees during checkout.",
      "placeholder": ""
    },
    "tax_status": {
      "id": "tax_status",
      "label": "Tax status",
      "description": "",
      "type": "select",
      "value": "taxable",
      "default": "taxable",
      "tip": "",
      "placeholder": "",
      "options": {
        "taxable": "Taxable",
        "none": "None"
      }
    },
    "cost": {
      "id": "cost",
      "label": "Cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "0",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": ""
    },
    "class_costs": {
      "id": "class_costs",
      "label": "Shipping class costs",
      "description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
      "type": "title",
      "value": "",
      "default": "",
      "tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
      "placeholder": ""
    },
    "class_cost_92": {
      "id": "class_cost_92",
      "label": "\"Express\" shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "class_cost_91": {
      "id": "class_cost_91",
      "label": "\"Priority\" shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "no_class_cost": {
      "id": "no_class_cost",
      "label": "No shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "type": {
      "id": "type",
      "label": "Calculation type",
      "description": "",
      "type": "select",
      "value": "class",
      "default": "class",
      "tip": "",
      "placeholder": "",
      "options": {
        "class": "Per class: Charge shipping for each shipping class individually",
        "order": "Per order: Charge shipping for the most expensive shipping class"
      }
    }
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods/26"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods"
      }
    ],
    "describes": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a shipping method from a shipping zone
This API lets you retrieve and view a specific shipping method from a shipping zone by ID.

```http
GET /wp-json/wc/v2/shipping/zones/<zone_id>/methods/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/shipping/zones/5/methods/26 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("shipping/zones/5/methods/26")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones/5/methods/26')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones/5/methods/26").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones/5/methods/26").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "instance_id": 26,
  "title": "Flat rate",
  "order": 1,
  "enabled": true,
  "method_id": "flat_rate",
  "method_title": "Flat rate",
  "method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
  "settings": {
    "title": {
      "id": "title",
      "label": "Method title",
      "description": "This controls the title which the user sees during checkout.",
      "type": "text",
      "value": "Flat rate",
      "default": "Flat rate",
      "tip": "This controls the title which the user sees during checkout.",
      "placeholder": ""
    },
    "tax_status": {
      "id": "tax_status",
      "label": "Tax status",
      "description": "",
      "type": "select",
      "value": "taxable",
      "default": "taxable",
      "tip": "",
      "placeholder": "",
      "options": {
        "taxable": "Taxable",
        "none": "None"
      }
    },
    "cost": {
      "id": "cost",
      "label": "Cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "0",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": ""
    },
    "class_costs": {
      "id": "class_costs",
      "label": "Shipping class costs",
      "description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
      "type": "title",
      "value": "",
      "default": "",
      "tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
      "placeholder": ""
    },
    "class_cost_92": {
      "id": "class_cost_92",
      "label": "\"Express\" shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "class_cost_91": {
      "id": "class_cost_91",
      "label": "\"Priority\" shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "no_class_cost": {
      "id": "no_class_cost",
      "label": "No shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "type": {
      "id": "type",
      "label": "Calculation type",
      "description": "",
      "type": "select",
      "value": "class",
      "default": "class",
      "tip": "",
      "placeholder": "",
      "options": {
        "class": "Per class: Charge shipping for each shipping class individually",
        "order": "Per order: Charge shipping for the most expensive shipping class"
      }
    }
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods/26"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods"
      }
    ],
    "describes": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all shipping methods from a shipping zone
This API helps you to view all the shipping methods from a shipping zone.

```http
GET /wp-json/wc/v2/shipping/zones/<id>/methods
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/shipping/zones/5/methods \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("shipping/zones/5/methods")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones/5/methods')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones/5/methods").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones/5/methods").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "instance_id": 26,
    "title": "Flat rate",
    "order": 1,
    "enabled": true,
    "method_id": "flat_rate",
    "method_title": "Flat rate",
    "method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
    "settings": {
      "title": {
        "id": "title",
        "label": "Method title",
        "description": "This controls the title which the user sees during checkout.",
        "type": "text",
        "value": "Flat rate",
        "default": "Flat rate",
        "tip": "This controls the title which the user sees during checkout.",
        "placeholder": ""
      },
      "tax_status": {
        "id": "tax_status",
        "label": "Tax status",
        "description": "",
        "type": "select",
        "value": "taxable",
        "default": "taxable",
        "tip": "",
        "placeholder": "",
        "options": {
          "taxable": "Taxable",
          "none": "None"
        }
      },
      "cost": {
        "id": "cost",
        "label": "Cost",
        "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
        "type": "text",
        "value": "0",
        "default": "",
        "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
        "placeholder": ""
      },
      "class_costs": {
        "id": "class_costs",
        "label": "Shipping class costs",
        "description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
        "type": "title",
        "value": "",
        "default": "",
        "tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
        "placeholder": ""
      },
      "class_cost_92": {
        "id": "class_cost_92",
        "label": "\"Express\" shipping class cost",
        "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
        "type": "text",
        "value": "",
        "default": "",
        "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
        "placeholder": "N/A"
      },
      "class_cost_91": {
        "id": "class_cost_91",
        "label": "\"Priority\" shipping class cost",
        "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
        "type": "text",
        "value": "",
        "default": "",
        "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
        "placeholder": "N/A"
      },
      "no_class_cost": {
        "id": "no_class_cost",
        "label": "No shipping class cost",
        "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
        "type": "text",
        "value": "",
        "default": "",
        "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
        "placeholder": "N/A"
      },
      "type": {
        "id": "type",
        "label": "Calculation type",
        "description": "",
        "type": "select",
        "value": "class",
        "default": "class",
        "tip": "",
        "placeholder": "",
        "options": {
          "class": "Per class: Charge shipping for each shipping class individually",
          "order": "Per order: Charge shipping for the most expensive shipping class"
        }
      }
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods/26"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods"
        }
      ],
      "describes": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
        }
      ]
    }
  },
  {
    "instance_id": 27,
    "title": "Free shipping",
    "order": 2,
    "enabled": true,
    "method_id": "free_shipping",
    "method_title": "Free shipping",
    "method_description": "<p>Free shipping is a special method which can be triggered with coupons and minimum spends.</p>\n",
    "settings": {
      "title": {
        "id": "title",
        "label": "Title",
        "description": "This controls the title which the user sees during checkout.",
        "type": "text",
        "value": "Free shipping",
        "default": "Free shipping",
        "tip": "This controls the title which the user sees during checkout.",
        "placeholder": ""
      },
      "requires": {
        "id": "requires",
        "label": "Free shipping requires...",
        "description": "",
        "type": "select",
        "value": "",
        "default": "",
        "tip": "",
        "placeholder": "",
        "options": {
          "": "N/A",
          "coupon": "A valid free shipping coupon",
          "min_amount": "A minimum order amount",
          "either": "A minimum order amount OR a coupon",
          "both": "A minimum order amount AND a coupon"
        }
      },
      "min_amount": {
        "id": "min_amount",
        "label": "Minimum order amount",
        "description": "Users will need to spend this amount to get free shipping (if enabled above).",
        "type": "price",
        "value": "0",
        "default": "",
        "tip": "Users will need to spend this amount to get free shipping (if enabled above).",
        "placeholder": ""
      }
    },
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods/27"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods"
        }
      ],
      "describes": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Update a shipping method of a shipping zone
This API lets you make changes to a shipping method of a shipping zone.

```http
PUT /wp-json/wc/v2/shipping/zones/<zone_id>/methods/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/shipping/zones/5/methods/26 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "settings": {
    "cost": "20.00"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  settings: {
    cost: "20.00"
  }
};

WooCommerce.put("shipping/zones/5/methods/26", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'regular_price' => [
        'cost' => '20.00'
    ]
];

print_r($woocommerce->put('shipping/zones/5/methods/26', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "regular_price": {
        "cost": "20.00"
    }
}

print(wcapi.put("shipping/zones/5/methods/26", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  regular_price: {
    "cost": "20.00"
  }
}

woocommerce.put("shipping/zones/5/methods/26", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "instance_id": 26,
  "title": "Flat rate",
  "order": 1,
  "enabled": true,
  "method_id": "flat_rate",
  "method_title": "Flat rate",
  "method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
  "settings": {
    "title": {
      "id": "title",
      "label": "Method title",
      "description": "This controls the title which the user sees during checkout.",
      "type": "text",
      "value": "Flat rate",
      "default": "Flat rate",
      "tip": "This controls the title which the user sees during checkout.",
      "placeholder": ""
    },
    "tax_status": {
      "id": "tax_status",
      "label": "Tax status",
      "description": "",
      "type": "select",
      "value": "taxable",
      "default": "taxable",
      "tip": "",
      "placeholder": "",
      "options": {
        "taxable": "Taxable",
        "none": "None"
      }
    },
    "cost": {
      "id": "cost",
      "label": "Cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "20.00",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": ""
    },
    "class_costs": {
      "id": "class_costs",
      "label": "Shipping class costs",
      "description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
      "type": "title",
      "value": "",
      "default": "",
      "tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
      "placeholder": ""
    },
    "class_cost_92": {
      "id": "class_cost_92",
      "label": "\"Express\" shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "class_cost_91": {
      "id": "class_cost_91",
      "label": "\"Priority\" shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "no_class_cost": {
      "id": "no_class_cost",
      "label": "No shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "type": {
      "id": "type",
      "label": "Calculation type",
      "description": "",
      "type": "select",
      "value": "class",
      "default": "class",
      "tip": "",
      "placeholder": "",
      "options": {
        "class": "Per class: Charge shipping for each shipping class individually",
        "order": "Per order: Charge shipping for the most expensive shipping class"
      }
    }
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods/26"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods"
      }
    ],
    "describes": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a shipping method from a shipping zone
This API helps you delete a shipping method from a shipping zone.

```http
DELETE /wp-json/wc/v2/shipping/zones/<zone_id>/methods/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/shipping/zones/5/methods/26?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("shipping/zones/5/methods/26", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('shipping/zones/5/methods/26', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("shipping/zones/5/methods/26", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("shipping/zones/5/methods/26", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "instance_id": 26,
  "title": "Flat rate",
  "order": 1,
  "enabled": true,
  "method_id": "flat_rate",
  "method_title": "Flat rate",
  "method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
  "settings": {
    "title": {
      "id": "title",
      "label": "Method title",
      "description": "This controls the title which the user sees during checkout.",
      "type": "text",
      "value": "Flat rate",
      "default": "Flat rate",
      "tip": "This controls the title which the user sees during checkout.",
      "placeholder": ""
    },
    "tax_status": {
      "id": "tax_status",
      "label": "Tax status",
      "description": "",
      "type": "select",
      "value": "taxable",
      "default": "taxable",
      "tip": "",
      "placeholder": "",
      "options": {
        "taxable": "Taxable",
        "none": "None"
      }
    },
    "cost": {
      "id": "cost",
      "label": "Cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "20.00",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": ""
    },
    "class_costs": {
      "id": "class_costs",
      "label": "Shipping class costs",
      "description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
      "type": "title",
      "value": "",
      "default": "",
      "tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
      "placeholder": ""
    },
    "class_cost_92": {
      "id": "class_cost_92",
      "label": "\"Express\" shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "class_cost_91": {
      "id": "class_cost_91",
      "label": "\"Priority\" shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "no_class_cost": {
      "id": "no_class_cost",
      "label": "No shipping class cost",
      "description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "type": "text",
      "value": "",
      "default": "",
      "tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
      "placeholder": "N/A"
    },
    "type": {
      "id": "type",
      "label": "Calculation type",
      "description": "",
      "type": "select",
      "value": "class",
      "default": "class",
      "tip": "",
      "placeholder": "",
      "options": {
        "class": "Per class: Charge shipping for each shipping class individually",
        "order": "Per order: Charge shipping for the most expensive shipping class"
      }
    }
  },
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods/26"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/methods"
      }
    ],
    "describes": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## Shipping zones

*Source: apis/rest-api/v2/shipping-zones.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Shipping zones
The shipping zones API allows you to create, view, update, and delete individual shipping zones.

## Shipping zone properties
| Attribute | Type    | Description                                                                   |
| --------- | ------- | ----------------------------------------------------------------------------- |
| `id`      | integer | Unique identifier for the resource. `READ-ONLY` |
| `name`    | string  | Shipping zone name. `MANDATORY`                 |
| `order`   | integer | Shipping zone order.                                                          |

## Create a shipping zone
This API helps you to create a new shipping zone.

```http
POST /wp-json/wc/v2/shipping/zones
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/shipping/zones \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Brazil"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Brazil"
};

WooCommerce.post("shipping/zones", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Brazil'
];

print_r($woocommerce->post('shipping/zones', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Brazil"
}

print(wcapi.post("shipping/zones", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Brazil"
}

woocommerce.post("shipping/zones", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 5,
  "name": "Brazil",
  "order": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones"
      }
    ],
    "describedby": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/locations"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a shipping zone
This API lets you retrieve and view a specific shipping zone by ID.

```http
GET /wp-json/wc/v2/shipping/zones/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/shipping/zones/5 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("shipping/zones/5")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones/5')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones/5").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones/5").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 5,
  "name": "Brazil",
  "order": 0,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones"
      }
    ],
    "describedby": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/locations"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all shipping zones
This API helps you to view all the shipping zones.

```http
GET /wp-json/wc/v2/shipping/zones
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/shipping/zones \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("shipping/zones")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 0,
    "name": "Rest of the World",
    "order": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/0"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones"
        }
      ],
      "describedby": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/0/locations"
        }
      ]
    }
  },
  {
    "id": 5,
    "name": "Brazil",
    "order": 0,
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones"
        }
      ],
      "describedby": [
        {
          "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/locations"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Update a shipping zone
This API lets you make changes to a shipping zone.

```http
PUT /wp-json/wc/v2/shipping/zones/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/shipping/zones/5 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "order": 1
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  order: 1
};

WooCommerce.put("shipping/zones/5", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'order' => 1
];

print_r($woocommerce->put('shipping/zones/5', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "order": 1
}

print(wcapi.put("shipping/zones/5", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  order: 1
}

woocommerce.put("shipping/zones/5", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 5,
  "name": "Brazil",
  "order": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones"
      }
    ],
    "describedby": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/locations"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a shipping zone
This API helps you delete a shipping zone.

```http
DELETE /wp-json/wc/v2/shipping/zones/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/shipping/zones/5?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("shipping/zones/5", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('shipping/zones/5', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("shipping/zones/5", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("shipping/zones/5", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 5,
  "name": "Brazil",
  "order": 1,
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones"
      }
    ],
    "describedby": [
      {
        "href": "https://example.com/wp-json/wc/v2/shipping/zones/5/locations"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## System status tools

*Source: apis/rest-api/v2/system-status-tools.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# System status tools
The system status tools API allows you to view and run tools from system status.

## System status tool properties
| Attribute     | Type    | Description                                                                                                         |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`          | string  | A unique identifier for the tool. `READ-ONLY`                                         |
| `name`        | string  | Tool name. `READ-ONLY`                                                                |
| `action`      | string  | What running the tool will do. `READ-ONLY`                                            |
| `description` | string  | Tool description. `READ-ONLY`                                                         |
| `success`     | boolean | Did the tool run successfully? `READ-ONLY` `WRITE-ONLY` |
| `message`     | string  | Tool return message. `READ-ONLY` `WRITE-ONLY`           |
| `confirm`     | boolean | Confirm execution of the tool. Default is `false`. `WRITE-ONLY`                       |

## Retrieve a tool from system status
This API lets you retrieve and view a specific tool from system status by ID.

```http
GET /wp-json/wc/v2/system_status/tools/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/system_status/tools/clear_transients \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("system_status/tools/clear_transients")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('system_status/tools/clear_transients')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("system_status/tools/clear_transients").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("system_status/tools/clear_transients").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": "clear_transients",
  "name": "WC transients",
  "action": "Clear transients",
  "description": "This tool will clear the product/shop transients cache.",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/system_status/tools/clear_transients"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/system_status/tools"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all tools from system status
This API helps you to view all tools from system status.

```http
GET /wp-json/wc/v2/system_status/tools
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/system_status/tools \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("system_status/tools")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('system_status/tools')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("system_status/tools").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("system_status/tools").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": "clear_transients",
    "name": "WC transients",
    "action": "Clear transients",
    "description": "This tool will clear the product/shop transients cache.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/clear_transients"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "clear_expired_transients",
    "name": "Expired transients",
    "action": "Clear expired transients",
    "description": "This tool will clear ALL expired transients from WordPress.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/clear_expired_transients"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "delete_orphaned_variations",
    "name": "Orphaned variations",
    "action": "Delete orphaned variations",
    "description": "This tool will delete all variations which have no parent.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/delete_orphaned_variations"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "clear_expired_download_permissions",
    "name": "Used-up download permissions",
    "action": "Clean up download permissions",
    "description": "This tool will delete expired download permissions and permissions with 0 remaining downloads.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/clear_expired_download_permissions"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "regenerate_product_lookup_tables",
    "name": "Product lookup tables",
    "action": "Regenerate",
    "description": "This tool will regenerate product lookup table data. This process may take a while.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/regenerate_product_lookup_tables"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "repair_coupons_lookup_table",
    "name": "Coupons lookup table",
    "action": "Repair",
    "description": "This tool will repair the coupons lookup table data with missing discount amounts. This process may take a while.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/repair_coupons_lookup_table"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "recount_terms",
    "name": "Term counts",
    "action": "Recount terms",
    "description": "This tool will recount product terms - useful when changing your settings in a way which hides products from the catalog.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/recount_terms"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "reset_roles",
    "name": "Capabilities",
    "action": "Reset capabilities",
    "description": "This tool will reset the admin, customer and shop_manager roles to default. Use this if your users cannot access all of the WooCommerce admin pages.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/reset_roles"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "clear_sessions",
    "name": "Customer sessions",
    "action": "Clear all sessions",
    "description": "<strong class=\"red\">Note:</strong> This tool will delete all customer session data from the database, including any current live carts.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/clear_sessions"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "clear_template_cache",
    "name": "Clear template cache",
    "action": "Clear",
    "description": "<strong class=\"red\">Note:</strong> This tool will empty the template cache.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/clear_template_cache"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "clear_system_status_theme_info_cache",
    "name": "Clear system status theme info cache",
    "action": "Clear",
    "description": "<strong class=\"red\">Note:</strong> This tool will empty the system status theme info cache.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/clear_system_status_theme_info_cache"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "install_pages",
    "name": "Install WooCommerce pages",
    "action": "Install pages",
    "description": "<strong class=\"red\">Note:</strong> This tool will install all the missing WooCommerce pages. Pages already defined and set up will not be replaced.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/install_pages"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "delete_taxes",
    "name": "Delete all WooCommerce tax rates",
    "action": "Delete ALL tax rates",
    "description": "<strong class=\"red\">Note:</strong> This option will delete ALL of your tax rates, use with caution.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/delete_taxes"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "regenerate_thumbnails",
    "name": "Regenerate shop thumbnails",
    "action": "Regenerate",
    "description": "This will regenerate all shop thumbnails to match your theme and/or image settings.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/regenerate_thumbnails"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "db_update_routine",
    "name": "Update database",
    "action": "Update database",
    "description": "<strong class=\"red\">Note:</strong> This tool will update your WooCommerce database to the latest version. Please ensure you make sufficient backups before proceeding.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/db_update_routine"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "recreate_order_address_fts_index",
    "name": "Re-create Order Address FTS index",
    "action": "Recreate index",
    "description": "This tool will recreate the full text search index for order addresses. If the index does not exist, it will try to create it.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/recreate_order_address_fts_index"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  },
  {
    "id": "verify_db_tables",
    "name": "Verify base database tables",
    "action": "Verify database",
    "description": "Verify if all base database tables are present.",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools/verify_db_tables"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/system_status/tools"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Run a tool from system status
This API lets you run a tool from system status.

```http
PUT /wp-json/wc/v2/system_status/tools/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/system_status/tools/clear_transients \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "confirm": true
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  confirm: true
};

WooCommerce.put("system_status/tools/clear_transients", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'confirm' => true
];

print_r($woocommerce->put('system_status/tools/clear_transients', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "confirm": True
}

print(wcapi.put("system_status/tools/clear_transients", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  confirm: true
}

woocommerce.put("system_status/tools/clear_transients", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": "clear_transients",
  "name": "WC transients",
  "action": "Clear transients",
  "description": "This tool will clear the product/shop transients cache.",
  "success": true,
  "message": "Product transients cleared",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/system_status/tools/clear_transients"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/system_status/tools"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>


---

## System status

*Source: apis/rest-api/v2/system-status.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# System status
The system status API allows you to view all system status items.

## System status properties
| Attribute        | Type   | Description                                                                                                                                |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `environment`    | object | Environment. See [System status - Environment properties](#system-status---environment-properties) `READ-ONLY` |
| `database`       | object | Database. See [System status - Database properties](#system-status---database-properties) `READ-ONLY`          |
| `active_plugins` | array  | Active plugins. `READ-ONLY`                                                                                  |
| `theme`          | object | Theme. See [System status - Theme properties](#system-status---theme-properties) `READ-ONLY`                   |
| `settings`       | object | Settings. See [System status - Settings properties](#system-status---settings-properties) `READ-ONLY`          |
| `security`       | object | Security. See [System status - Security properties](#system-status---security-properties) `READ-ONLY`          |
| `pages`          | array  | WooCommerce pages. `READ-ONLY`                                                                               |

### System status - Environment properties
| Attribute                   | Type    | Description                                                                |
| --------------------------- | ------- | -------------------------------------------------------------------------- |
| `home_url`                  | string  | Home URL. `READ-ONLY`                        |
| `site_url`                  | string  | Site URL. `READ-ONLY`                        |
| `wc_version`                | string  | WooCommerce version. `READ-ONLY`             |
| `log_directory`             | string  | Log directory. `READ-ONLY`                   |
| `log_directory_writable`    | boolean | Is log directory writable? `READ-ONLY`       |
| `wp_version`                | string  | WordPress version. `READ-ONLY`               |
| `wp_multisite`              | boolean | Is WordPress multisite? `READ-ONLY`          |
| `wp_memory_limit`           | integer | WordPress memory limit. `READ-ONLY`          |
| `wp_debug_mode`             | boolean | Is WordPress debug mode active? `READ-ONLY`  |
| `wp_cron`                   | boolean | Are WordPress cron jobs enabled? `READ-ONLY` |
| `wp_environment_type`       | string  | WordPress environment type. `READ-ONLY`      |
| `language`                  | string  | WordPress language. `READ-ONLY`              |
| `server_info`               | string  | Server info. `READ-ONLY`                     |
| `php_version`               | string  | PHP version. `READ-ONLY`                     |
| `php_post_max_size`         | integer | PHP post max size. `READ-ONLY`               |
| `php_max_execution_time`    | integer | PHP max execution time. `READ-ONLY`          |
| `php_max_input_vars`        | integer | PHP max input vars. `READ-ONLY`              |
| `curl_version`              | string  | cURL version. `READ-ONLY`                    |
| `suhosin_installed`         | boolean | Is SUHOSIN installed? `READ-ONLY`            |
| `max_upload_size`           | integer | Max upload size. `READ-ONLY`                 |
| `mysql_version`             | string  | MySQL version. `READ-ONLY`                   |
| `default_timezone`          | string  | Default timezone. `READ-ONLY`                |
| `fsockopen_or_curl_enabled` | boolean | Is fsockopen/cURL enabled? `READ-ONLY`       |
| `soapclient_enabled`        | boolean | Is SoapClient class enabled? `READ-ONLY`     |
| `domdocument_enabled`       | boolean | Is DomDocument class enabled? `READ-ONLY`    |
| `gzip_enabled`              | boolean | Is GZip enabled? `READ-ONLY`                 |
| `mbstring_enabled`          | boolean | Is mbstring enabled? `READ-ONLY`             |
| `remote_post_successful`    | boolean | Remote POST successful? `READ-ONLY`          |
| `remote_post_response`      | string  | Remote POST response. `READ-ONLY`            |
| `remote_get_successful`     | boolean | Remote GET successful? `READ-ONLY`           |
| `remote_get_response`       | string  | Remote GET response. `READ-ONLY`             |

### System status - Database properties
| Attribute                | Type   | Description                                                       |
| ------------------------ | ------ | ----------------------------------------------------------------- |
| `wc_database_version`    | string | WC database version. `READ-ONLY`    |
| `database_prefix`        | string | Database prefix. `READ-ONLY`        |
| `maxmind_geoip_database` | string | MaxMind GeoIP database. `READ-ONLY` |
| `database_tables`        | array  | Database tables. `READ-ONLY`        |

### System status - Theme properties
| Attribute                 | Type    | Description                                                                           |
| ------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `name`                    | string  | Theme name. `READ-ONLY`                                 |
| `version`                 | string  | Theme version. `READ-ONLY`                              |
| `version_latest`          | string  | Latest version of theme. `READ-ONLY`                    |
| `author_url`              | string  | Theme author URL. `READ-ONLY`                           |
| `is_child_theme`          | boolean | Is this theme a child theme? `READ-ONLY`                |
| `has_woocommerce_support` | boolean | Does the theme declare WooCommerce support? `READ-ONLY` |
| `has_woocommerce_file`    | boolean | Does the theme have a woocommerce.php file? `READ-ONLY` |
| `has_outdated_templates`  | boolean | Does this theme have outdated templates? `READ-ONLY`    |
| `overrides`               | array   | Template overrides. `READ-ONLY`                         |
| `parent_name`             | string  | Parent theme name. `READ-ONLY`                          |
| `parent_version`          | string  | Parent theme version. `READ-ONLY`                       |
| `parent_author_url`       | string  | Parent theme author URL. `READ-ONLY`                    |

### System status - Settings properties
| Attribute             | Type    | Description                                                                          |
| --------------------- | ------- | ------------------------------------------------------------------------------------ |
| `api_enabled`         | boolean | REST API enabled? `READ-ONLY`                          |
| `force_ssl`           | boolean | SSL forced? `READ-ONLY`                                |
| `currency`            | string  | Currency. `READ-ONLY`                                  |
| `currency_symbol`     | string  | Currency symbol. `READ-ONLY`                           |
| `currency_position`   | string  | Currency position. `READ-ONLY`                         |
| `thousand_separator`  | string  | Thousand separator. `READ-ONLY`                        |
| `decimal_separator`   | string  | Decimal separator. `READ-ONLY`                         |
| `number_of_decimals`  | integer | Number of decimals. `READ-ONLY`                        |
| `geolocation_enabled` | boolean | Geolocation enabled? `READ-ONLY`                       |
| `taxonomies`          | array   | Taxonomy terms for product/order statuses. `READ-ONLY` |

### System status - Security properties
| Attribute           | Type    | Description                                                                       |
| ------------------- | ------- | --------------------------------------------------------------------------------- |
| `secure_connection` | boolean | Is the connection to your store secure? `READ-ONLY` |
| `hide_errors`       | boolean | Hide errors from visitors? `READ-ONLY`              |

## List all system status items
This API helps you to view all the system status items.

```http
GET /wp-json/wc/v2/system_status
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/system_status \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("system_status")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('system_status')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("system_status").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("system_status").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "environment": {
    "home_url": "http://example.com",
    "site_url": "http://example.com",
    "version": "3.0.0",
    "log_directory": "/var/www/woocommerce/wp-content/uploads/wc-logs/",
    "log_directory_writable": true,
    "wp_version": "4.7.3",
    "wp_multisite": false,
    "wp_memory_limit": 134217728,
    "wp_debug_mode": true,
    "wp_cron": true,
    "wp_environment_type": "production",
    "language": "en_US",
    "server_info": "Apache/2.4.18 (Ubuntu)",
    "php_version": "7.1.3-2+deb.sury.org~yakkety+1",
    "php_post_max_size": 8388608,
    "php_max_execution_time": 30,
    "php_max_input_vars": 1000,
    "curl_version": "7.50.1, OpenSSL/1.0.2g",
    "suhosin_installed": false,
    "max_upload_size": 2097152,
    "mysql_version": "5.7.17",
    "default_timezone": "UTC",
    "fsockopen_or_curl_enabled": true,
    "soapclient_enabled": true,
    "domdocument_enabled": true,
    "gzip_enabled": true,
    "mbstring_enabled": true,
    "remote_post_successful": true,
    "remote_post_response": "200",
    "remote_get_successful": true,
    "remote_get_response": "200"
  },
  "database": {
    "wc_database_version": "3.0.0",
    "database_prefix": "wp_",
    "maxmind_geoip_database": "/var/www/woocommerce/wp-content/uploads/GeoIP.dat",
    "database_tables": {
      "woocommerce_sessions": true,
      "woocommerce_api_keys": true,
      "woocommerce_attribute_taxonomies": true,
      "woocommerce_downloadable_product_permissions": true,
      "woocommerce_order_items": true,
      "woocommerce_order_itemmeta": true,
      "woocommerce_tax_rates": true,
      "woocommerce_tax_rate_locations": true,
      "woocommerce_shipping_zones": true,
      "woocommerce_shipping_zone_locations": true,
      "woocommerce_shipping_zone_methods": true,
      "woocommerce_payment_tokens": true,
      "woocommerce_payment_tokenmeta": true
    }
  },
  "active_plugins": [
    {
      "plugin": "woocommerce/woocommerce.php",
      "name": "WooCommerce",
      "version": "3.0.0-rc.1",
      "version_latest": "2.6.14",
      "url": "https://woocommerce.com/",
      "author_name": "Automattic",
      "author_url": "https://woocommerce.com",
      "network_activated": false
    }
  ],
  "theme": {
    "name": "Twenty Sixteen",
    "version": "1.3",
    "version_latest": "1.3",
    "author_url": "https://wordpress.org/",
    "is_child_theme": false,
    "has_woocommerce_support": true,
    "has_woocommerce_file": false,
    "has_outdated_templates": false,
    "overrides": [],
    "parent_name": "",
    "parent_version": "",
    "parent_version_latest": "",
    "parent_author_url": ""
  },
  "settings": {
    "api_enabled": true,
    "force_ssl": false,
    "currency": "USD",
    "currency_symbol": "&#36;",
    "currency_position": "left",
    "thousand_separator": ",",
    "decimal_separator": ".",
    "number_of_decimals": 2,
    "geolocation_enabled": false,
    "taxonomies": {
      "external": "external",
      "grouped": "grouped",
      "simple": "simple",
      "variable": "variable"
    }
  },
  "security": {
    "secure_connection": true,
    "hide_errors": true
  },
  "pages": [
    {
      "page_name": "Shop base",
      "page_id": "4",
      "page_set": true,
      "page_exists": true,
      "page_visible": true,
      "shortcode": "",
      "shortcode_required": false,
      "shortcode_present": false
    },
    {
      "page_name": "Cart",
      "page_id": "5",
      "page_set": true,
      "page_exists": true,
      "page_visible": true,
      "shortcode": "[woocommerce_cart]",
      "shortcode_required": true,
      "shortcode_present": true
    },
    {
      "page_name": "Checkout",
      "page_id": "6",
      "page_set": true,
      "page_exists": true,
      "page_visible": true,
      "shortcode": "[woocommerce_checkout]",
      "shortcode_required": true,
      "shortcode_present": true
    },
    {
      "page_name": "My account",
      "page_id": "7",
      "page_set": true,
      "page_exists": true,
      "page_visible": true,
      "shortcode": "[woocommerce_my_account]",
      "shortcode_required": true,
      "shortcode_present": true
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Tax classes

*Source: apis/rest-api/v2/tax-classes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Tax classes
The tax classes API allows you to create, view, and delete individual tax classes.

## Tax class properties
| Attribute |  Type  |                                  Description                                  |
|-----------|--------|-------------------------------------------------------------------------------|
| `slug`    | string | Unique identifier for the resource. `READ-ONLY` |
| `name`    | string | Tax class name. `REQUIRED`                      |

## Create a tax class
This API helps you to create a new tax class.

```http
POST /wp-json/wc/v2/taxes/classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/taxes/classes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "Zero Rate"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Zero Rate"
};

WooCommerce.post("taxes/classes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Zero Rate'
];

print_r($woocommerce->post('taxes/classes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Zero Rate"
}

print(wcapi.post("taxes/classes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Zero Rate"
}

woocommerce.post("taxes/classes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "slug": "zero-rate",
  "name": "Zero Rate",
  "_links": {
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes/classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all tax classes
This API helps you to view all tax classes.

```http
GET /wp-json/wc/v2/taxes/classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/taxes/classes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("taxes/classes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes/classes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes/classes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes/classes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "slug": "standard",
    "name": "Standard Rate",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/classes"
        }
      ]
    }
  },
  {
    "slug": "reduced-rate",
    "name": "Reduced Rate",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/classes"
        }
      ]
    }
  },
  {
    "slug": "zero-rate",
    "name": "Zero Rate",
    "_links": {
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/classes"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

## Delete a tax class
This API helps you delete a tax class.

:::warning
This also will delete all tax rates from the selected class.
:::

```http
DELETE /wp-json/wc/v2/taxes/classes/<slug>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/taxes/classes/zero-rate?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("taxes/classes/zero-rate", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('taxes/classes/zero-rate', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("taxes/classes/zero-rate", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("taxes/classes/zero-rate", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "slug": "zero-rate",
  "name": "Zero Rate",
  "_links": {
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes/classes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, since this resource does not support trashing. |


---

## Tax rates

*Source: apis/rest-api/v2/taxes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Tax rates
The taxes API allows you to create, view, update, and delete individual tax rates, or a batch of tax rates.

## Tax rate properties
| Attribute  |   Type  |                                                                                   Description                                                                                   |
|------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`       | integer | Unique identifier for the resource. `READ-ONLY`                                                                                                   |
| `country`  | string  | Country ISO 3166 code. See [ISO 3166 Codes (Countries)](http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html) for more details                                              |
| `state`    | string  | State code.                                                                                                                                                                     |
| `postcode` | string  | Postcode/ZIP.                                                                                                                                                                   |
| `city`     | string  | City name.                                                                                                                                                                      |
| `rate`     | string  | Tax rate.                                                                                                                                                                       |
| `name`     | string  | Tax rate name.                                                                                                                                                                  |
| `priority` | integer | Tax priority. Only 1 matching rate per priority will be used. To define multiple tax rates for a single area you need to specify a different priority per rate. Default is `1`. |
| `compound` | boolean | Whether or not this is a compound rate. Compound tax rates are applied on top of other tax rates. Default is `false`.                                                           |
| `shipping` | boolean | Whether or not this tax rate also gets applied to shipping. Default is `true`.                                                                                                  |
| `order`    | integer | Indicates the order that will appear in queries.                                                                                                                                |
| `class`    | string  | Tax class. Default is `standard`.                                                                                                                                               |

## Create a tax rate
This API helps you to create a new tax rate.

```http
POST /wp-json/wc/v2/taxes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/taxes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "country": "US",
  "state": "AL",
  "rate": "4",
  "name": "State Tax",
  "shipping": false
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  country: "US",
  state: "AL",
  rate: "4",
  name: "State Tax",
  shipping: false
};

WooCommerce.post("taxes", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'country' => 'US',
    'state' => 'AL',
    'rate' => '4',
    'name' => 'State Tax',
    'shipping' => false
];

print_r($woocommerce->post('taxes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "country": "US",
    "state": "AL",
    "rate": "4",
    "name": "State Tax",
    "shipping": False
}

print(wcapi.post("taxes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  country: "US",
  state: "AL",
  rate: "4",
  name: "State Tax",
  shipping: false
}

woocommerce.post("taxes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 72,
  "country": "US",
  "state": "AL",
  "postcode": "",
  "city": "",
  "rate": "4.0000",
  "name": "State Tax",
  "priority": 0,
  "compound": false,
  "shipping": false,
  "order": 1,
  "class": "standard",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes/72"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a tax rate
This API lets you retrieve and view a specific tax rate by ID.

```http
GET /wp-json/wc/v2/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/taxes/72 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("taxes/72")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes/72')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes/72").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes/72").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 72,
  "country": "US",
  "state": "AL",
  "postcode": "",
  "city": "",
  "rate": "4.0000",
  "name": "State Tax",
  "priority": 0,
  "compound": false,
  "shipping": false,
  "order": 1,
  "class": "standard",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes/72"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all tax rates
This API helps you to view all the tax rates.

```http
GET /wp-json/wc/v2/taxes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/taxes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("taxes")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 72,
    "country": "US",
    "state": "AL",
    "postcode": "",
    "city": "",
    "rate": "4.0000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 1,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/72"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 73,
    "country": "US",
    "state": "AZ",
    "postcode": "",
    "city": "",
    "rate": "5.6000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 2,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/73"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 74,
    "country": "US",
    "state": "AR",
    "postcode": "",
    "city": "",
    "rate": "6.5000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 3,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/74"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 75,
    "country": "US",
    "state": "CA",
    "postcode": "",
    "city": "",
    "rate": "7.5000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 4,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/75"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 76,
    "country": "US",
    "state": "CO",
    "postcode": "",
    "city": "",
    "rate": "2.9000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 5,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/76"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 77,
    "country": "US",
    "state": "CT",
    "postcode": "",
    "city": "",
    "rate": "6.3500",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 6,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/77"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 78,
    "country": "US",
    "state": "DC",
    "postcode": "",
    "city": "",
    "rate": "5.7500",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 7,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/78"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 79,
    "country": "US",
    "state": "FL",
    "postcode": "",
    "city": "",
    "rate": "6.0000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 8,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/79"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 80,
    "country": "US",
    "state": "GA",
    "postcode": "",
    "city": "",
    "rate": "4.0000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": true,
    "order": 9,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/80"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  },
  {
    "id": 81,
    "country": "US",
    "state": "GU",
    "postcode": "",
    "city": "",
    "rate": "4.0000",
    "name": "State Tax",
    "priority": 0,
    "compound": false,
    "shipping": false,
    "order": 10,
    "class": "standard",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes/81"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/taxes"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter  |   Type  |                                                                Description                                                                 |
|------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `context`  | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`.                                  |
| `page`     | integer | Current page of the collection.                                                                                                            |
| `per_page` | integer | Maximum number of items to be returned in result set.                                                                                      |
| `offset`   | integer | Offset the result set by a specific number of items.                                                                                       |
| `order`    | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                                                 |
| `orderby`  | string  | Sort collection by object attribute. Default is `name`. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. |
| `class`    | string  | Sort by tax class.                                                                                                                         |

## Update a tax rate
This API lets you make changes to a tax rate.

```http
PUT /wp-json/wc/v2/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/taxes/72 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "US Tax"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "US Tax"
};

WooCommerce.put("taxes/72", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'US Tax'
];

print_r($woocommerce->put('taxes/72', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "US Tax"
}

print(wcapi.put("taxes/72", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "US Tax"
}

woocommerce.put("taxes/72", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 72,
  "country": "US",
  "state": "AL",
  "postcode": "",
  "city": "",
  "rate": "4.0000",
  "name": "US Tax",
  "priority": 0,
  "compound": false,
  "shipping": false,
  "order": 1,
  "class": "standard",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes/72"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a tax rate
This API helps you delete a tax rate.

```http
DELETE /wp-json/wc/v2/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/taxes/72?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("taxes/72", {
  force: true
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('taxes/72', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("taxes/72", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("taxes/72", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 72,
  "country": "US",
  "state": "AL",
  "postcode": "",
  "city": "",
  "rate": "4.0000",
  "name": "US Tax",
  "priority": 0,
  "compound": false,
  "shipping": false,
  "order": 1,
  "class": "standard",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes/72"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/taxes"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                          Description                          |
|-----------|--------|---------------------------------------------------------------|
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update tax rates
This API helps you to batch create, update and delete multiple tax rates.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/taxes/batch
```

> Example batch creating all US taxes:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/taxes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "country": "US",
      "state": "AL",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 1
    },
    {
      "country": "US",
      "state": "AZ",
      "rate": "5.6000",
      "name": "State Tax",
      "shipping": false,
      "order": 2
    },
    {
      "country": "US",
      "state": "AR",
      "rate": "6.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 3
    },
    {
      "country": "US",
      "state": "CA",
      "rate": "7.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 4
    },
    {
      "country": "US",
      "state": "CO",
      "rate": "2.9000",
      "name": "State Tax",
      "shipping": false,
      "order": 5
    },
    {
      "country": "US",
      "state": "CT",
      "rate": "6.3500",
      "name": "State Tax",
      "shipping": true,
      "order": 6
    },
    {
      "country": "US",
      "state": "DC",
      "rate": "5.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 7
    },
    {
      "country": "US",
      "state": "FL",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 8
    },
    {
      "country": "US",
      "state": "GA",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 9
    },
    {
      "country": "US",
      "state": "GU",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 10
    },
    {
      "country": "US",
      "state": "HI",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 11
    },
    {
      "country": "US",
      "state": "ID",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 12
    },
    {
      "country": "US",
      "state": "IL",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": false,
      "order": 13
    },
    {
      "country": "US",
      "state": "IN",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 14
    },
    {
      "country": "US",
      "state": "IA",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 15
    },
    {
      "country": "US",
      "state": "KS",
      "rate": "6.1500",
      "name": "State Tax",
      "shipping": true,
      "order": 16
    },
    {
      "country": "US",
      "state": "KY",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 17
    },
    {
      "country": "US",
      "state": "LA",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 18
    },
    {
      "country": "US",
      "state": "ME",
      "rate": "5.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 19
    },
    {
      "country": "US",
      "state": "MD",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 20
    },
    {
      "country": "US",
      "state": "MA",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": false,
      "order": 21
    },
    {
      "country": "US",
      "state": "MI",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 22
    },
    {
      "country": "US",
      "state": "MN",
      "rate": "6.8750",
      "name": "State Tax",
      "shipping": true,
      "order": 23
    },
    {
      "country": "US",
      "state": "MS",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 24
    },
    {
      "country": "US",
      "state": "MO",
      "rate": "4.2250",
      "name": "State Tax",
      "shipping": false,
      "order": 25
    },
    {
      "country": "US",
      "state": "NE",
      "rate": "5.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 26
    },
    {
      "country": "US",
      "state": "NV",
      "rate": "6.8500",
      "name": "State Tax",
      "shipping": false,
      "order": 27
    },
    {
      "country": "US",
      "state": "NJ",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 28
    },
    {
      "country": "US",
      "state": "NM",
      "rate": "5.1250",
      "name": "State Tax",
      "shipping": true,
      "order": 29
    },
    {
      "country": "US",
      "state": "NY",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 30
    },
    {
      "country": "US",
      "state": "NC",
      "rate": "4.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 31
    },
    {
      "country": "US",
      "state": "ND",
      "rate": "5.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 32
    },
    {
      "country": "US",
      "state": "OH",
      "rate": "5.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 33
    },
    {
      "country": "US",
      "state": "OK",
      "rate": "4.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 34
    },
    {
      "country": "US",
      "state": "PA",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 35
    },
    {
      "country": "US",
      "state": "PR",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 36
    },
    {
      "country": "US",
      "state": "RI",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 37
    },
    {
      "country": "US",
      "state": "SC",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 38
    },
    {
      "country": "US",
      "state": "SD",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 39
    },
    {
      "country": "US",
      "state": "TN",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 40
    },
    {
      "country": "US",
      "state": "TX",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": true,
      "order": 41
    },
    {
      "country": "US",
      "state": "UT",
      "rate": "5.9500",
      "name": "State Tax",
      "shipping": false,
      "order": 42
    },
    {
      "country": "US",
      "state": "VT",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 43
    },
    {
      "country": "US",
      "state": "VA",
      "rate": "5.3000",
      "name": "State Tax",
      "shipping": false,
      "order": 44
    },
    {
      "country": "US",
      "state": "WA",
      "rate": "6.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 45
    },
    {
      "country": "US",
      "state": "WV",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 46
    },
    {
      "country": "US",
      "state": "WI",
      "rate": "5.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 47
    },
    {
      "country": "US",
      "state": "WY",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 48
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      country: "US",
      state: "AL",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 1
    },
    {
      country: "US",
      state: "AZ",
      rate: "5.6000",
      name: "State Tax",
      shipping: false,
      order: 2
    },
    {
      country: "US",
      state: "AR",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 3
    },
    {
      country: "US",
      state: "CA",
      rate: "7.5000",
      name: "State Tax",
      shipping: false,
      order: 4
    },
    {
      country: "US",
      state: "CO",
      rate: "2.9000",
      name: "State Tax",
      shipping: false,
      order: 5
    },
    {
      country: "US",
      state: "CT",
      rate: "6.3500",
      name: "State Tax",
      shipping: true,
      order: 6
    },
    {
      country: "US",
      state: "DC",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 7
    },
    {
      country: "US",
      state: "FL",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 8
    },
    {
      country: "US",
      state: "GA",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 9
    },
    {
      country: "US",
      state: "GU",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 10
    },
    {
      country: "US",
      state: "HI",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 11
    },
    {
      country: "US",
      state: "ID",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 12
    },
    {
      country: "US",
      state: "IL",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 13
    },
    {
      country: "US",
      state: "IN",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 14
    },
    {
      country: "US",
      state: "IA",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 15
    },
    {
      country: "US",
      state: "KS",
      rate: "6.1500",
      name: "State Tax",
      shipping: true,
      order: 16
    },
    {
      country: "US",
      state: "KY",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 17
    },
    {
      country: "US",
      state: "LA",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 18
    },
    {
      country: "US",
      state: "ME",
      rate: "5.5000",
      name: "State Tax",
      shipping: false,
      order: 19
    },
    {
      country: "US",
      state: "MD",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 20
    },
    {
      country: "US",
      state: "MA",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 21
    },
    {
      country: "US",
      state: "MI",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 22
    },
    {
      country: "US",
      state: "MN",
      rate: "6.8750",
      name: "State Tax",
      shipping: true,
      order: 23
    },
    {
      country: "US",
      state: "MS",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 24
    },
    {
      country: "US",
      state: "MO",
      rate: "4.2250",
      name: "State Tax",
      shipping: false,
      order: 25
    },
    {
      country: "US",
      state: "NE",
      rate: "5.5000",
      name: "State Tax",
      shipping: true,
      order: 26
    },
    {
      country: "US",
      state: "NV",
      rate: "6.8500",
      name: "State Tax",
      shipping: false,
      order: 27
    },
    {
      country: "US",
      state: "NJ",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 28
    },
    {
      country: "US",
      state: "NM",
      rate: "5.1250",
      name: "State Tax",
      shipping: true,
      order: 29
    },
    {
      country: "US",
      state: "NY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 30
    },
    {
      country: "US",
      state: "NC",
      rate: "4.7500",
      name: "State Tax",
      shipping: true,
      order: 31
    },
    {
      country: "US",
      state: "ND",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 32
    },
    {
      country: "US",
      state: "OH",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 33
    },
    {
      country: "US",
      state: "OK",
      rate: "4.5000",
      name: "State Tax",
      shipping: false,
      order: 34
    },
    {
      country: "US",
      state: "PA",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 35
    },
    {
      country: "US",
      state: "PR",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 36
    },
    {
      country: "US",
      state: "RI",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 37
    },
    {
      country: "US",
      state: "SC",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 38
    },
    {
      country: "US",
      state: "SD",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 39
    },
    {
      country: "US",
      state: "TN",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 40
    },
    {
      country: "US",
      state: "TX",
      rate: "6.2500",
      name: "State Tax",
      shipping: true,
      order: 41
    },
    {
      country: "US",
      state: "UT",
      rate: "5.9500",
      name: "State Tax",
      shipping: false,
      order: 42
    },
    {
      country: "US",
      state: "VT",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 43
    },
    {
      country: "US",
      state: "VA",
      rate: "5.3000",
      name: "State Tax",
      shipping: false,
      order: 44
    },
    {
      country: "US",
      state: "WA",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 45
    },
    {
      country: "US",
      state: "WV",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 46
    },
    {
      country: "US",
      state: "WI",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 47
    },
    {
      country: "US",
      state: "WY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 48
    }
  ]
};

WooCommerce.post("taxes/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'country' => 'US',
            'state' => 'AL',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 1
        ],
        [
            'country' => 'US',
            'state' => 'AZ',
            'rate' => '5.6000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 2
        ],
        [
            'country' => 'US',
            'state' => 'AR',
            'rate' => '6.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 3
        ],
        [
            'country' => 'US',
            'state' => 'CA',
            'rate' => '7.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 4
        ],
        [
            'country' => 'US',
            'state' => 'CO',
            'rate' => '2.9000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 5
        ],
        [
            'country' => 'US',
            'state' => 'CT',
            'rate' => '6.3500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 6
        ],
        [
            'country' => 'US',
            'state' => 'DC',
            'rate' => '5.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 7
        ],
        [
            'country' => 'US',
            'state' => 'FL',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 8
        ],
        [
            'country' => 'US',
            'state' => 'GA',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 9
        ],
        [
            'country' => 'US',
            'state' => 'GU',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 10
        ],
        [
            'country' => 'US',
            'state' => 'HI',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 11
        ],
        [
            'country' => 'US',
            'state' => 'ID',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 12
        ],
        [
            'country' => 'US',
            'state' => 'IL',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 13
        ],
        [
            'country' => 'US',
            'state' => 'IN',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 14
        ],
        [
            'country' => 'US',
            'state' => 'IA',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 15
        ],
        [
            'country' => 'US',
            'state' => 'KS',
            'rate' => '6.1500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 16
        ],
        [
            'country' => 'US',
            'state' => 'KY',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 17
        ],
        [
            'country' => 'US',
            'state' => 'LA',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 18
        ],
        [
            'country' => 'US',
            'state' => 'ME',
            'rate' => '5.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 19
        ],
        [
            'country' => 'US',
            'state' => 'MD',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 20
        ],
        [
            'country' => 'US',
            'state' => 'MA',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 21
        ],
        [
            'country' => 'US',
            'state' => 'MI',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 22
        ],
        [
            'country' => 'US',
            'state' => 'MN',
            'rate' => '6.8750',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 23
        ],
        [
            'country' => 'US',
            'state' => 'MS',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 24
        ],
        [
            'country' => 'US',
            'state' => 'MO',
            'rate' => '4.2250',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 25
        ],
        [
            'country' => 'US',
            'state' => 'NE',
            'rate' => '5.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 26
        ],
        [
            'country' => 'US',
            'state' => 'NV',
            'rate' => '6.8500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 27
        ],
        [
            'country' => 'US',
            'state' => 'NJ',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 28
        ],
        [
            'country' => 'US',
            'state' => 'NM',
            'rate' => '5.1250',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 29
        ],
        [
            'country' => 'US',
            'state' => 'NY',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 30
        ],
        [
            'country' => 'US',
            'state' => 'NC',
            'rate' => '4.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 31
        ],
        [
            'country' => 'US',
            'state' => 'ND',
            'rate' => '5.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 32
        ],
        [
            'country' => 'US',
            'state' => 'OH',
            'rate' => '5.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 33
        ],
        [
            'country' => 'US',
            'state' => 'OK',
            'rate' => '4.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 34
        ],
        [
            'country' => 'US',
            'state' => 'PA',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 35
        ],
        [
            'country' => 'US',
            'state' => 'PR',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 36
        ],
        [
            'country' => 'US',
            'state' => 'RI',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 37
        ],
        [
            'country' => 'US',
            'state' => 'SC',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 38
        ],
        [
            'country' => 'US',
            'state' => 'SD',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 39
        ],
        [
            'country' => 'US',
            'state' => 'TN',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 40
        ],
        [
            'country' => 'US',
            'state' => 'TX',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 41
        ],
        [
            'country' => 'US',
            'state' => 'UT',
            'rate' => '5.9500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 42
        ],
        [
            'country' => 'US',
            'state' => 'VT',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 43
        ],
        [
            'country' => 'US',
            'state' => 'VA',
            'rate' => '5.3000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 44
        ],
        [
            'country' => 'US',
            'state' => 'WA',
            'rate' => '6.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 45
        ],
        [
            'country' => 'US',
            'state' => 'WV',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 46
        ],
        [
            'country' => 'US',
            'state' => 'WI',
            'rate' => '5.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 47
        ],
        [
            'country' => 'US',
            'state' => 'WY',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 48
        ]
    ]
];

print_r($woocommerce->post('taxes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "country": "US",
            "state": "AL",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 1
        },
        {
            "country": "US",
            "state": "AZ",
            "rate": "5.6000",
            "name": "State Tax",
            "shipping": False,
            "order": 2
        },
        {
            "country": "US",
            "state": "AR",
            "rate": "6.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 3
        },
        {
            "country": "US",
            "state": "CA",
            "rate": "7.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 4
        },
        {
            "country": "US",
            "state": "CO",
            "rate": "2.9000",
            "name": "State Tax",
            "shipping": False,
            "order": 5
        },
        {
            "country": "US",
            "state": "CT",
            "rate": "6.3500",
            "name": "State Tax",
            "shipping": True,
            "order": 6
        },
        {
            "country": "US",
            "state": "DC",
            "rate": "5.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 7
        },
        {
            "country": "US",
            "state": "FL",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 8
        },
        {
            "country": "US",
            "state": "GA",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 9
        },
        {
            "country": "US",
            "state": "GU",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 10
        },
        {
            "country": "US",
            "state": "HI",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 11
        },
        {
            "country": "US",
            "state": "ID",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 12
        },
        {
            "country": "US",
            "state": "IL",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": False,
            "order": 13
        },
        {
            "country": "US",
            "state": "IN",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 14
        },
        {
            "country": "US",
            "state": "IA",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 15
        },
        {
            "country": "US",
            "state": "KS",
            "rate": "6.1500",
            "name": "State Tax",
            "shipping": True,
            "order": 16
        },
        {
            "country": "US",
            "state": "KY",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 17
        },
        {
            "country": "US",
            "state": "LA",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 18
        },
        {
            "country": "US",
            "state": "ME",
            "rate": "5.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 19
        },
        {
            "country": "US",
            "state": "MD",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 20
        },
        {
            "country": "US",
            "state": "MA",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": False,
            "order": 21
        },
        {
            "country": "US",
            "state": "MI",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 22
        },
        {
            "country": "US",
            "state": "MN",
            "rate": "6.8750",
            "name": "State Tax",
            "shipping": True,
            "order": 23
        },
        {
            "country": "US",
            "state": "MS",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 24
        },
        {
            "country": "US",
            "state": "MO",
            "rate": "4.2250",
            "name": "State Tax",
            "shipping": False,
            "order": 25
        },
        {
            "country": "US",
            "state": "NE",
            "rate": "5.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 26
        },
        {
            "country": "US",
            "state": "NV",
            "rate": "6.8500",
            "name": "State Tax",
            "shipping": False,
            "order": 27
        },
        {
            "country": "US",
            "state": "NJ",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 28
        },
        {
            "country": "US",
            "state": "NM",
            "rate": "5.1250",
            "name": "State Tax",
            "shipping": True,
            "order": 29
        },
        {
            "country": "US",
            "state": "NY",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 30
        },
        {
            "country": "US",
            "state": "NC",
            "rate": "4.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 31
        },
        {
            "country": "US",
            "state": "ND",
            "rate": "5.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 32
        },
        {
            "country": "US",
            "state": "OH",
            "rate": "5.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 33
        },
        {
            "country": "US",
            "state": "OK",
            "rate": "4.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 34
        },
        {
            "country": "US",
            "state": "PA",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 35
        },
        {
            "country": "US",
            "state": "PR",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 36
        },
        {
            "country": "US",
            "state": "RI",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 37
        },
        {
            "country": "US",
            "state": "SC",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 38
        },
        {
            "country": "US",
            "state": "SD",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 39
        },
        {
            "country": "US",
            "state": "TN",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 40
        },
        {
            "country": "US",
            "state": "TX",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": True,
            "order": 41
        },
        {
            "country": "US",
            "state": "UT",
            "rate": "5.9500",
            "name": "State Tax",
            "shipping": False,
            "order": 42
        },
        {
            "country": "US",
            "state": "VT",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 43
        },
        {
            "country": "US",
            "state": "VA",
            "rate": "5.3000",
            "name": "State Tax",
            "shipping": False,
            "order": 44
        },
        {
            "country": "US",
            "state": "WA",
            "rate": "6.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 45
        },
        {
            "country": "US",
            "state": "WV",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 46
        },
        {
            "country": "US",
            "state": "WI",
            "rate": "5.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 47
        },
        {
            "country": "US",
            "state": "WY",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 48
        }
    ]
}

print(wcapi.post("taxes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      country: "US",
      state: "AL",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 1
    },
    {
      country: "US",
      state: "AZ",
      rate: "5.6000",
      name: "State Tax",
      shipping: false,
      order: 2
    },
    {
      country: "US",
      state: "AR",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 3
    },
    {
      country: "US",
      state: "CA",
      rate: "7.5000",
      name: "State Tax",
      shipping: false,
      order: 4
    },
    {
      country: "US",
      state: "CO",
      rate: "2.9000",
      name: "State Tax",
      shipping: false,
      order: 5
    },
    {
      country: "US",
      state: "CT",
      rate: "6.3500",
      name: "State Tax",
      shipping: true,
      order: 6
    },
    {
      country: "US",
      state: "DC",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 7
    },
    {
      country: "US",
      state: "FL",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 8
    },
    {
      country: "US",
      state: "GA",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 9
    },
    {
      country: "US",
      state: "GU",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 10
    },
    {
      country: "US",
      state: "HI",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 11
    },
    {
      country: "US",
      state: "ID",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 12
    },
    {
      country: "US",
      state: "IL",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 13
    },
    {
      country: "US",
      state: "IN",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 14
    },
    {
      country: "US",
      state: "IA",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 15
    },
    {
      country: "US",
      state: "KS",
      rate: "6.1500",
      name: "State Tax",
      shipping: true,
      order: 16
    },
    {
      country: "US",
      state: "KY",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 17
    },
    {
      country: "US",
      state: "LA",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 18
    },
    {
      country: "US",
      state: "ME",
      rate: "5.5000",
      name: "State Tax",
      shipping: false,
      order: 19
    },
    {
      country: "US",
      state: "MD",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 20
    },
    {
      country: "US",
      state: "MA",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 21
    },
    {
      country: "US",
      state: "MI",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 22
    },
    {
      country: "US",
      state: "MN",
      rate: "6.8750",
      name: "State Tax",
      shipping: true,
      order: 23
    },
    {
      country: "US",
      state: "MS",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 24
    },
    {
      country: "US",
      state: "MO",
      rate: "4.2250",
      name: "State Tax",
      shipping: false,
      order: 25
    },
    {
      country: "US",
      state: "NE",
      rate: "5.5000",
      name: "State Tax",
      shipping: true,
      order: 26
    },
    {
      country: "US",
      state: "NV",
      rate: "6.8500",
      name: "State Tax",
      shipping: false,
      order: 27
    },
    {
      country: "US",
      state: "NJ",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 28
    },
    {
      country: "US",
      state: "NM",
      rate: "5.1250",
      name: "State Tax",
      shipping: true,
      order: 29
    },
    {
      country: "US",
      state: "NY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 30
    },
    {
      country: "US",
      state: "NC",
      rate: "4.7500",
      name: "State Tax",
      shipping: true,
      order: 31
    },
    {
      country: "US",
      state: "ND",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 32
    },
    {
      country: "US",
      state: "OH",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 33
    },
    {
      country: "US",
      state: "OK",
      rate: "4.5000",
      name: "State Tax",
      shipping: false,
      order: 34
    },
    {
      country: "US",
      state: "PA",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 35
    },
    {
      country: "US",
      state: "PR",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 36
    },
    {
      country: "US",
      state: "RI",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 37
    },
    {
      country: "US",
      state: "SC",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 38
    },
    {
      country: "US",
      state: "SD",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 39
    },
    {
      country: "US",
      state: "TN",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 40
    },
    {
      country: "US",
      state: "TX",
      rate: "6.2500",
      name: "State Tax",
      shipping: true,
      order: 41
    },
    {
      country: "US",
      state: "UT",
      rate: "5.9500",
      name: "State Tax",
      shipping: false,
      order: 42
    },
    {
      country: "US",
      state: "VT",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 43
    },
    {
      country: "US",
      state: "VA",
      rate: "5.3000",
      name: "State Tax",
      shipping: false,
      order: 44
    },
    {
      country: "US",
      state: "WA",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 45
    },
    {
      country: "US",
      state: "WV",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 46
    },
    {
      country: "US",
      state: "WI",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 47
    },
    {
      country: "US",
      state: "WY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 48
    }
  ]
}

woocommerce.post("taxes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 72,
      "country": "US",
      "state": "AL",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 1,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/72"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 73,
      "country": "US",
      "state": "AZ",
      "postcode": "",
      "city": "",
      "rate": "5.6000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 2,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/73"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 74,
      "country": "US",
      "state": "AR",
      "postcode": "",
      "city": "",
      "rate": "6.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 3,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/74"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 75,
      "country": "US",
      "state": "CA",
      "postcode": "",
      "city": "",
      "rate": "7.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 4,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/75"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 76,
      "country": "US",
      "state": "CO",
      "postcode": "",
      "city": "",
      "rate": "2.9000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 5,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/76"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 77,
      "country": "US",
      "state": "CT",
      "postcode": "",
      "city": "",
      "rate": "6.3500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 6,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/77"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 78,
      "country": "US",
      "state": "DC",
      "postcode": "",
      "city": "",
      "rate": "5.7500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 7,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/78"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 79,
      "country": "US",
      "state": "FL",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 8,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/79"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 80,
      "country": "US",
      "state": "GA",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 9,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/80"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 81,
      "country": "US",
      "state": "GU",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 10,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/81"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 82,
      "country": "US",
      "state": "HI",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 11,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/82"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 83,
      "country": "US",
      "state": "ID",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 12,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/83"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 84,
      "country": "US",
      "state": "IL",
      "postcode": "",
      "city": "",
      "rate": "6.2500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 13,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/84"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 85,
      "country": "US",
      "state": "IN",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 14,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/85"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 86,
      "country": "US",
      "state": "IA",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 15,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/86"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 87,
      "country": "US",
      "state": "KS",
      "postcode": "",
      "city": "",
      "rate": "6.1500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 16,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/87"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 88,
      "country": "US",
      "state": "KY",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 17,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/88"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 89,
      "country": "US",
      "state": "LA",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 18,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/89"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 90,
      "country": "US",
      "state": "ME",
      "postcode": "",
      "city": "",
      "rate": "5.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 19,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/90"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 91,
      "country": "US",
      "state": "MD",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 20,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/91"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 92,
      "country": "US",
      "state": "MA",
      "postcode": "",
      "city": "",
      "rate": "6.2500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 21,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/92"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 93,
      "country": "US",
      "state": "MI",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 22,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/93"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 94,
      "country": "US",
      "state": "MN",
      "postcode": "",
      "city": "",
      "rate": "6.8750",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 23,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/94"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 95,
      "country": "US",
      "state": "MS",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 24,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/95"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 96,
      "country": "US",
      "state": "MO",
      "postcode": "",
      "city": "",
      "rate": "4.2250",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 25,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/96"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 97,
      "country": "US",
      "state": "NE",
      "postcode": "",
      "city": "",
      "rate": "5.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 26,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/97"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 98,
      "country": "US",
      "state": "NV",
      "postcode": "",
      "city": "",
      "rate": "6.8500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 27,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/98"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 99,
      "country": "US",
      "state": "NJ",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 28,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/99"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 100,
      "country": "US",
      "state": "NM",
      "postcode": "",
      "city": "",
      "rate": "5.1250",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 29,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/100"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 101,
      "country": "US",
      "state": "NY",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 30,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/101"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 102,
      "country": "US",
      "state": "NC",
      "postcode": "",
      "city": "",
      "rate": "4.7500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 31,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/102"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 103,
      "country": "US",
      "state": "ND",
      "postcode": "",
      "city": "",
      "rate": "5.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 32,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/103"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 104,
      "country": "US",
      "state": "OH",
      "postcode": "",
      "city": "",
      "rate": "5.7500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 33,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/104"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 105,
      "country": "US",
      "state": "OK",
      "postcode": "",
      "city": "",
      "rate": "4.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 34,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/105"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 106,
      "country": "US",
      "state": "PA",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 35,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/106"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 107,
      "country": "US",
      "state": "PR",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 36,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/107"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 108,
      "country": "US",
      "state": "RI",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 37,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/108"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 109,
      "country": "US",
      "state": "SC",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 38,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/109"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 110,
      "country": "US",
      "state": "SD",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 39,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/110"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 111,
      "country": "US",
      "state": "TN",
      "postcode": "",
      "city": "",
      "rate": "7.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 40,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/111"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 112,
      "country": "US",
      "state": "TX",
      "postcode": "",
      "city": "",
      "rate": "6.2500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 41,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/112"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 113,
      "country": "US",
      "state": "UT",
      "postcode": "",
      "city": "",
      "rate": "5.9500",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 42,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/113"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 114,
      "country": "US",
      "state": "VT",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 43,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/114"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 115,
      "country": "US",
      "state": "VA",
      "postcode": "",
      "city": "",
      "rate": "5.3000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": false,
      "order": 44,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/115"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 116,
      "country": "US",
      "state": "WA",
      "postcode": "",
      "city": "",
      "rate": "6.5000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 45,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/116"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 117,
      "country": "US",
      "state": "WV",
      "postcode": "",
      "city": "",
      "rate": "6.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 46,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/117"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 118,
      "country": "US",
      "state": "WI",
      "postcode": "",
      "city": "",
      "rate": "5.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 47,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/118"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    },
    {
      "id": 119,
      "country": "US",
      "state": "WY",
      "postcode": "",
      "city": "",
      "rate": "4.0000",
      "name": "State Tax",
      "priority": 0,
      "compound": false,
      "shipping": true,
      "order": 48,
      "class": "standard",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes/119"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/taxes"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>


---

## Webhooks

*Source: apis/rest-api/v2/webhooks.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Webhooks
The webhooks API allows you to create, view, update, and delete individual, or a batch, of webhooks.

Webhooks can be managed via the WooCommerce settings screen or by using the REST API endpoints. The `WC_Webhook` class manages all data storage and retrieval of the webhook custom post type, as well as enqueuing webhook actions and processing/delivering/logging webhooks. On `woocommerce_init`, active webhooks are loaded.

Each webhook has:

* `status`: active (delivers payload), paused (delivery paused by admin), disabled (delivery paused by failure).
* `topic`: determines which resource events the webhook is triggered for.
* `delivery URL`: URL where the payload is delivered, must be HTTP or HTTPS.
* `secret`: an optional secret key that is used to generate a HMAC-SHA256 hash of the request body so the receiver can verify authenticity of the webhook.
* `hooks`: an array of hook names that are added and bound to the webhook for processing.

### Topics
The topic is a combination resource (e.g. order) and event (e.g. created) and maps to one or more hook names (e.g. `woocommerce_checkout_order_processed`). Webhooks can be created using the topic name and the appropriate hooks are automatically added.

Core topics are:

* Coupons: `coupon.created`, `coupon.updated` and `coupon.deleted`.
* Customers: `customer.created`, `customer.updated` and `customer.deleted`.
* Orders: `order.created`, `order.updated` and `order.deleted`.
* Products: `product.created`, `product.updated` and `product.deleted`.

Custom topics can also be used which map to a single hook name, for example you could add a webhook with topic `action.woocommerce_add_to_cart` that is triggered on that event. Custom topics pass the first hook argument to the payload, so in this example the `cart_item_key` would be included in the payload.

### Delivery/payload
Delivery is performed using `wp_remote_post()` (HTTP POST) and processed in the background by default using wp-cron. A few custom headers are added to the request to help the receiver process the webhook:

* `X-WC-Webhook-Source`: `http://example.com/`.
* `X-WC-Webhook-Topic` - e.g. `order.updated`.
* `X-WC-Webhook-Resource` - e.g. `order`.
* `X-WC-Webhook-Event` - e.g. `updated`.
* `X-WC-Webhook-Signature` - a base64 encoded HMAC-SHA256 hash of the payload.
* `X-WC-Webhook-ID` - webhook's post ID.
* `X-WC-Webhook-Delivery-ID` - delivery log ID (a comment).

The payload is JSON encoded and for API resources (coupons, customers, orders, products), the response is exactly the same as if requested via the REST API.

### Logging
Requests/responses are logged as comments on the webhook custom post type. Each delivery log includes:

* Request duration.
* Request URL, method, headers, and body.
* Response Code, message, headers, and body.

Only the 25 most recent delivery logs are kept in order to reduce comment table bloat.

After 5 consecutive failed deliveries (as defined by a non HTTP 2xx response code), the webhook is disabled and must be edited via the REST API to re-enable.

Delivery logs can be fetched through the REST API endpoint or in code using `WC_Webhook::get_delivery_logs()`.

### Visual interface
You can find the Webhooks interface going to "WooCommerce" > "Settings" > "API" > "Webhooks", see our [Visual Webhooks docs](https://docs.woocommerce.com/document/webhooks/) for more details.

## Webhook properties
| Attribute           | Type      | Description                                                                                                                                                                                                                                                                |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                                                                                                                              |
| `name`              | string    | A friendly name for the webhook.                                                                                                                                                                                                                                           |
| `status`            | string    | Webhook status. Options: `active`, `paused` and `disabled`. Default is `active`.                                                                                                                                                                                           |
| `topic`             | string    | Webhook topic. `MANDATORY`                                                                                                                                                                                                                   |
| `resource`          | string    | Webhook resource. `READ-ONLY`                                                                                                                                                                                                                |
| `event`             | string    | Webhook event. `READ-ONLY`                                                                                                                                                                                                                   |
| `hooks`             | array     | WooCommerce action names associated with the webhook. `READ-ONLY`                                                                                                                                                                            |
| `delivery_url`      | string    | The URL where the webhook payload is delivered. `READ-ONLY` `MANDATORY`                                                                                                                                        |
| `secret`            | string    | Secret key used to generate a hash of the delivered webhook and provided in the request headers. This will default is a MD5 hash from the current user's ID|username if not provided. `WRITE-ONLY` `MANDATORY` |
| `date_created`      | date-time | The date the webhook was created, in the site's timezone. `READ-ONLY`                                                                                                                                                                        |
| `date_created_gmt`  | date-time | The date the webhook was created, as GMT. `READ-ONLY`                                                                                                                                                                                        |
| `date_modified`     | date-time | The date the webhook was last modified, in the site's timezone. `READ-ONLY`                                                                                                                                                                  |
| `date_modified_gmt` | date-time | The date the webhook was last modified, as GMT. `READ-ONLY`                                                                                                                                                                                  |

### Webhook delivery properties
| Attribute          | Type      | Description                                                                                                                       |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | integer   | Unique identifier for the resource. `READ-ONLY`                                                     |
| `duration`         | string    | The delivery duration, in seconds. `READ-ONLY`                                                      |
| `summary`          | string    | A friendly summary of the response including the HTTP response code, message, and body. `READ-ONLY` |
| `request_url`      | string    | The URL where the webhook was delivered. `READ-ONLY`                                                |
| `request_headers`  | array     | Request headers. `READ-ONLY`                                                                        |
| `request_body`     | string    | Request body. `READ-ONLY`                                                                           |
| `response_code`    | string    | The HTTP response code from the receiving server. `READ-ONLY`                                       |
| `response_message` | string    | The HTTP response message from the receiving server. `READ-ONLY`                                    |
| `response_headers` | array     | Array of the response headers from the receiving server. `READ-ONLY`                                |
| `response_body`    | string    | The response body from the receiving server. `READ-ONLY`                                            |
| `date_created`     | date-time | The date the webhook delivery was logged, in the site's timezone. `READ-ONLY`                       |
| `date_created_gmt` | date-time | The date the webhook delivery was logged, GMT. `READ-ONLY`                                          |

#### Request header properties
|         Attribute          |   Type  |                                                             Description                                                              |
|----------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------|
| `User-Agent`               | string  | The request user agent, default is "WooCommerce/\{version\} Hookshot (WordPress/\{version\})". `READ-ONLY` |
| `Content-Type`             | string  | The request content-type, default is "application/json". `READ-ONLY`                                   |
| `X-WC-Webhook-Source`      | string  | The webhook source. `READ-ONLY`                                                                        |
| `X-WC-Webhook-Topic`       | string  | The webhook topic. `READ-ONLY`                                                                         |
| `X-WC-Webhook-Resource`    | string  | The webhook resource. `READ-ONLY`                                                                      |
| `X-WC-Webhook-Event`       | string  | The webhook event. `READ-ONLY`                                                                         |
| `X-WC-Webhook-Signature`   | string  | A base64 encoded HMAC-SHA256 hash of the payload. `READ-ONLY`                                          |
| `X-WC-Webhook-ID`          | integer | The webhook's ID. `READ-ONLY`                                                                          |
| `X-WC-Webhook-Delivery-ID` | integer | The delivery ID. `READ-ONLY`                                                                           |

## Create a webhook
This API helps you to create a new webhook.

```http
POST /wp-json/wc/v2/webhooks
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/webhooks \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Order updated",
  "topic": "order.updated",
  "delivery_url": "http://requestb.in/1g0sxmo1"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  name: "Order updated",
  topic: "order.updated",
  delivery_url: "http://requestb.in/1g0sxmo1"
};

WooCommerce.post("webhooks", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Order updated',
    'topic' => 'order.updated',
    'delivery_url' => 'http://requestb.in/1g0sxmo1'
];

print_r($woocommerce->post('webhooks', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Order updated",
    "topic": "order.updated",
    "delivery_url": "http://requestb.in/1g0sxmo1"
}

print(wcapi.post("webhooks", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Order updated",
  topic: "order.updated",
  delivery_url: "http://requestb.in/1g0sxmo1"
}

woocommerce.post("webhooks", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 142,
  "name": "Order updated",
  "status": "active",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T23:17:52",
  "date_created_gmt": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T23:17:52",
  "date_modified_gmt": "2016-05-15T20:17:52",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Retrieve a webhook
This API lets you retrieve and view a specific webhook.

```http
GET /wp-json/wc/v2/webhooks/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/webhooks/142 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("webhooks/142")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks/142')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks/142").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks/142").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 142,
  "name": "Order updated",
  "status": "active",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T23:17:52",
  "date_created_gmt": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T23:17:52",
  "date_modified_gmt": "2016-05-15T20:17:52",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## List all webhooks
This API helps you to view all the webhooks.

```http
GET /wp-json/wc/v2/webhooks
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/webhooks \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("webhooks")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 143,
    "name": "Customer created",
    "status": "active",
    "topic": "customer.created",
    "resource": "customer",
    "event": "created",
    "hooks": [
      "user_register",
      "woocommerce_created_customer",
      "woocommerce_api_create_customer"
    ],
    "delivery_url": "http://requestb.in/1g0sxmo1",
    "date_created": "2016-05-15T23:17:52",
    "date_created_gmt": "2016-05-15T20:17:52",
    "date_modified": "2016-05-15T23:17:52",
    "date_modified_gmt": "2016-05-15T20:17:52",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks/143"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks"
        }
      ]
    }
  },
  {
    "id": 142,
    "name": "Order updated",
    "status": "active",
    "topic": "order.updated",
    "resource": "order",
    "event": "updated",
    "hooks": [
      "woocommerce_process_shop_order_meta",
      "woocommerce_api_edit_order",
      "woocommerce_order_edit_status",
      "woocommerce_order_status_changed"
    ],
    "delivery_url": "http://requestb.in/1g0sxmo1",
    "date_created": "2016-05-15T23:17:52",
    "date_created_gmt": "2016-05-15T20:17:52",
    "date_modified": "2016-05-15T23:17:52",
    "date_modified_gmt": "2016-05-15T20:17:52",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks/142"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter       | Type    | Description                                                                                                                   |
| --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `context`       | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.  |
| `page`          | integer | Current page of the collection. Default is `1`.                                                                               |
| `per_page`      | integer | Maximum number of items to be returned in result set. Default is `10`.                                                        |
| `search`        | string  | Limit results to those matching a string.                                                                                     |
| `after`         | string  | Limit response to resources published after a given ISO8601 compliant date.                                                   |
| `before`        | string  | Limit response to resources published before a given ISO8601 compliant date.                                                  |
| `dates_are_gmt` | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                      |
| `exclude`       | array   | Ensure result set excludes specific IDs.                                                                                      |
| `include`       | array   | Limit result set to specific ids.                                                                                             |
| `offset`        | integer | Offset the result set by a specific number of items.                                                                          |
| `order`         | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                   |
| `orderby`       | string  | Sort collection by object attribute. Options: `date`, `id`, `include`, `title` and `slug`. Default is `date`.                 |
| `status`        | string  | Limit result set to webhooks assigned a specific status. Options: `all`, `active`, `paused` and `disabled`. Default is `all`. |

## Update a webhook
This API lets you make changes to a webhook.

```http
PUT /wp-json/wc/v2/webhook/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v2/webhook/142 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "status": "paused"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  status: "paused"
}

WooCommerce.put("webhooks/142", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'status' => 'paused'
];

print_r($woocommerce->put('webhooks/142', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "status": "paused"
}

print(wcapi.put("webhooks/142", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  status: "paused"
}

woocommerce.put("webhooks/142", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 142,
  "name": "Order updated",
  "status": "paused",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T23:17:52",
  "date_created_gmt": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T17:30:12",
  "date_modified_gmt": "2016-05-15T20:30:12",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

## Delete a webhook
This API helps you delete a webhook.

```http
DELETE /wp-json/wc/v2/webhooks/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v2/webhooks/142 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete("webhooks/142")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('webhooks/142')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("webhooks/142").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("webhooks/142").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 142,
  "name": "Order updated",
  "status": "paused",
  "topic": "order.updated",
  "resource": "order",
  "event": "updated",
  "hooks": [
    "woocommerce_process_shop_order_meta",
    "woocommerce_api_edit_order",
    "woocommerce_order_edit_status",
    "woocommerce_order_status_changed"
  ],
  "delivery_url": "http://requestb.in/1g0sxmo1",
  "date_created": "2016-05-15T23:17:52",
  "date_created_gmt": "2016-05-15T20:17:52",
  "date_modified": "2016-05-15T23:30:12",
  "date_modified_gmt": "2016-05-15T20:30:12",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks/142"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

#### Available parameters
| Parameter |  Type  |                                Description                                 |
|-----------|--------|----------------------------------------------------------------------------|
| `force`   | string | Use `true` whether to permanently delete the webhook, Default is `false`. |

## Batch update webhooks
This API helps you to batch create, update and delete multiple webhooks.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or deleted.
:::

```http
POST /wp-json/wc/v2/webhooks/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v2/webhooks/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Coupon created",
      "topic": "coupon.created",
      "delivery_url": "http://requestb.in/1g0sxmo1"
    },
    {
      "name": "Customer deleted",
      "topic": "customer.deleted",
      "delivery_url": "http://requestb.in/1g0sxmo1"
    }
  ],
  "delete": [
    143
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
  create: [
    {
      name: "Round toe",
      topic: "coupon.created",
      delivery_url: "http://requestb.in/1g0sxmo1"
    },
    {
      name: "Customer deleted",
      topic: "customer.deleted",
      delivery_url: "http://requestb.in/1g0sxmo1"
    }
  ],
  delete: [
    143
  ]
};

WooCommerce.post("webhooks/batch", data)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Round toe',
            'topic' => 'coupon.created',
            'delivery_url' => 'http://requestb.in/1g0sxmo1'
        ],
        [
            'name' => 'Customer deleted',
            'topic' => 'customer.deleted',
            'delivery_url' => 'http://requestb.in/1g0sxmo1'
        ]
    ],
    'delete' => [
        143
    ]
];

print_r($woocommerce->post('webhooks/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Round toe",
            "topic": "coupon.created",
            "delivery_url": "http://requestb.in/1g0sxmo1"
        },
        {
            "name": "Customer deleted",
            "topic": "customer.deleted",
            "delivery_url": "http://requestb.in/1g0sxmo1"
        }
    ],
    "delete": [
        143
    ]
}

print(wcapi.post("webhooks/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Round toe",
      topic: "coupon.created",
      delivery_url: "http://requestb.in/1g0sxmo1"
    },
    {
      name: "Customer deleted",
      topic: "customer.deleted",
      delivery_url: "http://requestb.in/1g0sxmo1"
    }
  ],
  delete: [
    143
  ]
}

woocommerce.post("webhooks/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "create": [
    {
      "id": 146,
      "name": "Coupon created",
      "status": "active",
      "topic": "coupon.created",
      "resource": "coupon",
      "event": "created",
      "hooks": [
        "woocommerce_process_shop_coupon_meta",
        "woocommerce_api_create_coupon"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-25T01:56:26",
      "date_created_gmt": "2016-05-24T22:56:26",
      "date_modified": "2016-05-25T01:56:26",
      "date_modified_gmt": "2016-05-24T22:56:26",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/webhooks/146"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/webhooks"
          }
        ]
      }
    },
    {
      "id": 147,
      "name": "Customer deleted",
      "status": "active",
      "topic": "customer.deleted",
      "resource": "customer",
      "event": "deleted",
      "hooks": [
        "delete_user"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-25T01:56:30",
      "date_created_gmt": "2016-05-24T22:56:30",
      "date_modified": "2016-05-25T01:56:30",
      "date_modified_gmt": "2016-05-24T22:56:30",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/webhooks/147"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/webhooks"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 143,
      "name": "Webhook created on May 24, 2016 @ 03:20 AM",
      "status": "active",
      "topic": "customer.created",
      "resource": "customer",
      "event": "created",
      "hooks": [
        "user_register",
        "woocommerce_created_customer",
        "woocommerce_api_create_customer"
      ],
      "delivery_url": "http://requestb.in/1g0sxmo1",
      "date_created": "2016-05-15T23:17:52",
      "date_created_gmt": "2016-05-15T20:17:52",
      "date_modified": "2016-05-15T23:17:52",
      "date_modified_gmt": "2016-05-15T20:17:52",
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v2/webhooks/143"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v2/webhooks"
          }
        ]
      }
    }
  ]
}
```

  </TabItem>
</Tabs>

## Retrieve webhook delivery
This API lets you retrieve and view a specific webhook delivery.

```http
GET /wp-json/wc/v2/webhooks/<id>/deliveries/<delivery_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/webhooks/142/deliveries/54 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("webhooks/142/deliveries/54")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks/142/deliveries/54')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks/142/deliveries/54").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks/142/deliveries/54").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
  "id": 54,
  "duration": "0.40888",
  "summary": "HTTP 200 OK: ok",
  "request_method": "POST",
  "request_url": "http://requestb.in/1g0sxmo1",
  "request_headers": {
    "User-Agent": "WooCommerce/2.6.0 Hookshot (WordPress/4.5.2)",
    "Content-Type": "application/json",
    "X-WC-Webhook-Source": "http://example.com/",
    "X-WC-Webhook-Topic": "order.updated",
    "X-WC-Webhook-Resource": "order",
    "X-WC-Webhook-Event": "updated",
    "X-WC-Webhook-Signature": "J72iu7hL93aUt2dFnyOBoBypwbmP6nt6Aor33nnOHxU=",
    "X-WC-Webhook-ID": 142,
    "X-WC-Webhook-Delivery-ID": 54
  },
  "request_body": "{\"order\":{\"id\":118,\"order_number\":118,\"order_key\":\"wc_order_5728e9a347a2d\",\"created_at\":\"2016-05-03T18:10:00Z\",\"updated_at\":\"2016-05-16T03:30:30Z\",\"completed_at\":\"2016-05-16T03:29:19Z\",\"status\":\"completed\",\"currency\":\"BRL\",\"total\":\"14.00\",\"subtotal\":\"4.00\",\"total_line_items_quantity\":2,\"total_tax\":\"0.00\",\"total_shipping\":\"10.00\",\"cart_tax\":\"0.00\",\"shipping_tax\":\"0.00\",\"total_discount\":\"0.00\",\"shipping_methods\":\"Flat Rate\",\"payment_details\":{\"method_id\":\"bacs\",\"method_title\":\"Direct Bank Transfer\",\"paid\":true},\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"},\"note\":\"\",\"customer_ip\":\"127.0.0.1\",\"customer_user_agent\":\"curl/7.47.0\",\"customer_id\":0,\"view_order_url\":\"http://example.com/my-account/view-order/118\",\"line_items\":[{\"id\":8,\"subtotal\":\"4.00\",\"subtotal_tax\":\"0.00\",\"total\":\"4.00\",\"total_tax\":\"0.00\",\"price\":\"2.00\",\"quantity\":2,\"tax_class\":null,\"name\":\"Woo Single #2\",\"product_id\":99,\"sku\":\"12345\",\"meta\":[]}],\"shipping_lines\":[{\"id\":9,\"method_id\":\"flat_rate\",\"method_title\":\"Flat Rate\",\"total\":\"10.00\"}],\"tax_lines\":[],\"fee_lines\":[],\"coupon_lines\":[],\"is_vat_exempt\":false,\"customer\":{\"id\":0,\"email\":\"john.doe@claudiosmweb.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"}}}}",
  "response_code": "200",
  "response_message": "OK",
  "response_headers": {
    "connection": "close",
    "server": "gunicorn/19.3.0",
    "date": "Tue, 16 May 2016 03:30:31 GMT",
    "content-type": "text/html; charset=utf-8",
    "content-length": "2",
    "sponsored-by": "https://www.runscope.com",
    "via": "1.1 vegur"
  },
  "response_body": "ok",
  "date_created": "2016-05-16T06:30:31",
  "date_created_gmt": "2016-05-16T03:30:31",
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks/142/deliveries/54"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks/142/deliveries"
      }
    ],
    "up": [
      {
        "href": "https://example.com/wp-json/wc/v2/webhooks/142"
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

:::note
View the <a href="#webhooks-delivery-properties">Webhooks Delivery properties</a> for more details on this response.
:::

## List all webhook deliveries
This API helps you to view all deliveries from a specific webhooks.

```http
GET /wp-json/wc/v2/webhooks/<id>/deliveries
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v2/webhooks/142/deliveries \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get("webhooks/142/deliveries")
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error.response.data);
  });
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks/142/deliveries')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks/142/deliveries").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks/142/deliveries").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
  {
    "id": 54,
    "duration": "0.40888",
    "summary": "HTTP 200 OK: ok",
    "request_method": "POST",
    "request_url": "http://requestb.in/1g0sxmo1",
    "request_headers": {
      "User-Agent": "WooCommerce/2.6.0 Hookshot (WordPress/4.5.2)",
      "Content-Type": "application/json",
      "X-WC-Webhook-Source": "http://example.com/",
      "X-WC-Webhook-Topic": "order.updated",
      "X-WC-Webhook-Resource": "order",
      "X-WC-Webhook-Event": "updated",
      "X-WC-Webhook-Signature": "J72iu7hL93aUt2dFnyOBoBypwbmP6nt6Aor33nnOHxU=",
      "X-WC-Webhook-ID": 142,
      "X-WC-Webhook-Delivery-ID": 54
    },
    "request_body": "{\"order\":{\"id\":118,\"order_number\":118,\"order_key\":\"wc_order_5728e9a347a2d\",\"created_at\":\"2016-05-03T18:10:00Z\",\"updated_at\":\"2016-05-16T03:30:30Z\",\"completed_at\":\"2016-05-16T03:29:19Z\",\"status\":\"completed\",\"currency\":\"BRL\",\"total\":\"14.00\",\"subtotal\":\"4.00\",\"total_line_items_quantity\":2,\"total_tax\":\"0.00\",\"total_shipping\":\"10.00\",\"cart_tax\":\"0.00\",\"shipping_tax\":\"0.00\",\"total_discount\":\"0.00\",\"shipping_methods\":\"Flat Rate\",\"payment_details\":{\"method_id\":\"bacs\",\"method_title\":\"Direct Bank Transfer\",\"paid\":true},\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"},\"note\":\"\",\"customer_ip\":\"127.0.0.1\",\"customer_user_agent\":\"curl/7.47.0\",\"customer_id\":0,\"view_order_url\":\"http://example.com/my-account/view-order/118\",\"line_items\":[{\"id\":8,\"subtotal\":\"4.00\",\"subtotal_tax\":\"0.00\",\"total\":\"4.00\",\"total_tax\":\"0.00\",\"price\":\"2.00\",\"quantity\":2,\"tax_class\":null,\"name\":\"Woo Single #2\",\"product_id\":99,\"sku\":\"12345\",\"meta\":[]}],\"shipping_lines\":[{\"id\":9,\"method_id\":\"flat_rate\",\"method_title\":\"Flat Rate\",\"total\":\"10.00\"}],\"tax_lines\":[],\"fee_lines\":[],\"coupon_lines\":[],\"is_vat_exempt\":false,\"customer\":{\"id\":0,\"email\":\"john.doe@claudiosmweb.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"}}}}",
    "response_code": "200",
    "response_message": "OK",
    "response_headers": {
      "connection": "close",
      "server": "gunicorn/19.3.0",
      "date": "Tue, 16 May 2016 03:30:31 GMT",
      "content-type": "text/html; charset=utf-8",
      "content-length": "2",
      "sponsored-by": "https://www.runscope.com",
      "via": "1.1 vegur"
    },
    "response_body": "ok",
    "date_created": "2016-05-16T06:30:31",
    "date_created_gmt": "2016-05-16T03:30:31",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks/142/deliveries/54"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks/142/deliveries"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks/142"
        }
      ]
    }
  },
  {
    "id": 53,
    "duration": "0.7615",
    "summary": "HTTP 200 OK: ok",
    "request_method": "POST",
    "request_url": "http://requestb.in/1g0sxmo1",
    "request_headers": {
      "User-Agent": "WooCommerce/2.6.0 Hookshot (WordPress/4.5.2)",
      "Content-Type": "application/json",
      "X-WC-Webhook-Source": "http://example.com/",
      "X-WC-Webhook-Topic": "order.updated",
      "X-WC-Webhook-Resource": "order",
      "X-WC-Webhook-Event": "updated",
      "X-WC-Webhook-Signature": "Z996ccyueeoqdXZFq2ND2ETpsPGrXmWKj+yvQ0c2N1w=",
      "X-WC-Webhook-ID": 142,
      "X-WC-Webhook-Delivery-ID": 53
    },
    "request_body": "{\"order\":{\"id\":118,\"order_number\":118,\"order_key\":\"wc_order_5728e9a347a2d\",\"created_at\":\"2016-05-03T18:10:00Z\",\"updated_at\":\"2016-05-16T03:29:13Z\",\"completed_at\":\"2016-05-16T03:29:19Z\",\"status\":\"completed\",\"currency\":\"BRL\",\"total\":\"14.00\",\"subtotal\":\"4.00\",\"total_line_items_quantity\":2,\"total_tax\":\"0.00\",\"total_shipping\":\"10.00\",\"cart_tax\":\"0.00\",\"shipping_tax\":\"0.00\",\"total_discount\":\"0.00\",\"shipping_methods\":\"Flat Rate\",\"payment_details\":{\"method_id\":\"bacs\",\"method_title\":\"Direct Bank Transfer\",\"paid\":true},\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"},\"note\":\"\",\"customer_ip\":\"127.0.0.1\",\"customer_user_agent\":\"curl/7.47.0\",\"customer_id\":0,\"view_order_url\":\"http://example.com/my-account/view-order/118\",\"line_items\":[{\"id\":8,\"subtotal\":\"4.00\",\"subtotal_tax\":\"0.00\",\"total\":\"4.00\",\"total_tax\":\"0.00\",\"price\":\"2.00\",\"quantity\":2,\"tax_class\":null,\"name\":\"Woo Single #2\",\"product_id\":99,\"sku\":\"12345\",\"meta\":[]}],\"shipping_lines\":[{\"id\":9,\"method_id\":\"flat_rate\",\"method_title\":\"Flat Rate\",\"total\":\"10.00\"}],\"tax_lines\":[],\"fee_lines\":[],\"coupon_lines\":[],\"is_vat_exempt\":false,\"customer\":{\"id\":0,\"email\":\"john.doe@claudiosmweb.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"billing_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\",\"email\":\"john.doe@claudiosmweb.com\",\"phone\":\"(555) 555-5555\"},\"shipping_address\":{\"first_name\":\"John\",\"last_name\":\"Doe\",\"company\":\"\",\"address_1\":\"969 Market\",\"address_2\":\"\",\"city\":\"San Francisco\",\"state\":\"CA\",\"postcode\":\"94103\",\"country\":\"US\"}}}}",
    "response_code": "200",
    "response_message": "OK",
    "response_headers": {
      "connection": "close",
      "server": "gunicorn/19.3.0",
      "date": "Tue, 16 May 2016 03:29:20 GMT",
      "content-type": "text/html; charset=utf-8",
      "content-length": "2",
      "sponsored-by": "https://www.runscope.com",
      "via": "1.1 vegur"
    },
    "response_body": "ok",
    "date_created": "2016-05-16T06:29:19",
    "date_created_gmt": "2016-05-16T03:29:19",
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks/142/deliveries/53"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks/142/deliveries"
        }
      ],
      "up": [
        {
          "href": "https://example.com/wp-json/wc/v2/webhooks/142"
        }
      ]
    }
  }
]
```

  </TabItem>
</Tabs>


---

## Index

*Source: apis/rest-api/v3/api-reference.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Index

By default, the API provides information about all available endpoints on the site. Authentication is not required to access the API index.

```http
GET /wp-json/wc/v3
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( '' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"namespace": "wc/v3",
	"routes": {
		"/wc/v3": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"namespace": {
							"required": false,
							"default": "wc/v3"
						},
						"context": {
							"required": false,
							"default": "view"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3"
			}
		},
		"/wc/v3/coupons": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"after": {
							"required": false,
							"description": "Limit response to resources published after a given ISO8601 compliant date.",
							"type": "string"
						},
						"before": {
							"required": false,
							"description": "Limit response to resources published before a given ISO8601 compliant date.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "desc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "date",
							"enum": [
								"date",
								"id",
								"include",
								"title",
								"slug"
							],
							"description": "Sort collection by object attribute.",
							"type": "string"
						},
						"code": {
							"required": false,
							"description": "Limit result set to resources with a specific code.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"code": {
							"required": true,
							"description": "Coupon code.",
							"type": "string"
						},
						"amount": {
							"required": false,
							"description": "The amount of discount. Should always be numeric, even if setting a percentage.",
							"type": "string"
						},
						"discount_type": {
							"required": false,
							"default": "fixed_cart",
							"enum": [
								"percent",
								"fixed_cart",
								"fixed_product"
							],
							"description": "Determines the type of discount that will be applied.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "Coupon description.",
							"type": "string"
						},
						"date_expires": {
							"required": false,
							"description": "The date the coupon expires, in the site's timezone.",
							"type": "string"
						},
						"date_expires_gmt": {
							"required": false,
							"description": "The date the coupon expires, as GMT.",
							"type": "string"
						},
						"individual_use": {
							"required": false,
							"default": false,
							"description": "If true, the coupon can only be used individually. Other applied coupons will be removed from the cart.",
							"type": "boolean"
						},
						"product_ids": {
							"required": false,
							"description": "List of product IDs the coupon can be used on.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"excluded_product_ids": {
							"required": false,
							"description": "List of product IDs the coupon cannot be used on.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"usage_limit": {
							"required": false,
							"description": "How many times the coupon can be used in total.",
							"type": "integer"
						},
						"usage_limit_per_user": {
							"required": false,
							"description": "How many times the coupon can be used per customer.",
							"type": "integer"
						},
						"limit_usage_to_x_items": {
							"required": false,
							"description": "Max number of items in the cart the coupon can be applied to.",
							"type": "integer"
						},
						"free_shipping": {
							"required": false,
							"default": false,
							"description": "If true and if the free shipping method requires a coupon, this coupon will enable free shipping.",
							"type": "boolean"
						},
						"product_categories": {
							"required": false,
							"description": "List of category IDs the coupon applies to.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"excluded_product_categories": {
							"required": false,
							"description": "List of category IDs the coupon does not apply to.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"exclude_sale_items": {
							"required": false,
							"default": false,
							"description": "If true, this coupon will not be applied to items that have sale prices.",
							"type": "boolean"
						},
						"minimum_amount": {
							"required": false,
							"description": "Minimum order amount that needs to be in the cart before coupon applies.",
							"type": "string"
						},
						"maximum_amount": {
							"required": false,
							"description": "Maximum order amount allowed when using the coupon.",
							"type": "string"
						},
						"email_restrictions": {
							"required": false,
							"description": "List of email addresses that can use this coupon.",
							"type": "array",
							"items": {
								"type": "string"
							}
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/coupons"
			}
		},
		"/wc/v3/coupons/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"code": {
							"required": false,
							"description": "Coupon code.",
							"type": "string"
						},
						"amount": {
							"required": false,
							"description": "The amount of discount. Should always be numeric, even if setting a percentage.",
							"type": "string"
						},
						"discount_type": {
							"required": false,
							"enum": [
								"percent",
								"fixed_cart",
								"fixed_product"
							],
							"description": "Determines the type of discount that will be applied.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "Coupon description.",
							"type": "string"
						},
						"date_expires": {
							"required": false,
							"description": "The date the coupon expires, in the site's timezone.",
							"type": "string"
						},
						"date_expires_gmt": {
							"required": false,
							"description": "The date the coupon expires, as GMT.",
							"type": "string"
						},
						"individual_use": {
							"required": false,
							"description": "If true, the coupon can only be used individually. Other applied coupons will be removed from the cart.",
							"type": "boolean"
						},
						"product_ids": {
							"required": false,
							"description": "List of product IDs the coupon can be used on.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"excluded_product_ids": {
							"required": false,
							"description": "List of product IDs the coupon cannot be used on.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"usage_limit": {
							"required": false,
							"description": "How many times the coupon can be used in total.",
							"type": "integer"
						},
						"usage_limit_per_user": {
							"required": false,
							"description": "How many times the coupon can be used per customer.",
							"type": "integer"
						},
						"limit_usage_to_x_items": {
							"required": false,
							"description": "Max number of items in the cart the coupon can be applied to.",
							"type": "integer"
						},
						"free_shipping": {
							"required": false,
							"description": "If true and if the free shipping method requires a coupon, this coupon will enable free shipping.",
							"type": "boolean"
						},
						"product_categories": {
							"required": false,
							"description": "List of category IDs the coupon applies to.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"excluded_product_categories": {
							"required": false,
							"description": "List of category IDs the coupon does not apply to.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"exclude_sale_items": {
							"required": false,
							"description": "If true, this coupon will not be applied to items that have sale prices.",
							"type": "boolean"
						},
						"minimum_amount": {
							"required": false,
							"description": "Minimum order amount that needs to be in the cart before coupon applies.",
							"type": "string"
						},
						"maximum_amount": {
							"required": false,
							"description": "Maximum order amount allowed when using the coupon.",
							"type": "string"
						},
						"email_restrictions": {
							"required": false,
							"description": "List of email addresses that can use this coupon.",
							"type": "array",
							"items": {
								"type": "string"
							}
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Whether to bypass trash and force deletion.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/coupons/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"code": {
							"required": false,
							"description": "Coupon code.",
							"type": "string"
						},
						"amount": {
							"required": false,
							"description": "The amount of discount. Should always be numeric, even if setting a percentage.",
							"type": "string"
						},
						"discount_type": {
							"required": false,
							"enum": [
								"percent",
								"fixed_cart",
								"fixed_product"
							],
							"description": "Determines the type of discount that will be applied.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "Coupon description.",
							"type": "string"
						},
						"date_expires": {
							"required": false,
							"description": "The date the coupon expires, in the site's timezone.",
							"type": "string"
						},
						"date_expires_gmt": {
							"required": false,
							"description": "The date the coupon expires, as GMT.",
							"type": "string"
						},
						"individual_use": {
							"required": false,
							"description": "If true, the coupon can only be used individually. Other applied coupons will be removed from the cart.",
							"type": "boolean"
						},
						"product_ids": {
							"required": false,
							"description": "List of product IDs the coupon can be used on.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"excluded_product_ids": {
							"required": false,
							"description": "List of product IDs the coupon cannot be used on.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"usage_limit": {
							"required": false,
							"description": "How many times the coupon can be used in total.",
							"type": "integer"
						},
						"usage_limit_per_user": {
							"required": false,
							"description": "How many times the coupon can be used per customer.",
							"type": "integer"
						},
						"limit_usage_to_x_items": {
							"required": false,
							"description": "Max number of items in the cart the coupon can be applied to.",
							"type": "integer"
						},
						"free_shipping": {
							"required": false,
							"description": "If true and if the free shipping method requires a coupon, this coupon will enable free shipping.",
							"type": "boolean"
						},
						"product_categories": {
							"required": false,
							"description": "List of category IDs the coupon applies to.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"excluded_product_categories": {
							"required": false,
							"description": "List of category IDs the coupon does not apply to.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"exclude_sale_items": {
							"required": false,
							"description": "If true, this coupon will not be applied to items that have sale prices.",
							"type": "boolean"
						},
						"minimum_amount": {
							"required": false,
							"description": "Minimum order amount that needs to be in the cart before coupon applies.",
							"type": "string"
						},
						"maximum_amount": {
							"required": false,
							"description": "Maximum order amount allowed when using the coupon.",
							"type": "string"
						},
						"email_restrictions": {
							"required": false,
							"description": "List of email addresses that can use this coupon.",
							"type": "array",
							"items": {
								"type": "string"
							}
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/coupons/batch"
			}
		},
		"/wc/v3/customers/(?P<customer_id>[\\d]+)/downloads": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"customer_id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/customers": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "asc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "name",
							"enum": [
								"id",
								"include",
								"name",
								"registered_date"
							],
							"description": "Sort collection by object attribute.",
							"type": "string"
						},
						"email": {
							"required": false,
							"description": "Limit result set to resources with a specific email.",
							"type": "string"
						},
						"role": {
							"required": false,
							"default": "customer",
							"enum": [
								"all",
								"administrator",
								"editor",
								"author",
								"contributor",
								"subscriber",
								"customer",
								"shop_manager"
							],
							"description": "Limit result set to resources with a specific role.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"email": {
							"required": true,
							"description": "New user email address.",
							"type": "string"
						},
						"first_name": {
							"required": false,
							"description": "Customer first name.",
							"type": "string"
						},
						"last_name": {
							"required": false,
							"description": "Customer last name.",
							"type": "string"
						},
						"username": {
							"required": false,
							"description": "New user username.",
							"type": "string"
						},
						"password": {
							"required": false,
							"description": "New user password.",
							"type": "string"
						},
						"billing": {
							"required": false,
							"description": "List of billing address data.",
							"type": "object"
						},
						"shipping": {
							"required": false,
							"description": "List of shipping address data.",
							"type": "object"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/customers"
			}
		},
		"/wc/v3/customers/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"email": {
							"required": false,
							"description": "The email address for the customer.",
							"type": "string"
						},
						"first_name": {
							"required": false,
							"description": "Customer first name.",
							"type": "string"
						},
						"last_name": {
							"required": false,
							"description": "Customer last name.",
							"type": "string"
						},
						"username": {
							"required": false,
							"description": "Customer login name.",
							"type": "string"
						},
						"password": {
							"required": false,
							"description": "Customer password.",
							"type": "string"
						},
						"billing": {
							"required": false,
							"description": "List of billing address data.",
							"type": "object"
						},
						"shipping": {
							"required": false,
							"description": "List of shipping address data.",
							"type": "object"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						},
						"reassign": {
							"required": false,
							"default": 0,
							"description": "ID to reassign posts to.",
							"type": "integer"
						}
					}
				}
			]
		},
		"/wc/v3/customers/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"email": {
							"required": false,
							"description": "The email address for the customer.",
							"type": "string"
						},
						"first_name": {
							"required": false,
							"description": "Customer first name.",
							"type": "string"
						},
						"last_name": {
							"required": false,
							"description": "Customer last name.",
							"type": "string"
						},
						"username": {
							"required": false,
							"description": "Customer login name.",
							"type": "string"
						},
						"password": {
							"required": false,
							"description": "Customer password.",
							"type": "string"
						},
						"billing": {
							"required": false,
							"description": "List of billing address data.",
							"type": "object"
						},
						"shipping": {
							"required": false,
							"description": "List of shipping address data.",
							"type": "object"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/customers/batch"
			}
		},
		"/wc/v3/orders/(?P<order_id>[\\d]+)/notes": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"order_id": {
							"required": false,
							"description": "The order ID.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"type": {
							"required": false,
							"default": "any",
							"enum": [ "any", "customer", "internal" ],
							"description": "Limit result to customers or internal notes.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"order_id": {
							"required": false,
							"description": "The order ID.",
							"type": "integer"
						},
						"note": {
							"required": true,
							"description": "Order note content.",
							"type": "string"
						},
						"customer_note": {
							"required": false,
							"default": false,
							"description": "If true, the note will be shown to customers and they will be notified. If false, the note will be for admin reference only.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/orders/(?P<order_id>[\\d]+)/notes/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"order_id": {
							"required": false,
							"description": "The order ID.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"order_id": {
							"required": false,
							"description": "The order ID.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/orders/(?P<order_id>[\\d]+)/refunds": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"order_id": {
							"required": false,
							"description": "The order ID.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"after": {
							"required": false,
							"description": "Limit response to resources published after a given ISO8601 compliant date.",
							"type": "string"
						},
						"before": {
							"required": false,
							"description": "Limit response to resources published before a given ISO8601 compliant date.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "desc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "date",
							"enum": [
								"date",
								"id",
								"include",
								"title",
								"slug"
							],
							"description": "Sort collection by object attribute.",
							"type": "string"
						},
						"parent": {
							"required": false,
							"default": [],
							"description": "Limit result set to those of particular parent IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"parent_exclude": {
							"required": false,
							"default": [],
							"description": "Limit result set to all items except those of a particular parent ID.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"dp": {
							"required": false,
							"default": 2,
							"description": "Number of decimal points to use in each resource.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"order_id": {
							"required": false,
							"description": "The order ID.",
							"type": "integer"
						},
						"amount": {
							"required": false,
							"description": "Refund amount.",
							"type": "string"
						},
						"reason": {
							"required": false,
							"description": "Reason for refund.",
							"type": "string"
						},
						"refunded_by": {
							"required": false,
							"description": "User ID of user who created the refund.",
							"type": "integer"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"line_items": {
							"required": false,
							"description": "Line items data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "Product name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"product_id": {
										"description": "Product ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"variation_id": {
										"description": "Variation ID, if applicable.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"quantity": {
										"description": "Quantity ordered.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"tax_class": {
										"description": "Tax class of product.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"subtotal": {
										"description": "Line subtotal (before discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"subtotal_tax": {
										"description": "Line subtotal tax (before discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													]
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"subtotal": {
													"description": "Tax subtotal.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									},
									"sku": {
										"description": "Product SKU.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"price": {
										"description": "Product price.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"api_refund": {
							"required": false,
							"default": true,
							"description": "When true, the payment gateway API is used to generate the refund.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/orders/(?P<order_id>[\\d]+)/refunds/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"order_id": {
							"required": false,
							"description": "The order ID.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"order_id": {
							"required": false,
							"description": "The order ID.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": true,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/orders": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"after": {
							"required": false,
							"description": "Limit response to resources published after a given ISO8601 compliant date.",
							"type": "string"
						},
						"before": {
							"required": false,
							"description": "Limit response to resources published before a given ISO8601 compliant date.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "desc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "date",
							"enum": [
								"date",
								"id",
								"include",
								"title",
								"slug"
							],
							"description": "Sort collection by object attribute.",
							"type": "string"
						},
						"parent": {
							"required": false,
							"default": [],
							"description": "Limit result set to those of particular parent IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"parent_exclude": {
							"required": false,
							"default": [],
							"description": "Limit result set to all items except those of a particular parent ID.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"status": {
							"required": false,
							"default": "any",
							"enum": [
								"any",
								"pending",
								"processing",
								"on-hold",
								"completed",
								"cancelled",
								"refunded",
								"failed"
							],
							"description": "Limit result set to orders assigned a specific status.",
							"type": "string"
						},
						"customer": {
							"required": false,
							"description": "Limit result set to orders assigned a specific customer.",
							"type": "integer"
						},
						"product": {
							"required": false,
							"description": "Limit result set to orders assigned a specific product.",
							"type": "integer"
						},
						"dp": {
							"required": false,
							"default": 2,
							"description": "Number of decimal points to use in each resource.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"parent_id": {
							"required": false,
							"description": "Parent order ID.",
							"type": "integer"
						},
						"status": {
							"required": false,
							"default": "pending",
							"enum": [
								"pending",
								"processing",
								"on-hold",
								"completed",
								"cancelled",
								"refunded",
								"failed"
							],
							"description": "Order status.",
							"type": "string"
						},
						"currency": {
							"required": false,
							"default": "USD",
							"enum": [
								"AED",
								"AFN",
								"ALL",
								"AMD",
								"ANG",
								"AOA",
								"ARS",
								"AUD",
								"AWG",
								"AZN",
								"BAM",
								"BBD",
								"BDT",
								"BGN",
								"BHD",
								"BIF",
								"BMD",
								"BND",
								"BOB",
								"BRL",
								"BSD",
								"BTC",
								"BTN",
								"BWP",
								"BYR",
								"BZD",
								"CAD",
								"CDF",
								"CHF",
								"CLP",
								"CNY",
								"COP",
								"CRC",
								"CUC",
								"CUP",
								"CVE",
								"CZK",
								"DJF",
								"DKK",
								"DOP",
								"DZD",
								"EGP",
								"ERN",
								"ETB",
								"EUR",
								"FJD",
								"FKP",
								"GBP",
								"GEL",
								"GGP",
								"GHS",
								"GIP",
								"GMD",
								"GNF",
								"GTQ",
								"GYD",
								"HKD",
								"HNL",
								"HRK",
								"HTG",
								"HUF",
								"IDR",
								"ILS",
								"IMP",
								"INR",
								"IQD",
								"IRR",
								"IRT",
								"ISK",
								"JEP",
								"JMD",
								"JOD",
								"JPY",
								"KES",
								"KGS",
								"KHR",
								"KMF",
								"KPW",
								"KRW",
								"KWD",
								"KYD",
								"KZT",
								"LAK",
								"LBP",
								"LKR",
								"LRD",
								"LSL",
								"LYD",
								"MAD",
								"MDL",
								"MGA",
								"MKD",
								"MMK",
								"MNT",
								"MOP",
								"MRO",
								"MUR",
								"MVR",
								"MWK",
								"MXN",
								"MYR",
								"MZN",
								"NAD",
								"NGN",
								"NIO",
								"NOK",
								"NPR",
								"NZD",
								"OMR",
								"PAB",
								"PEN",
								"PGK",
								"PHP",
								"PKR",
								"PLN",
								"PRB",
								"PYG",
								"QAR",
								"RON",
								"RSD",
								"RUB",
								"RWF",
								"SAR",
								"SBD",
								"SCR",
								"SDG",
								"SEK",
								"SGD",
								"SHP",
								"SLL",
								"SOS",
								"SRD",
								"SSP",
								"STD",
								"SYP",
								"SZL",
								"THB",
								"TJS",
								"TMT",
								"TND",
								"TOP",
								"TRY",
								"TTD",
								"TWD",
								"TZS",
								"UAH",
								"UGX",
								"USD",
								"UYU",
								"UZS",
								"VEF",
								"VND",
								"VUV",
								"WST",
								"XAF",
								"XCD",
								"XOF",
								"XPF",
								"YER",
								"ZAR",
								"ZMW"
							],
							"description": "Currency the order was created with, in ISO format.",
							"type": "string"
						},
						"customer_id": {
							"required": false,
							"default": 0,
							"description": "User ID who owns the order. 0 for guests.",
							"type": "integer"
						},
						"customer_note": {
							"required": false,
							"description": "Note left by customer during checkout.",
							"type": "string"
						},
						"billing": {
							"required": false,
							"description": "Billing address.",
							"type": "object"
						},
						"shipping": {
							"required": false,
							"description": "Shipping address.",
							"type": "object"
						},
						"payment_method": {
							"required": false,
							"description": "Payment method ID.",
							"type": "string"
						},
						"payment_method_title": {
							"required": false,
							"description": "Payment method title.",
							"type": "string"
						},
						"transaction_id": {
							"required": false,
							"description": "Unique transaction ID.",
							"type": "string"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"line_items": {
							"required": false,
							"description": "Line items data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "Product name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"product_id": {
										"description": "Product ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"variation_id": {
										"description": "Variation ID, if applicable.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"quantity": {
										"description": "Quantity ordered.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"tax_class": {
										"description": "Tax class of product.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"subtotal": {
										"description": "Line subtotal (before discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"subtotal_tax": {
										"description": "Line subtotal tax (before discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													]
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"subtotal": {
													"description": "Tax subtotal.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									},
									"sku": {
										"description": "Product SKU.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"price": {
										"description": "Product price.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"shipping_lines": {
							"required": false,
							"description": "Shipping lines data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"method_title": {
										"description": "Shipping method name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"method_id": {
										"description": "Shipping method ID.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"fee_lines": {
							"required": false,
							"description": "Fee lines data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "Fee name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"tax_class": {
										"description": "Tax class of fee.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"tax_status": {
										"description": "Tax status of fee.",
										"type": "string",
										"context": [ "view", "edit" ],
										"enum": [ "taxable", "none" ]
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"subtotal": {
													"description": "Tax subtotal.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"coupon_lines": {
							"required": false,
							"description": "Coupons line data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"code": {
										"description": "Coupon code.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"discount": {
										"description": "Discount total.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"discount_tax": {
										"description": "Discount total tax.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"set_paid": {
							"required": false,
							"default": false,
							"description": "Define if the order is paid. It will set the status to processing and reduce stock items.",
							"type": "boolean"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/orders"
			}
		},
		"/wc/v3/orders/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"parent_id": {
							"required": false,
							"description": "Parent order ID.",
							"type": "integer"
						},
						"status": {
							"required": false,
							"enum": [
								"pending",
								"processing",
								"on-hold",
								"completed",
								"cancelled",
								"refunded",
								"failed"
							],
							"description": "Order status.",
							"type": "string"
						},
						"currency": {
							"required": false,
							"enum": [
								"AED",
								"AFN",
								"ALL",
								"AMD",
								"ANG",
								"AOA",
								"ARS",
								"AUD",
								"AWG",
								"AZN",
								"BAM",
								"BBD",
								"BDT",
								"BGN",
								"BHD",
								"BIF",
								"BMD",
								"BND",
								"BOB",
								"BRL",
								"BSD",
								"BTC",
								"BTN",
								"BWP",
								"BYR",
								"BZD",
								"CAD",
								"CDF",
								"CHF",
								"CLP",
								"CNY",
								"COP",
								"CRC",
								"CUC",
								"CUP",
								"CVE",
								"CZK",
								"DJF",
								"DKK",
								"DOP",
								"DZD",
								"EGP",
								"ERN",
								"ETB",
								"EUR",
								"FJD",
								"FKP",
								"GBP",
								"GEL",
								"GGP",
								"GHS",
								"GIP",
								"GMD",
								"GNF",
								"GTQ",
								"GYD",
								"HKD",
								"HNL",
								"HRK",
								"HTG",
								"HUF",
								"IDR",
								"ILS",
								"IMP",
								"INR",
								"IQD",
								"IRR",
								"IRT",
								"ISK",
								"JEP",
								"JMD",
								"JOD",
								"JPY",
								"KES",
								"KGS",
								"KHR",
								"KMF",
								"KPW",
								"KRW",
								"KWD",
								"KYD",
								"KZT",
								"LAK",
								"LBP",
								"LKR",
								"LRD",
								"LSL",
								"LYD",
								"MAD",
								"MDL",
								"MGA",
								"MKD",
								"MMK",
								"MNT",
								"MOP",
								"MRO",
								"MUR",
								"MVR",
								"MWK",
								"MXN",
								"MYR",
								"MZN",
								"NAD",
								"NGN",
								"NIO",
								"NOK",
								"NPR",
								"NZD",
								"OMR",
								"PAB",
								"PEN",
								"PGK",
								"PHP",
								"PKR",
								"PLN",
								"PRB",
								"PYG",
								"QAR",
								"RON",
								"RSD",
								"RUB",
								"RWF",
								"SAR",
								"SBD",
								"SCR",
								"SDG",
								"SEK",
								"SGD",
								"SHP",
								"SLL",
								"SOS",
								"SRD",
								"SSP",
								"STD",
								"SYP",
								"SZL",
								"THB",
								"TJS",
								"TMT",
								"TND",
								"TOP",
								"TRY",
								"TTD",
								"TWD",
								"TZS",
								"UAH",
								"UGX",
								"USD",
								"UYU",
								"UZS",
								"VEF",
								"VND",
								"VUV",
								"WST",
								"XAF",
								"XCD",
								"XOF",
								"XPF",
								"YER",
								"ZAR",
								"ZMW"
							],
							"description": "Currency the order was created with, in ISO format.",
							"type": "string"
						},
						"customer_id": {
							"required": false,
							"description": "User ID who owns the order. 0 for guests.",
							"type": "integer"
						},
						"customer_note": {
							"required": false,
							"description": "Note left by customer during checkout.",
							"type": "string"
						},
						"billing": {
							"required": false,
							"description": "Billing address.",
							"type": "object"
						},
						"shipping": {
							"required": false,
							"description": "Shipping address.",
							"type": "object"
						},
						"payment_method": {
							"required": false,
							"description": "Payment method ID.",
							"type": "string"
						},
						"payment_method_title": {
							"required": false,
							"description": "Payment method title.",
							"type": "string"
						},
						"transaction_id": {
							"required": false,
							"description": "Unique transaction ID.",
							"type": "string"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"line_items": {
							"required": false,
							"description": "Line items data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "Product name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"product_id": {
										"description": "Product ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"variation_id": {
										"description": "Variation ID, if applicable.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"quantity": {
										"description": "Quantity ordered.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"tax_class": {
										"description": "Tax class of product.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"subtotal": {
										"description": "Line subtotal (before discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"subtotal_tax": {
										"description": "Line subtotal tax (before discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													]
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"subtotal": {
													"description": "Tax subtotal.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									},
									"sku": {
										"description": "Product SKU.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"price": {
										"description": "Product price.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"shipping_lines": {
							"required": false,
							"description": "Shipping lines data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"method_title": {
										"description": "Shipping method name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"method_id": {
										"description": "Shipping method ID.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"fee_lines": {
							"required": false,
							"description": "Fee lines data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "Fee name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"tax_class": {
										"description": "Tax class of fee.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"tax_status": {
										"description": "Tax status of fee.",
										"type": "string",
										"context": [ "view", "edit" ],
										"enum": [ "taxable", "none" ]
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"subtotal": {
													"description": "Tax subtotal.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"coupon_lines": {
							"required": false,
							"description": "Coupons line data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"code": {
										"description": "Coupon code.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"discount": {
										"description": "Discount total.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"discount_tax": {
										"description": "Discount total tax.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"set_paid": {
							"required": false,
							"description": "Define if the order is paid. It will set the status to processing and reduce stock items.",
							"type": "boolean"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Whether to bypass trash and force deletion.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/orders/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"parent_id": {
							"required": false,
							"description": "Parent order ID.",
							"type": "integer"
						},
						"status": {
							"required": false,
							"enum": [
								"pending",
								"processing",
								"on-hold",
								"completed",
								"cancelled",
								"refunded",
								"failed"
							],
							"description": "Order status.",
							"type": "string"
						},
						"currency": {
							"required": false,
							"enum": [
								"AED",
								"AFN",
								"ALL",
								"AMD",
								"ANG",
								"AOA",
								"ARS",
								"AUD",
								"AWG",
								"AZN",
								"BAM",
								"BBD",
								"BDT",
								"BGN",
								"BHD",
								"BIF",
								"BMD",
								"BND",
								"BOB",
								"BRL",
								"BSD",
								"BTC",
								"BTN",
								"BWP",
								"BYR",
								"BZD",
								"CAD",
								"CDF",
								"CHF",
								"CLP",
								"CNY",
								"COP",
								"CRC",
								"CUC",
								"CUP",
								"CVE",
								"CZK",
								"DJF",
								"DKK",
								"DOP",
								"DZD",
								"EGP",
								"ERN",
								"ETB",
								"EUR",
								"FJD",
								"FKP",
								"GBP",
								"GEL",
								"GGP",
								"GHS",
								"GIP",
								"GMD",
								"GNF",
								"GTQ",
								"GYD",
								"HKD",
								"HNL",
								"HRK",
								"HTG",
								"HUF",
								"IDR",
								"ILS",
								"IMP",
								"INR",
								"IQD",
								"IRR",
								"IRT",
								"ISK",
								"JEP",
								"JMD",
								"JOD",
								"JPY",
								"KES",
								"KGS",
								"KHR",
								"KMF",
								"KPW",
								"KRW",
								"KWD",
								"KYD",
								"KZT",
								"LAK",
								"LBP",
								"LKR",
								"LRD",
								"LSL",
								"LYD",
								"MAD",
								"MDL",
								"MGA",
								"MKD",
								"MMK",
								"MNT",
								"MOP",
								"MRO",
								"MUR",
								"MVR",
								"MWK",
								"MXN",
								"MYR",
								"MZN",
								"NAD",
								"NGN",
								"NIO",
								"NOK",
								"NPR",
								"NZD",
								"OMR",
								"PAB",
								"PEN",
								"PGK",
								"PHP",
								"PKR",
								"PLN",
								"PRB",
								"PYG",
								"QAR",
								"RON",
								"RSD",
								"RUB",
								"RWF",
								"SAR",
								"SBD",
								"SCR",
								"SDG",
								"SEK",
								"SGD",
								"SHP",
								"SLL",
								"SOS",
								"SRD",
								"SSP",
								"STD",
								"SYP",
								"SZL",
								"THB",
								"TJS",
								"TMT",
								"TND",
								"TOP",
								"TRY",
								"TTD",
								"TWD",
								"TZS",
								"UAH",
								"UGX",
								"USD",
								"UYU",
								"UZS",
								"VEF",
								"VND",
								"VUV",
								"WST",
								"XAF",
								"XCD",
								"XOF",
								"XPF",
								"YER",
								"ZAR",
								"ZMW"
							],
							"description": "Currency the order was created with, in ISO format.",
							"type": "string"
						},
						"customer_id": {
							"required": false,
							"description": "User ID who owns the order. 0 for guests.",
							"type": "integer"
						},
						"customer_note": {
							"required": false,
							"description": "Note left by customer during checkout.",
							"type": "string"
						},
						"billing": {
							"required": false,
							"description": "Billing address.",
							"type": "object"
						},
						"shipping": {
							"required": false,
							"description": "Shipping address.",
							"type": "object"
						},
						"payment_method": {
							"required": false,
							"description": "Payment method ID.",
							"type": "string"
						},
						"payment_method_title": {
							"required": false,
							"description": "Payment method title.",
							"type": "string"
						},
						"transaction_id": {
							"required": false,
							"description": "Unique transaction ID.",
							"type": "string"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"line_items": {
							"required": false,
							"description": "Line items data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "Product name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"product_id": {
										"description": "Product ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"variation_id": {
										"description": "Variation ID, if applicable.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"quantity": {
										"description": "Quantity ordered.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"tax_class": {
										"description": "Tax class of product.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"subtotal": {
										"description": "Line subtotal (before discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"subtotal_tax": {
										"description": "Line subtotal tax (before discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													]
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"subtotal": {
													"description": "Tax subtotal.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									},
									"sku": {
										"description": "Product SKU.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"price": {
										"description": "Product price.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"shipping_lines": {
							"required": false,
							"description": "Shipping lines data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"method_title": {
										"description": "Shipping method name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"method_id": {
										"description": "Shipping method ID.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"fee_lines": {
							"required": false,
							"description": "Fee lines data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "Fee name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"tax_class": {
										"description": "Tax class of fee.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"tax_status": {
										"description": "Tax status of fee.",
										"type": "string",
										"context": [ "view", "edit" ],
										"enum": [ "taxable", "none" ]
									},
									"total": {
										"description": "Line total (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"total_tax": {
										"description": "Line total tax (after discounts).",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"taxes": {
										"description": "Line taxes.",
										"type": "array",
										"context": [ "view", "edit" ],
										"readonly": true,
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Tax rate ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"total": {
													"description": "Tax total.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"subtotal": {
													"description": "Tax subtotal.",
													"type": "string",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												}
											}
										}
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"coupon_lines": {
							"required": false,
							"description": "Coupons line data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Item ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"code": {
										"description": "Coupon code.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"discount": {
										"description": "Discount total.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"discount_tax": {
										"description": "Discount total tax.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"meta_data": {
										"description": "Meta data.",
										"type": "array",
										"context": [ "view", "edit" ],
										"items": {
											"type": "object",
											"properties": {
												"id": {
													"description": "Meta ID.",
													"type": "integer",
													"context": [
														"view",
														"edit"
													],
													"readonly": true
												},
												"key": {
													"description": "Meta key.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												},
												"value": {
													"description": "Meta value.",
													"type": "string",
													"context": [
														"view",
														"edit"
													]
												}
											}
										}
									}
								}
							}
						},
						"set_paid": {
							"required": false,
							"description": "Define if the order is paid. It will set the status to processing and reduce stock items.",
							"type": "boolean"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/orders/batch"
			}
		},
		"/wc/v3/products/attributes/(?P<attribute_id>[\\d]+)/terms": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"attribute_id": {
							"required": false,
							"description": "Unique identifier for the attribute of the terms.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"order": {
							"required": false,
							"default": "asc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "name",
							"enum": [
								"id",
								"include",
								"name",
								"slug",
								"term_group",
								"description",
								"count"
							],
							"description": "Sort collection by resource attribute.",
							"type": "string"
						},
						"hide_empty": {
							"required": false,
							"default": false,
							"description": "Whether to hide resources not assigned to any products.",
							"type": "boolean"
						},
						"parent": {
							"required": false,
							"description": "Limit result set to resources assigned to a specific parent.",
							"type": "integer"
						},
						"product": {
							"required": false,
							"description": "Limit result set to resources assigned to a specific product.",
							"type": "integer"
						},
						"slug": {
							"required": false,
							"description": "Limit result set to resources with a specific slug.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"attribute_id": {
							"required": false,
							"description": "Unique identifier for the attribute of the terms.",
							"type": "integer"
						},
						"name": {
							"required": true,
							"description": "Name for the resource.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort the resource.",
							"type": "integer"
						}
					}
				}
			]
		},
		"/wc/v3/products/attributes/(?P<attribute_id>[\\d]+)/terms/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"attribute_id": {
							"required": false,
							"description": "Unique identifier for the attribute of the terms.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"attribute_id": {
							"required": false,
							"description": "Unique identifier for the attribute of the terms.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Term name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort the resource.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"attribute_id": {
							"required": false,
							"description": "Unique identifier for the attribute of the terms.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/products/attributes/(?P<attribute_id>[\\d]+)/terms/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"attribute_id": {
							"required": false,
							"description": "Unique identifier for the attribute of the terms.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Term name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort the resource.",
							"type": "integer"
						}
					}
				}
			]
		},
		"/wc/v3/products/attributes": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"name": {
							"required": true,
							"description": "Name for the resource.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"type": {
							"required": false,
							"default": "select",
							"enum": [ "select", "text" ],
							"description": "Type of attribute.",
							"type": "string"
						},
						"order_by": {
							"required": false,
							"default": "menu_order",
							"enum": [ "menu_order", "name", "name_num", "id" ],
							"description": "Default sort order.",
							"type": "string"
						},
						"has_archives": {
							"required": false,
							"default": false,
							"description": "Enable/Disable attribute archives.",
							"type": "boolean"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/attributes"
			}
		},
		"/wc/v3/products/attributes/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Attribute name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"type": {
							"required": false,
							"enum": [ "select", "text" ],
							"description": "Type of attribute.",
							"type": "string"
						},
						"order_by": {
							"required": false,
							"enum": [ "menu_order", "name", "name_num", "id" ],
							"description": "Default sort order.",
							"type": "string"
						},
						"has_archives": {
							"required": false,
							"description": "Enable/Disable attribute archives.",
							"type": "boolean"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": true,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/products/attributes/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"name": {
							"required": false,
							"description": "Attribute name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"type": {
							"required": false,
							"enum": [ "select", "text" ],
							"description": "Type of attribute.",
							"type": "string"
						},
						"order_by": {
							"required": false,
							"enum": [ "menu_order", "name", "name_num", "id" ],
							"description": "Default sort order.",
							"type": "string"
						},
						"has_archives": {
							"required": false,
							"description": "Enable/Disable attribute archives.",
							"type": "boolean"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/attributes/batch"
			}
		},
		"/wc/v3/products/categories": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"order": {
							"required": false,
							"default": "asc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "name",
							"enum": [
								"id",
								"include",
								"name",
								"slug",
								"term_group",
								"description",
								"count"
							],
							"description": "Sort collection by resource attribute.",
							"type": "string"
						},
						"hide_empty": {
							"required": false,
							"default": false,
							"description": "Whether to hide resources not assigned to any products.",
							"type": "boolean"
						},
						"parent": {
							"required": false,
							"description": "Limit result set to resources assigned to a specific parent.",
							"type": "integer"
						},
						"product": {
							"required": false,
							"description": "Limit result set to resources assigned to a specific product.",
							"type": "integer"
						},
						"slug": {
							"required": false,
							"description": "Limit result set to resources with a specific slug.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"name": {
							"required": true,
							"description": "Name for the resource.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"parent": {
							"required": false,
							"description": "The ID for the parent of the resource.",
							"type": "integer"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						},
						"display": {
							"required": false,
							"default": "default",
							"enum": [
								"default",
								"products",
								"subcategories",
								"both"
							],
							"description": "Category archive display type.",
							"type": "string"
						},
						"image": {
							"required": false,
							"description": "Image data.",
							"type": "object"
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort the resource.",
							"type": "integer"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/categories"
			}
		},
		"/wc/v3/products/categories/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Category name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"parent": {
							"required": false,
							"description": "The ID for the parent of the resource.",
							"type": "integer"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						},
						"display": {
							"required": false,
							"enum": [
								"default",
								"products",
								"subcategories",
								"both"
							],
							"description": "Category archive display type.",
							"type": "string"
						},
						"image": {
							"required": false,
							"description": "Image data.",
							"type": "object"
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort the resource.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/products/categories/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"name": {
							"required": false,
							"description": "Category name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"parent": {
							"required": false,
							"description": "The ID for the parent of the resource.",
							"type": "integer"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						},
						"display": {
							"required": false,
							"enum": [
								"default",
								"products",
								"subcategories",
								"both"
							],
							"description": "Category archive display type.",
							"type": "string"
						},
						"image": {
							"required": false,
							"description": "Image data.",
							"type": "object"
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort the resource.",
							"type": "integer"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/categories/batch"
			}
		},
		"/wc/v3/products/(?P<product_id>[\\d]+)/reviews": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the variation.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the variation.",
							"type": "integer"
						},
						"review": {
							"required": true,
							"description": "Review content.",
							"type": "string"
						},
						"date_created": {
							"required": false,
							"description": "The date the review was created, in the site's timezone.",
							"type": "date-time"
						},
						"date_created_gmt": {
							"required": false,
							"description": "The date the review was created, as GMT.",
							"type": "date-time"
						},
						"rating": {
							"required": false,
							"description": "Review rating (0 to 5).",
							"type": "integer"
						},
						"name": {
							"required": true,
							"description": "Name of the reviewer.",
							"type": "string"
						},
						"email": {
							"required": true,
							"description": "Email of the reviewer.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/products/(?P<product_id>[\\d]+)/reviews/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"review": {
							"required": false,
							"description": "The content of the review.",
							"type": "string"
						},
						"date_created": {
							"required": false,
							"description": "The date the review was created, in the site's timezone.",
							"type": "date-time"
						},
						"date_created_gmt": {
							"required": false,
							"description": "The date the review was created, as GMT.",
							"type": "date-time"
						},
						"rating": {
							"required": false,
							"description": "Review rating (0 to 5).",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Reviewer name.",
							"type": "string"
						},
						"email": {
							"required": false,
							"description": "Reviewer email.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Whether to bypass trash and force deletion.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/products/(?P<product_id>[\\d]+)/reviews/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"review": {
							"required": false,
							"description": "The content of the review.",
							"type": "string"
						},
						"date_created": {
							"required": false,
							"description": "The date the review was created, in the site's timezone.",
							"type": "date-time"
						},
						"date_created_gmt": {
							"required": false,
							"description": "The date the review was created, as GMT.",
							"type": "date-time"
						},
						"rating": {
							"required": false,
							"description": "Review rating (0 to 5).",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Reviewer name.",
							"type": "string"
						},
						"email": {
							"required": false,
							"description": "Reviewer email.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/products/shipping_classes": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "asc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "name",
							"enum": [
								"id",
								"include",
								"name",
								"slug",
								"term_group",
								"description",
								"count"
							],
							"description": "Sort collection by resource attribute.",
							"type": "string"
						},
						"hide_empty": {
							"required": false,
							"default": false,
							"description": "Whether to hide resources not assigned to any products.",
							"type": "boolean"
						},
						"product": {
							"required": false,
							"description": "Limit result set to resources assigned to a specific product.",
							"type": "integer"
						},
						"slug": {
							"required": false,
							"description": "Limit result set to resources with a specific slug.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"name": {
							"required": true,
							"description": "Name for the resource.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/shipping_classes"
			}
		},
		"/wc/v3/products/shipping_classes/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Shipping class name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/products/shipping_classes/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"name": {
							"required": false,
							"description": "Shipping class name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/shipping_classes/batch"
			}
		},
		"/wc/v3/products/tags": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "asc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "name",
							"enum": [
								"id",
								"include",
								"name",
								"slug",
								"term_group",
								"description",
								"count"
							],
							"description": "Sort collection by resource attribute.",
							"type": "string"
						},
						"hide_empty": {
							"required": false,
							"default": false,
							"description": "Whether to hide resources not assigned to any products.",
							"type": "boolean"
						},
						"product": {
							"required": false,
							"description": "Limit result set to resources assigned to a specific product.",
							"type": "integer"
						},
						"slug": {
							"required": false,
							"description": "Limit result set to resources with a specific slug.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"name": {
							"required": true,
							"description": "Name for the resource.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/tags"
			}
		},
		"/wc/v3/products/tags/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Tag name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/products/tags/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"name": {
							"required": false,
							"description": "Tag name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "An alphanumeric identifier for the resource unique to its type.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "HTML description of the resource.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/tags/batch"
			}
		},
		"/wc/v3/products": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"after": {
							"required": false,
							"description": "Limit response to resources published after a given ISO8601 compliant date.",
							"type": "string"
						},
						"before": {
							"required": false,
							"description": "Limit response to resources published before a given ISO8601 compliant date.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "desc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "date",
							"enum": [
								"date",
								"id",
								"include",
								"title",
								"slug",
								"price",
								"popularity",
								"rating"
							],
							"description": "Sort collection by object attribute.",
							"type": "string"
						},
						"parent": {
							"required": false,
							"default": [],
							"description": "Limit result set to those of particular parent IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"parent_exclude": {
							"required": false,
							"default": [],
							"description": "Limit result set to all items except those of a particular parent ID.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"slug": {
							"required": false,
							"description": "Limit result set to products with a specific slug.",
							"type": "string"
						},
						"status": {
							"required": false,
							"default": "any",
							"enum": [
								"any",
								"draft",
								"pending",
								"private",
								"publish"
							],
							"description": "Limit result set to products assigned a specific status.",
							"type": "string"
						},
						"type": {
							"required": false,
							"enum": [
								"simple",
								"grouped",
								"external",
								"variable"
							],
							"description": "Limit result set to products assigned a specific type.",
							"type": "string"
						},
						"sku": {
							"required": false,
							"description": "Limit result set to products with a specific SKU.",
							"type": "string"
						},
						"featured": {
							"required": false,
							"description": "Limit result set to featured products.",
							"type": "boolean"
						},
						"category": {
							"required": false,
							"description": "Limit result set to products assigned a specific category ID.",
							"type": "string"
						},
						"tag": {
							"required": false,
							"description": "Limit result set to products assigned a specific tag ID.",
							"type": "string"
						},
						"shipping_class": {
							"required": false,
							"description": "Limit result set to products assigned a specific shipping class ID.",
							"type": "string"
						},
						"attribute": {
							"required": false,
							"description": "Limit result set to products with a specific attribute.",
							"type": "string"
						},
						"attribute_term": {
							"required": false,
							"description": "Limit result set to products with a specific attribute term ID (required an assigned attribute).",
							"type": "string"
						},
						"tax_class": {
							"required": false,
							"enum": [ "standard", "reduced-rate", "zero-rate" ],
							"description": "Limit result set to products with a specific tax class.",
							"type": "string"
						},
						"in_stock": {
							"required": false,
							"description": "Limit result set to products in stock or out of stock.",
							"type": "boolean"
						},
						"on_sale": {
							"required": false,
							"description": "Limit result set to products on sale.",
							"type": "boolean"
						},
						"min_price": {
							"required": false,
							"description": "Limit result set to products based on a minimum price.",
							"type": "string"
						},
						"max_price": {
							"required": false,
							"description": "Limit result set to products based on a maximum price.",
							"type": "string"
						},
						"image_size": {
							"required": false,
							"default": "full",
							"description": "Use a specific registered image size for the returned image src values. Falls back to the full size if the requested size is not registered.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"name": {
							"required": false,
							"description": "Product name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "Product slug.",
							"type": "string"
						},
						"type": {
							"required": false,
							"default": "simple",
							"enum": [
								"simple",
								"grouped",
								"external",
								"variable"
							],
							"description": "Product type.",
							"type": "string"
						},
						"status": {
							"required": false,
							"default": "publish",
							"enum": [
								"draft",
								"pending",
								"private",
								"publish"
							],
							"description": "Product status (post status).",
							"type": "string"
						},
						"featured": {
							"required": false,
							"default": false,
							"description": "Featured product.",
							"type": "boolean"
						},
						"catalog_visibility": {
							"required": false,
							"default": "visible",
							"enum": [
								"visible",
								"catalog",
								"search",
								"hidden"
							],
							"description": "Catalog visibility.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "Product description.",
							"type": "string"
						},
						"short_description": {
							"required": false,
							"description": "Product short description.",
							"type": "string"
						},
						"sku": {
							"required": false,
							"description": "Unique identifier.",
							"type": "string"
						},
						"regular_price": {
							"required": false,
							"description": "Product regular price.",
							"type": "string"
						},
						"sale_price": {
							"required": false,
							"description": "Product sale price.",
							"type": "string"
						},
						"date_on_sale_from": {
							"required": false,
							"description": "Start date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_from_gmt": {
							"required": false,
							"description": "Start date of sale price, as GMT.",
							"type": "date-time"
						},
						"date_on_sale_to": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_to_gmt": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"virtual": {
							"required": false,
							"default": false,
							"description": "If the product is virtual.",
							"type": "boolean"
						},
						"downloadable": {
							"required": false,
							"default": false,
							"description": "If the product is downloadable.",
							"type": "boolean"
						},
						"downloads": {
							"required": false,
							"description": "List of downloadable files.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "File ID.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "File name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"file": {
										"description": "File URL.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"download_limit": {
							"required": false,
							"default": -1,
							"description": "Number of times downloadable files can be downloaded after purchase.",
							"type": "integer"
						},
						"download_expiry": {
							"required": false,
							"default": -1,
							"description": "Number of days until access to downloadable files expires.",
							"type": "integer"
						},
						"external_url": {
							"required": false,
							"description": "Product external URL. Only for external products.",
							"type": "string"
						},
						"button_text": {
							"required": false,
							"description": "Product external button text. Only for external products.",
							"type": "string"
						},
						"tax_status": {
							"required": false,
							"default": "taxable",
							"enum": [ "taxable", "shipping", "none" ],
							"description": "Tax status.",
							"type": "string"
						},
						"tax_class": {
							"required": false,
							"description": "Tax class.",
							"type": "string"
						},
						"manage_stock": {
							"required": false,
							"default": false,
							"description": "Stock management at product level.",
							"type": "boolean"
						},
						"stock_quantity": {
							"required": false,
							"description": "Stock quantity.",
							"type": "integer"
						},
						"in_stock": {
							"required": false,
							"default": true,
							"description": "Controls whether or not the product is listed as \"in stock\" or \"out of stock\" on the frontend.",
							"type": "boolean"
						},
						"backorders": {
							"required": false,
							"default": "no",
							"enum": [ "no", "notify", "yes" ],
							"description": "If managing stock, this controls if backorders are allowed.",
							"type": "string"
						},
						"sold_individually": {
							"required": false,
							"default": false,
							"description": "Allow one item to be bought in a single order.",
							"type": "boolean"
						},
						"weight": {
							"required": false,
							"description": "Product weight (kg).",
							"type": "string"
						},
						"dimensions": {
							"required": false,
							"description": "Product dimensions.",
							"type": "object"
						},
						"shipping_class": {
							"required": false,
							"description": "Shipping class slug.",
							"type": "string"
						},
						"reviews_allowed": {
							"required": false,
							"default": true,
							"description": "Allow reviews.",
							"type": "boolean"
						},
						"upsell_ids": {
							"required": false,
							"description": "List of up-sell products IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"cross_sell_ids": {
							"required": false,
							"description": "List of cross-sell products IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"parent_id": {
							"required": false,
							"description": "Product parent ID.",
							"type": "integer"
						},
						"purchase_note": {
							"required": false,
							"description": "Optional note to send the customer after purchase.",
							"type": "string"
						},
						"categories": {
							"required": false,
							"description": "List of categories.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Category ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Category name.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"slug": {
										"description": "Category slug.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"tags": {
							"required": false,
							"description": "List of tags.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Tag ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Tag name.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"slug": {
										"description": "Tag slug.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"images": {
							"required": false,
							"description": "List of images.",
							"type": "object",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Image ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"date_created": {
										"description": "The date the image was created, in the site's timezone.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_created_gmt": {
										"description": "The date the image was created, as GMT.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_modified": {
										"description": "The date the image was last modified, in the site's timezone.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_modified_gmt": {
										"description": "The date the image was last modified, as GMT.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"src": {
										"description": "Image URL.",
										"type": "string",
										"format": "uri",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Image name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"alt": {
										"description": "Image alternative text.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"position": {
										"description": "Image position. 0 means that the image is featured.",
										"type": "integer",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"attributes": {
							"required": false,
							"description": "List of attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"position": {
										"description": "Attribute position.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"visible": {
										"description": "Define if the attribute is visible on the \"Additional information\" tab in the product's page.",
										"type": "boolean",
										"default": false,
										"context": [ "view", "edit" ]
									},
									"variation": {
										"description": "Define if the attribute can be used as variation.",
										"type": "boolean",
										"default": false,
										"context": [ "view", "edit" ]
									},
									"options": {
										"description": "List of available term names of the attribute.",
										"type": "array",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"default_attributes": {
							"required": false,
							"description": "Defaults variation attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"option": {
										"description": "Selected attribute term name.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort products.",
							"type": "integer"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products"
			}
		},
		"/wc/v3/products/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"image_size": {
							"required": false,
							"default": "full",
							"description": "Use a specific registered image size for the returned image src values. Falls back to the full size if the requested size is not registered.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Product name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "Product slug.",
							"type": "string"
						},
						"type": {
							"required": false,
							"enum": [
								"simple",
								"grouped",
								"external",
								"variable"
							],
							"description": "Product type.",
							"type": "string"
						},
						"status": {
							"required": false,
							"enum": [
								"draft",
								"pending",
								"private",
								"publish"
							],
							"description": "Product status (post status).",
							"type": "string"
						},
						"featured": {
							"required": false,
							"description": "Featured product.",
							"type": "boolean"
						},
						"catalog_visibility": {
							"required": false,
							"enum": [
								"visible",
								"catalog",
								"search",
								"hidden"
							],
							"description": "Catalog visibility.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "Product description.",
							"type": "string"
						},
						"short_description": {
							"required": false,
							"description": "Product short description.",
							"type": "string"
						},
						"sku": {
							"required": false,
							"description": "Unique identifier.",
							"type": "string"
						},
						"regular_price": {
							"required": false,
							"description": "Product regular price.",
							"type": "string"
						},
						"sale_price": {
							"required": false,
							"description": "Product sale price.",
							"type": "string"
						},
						"date_on_sale_from": {
							"required": false,
							"description": "Start date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_from_gmt": {
							"required": false,
							"description": "Start date of sale price, as GMT.",
							"type": "date-time"
						},
						"date_on_sale_to": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_to_gmt": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"virtual": {
							"required": false,
							"description": "If the product is virtual.",
							"type": "boolean"
						},
						"downloadable": {
							"required": false,
							"description": "If the product is downloadable.",
							"type": "boolean"
						},
						"downloads": {
							"required": false,
							"description": "List of downloadable files.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "File ID.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "File name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"file": {
										"description": "File URL.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"download_limit": {
							"required": false,
							"description": "Number of times downloadable files can be downloaded after purchase.",
							"type": "integer"
						},
						"download_expiry": {
							"required": false,
							"description": "Number of days until access to downloadable files expires.",
							"type": "integer"
						},
						"external_url": {
							"required": false,
							"description": "Product external URL. Only for external products.",
							"type": "string"
						},
						"button_text": {
							"required": false,
							"description": "Product external button text. Only for external products.",
							"type": "string"
						},
						"tax_status": {
							"required": false,
							"enum": [ "taxable", "shipping", "none" ],
							"description": "Tax status.",
							"type": "string"
						},
						"tax_class": {
							"required": false,
							"description": "Tax class.",
							"type": "string"
						},
						"manage_stock": {
							"required": false,
							"description": "Stock management at product level.",
							"type": "boolean"
						},
						"stock_quantity": {
							"required": false,
							"description": "Stock quantity.",
							"type": "integer"
						},
						"in_stock": {
							"required": false,
							"description": "Controls whether or not the product is listed as \"in stock\" or \"out of stock\" on the frontend.",
							"type": "boolean"
						},
						"backorders": {
							"required": false,
							"enum": [ "no", "notify", "yes" ],
							"description": "If managing stock, this controls if backorders are allowed.",
							"type": "string"
						},
						"sold_individually": {
							"required": false,
							"description": "Allow one item to be bought in a single order.",
							"type": "boolean"
						},
						"weight": {
							"required": false,
							"description": "Product weight (kg).",
							"type": "string"
						},
						"dimensions": {
							"required": false,
							"description": "Product dimensions.",
							"type": "object"
						},
						"shipping_class": {
							"required": false,
							"description": "Shipping class slug.",
							"type": "string"
						},
						"reviews_allowed": {
							"required": false,
							"description": "Allow reviews.",
							"type": "boolean"
						},
						"upsell_ids": {
							"required": false,
							"description": "List of up-sell products IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"cross_sell_ids": {
							"required": false,
							"description": "List of cross-sell products IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"parent_id": {
							"required": false,
							"description": "Product parent ID.",
							"type": "integer"
						},
						"purchase_note": {
							"required": false,
							"description": "Optional note to send the customer after purchase.",
							"type": "string"
						},
						"categories": {
							"required": false,
							"description": "List of categories.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Category ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Category name.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"slug": {
										"description": "Category slug.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"tags": {
							"required": false,
							"description": "List of tags.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Tag ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Tag name.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"slug": {
										"description": "Tag slug.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"images": {
							"required": false,
							"description": "List of images.",
							"type": "object",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Image ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"date_created": {
										"description": "The date the image was created, in the site's timezone.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_created_gmt": {
										"description": "The date the image was created, as GMT.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_modified": {
										"description": "The date the image was last modified, in the site's timezone.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_modified_gmt": {
										"description": "The date the image was last modified, as GMT.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"src": {
										"description": "Image URL.",
										"type": "string",
										"format": "uri",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Image name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"alt": {
										"description": "Image alternative text.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"position": {
										"description": "Image position. 0 means that the image is featured.",
										"type": "integer",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"attributes": {
							"required": false,
							"description": "List of attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"position": {
										"description": "Attribute position.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"visible": {
										"description": "Define if the attribute is visible on the \"Additional information\" tab in the product's page.",
										"type": "boolean",
										"default": false,
										"context": [ "view", "edit" ]
									},
									"variation": {
										"description": "Define if the attribute can be used as variation.",
										"type": "boolean",
										"default": false,
										"context": [ "view", "edit" ]
									},
									"options": {
										"description": "List of available term names of the attribute.",
										"type": "array",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"default_attributes": {
							"required": false,
							"description": "Defaults variation attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"option": {
										"description": "Selected attribute term name.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort products.",
							"type": "integer"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Whether to bypass trash and force deletion.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/products/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"name": {
							"required": false,
							"description": "Product name.",
							"type": "string"
						},
						"slug": {
							"required": false,
							"description": "Product slug.",
							"type": "string"
						},
						"type": {
							"required": false,
							"enum": [
								"simple",
								"grouped",
								"external",
								"variable"
							],
							"description": "Product type.",
							"type": "string"
						},
						"status": {
							"required": false,
							"enum": [
								"draft",
								"pending",
								"private",
								"publish"
							],
							"description": "Product status (post status).",
							"type": "string"
						},
						"featured": {
							"required": false,
							"description": "Featured product.",
							"type": "boolean"
						},
						"catalog_visibility": {
							"required": false,
							"enum": [
								"visible",
								"catalog",
								"search",
								"hidden"
							],
							"description": "Catalog visibility.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "Product description.",
							"type": "string"
						},
						"short_description": {
							"required": false,
							"description": "Product short description.",
							"type": "string"
						},
						"sku": {
							"required": false,
							"description": "Unique identifier.",
							"type": "string"
						},
						"regular_price": {
							"required": false,
							"description": "Product regular price.",
							"type": "string"
						},
						"sale_price": {
							"required": false,
							"description": "Product sale price.",
							"type": "string"
						},
						"date_on_sale_from": {
							"required": false,
							"description": "Start date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_from_gmt": {
							"required": false,
							"description": "Start date of sale price, as GMT.",
							"type": "date-time"
						},
						"date_on_sale_to": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_to_gmt": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"virtual": {
							"required": false,
							"description": "If the product is virtual.",
							"type": "boolean"
						},
						"downloadable": {
							"required": false,
							"description": "If the product is downloadable.",
							"type": "boolean"
						},
						"downloads": {
							"required": false,
							"description": "List of downloadable files.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "File ID.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "File name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"file": {
										"description": "File URL.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"download_limit": {
							"required": false,
							"description": "Number of times downloadable files can be downloaded after purchase.",
							"type": "integer"
						},
						"download_expiry": {
							"required": false,
							"description": "Number of days until access to downloadable files expires.",
							"type": "integer"
						},
						"external_url": {
							"required": false,
							"description": "Product external URL. Only for external products.",
							"type": "string"
						},
						"button_text": {
							"required": false,
							"description": "Product external button text. Only for external products.",
							"type": "string"
						},
						"tax_status": {
							"required": false,
							"enum": [ "taxable", "shipping", "none" ],
							"description": "Tax status.",
							"type": "string"
						},
						"tax_class": {
							"required": false,
							"description": "Tax class.",
							"type": "string"
						},
						"manage_stock": {
							"required": false,
							"description": "Stock management at product level.",
							"type": "boolean"
						},
						"stock_quantity": {
							"required": false,
							"description": "Stock quantity.",
							"type": "integer"
						},
						"in_stock": {
							"required": false,
							"description": "Controls whether or not the product is listed as \"in stock\" or \"out of stock\" on the frontend.",
							"type": "boolean"
						},
						"backorders": {
							"required": false,
							"enum": [ "no", "notify", "yes" ],
							"description": "If managing stock, this controls if backorders are allowed.",
							"type": "string"
						},
						"sold_individually": {
							"required": false,
							"description": "Allow one item to be bought in a single order.",
							"type": "boolean"
						},
						"weight": {
							"required": false,
							"description": "Product weight (kg).",
							"type": "string"
						},
						"dimensions": {
							"required": false,
							"description": "Product dimensions.",
							"type": "object"
						},
						"shipping_class": {
							"required": false,
							"description": "Shipping class slug.",
							"type": "string"
						},
						"reviews_allowed": {
							"required": false,
							"description": "Allow reviews.",
							"type": "boolean"
						},
						"upsell_ids": {
							"required": false,
							"description": "List of up-sell products IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"cross_sell_ids": {
							"required": false,
							"description": "List of cross-sell products IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"parent_id": {
							"required": false,
							"description": "Product parent ID.",
							"type": "integer"
						},
						"purchase_note": {
							"required": false,
							"description": "Optional note to send the customer after purchase.",
							"type": "string"
						},
						"categories": {
							"required": false,
							"description": "List of categories.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Category ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Category name.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"slug": {
										"description": "Category slug.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"tags": {
							"required": false,
							"description": "List of tags.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Tag ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Tag name.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"slug": {
										"description": "Tag slug.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									}
								}
							}
						},
						"images": {
							"required": false,
							"description": "List of images.",
							"type": "object",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Image ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"date_created": {
										"description": "The date the image was created, in the site's timezone.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_created_gmt": {
										"description": "The date the image was created, as GMT.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_modified": {
										"description": "The date the image was last modified, in the site's timezone.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"date_modified_gmt": {
										"description": "The date the image was last modified, as GMT.",
										"type": "date-time",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"src": {
										"description": "Image URL.",
										"type": "string",
										"format": "uri",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Image name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"alt": {
										"description": "Image alternative text.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"position": {
										"description": "Image position. 0 means that the image is featured.",
										"type": "integer",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"attributes": {
							"required": false,
							"description": "List of attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"position": {
										"description": "Attribute position.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"visible": {
										"description": "Define if the attribute is visible on the \"Additional information\" tab in the product's page.",
										"type": "boolean",
										"default": false,
										"context": [ "view", "edit" ]
									},
									"variation": {
										"description": "Define if the attribute can be used as variation.",
										"type": "boolean",
										"default": false,
										"context": [ "view", "edit" ]
									},
									"options": {
										"description": "List of available term names of the attribute.",
										"type": "array",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"default_attributes": {
							"required": false,
							"description": "Defaults variation attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"option": {
										"description": "Selected attribute term name.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort products.",
							"type": "integer"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/products/batch"
			}
		},
		"/wc/v3/products/(?P<product_id>[\\d]+)/variations": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"after": {
							"required": false,
							"description": "Limit response to resources published after a given ISO8601 compliant date.",
							"type": "string"
						},
						"before": {
							"required": false,
							"description": "Limit response to resources published before a given ISO8601 compliant date.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "desc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "date",
							"enum": [
								"date",
								"id",
								"include",
								"title",
								"slug"
							],
							"description": "Sort collection by object attribute.",
							"type": "string"
						},
						"parent": {
							"required": false,
							"default": [],
							"description": "Limit result set to those of particular parent IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"parent_exclude": {
							"required": false,
							"default": [],
							"description": "Limit result set to all items except those of a particular parent ID.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"slug": {
							"required": false,
							"description": "Limit result set to products with a specific slug.",
							"type": "string"
						},
						"status": {
							"required": false,
							"default": "any",
							"enum": [
								"any",
								"draft",
								"pending",
								"private",
								"publish"
							],
							"description": "Limit result set to products assigned a specific status.",
							"type": "string"
						},
						"type": {
							"required": false,
							"enum": [
								"simple",
								"grouped",
								"external",
								"variable"
							],
							"description": "Limit result set to products assigned a specific type.",
							"type": "string"
						},
						"sku": {
							"required": false,
							"description": "Limit result set to products with a specific SKU.",
							"type": "string"
						},
						"featured": {
							"required": false,
							"description": "Limit result set to featured products.",
							"type": "boolean"
						},
						"category": {
							"required": false,
							"description": "Limit result set to products assigned a specific category ID.",
							"type": "string"
						},
						"tag": {
							"required": false,
							"description": "Limit result set to products assigned a specific tag ID.",
							"type": "string"
						},
						"shipping_class": {
							"required": false,
							"description": "Limit result set to products assigned a specific shipping class ID.",
							"type": "string"
						},
						"attribute": {
							"required": false,
							"description": "Limit result set to products with a specific attribute.",
							"type": "string"
						},
						"attribute_term": {
							"required": false,
							"description": "Limit result set to products with a specific attribute term ID (required an assigned attribute).",
							"type": "string"
						},
						"tax_class": {
							"required": false,
							"enum": [ "standard", "reduced-rate", "zero-rate" ],
							"description": "Limit result set to products with a specific tax class.",
							"type": "string"
						},
						"in_stock": {
							"required": false,
							"description": "Limit result set to products in stock or out of stock.",
							"type": "boolean"
						},
						"on_sale": {
							"required": false,
							"description": "Limit result set to products on sale.",
							"type": "boolean"
						},
						"min_price": {
							"required": false,
							"description": "Limit result set to products based on a minimum price.",
							"type": "string"
						},
						"max_price": {
							"required": false,
							"description": "Limit result set to products based on a maximum price.",
							"type": "string"
						},
						"image_size": {
							"required": false,
							"default": "full",
							"description": "Use a specific registered image size for the returned variation image src. Falls back to the full size if the requested size is not registered.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"description": {
							"required": false,
							"description": "Variation description.",
							"type": "string"
						},
						"sku": {
							"required": false,
							"description": "Unique identifier.",
							"type": "string"
						},
						"regular_price": {
							"required": false,
							"description": "Variation regular price.",
							"type": "string"
						},
						"sale_price": {
							"required": false,
							"description": "Variation sale price.",
							"type": "string"
						},
						"date_on_sale_from": {
							"required": false,
							"description": "Start date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_from_gmt": {
							"required": false,
							"description": "Start date of sale price, as GMT.",
							"type": "date-time"
						},
						"date_on_sale_to": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_to_gmt": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"visible": {
							"required": false,
							"default": true,
							"description": "Define if the attribute is visible on the \"Additional information\" tab in the product's page.",
							"type": "boolean"
						},
						"virtual": {
							"required": false,
							"default": false,
							"description": "If the variation is virtual.",
							"type": "boolean"
						},
						"downloadable": {
							"required": false,
							"default": false,
							"description": "If the variation is downloadable.",
							"type": "boolean"
						},
						"downloads": {
							"required": false,
							"description": "List of downloadable files.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "File ID.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "File name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"file": {
										"description": "File URL.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"download_limit": {
							"required": false,
							"default": -1,
							"description": "Number of times downloadable files can be downloaded after purchase.",
							"type": "integer"
						},
						"download_expiry": {
							"required": false,
							"default": -1,
							"description": "Number of days until access to downloadable files expires.",
							"type": "integer"
						},
						"tax_status": {
							"required": false,
							"default": "taxable",
							"enum": [ "taxable", "shipping", "none" ],
							"description": "Tax status.",
							"type": "string"
						},
						"tax_class": {
							"required": false,
							"description": "Tax class.",
							"type": "string"
						},
						"manage_stock": {
							"required": false,
							"default": false,
							"description": "Stock management at variation level.",
							"type": [ "boolean", "string" ]
						},
						"stock_quantity": {
							"required": false,
							"description": "Stock quantity.",
							"type": "integer"
						},
						"in_stock": {
							"required": false,
							"default": true,
							"description": "Controls whether or not the variation is listed as \"in stock\" or \"out of stock\" on the frontend.",
							"type": "boolean"
						},
						"backorders": {
							"required": false,
							"default": "no",
							"enum": [ "no", "notify", "yes" ],
							"description": "If managing stock, this controls if backorders are allowed.",
							"type": "string"
						},
						"weight": {
							"required": false,
							"description": "Variation weight (kg).",
							"type": "string"
						},
						"dimensions": {
							"required": false,
							"description": "Variation dimensions.",
							"type": "object"
						},
						"shipping_class": {
							"required": false,
							"description": "Shipping class slug.",
							"type": "string"
						},
						"image": {
							"required": false,
							"description": "Variation image data.",
							"type": "object"
						},
						"gallery_image_ids": {
							"required": false,
							"description": "Variation gallery image IDs, excluding the featured image (which is set via \"image\").",
							"type": "array",
							"items": {
								"type": "integer",
								"minimum": 1
							}
						},
						"attributes": {
							"required": false,
							"description": "List of attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"option": {
										"description": "Selected attribute term name.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort products.",
							"type": "integer"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				}
			]
		},
		"/wc/v3/products/(?P<product_id>[\\d]+)/variations/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the variation.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"image_size": {
							"required": false,
							"default": "full",
							"description": "Use a specific registered image size for the returned variation image src. Falls back to the full size if the requested size is not registered.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the variation.",
							"type": "integer"
						},
						"description": {
							"required": false,
							"description": "Variation description.",
							"type": "string"
						},
						"sku": {
							"required": false,
							"description": "Unique identifier.",
							"type": "string"
						},
						"regular_price": {
							"required": false,
							"description": "Variation regular price.",
							"type": "string"
						},
						"sale_price": {
							"required": false,
							"description": "Variation sale price.",
							"type": "string"
						},
						"date_on_sale_from": {
							"required": false,
							"description": "Start date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_from_gmt": {
							"required": false,
							"description": "Start date of sale price, as GMT.",
							"type": "date-time"
						},
						"date_on_sale_to": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_to_gmt": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"visible": {
							"required": false,
							"description": "Define if the attribute is visible on the \"Additional information\" tab in the product's page.",
							"type": "boolean"
						},
						"virtual": {
							"required": false,
							"description": "If the variation is virtual.",
							"type": "boolean"
						},
						"downloadable": {
							"required": false,
							"description": "If the variation is downloadable.",
							"type": "boolean"
						},
						"downloads": {
							"required": false,
							"description": "List of downloadable files.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "File ID.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "File name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"file": {
										"description": "File URL.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"download_limit": {
							"required": false,
							"description": "Number of times downloadable files can be downloaded after purchase.",
							"type": "integer"
						},
						"download_expiry": {
							"required": false,
							"description": "Number of days until access to downloadable files expires.",
							"type": "integer"
						},
						"tax_status": {
							"required": false,
							"enum": [ "taxable", "shipping", "none" ],
							"description": "Tax status.",
							"type": "string"
						},
						"tax_class": {
							"required": false,
							"description": "Tax class.",
							"type": "string"
						},
						"manage_stock": {
							"required": false,
							"description": "Stock management at variation level.",
							"type": [ "boolean", "string" ]
						},
						"stock_quantity": {
							"required": false,
							"description": "Stock quantity.",
							"type": "integer"
						},
						"in_stock": {
							"required": false,
							"description": "Controls whether or not the variation is listed as \"in stock\" or \"out of stock\" on the frontend.",
							"type": "boolean"
						},
						"backorders": {
							"required": false,
							"enum": [ "no", "notify", "yes" ],
							"description": "If managing stock, this controls if backorders are allowed.",
							"type": "string"
						},
						"weight": {
							"required": false,
							"description": "Variation weight (kg).",
							"type": "string"
						},
						"dimensions": {
							"required": false,
							"description": "Variation dimensions.",
							"type": "object"
						},
						"shipping_class": {
							"required": false,
							"description": "Shipping class slug.",
							"type": "string"
						},
						"image": {
							"required": false,
							"description": "Variation image data.",
							"type": "object"
						},
						"gallery_image_ids": {
							"required": false,
							"description": "Variation gallery image IDs, excluding the featured image (which is set via \"image\").",
							"type": "array",
							"items": {
								"type": "integer",
								"minimum": 1
							}
						},
						"attributes": {
							"required": false,
							"description": "List of attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"option": {
										"description": "Selected attribute term name.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort products.",
							"type": "integer"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the variation.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Whether to bypass trash and force deletion.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/products/(?P<product_id>[\\d]+)/variations/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"product_id": {
							"required": false,
							"description": "Unique identifier for the variable product.",
							"type": "integer"
						},
						"description": {
							"required": false,
							"description": "Variation description.",
							"type": "string"
						},
						"sku": {
							"required": false,
							"description": "Unique identifier.",
							"type": "string"
						},
						"regular_price": {
							"required": false,
							"description": "Variation regular price.",
							"type": "string"
						},
						"sale_price": {
							"required": false,
							"description": "Variation sale price.",
							"type": "string"
						},
						"date_on_sale_from": {
							"required": false,
							"description": "Start date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_from_gmt": {
							"required": false,
							"description": "Start date of sale price, as GMT.",
							"type": "date-time"
						},
						"date_on_sale_to": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"date_on_sale_to_gmt": {
							"required": false,
							"description": "End date of sale price, in the site's timezone.",
							"type": "date-time"
						},
						"visible": {
							"required": false,
							"description": "Define if the attribute is visible on the \"Additional information\" tab in the product's page.",
							"type": "boolean"
						},
						"virtual": {
							"required": false,
							"description": "If the variation is virtual.",
							"type": "boolean"
						},
						"downloadable": {
							"required": false,
							"description": "If the variation is downloadable.",
							"type": "boolean"
						},
						"downloads": {
							"required": false,
							"description": "List of downloadable files.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "File ID.",
										"type": "string",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"name": {
										"description": "File name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"file": {
										"description": "File URL.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"download_limit": {
							"required": false,
							"description": "Number of times downloadable files can be downloaded after purchase.",
							"type": "integer"
						},
						"download_expiry": {
							"required": false,
							"description": "Number of days until access to downloadable files expires.",
							"type": "integer"
						},
						"tax_status": {
							"required": false,
							"enum": [ "taxable", "shipping", "none" ],
							"description": "Tax status.",
							"type": "string"
						},
						"tax_class": {
							"required": false,
							"description": "Tax class.",
							"type": "string"
						},
						"manage_stock": {
							"required": false,
							"description": "Stock management at variation level.",
							"type": [ "boolean", "string" ]
						},
						"stock_quantity": {
							"required": false,
							"description": "Stock quantity.",
							"type": "integer"
						},
						"in_stock": {
							"required": false,
							"description": "Controls whether or not the variation is listed as \"in stock\" or \"out of stock\" on the frontend.",
							"type": "boolean"
						},
						"backorders": {
							"required": false,
							"enum": [ "no", "notify", "yes" ],
							"description": "If managing stock, this controls if backorders are allowed.",
							"type": "string"
						},
						"weight": {
							"required": false,
							"description": "Variation weight (kg).",
							"type": "string"
						},
						"dimensions": {
							"required": false,
							"description": "Variation dimensions.",
							"type": "object"
						},
						"shipping_class": {
							"required": false,
							"description": "Shipping class slug.",
							"type": "string"
						},
						"image": {
							"required": false,
							"description": "Variation image data.",
							"type": "object"
						},
						"gallery_image_ids": {
							"required": false,
							"description": "Variation gallery image IDs, excluding the featured image (which is set via \"image\").",
							"type": "array",
							"items": {
								"type": "integer",
								"minimum": 1
							}
						},
						"attributes": {
							"required": false,
							"description": "List of attributes.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Attribute ID.",
										"type": "integer",
										"context": [ "view", "edit" ]
									},
									"name": {
										"description": "Attribute name.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"option": {
										"description": "Selected attribute term name.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						},
						"menu_order": {
							"required": false,
							"description": "Menu order, used to custom sort products.",
							"type": "integer"
						},
						"meta_data": {
							"required": false,
							"description": "Meta data.",
							"type": "array",
							"items": {
								"type": "object",
								"properties": {
									"id": {
										"description": "Meta ID.",
										"type": "integer",
										"context": [ "view", "edit" ],
										"readonly": true
									},
									"key": {
										"description": "Meta key.",
										"type": "string",
										"context": [ "view", "edit" ]
									},
									"value": {
										"description": "Meta value.",
										"type": "string",
										"context": [ "view", "edit" ]
									}
								}
							}
						}
					}
				}
			]
		},
		"/wc/v3/reports/sales": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"period": {
							"required": false,
							"enum": [ "week", "month", "last_month", "year" ],
							"description": "Report period.",
							"type": "string"
						},
						"date_min": {
							"required": false,
							"description": "Return sales for a specific start date, the date need to be in the YYYY-MM-DD format.",
							"type": "string"
						},
						"date_max": {
							"required": false,
							"description": "Return sales for a specific end date, the date need to be in the YYYY-MM-DD format.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/reports/sales"
			}
		},
		"/wc/v3/reports/top_sellers": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"period": {
							"required": false,
							"enum": [ "week", "month", "last_month", "year" ],
							"description": "Report period.",
							"type": "string"
						},
						"date_min": {
							"required": false,
							"description": "Return sales for a specific start date, the date need to be in the YYYY-MM-DD format.",
							"type": "string"
						},
						"date_max": {
							"required": false,
							"description": "Return sales for a specific end date, the date need to be in the YYYY-MM-DD format.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/reports/top_sellers"
			}
		},
		"/wc/v3/reports": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/reports"
			}
		},
		"/wc/v3/settings": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": []
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/settings"
			}
		},
		"/wc/v3/settings/(?P<group_id>[\\w-]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"group": {
							"required": false,
							"description": "Settings group ID.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/settings/(?P<group_id>[\\w-]+)/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"group": {
							"required": false,
							"description": "Settings group ID.",
							"type": "string"
						},
						"value": {
							"required": false,
							"description": "Setting value.",
							"type": "mixed"
						}
					}
				}
			]
		},
		"/wc/v3/settings/(?P<group_id>[\\w-]+)/(?P<id>[\\w-]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"group": {
							"required": false,
							"description": "Settings group ID.",
							"type": "string"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"group": {
							"required": false,
							"description": "Settings group ID.",
							"type": "string"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "string"
						},
						"value": {
							"required": false,
							"description": "Setting value.",
							"type": "mixed"
						}
					}
				}
			]
		},
		"/wc/v3/shipping/zones": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": []
				},
				{
					"methods": [ "POST" ],
					"args": {
						"name": {
							"required": true,
							"description": "Shipping zone name.",
							"type": "string"
						},
						"order": {
							"required": false,
							"description": "Shipping zone order.",
							"type": "integer"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/shipping/zones"
			}
		},
		"/wc/v3/shipping/zones/(?P<id>[\\d-]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique ID for the resource.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique ID for the resource.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "Shipping zone name.",
							"type": "string"
						},
						"order": {
							"required": false,
							"description": "Shipping zone order.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique ID for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Whether to bypass trash and force deletion.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/shipping/zones/(?P<id>[\\d-]+)/locations": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique ID for the resource.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique ID for the resource.",
							"type": "integer"
						},
						"code": {
							"required": false,
							"description": "Shipping zone location code.",
							"type": "string"
						},
						"type": {
							"required": false,
							"enum": [
								"postcode",
								"state",
								"country",
								"continent"
							],
							"description": "Shipping zone location type.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/shipping/zones/(?P<zone_id>[\\d-]+)/methods": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"zone_id": {
							"required": false,
							"description": "Unique ID for the zone.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"zone_id": {
							"required": false,
							"description": "Unique ID for the zone.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"description": "Shipping method sort order.",
							"type": "integer"
						},
						"enabled": {
							"required": false,
							"description": "Shipping method enabled status.",
							"type": "boolean"
						},
						"settings": {
							"required": false,
							"description": "Shipping method settings.",
							"type": "object"
						},
						"method_id": {
							"required": true,
							"description": "Shipping method ID."
						}
					}
				}
			]
		},
		"/wc/v3/shipping/zones/(?P<zone_id>[\\d-]+)/methods/(?P<instance_id>[\\d-]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"zone_id": {
							"required": false,
							"description": "Unique ID for the zone.",
							"type": "integer"
						},
						"instance_id": {
							"required": false,
							"description": "Unique ID for the instance.",
							"type": "integer"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"zone_id": {
							"required": false,
							"description": "Unique ID for the zone.",
							"type": "integer"
						},
						"instance_id": {
							"required": false,
							"description": "Unique ID for the instance.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"description": "Shipping method sort order.",
							"type": "integer"
						},
						"enabled": {
							"required": false,
							"description": "Shipping method enabled status.",
							"type": "boolean"
						},
						"settings": {
							"required": false,
							"description": "Shipping method settings.",
							"type": "object"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"zone_id": {
							"required": false,
							"description": "Unique ID for the zone.",
							"type": "integer"
						},
						"instance_id": {
							"required": false,
							"description": "Unique ID for the instance.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Whether to bypass trash and force deletion.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/taxes/classes": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"name": {
							"required": true,
							"description": "Tax class name.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/taxes/classes"
			}
		},
		"/wc/v3/taxes/classes/(?P<slug>\\w[\\w\\s\\-]*)": {
			"namespace": "wc/v3",
			"methods": [ "DELETE" ],
			"endpoints": [
				{
					"methods": [ "DELETE" ],
					"args": {
						"slug": {
							"required": false,
							"description": "Unique slug for the resource.",
							"type": "string"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/taxes": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "asc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "order",
							"enum": [ "id", "order" ],
							"description": "Sort collection by object attribute.",
							"type": "string"
						},
						"class": {
							"required": false,
							"enum": [ "standard", "reduced-rate", "zero-rate" ],
							"description": "Sort by tax class.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"country": {
							"required": false,
							"description": "Country ISO 3166 code.",
							"type": "string"
						},
						"state": {
							"required": false,
							"description": "State code.",
							"type": "string"
						},
						"postcode": {
							"required": false,
							"description": "Postcode / ZIP.",
							"type": "string"
						},
						"city": {
							"required": false,
							"description": "City name.",
							"type": "string"
						},
						"rate": {
							"required": false,
							"description": "Tax rate.",
							"type": "string"
						},
						"name": {
							"required": false,
							"description": "Tax rate name.",
							"type": "string"
						},
						"priority": {
							"required": false,
							"default": 1,
							"description": "Tax priority.",
							"type": "integer"
						},
						"compound": {
							"required": false,
							"default": false,
							"description": "Whether or not this is a compound rate.",
							"type": "boolean"
						},
						"shipping": {
							"required": false,
							"default": true,
							"description": "Whether or not this tax rate also gets applied to shipping.",
							"type": "boolean"
						},
						"order": {
							"required": false,
							"description": "Indicates the order that will appear in queries.",
							"type": "integer"
						},
						"class": {
							"required": false,
							"default": "standard",
							"enum": [ "standard", "reduced-rate", "zero-rate" ],
							"description": "Tax class.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/taxes"
			}
		},
		"/wc/v3/taxes/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"country": {
							"required": false,
							"description": "Country ISO 3166 code.",
							"type": "string"
						},
						"state": {
							"required": false,
							"description": "State code.",
							"type": "string"
						},
						"postcode": {
							"required": false,
							"description": "Postcode / ZIP.",
							"type": "string"
						},
						"city": {
							"required": false,
							"description": "City name.",
							"type": "string"
						},
						"rate": {
							"required": false,
							"description": "Tax rate.",
							"type": "string"
						},
						"name": {
							"required": false,
							"description": "Tax rate name.",
							"type": "string"
						},
						"priority": {
							"required": false,
							"description": "Tax priority.",
							"type": "integer"
						},
						"compound": {
							"required": false,
							"description": "Whether or not this is a compound rate.",
							"type": "boolean"
						},
						"shipping": {
							"required": false,
							"description": "Whether or not this tax rate also gets applied to shipping.",
							"type": "boolean"
						},
						"order": {
							"required": false,
							"description": "Indicates the order that will appear in queries.",
							"type": "integer"
						},
						"class": {
							"required": false,
							"enum": [ "standard", "reduced-rate", "zero-rate" ],
							"description": "Tax class.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/taxes/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"country": {
							"required": false,
							"description": "Country ISO 3166 code.",
							"type": "string"
						},
						"state": {
							"required": false,
							"description": "State code.",
							"type": "string"
						},
						"postcode": {
							"required": false,
							"description": "Postcode / ZIP.",
							"type": "string"
						},
						"city": {
							"required": false,
							"description": "City name.",
							"type": "string"
						},
						"rate": {
							"required": false,
							"description": "Tax rate.",
							"type": "string"
						},
						"name": {
							"required": false,
							"description": "Tax rate name.",
							"type": "string"
						},
						"priority": {
							"required": false,
							"description": "Tax priority.",
							"type": "integer"
						},
						"compound": {
							"required": false,
							"description": "Whether or not this is a compound rate.",
							"type": "boolean"
						},
						"shipping": {
							"required": false,
							"description": "Whether or not this tax rate also gets applied to shipping.",
							"type": "boolean"
						},
						"order": {
							"required": false,
							"description": "Indicates the order that will appear in queries.",
							"type": "integer"
						},
						"class": {
							"required": false,
							"enum": [ "standard", "reduced-rate", "zero-rate" ],
							"description": "Tax class.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/taxes/batch"
			}
		},
		"/wc/v3/webhooks/(?P<webhook_id>[\\d]+)/deliveries": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"webhook_id": {
							"required": false,
							"description": "Unique identifier for the webhook.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/webhooks/(?P<webhook_id>[\\d]+)/deliveries/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"webhook_id": {
							"required": false,
							"description": "Unique identifier for the webhook.",
							"type": "integer"
						},
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/webhooks": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						},
						"page": {
							"required": false,
							"default": 1,
							"description": "Current page of the collection.",
							"type": "integer"
						},
						"per_page": {
							"required": false,
							"default": 10,
							"description": "Maximum number of items to be returned in result set.",
							"type": "integer"
						},
						"search": {
							"required": false,
							"description": "Limit results to those matching a string.",
							"type": "string"
						},
						"after": {
							"required": false,
							"description": "Limit response to resources published after a given ISO8601 compliant date.",
							"type": "string"
						},
						"before": {
							"required": false,
							"description": "Limit response to resources published before a given ISO8601 compliant date.",
							"type": "string"
						},
						"exclude": {
							"required": false,
							"default": [],
							"description": "Ensure result set excludes specific IDs.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"include": {
							"required": false,
							"default": [],
							"description": "Limit result set to specific ids.",
							"type": "array",
							"items": {
								"type": "integer"
							}
						},
						"offset": {
							"required": false,
							"description": "Offset the result set by a specific number of items.",
							"type": "integer"
						},
						"order": {
							"required": false,
							"default": "desc",
							"enum": [ "asc", "desc" ],
							"description": "Order sort attribute ascending or descending.",
							"type": "string"
						},
						"orderby": {
							"required": false,
							"default": "date",
							"enum": [
								"date",
								"id",
								"include",
								"title",
								"slug"
							],
							"description": "Sort collection by object attribute.",
							"type": "string"
						},
						"status": {
							"required": false,
							"default": "all",
							"enum": [ "all", "active", "paused", "disabled" ],
							"description": "Limit result set to webhooks assigned a specific status.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST" ],
					"args": {
						"name": {
							"required": false,
							"description": "A friendly name for the webhook.",
							"type": "string"
						},
						"status": {
							"required": false,
							"default": "active",
							"enum": [ "active", "paused", "disabled" ],
							"description": "Webhook status.",
							"type": "string"
						},
						"topic": {
							"required": true,
							"description": "Webhook topic.",
							"type": "string"
						},
						"secret": {
							"required": true,
							"description": "Webhook secret.",
							"type": "string"
						},
						"delivery_url": {
							"required": true,
							"description": "Webhook delivery URL.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/webhooks"
			}
		},
		"/wc/v3/webhooks/(?P<id>[\\d]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH", "DELETE" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"name": {
							"required": false,
							"description": "A friendly name for the webhook.",
							"type": "string"
						},
						"status": {
							"required": false,
							"enum": [ "active", "paused", "disabled" ],
							"description": "Webhook status.",
							"type": "string"
						},
						"topic": {
							"required": false,
							"description": "Webhook topic.",
							"type": "string"
						},
						"secret": {
							"required": false,
							"description": "Secret key used to generate a hash of the delivered webhook and provided in the request headers. This will default is a MD5 hash from the current user's ID|username if not provided.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "DELETE" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "integer"
						},
						"force": {
							"required": false,
							"default": false,
							"description": "Required to be true, as resource does not support trashing.",
							"type": "boolean"
						}
					}
				}
			]
		},
		"/wc/v3/webhooks/batch": {
			"namespace": "wc/v3",
			"methods": [ "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"name": {
							"required": false,
							"description": "A friendly name for the webhook.",
							"type": "string"
						},
						"status": {
							"required": false,
							"enum": [ "active", "paused", "disabled" ],
							"description": "Webhook status.",
							"type": "string"
						},
						"topic": {
							"required": false,
							"description": "Webhook topic.",
							"type": "string"
						},
						"secret": {
							"required": false,
							"description": "Secret key used to generate a hash of the delivered webhook and provided in the request headers. This will default is a MD5 hash from the current user's ID|username if not provided.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/webhooks/batch"
			}
		},
		"/wc/v3/system_status": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/system_status"
			}
		},
		"/wc/v3/system_status/tools": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/system_status/tools"
			}
		},
		"/wc/v3/system_status/tools/(?P<id>[\\w-]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "A unique identifier for the tool.",
							"type": "string"
						},
						"name": {
							"required": false,
							"description": "Tool name.",
							"type": "string"
						},
						"action": {
							"required": false,
							"description": "What running the tool will do.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "Tool description.",
							"type": "string"
						},
						"success": {
							"required": false,
							"description": "Did the tool run successfully?",
							"type": "boolean"
						},
						"message": {
							"required": false,
							"description": "Tool return message.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/shipping_methods": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/shipping_methods"
			}
		},
		"/wc/v3/shipping_methods/(?P<id>[\\w-]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "string"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			]
		},
		"/wc/v3/payment_gateways": {
			"namespace": "wc/v3",
			"methods": [ "GET" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				}
			],
			"_links": {
				"self": "https://example.com/wp-json/wc/v3/payment_gateways"
			}
		},
		"/wc/v3/payment_gateways/(?P<id>[\\w-]+)": {
			"namespace": "wc/v3",
			"methods": [ "GET", "POST", "PUT", "PATCH" ],
			"endpoints": [
				{
					"methods": [ "GET" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "string"
						},
						"context": {
							"required": false,
							"default": "view",
							"enum": [ "view", "edit" ],
							"description": "Scope under which the request is made; determines fields present in response.",
							"type": "string"
						}
					}
				},
				{
					"methods": [ "POST", "PUT", "PATCH" ],
					"args": {
						"id": {
							"required": false,
							"description": "Unique identifier for the resource.",
							"type": "string"
						},
						"title": {
							"required": false,
							"description": "Payment gateway title on checkout.",
							"type": "string"
						},
						"description": {
							"required": false,
							"description": "Payment gateway description on checkout.",
							"type": "string"
						},
						"order": {
							"required": false,
							"description": "Payment gateway sort order.",
							"type": "integer"
						},
						"enabled": {
							"required": false,
							"description": "Payment gateway enabled status.",
							"type": "boolean"
						},
						"settings": {
							"required": false,
							"description": "Payment gateway settings.",
							"type": "object"
						}
					}
				}
			]
		}
	},
	"_links": {
		"up": [
			{
				"href": "https://example.com/wp-json/"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

---

## Coupons

*Source: apis/rest-api/v3/coupons.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Coupons

The coupons API allows you to create, view, update, and delete individual, or a batch, of coupon codes.

## Coupon properties

| Attribute                     | Type      | Description                                                                                                                          |
| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                          | integer   | Unique identifier for the object. `READ-ONLY`                                                          |
| `code`                        | string    | Coupon code. `MANDATORY`                                                                               |
| `amount`                      | string    | The amount of discount. Should always be numeric, even if setting a percentage.                                                      |
| `date_created`                | date-time | The date the coupon was created, in the site's timezone. `READ-ONLY`                                   |
| `date_created_gmt`            | date-time | The date the coupon was created, as GMT. `READ-ONLY`                                                   |
| `date_modified`               | date-time | The date the coupon was last modified, in the site's timezone. `READ-ONLY`                             |
| `date_modified_gmt`           | date-time | The date the coupon was last modified, as GMT. `READ-ONLY`                                             |
| `discount_type`               | string    | Determines the type of discount that will be applied. Options: `percent`, `fixed_cart` and `fixed_product`. Default is `fixed_cart`. |
| `description`                 | string    | Coupon description.                                                                                                                  |
| `date_expires`                | string    | The date the coupon expires, in the site's timezone.                                                                                 |
| `date_expires_gmt`            | string    | The date the coupon expires, as GMT.                                                                                                 |
| `usage_count`                 | integer   | Number of times the coupon has been used already. `READ-ONLY`                                          |
| `individual_use`              | boolean   | If true, the coupon can only be used individually. Other applied coupons will be removed from the cart. Default is `false`.          |
| `product_ids`                 | array     | List of product IDs the coupon can be used on.                                                                                       |
| `excluded_product_ids`        | array     | List of product IDs the coupon cannot be used on.                                                                                    |
| `usage_limit`                 | integer   | How many times the coupon can be used in total.                                                                                      |
| `usage_limit_per_user`        | integer   | How many times the coupon can be used per customer.                                                                                  |
| `limit_usage_to_x_items`      | integer   | Max number of items in the cart the coupon can be applied to.                                                                        |
| `free_shipping`               | boolean   | If true and if the free shipping method requires a coupon, this coupon will enable free shipping. Default is `false`.                |
| `product_categories`          | array     | List of category IDs the coupon applies to.                                                                                          |
| `excluded_product_categories` | array     | List of category IDs the coupon does not apply to.                                                                                   |
| `exclude_sale_items`          | boolean   | If true, this coupon will not be applied to items that have sale prices. Default is `false`.                                         |
| `minimum_amount`              | string    | Minimum order amount that needs to be in the cart before coupon applies.                                                             |
| `maximum_amount`              | string    | Maximum order amount allowed when using the coupon.                                                                                  |
| `email_restrictions`          | array     | List of email addresses that can use this coupon.                                                                                    |
| `used_by`                     | array     | List of user IDs (or guest email addresses) that have used the coupon. `READ-ONLY`                     |
| `meta_data`                   | array     | Meta data. See [Coupon - Meta data properties](#coupon---meta-data-properties)                                                         |

### Coupon - Meta data properties

| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

## Create a coupon

This API helps you to create a new coupon.

```http
POST /wp-json/wc/v3/coupons
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/coupons \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "code": "10off",
  "discount_type": "percent",
  "amount": "10",
  "individual_use": true,
  "exclude_sale_items": true,
  "minimum_amount": "100.00"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	code: '10off',
	discount_type: 'percent',
	amount: '10',
	individual_use: true,
	exclude_sale_items: true,
	minimum_amount: '100.00',
};

WooCommerce.post( 'coupons', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'code' => '10off',
    'discount_type' => 'percent',
    'amount' => '10',
    'individual_use' => true,
    'exclude_sale_items' => true,
    'minimum_amount' => '100.00'
];

print_r($woocommerce->post('coupons', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "code": "10off",
    "discount_type": "percent",
    "amount": "10",
    "individual_use": True,
    "exclude_sale_items": True,
    "minimum_amount": "100.00"
}

print(wcapi.post("coupons", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  code: "10off",
  discount_type: "percent",
  amount: "10",
  individual_use: true,
  exclude_sale_items: true,
  minimum_amount: "100.00"
}

woocommerce.post("coupons", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 719,
	"code": "10off",
	"amount": "10.00",
	"date_created": "2017-03-21T15:23:00",
	"date_created_gmt": "2017-03-21T18:23:00",
	"date_modified": "2017-03-21T15:23:00",
	"date_modified_gmt": "2017-03-21T18:23:00",
	"discount_type": "percent",
	"description": "",
	"date_expires": null,
	"date_expires_gmt": null,
	"usage_count": 0,
	"individual_use": true,
	"product_ids": [],
	"excluded_product_ids": [],
	"usage_limit": null,
	"usage_limit_per_user": null,
	"limit_usage_to_x_items": null,
	"free_shipping": false,
	"product_categories": [],
	"excluded_product_categories": [],
	"exclude_sale_items": true,
	"minimum_amount": "100.00",
	"maximum_amount": "0.00",
	"email_restrictions": [],
	"used_by": [],
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons/719"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a coupon

This API lets you retrieve and view a specific coupon by ID.

```http
GET /wp-json/wc/v3/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/coupons/719 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'coupons/719' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('coupons/719')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("coupons/719").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("coupons/719").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 719,
	"code": "10off",
	"amount": "10.00",
	"date_created": "2017-03-21T15:23:00",
	"date_created_gmt": "2017-03-21T18:23:00",
	"date_modified": "2017-03-21T15:23:00",
	"date_modified_gmt": "2017-03-21T18:23:00",
	"discount_type": "percent",
	"description": "",
	"date_expires": null,
	"date_expires_gmt": null,
	"usage_count": 0,
	"individual_use": true,
	"product_ids": [],
	"excluded_product_ids": [],
	"usage_limit": null,
	"usage_limit_per_user": null,
	"limit_usage_to_x_items": null,
	"free_shipping": false,
	"product_categories": [],
	"excluded_product_categories": [],
	"exclude_sale_items": true,
	"minimum_amount": "100.00",
	"maximum_amount": "0.00",
	"email_restrictions": [],
	"used_by": [],
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons/719"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all coupons

This API helps you to list all the coupons that have been created.

```http
GET /wp-json/wc/v3/coupons
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/coupons \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'coupons' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('coupons')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("coupons").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("coupons").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 720,
		"code": "free shipping",
		"amount": "0.00",
		"date_created": "2017-03-21T15:25:02",
		"date_created_gmt": "2017-03-21T18:25:02",
		"date_modified": "2017-03-21T15:25:02",
		"date_modified_gmt": "2017-03-21T18:25:02",
		"discount_type": "fixed_cart",
		"description": "",
		"date_expires": null,
		"date_expires_gmt": null,
		"usage_count": 0,
		"individual_use": true,
		"product_ids": [],
		"excluded_product_ids": [],
		"usage_limit": null,
		"usage_limit_per_user": null,
		"limit_usage_to_x_items": null,
		"free_shipping": true,
		"product_categories": [],
		"excluded_product_categories": [],
		"exclude_sale_items": false,
		"minimum_amount": "0.00",
		"maximum_amount": "0.00",
		"email_restrictions": [],
		"used_by": [],
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/coupons/720"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/coupons"
				}
			]
		}
	},
	{
		"id": 719,
		"code": "10off",
		"amount": "10.00",
		"date_created": "2017-03-21T15:23:00",
		"date_created_gmt": "2017-03-21T18:23:00",
		"date_modified": "2017-03-21T15:23:00",
		"date_modified_gmt": "2017-03-21T18:23:00",
		"discount_type": "percent",
		"description": "",
		"date_expires": null,
		"date_expires_gmt": null,
		"usage_count": 0,
		"individual_use": true,
		"product_ids": [],
		"excluded_product_ids": [],
		"usage_limit": null,
		"usage_limit_per_user": null,
		"limit_usage_to_x_items": null,
		"free_shipping": false,
		"product_categories": [],
		"excluded_product_categories": [],
		"exclude_sale_items": true,
		"minimum_amount": "100.00",
		"maximum_amount": "0.00",
		"email_restrictions": [],
		"used_by": [],
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/coupons/719"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/coupons"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter         | Type    | Description                                                                                                                  |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `context`         | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |
| `page`            | integer | Current page of the collection. Default is `1`.                                                                              |
| `per_page`        | integer | Maximum number of items to be returned in result set. Default is `10`.                                                       |
| `search`          | string  | Limit results to those matching a string.                                                                                    |
| `after`           | string  | Limit response to resources published after a given ISO8601 compliant date.                                                  |
| `before`          | string  | Limit response to resources published before a given ISO8601 compliant date.                                                 |
| `modified_after`  | string  | Limit response to resources modified after a given ISO8601 compliant date.                                                   |
| `modified_before` | string  | Limit response to resources modified after a given ISO8601 compliant date.                                                   |
| `dates_are_gmt`   | boolean | Whether to interpret dates as GMT when limiting response by published or modified date.                                      |
| `exclude`         | array   | Ensure result set excludes specific IDs.                                                                                     |
| `include`         | array   | Limit result set to specific ids.                                                                                            |
| `offset`          | integer | Offset the result set by a specific number of items.                                                                         |
| `order`           | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                  |
| `orderby`         | string  | Sort collection by object attribute. Options: `date`, `modified`, `id`, `include`, `title` and `slug`. Default is `date`.    |
| `code`            | string  | Limit result set to resources with a specific code.                                                                          |

## Update a coupon

This API lets you make changes to a coupon.

```http
PUT /wp-json/wc/v3/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/coupons/719 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "amount": "5"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	amount: '5',
};

WooCommerce.put( 'coupons/719', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'amount' => '5'
];

print_r($woocommerce->put('coupons/719', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "amount": "5"
}

print(wcapi.put("coupons/719", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  amount: "5"
}

woocommerce.put("coupons/719", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 719,
	"code": "10off",
	"amount": "5.00",
	"date_created": "2017-03-21T15:23:00",
	"date_created_gmt": "2017-03-21T18:23:00",
	"date_modified": "2017-03-21T15:26:16",
	"date_modified_gmt": "2017-03-21T18:26:16",
	"discount_type": "percent",
	"description": "",
	"date_expires": null,
	"date_expires_gmt": null,
	"usage_count": 0,
	"individual_use": true,
	"product_ids": [],
	"excluded_product_ids": [],
	"usage_limit": null,
	"usage_limit_per_user": null,
	"limit_usage_to_x_items": null,
	"free_shipping": false,
	"product_categories": [],
	"excluded_product_categories": [],
	"exclude_sale_items": true,
	"minimum_amount": "100.00",
	"maximum_amount": "0.00",
	"email_restrictions": [],
	"used_by": [],
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons/719"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a coupon

This API helps you delete a coupon.

To remove an applied coupon from an order without deleting the coupon itself, [update the order's coupon lines](../orders#remove-a-coupon-from-an-order).

```http
DELETE /wp-json/wc/v3/coupons/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/coupons/719?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'coupons/719', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('coupons/719', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("coupons/719", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("coupons/719", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 719,
	"code": "10off",
	"amount": "5.00",
	"date_created": "2017-03-21T15:23:00",
	"date_created_gmt": "2017-03-21T18:23:00",
	"date_modified": "2017-03-21T15:26:16",
	"date_modified_gmt": "2017-03-21T18:26:16",
	"discount_type": "percent",
	"description": "",
	"date_expires": null,
	"date_expires_gmt": null,
	"usage_count": 0,
	"individual_use": true,
	"product_ids": [],
	"excluded_product_ids": [],
	"usage_limit": null,
	"usage_limit_per_user": null,
	"limit_usage_to_x_items": null,
	"free_shipping": false,
	"product_categories": [],
	"excluded_product_categories": [],
	"exclude_sale_items": true,
	"minimum_amount": "100.00",
	"maximum_amount": "0.00",
	"email_restrictions": [],
	"used_by": [],
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons/719"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                              |
| --------- | ------ | ------------------------------------------------------------------------ |
| `force`   | string | Use `true` whether to permanently delete the coupon, Default is `false`. |

## Batch update coupons

This API helps you to batch create, update and delete multiple coupons.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/coupons/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/coupons/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "code": "20off",
      "discount_type": "percent",
      "amount": "20",
      "individual_use": true,
      "exclude_sale_items": true,
      "minimum_amount": "100.00"
    },
    {
      "code": "30off",
      "discount_type": "percent",
      "amount": "30",
      "individual_use": true,
      "exclude_sale_items": true,
      "minimum_amount": "100.00"
    }
  ],
  "update": [
    {
      "id": 719,
      "minimum_amount": "50.00"
    }
  ],
  "delete": [
    720
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			code: '20off',
			discount_type: 'percent',
			amount: '20',
			individual_use: true,
			exclude_sale_items: true,
			minimum_amount: '100.00',
		},
		{
			code: '30off',
			discount_type: 'percent',
			amount: '30',
			individual_use: true,
			exclude_sale_items: true,
			minimum_amount: '100.00',
		},
	],
	update: [
		{
			id: 719,
			minimum_amount: '50.00',
		},
	],
	delete: [ 720 ],
};

WooCommerce.post( 'coupons/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'code' => '20off',
            'discount_type' => 'percent',
            'amount' => '20',
            'individual_use' => true,
            'exclude_sale_items' => true,
            'minimum_amount' => '100.00'
        ],
        [
            'code' => '30off',
            'discount_type' => 'percent',
            'amount' => '30',
            'individual_use' => true,
            'exclude_sale_items' => true,
            'minimum_amount' => '100.00'
        ]
    ],
    'update' => [
        [
            'id' => 719,
            'minimum_amount' => '50.00'
        ]
    ],
    'delete' => [
        720
    ]
];

print_r($woocommerce->post('coupons/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "code": "20off",
            "discount_type": "percent",
            "amount": "20",
            "individual_use": True,
            "exclude_sale_items": True,
            "minimum_amount": "100.00"
        },
        {
            "code": "30off",
            "discount_type": "percent",
            "amount": "30",
            "individual_use": True,
            "exclude_sale_items": True,
            "minimum_amount": "100.00"
        }
    ],
    "update": [
        {
            "id": 719,
            "minimum_amount": "50.00"
        }
    ],
    "delete": [
        720
    ]
}

print(wcapi.post("coupons/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      code: "20off",
      discount_type: "percent",
      amount: "20",
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    },
    {
      code: "30off",
      discount_type: "percent",
      amount: "30",
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    }
  ],
  update: [
    {
      id: 719,
      minimum_amount: "50.00"
    }
  ],
  delete: [
    720
  ]
}

woocommerce.post("coupons/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 721,
			"code": "20off",
			"amount": "20.00",
			"date_created": "2017-03-21T15:27:29",
			"date_created_gmt": "2017-03-21T18:27:29",
			"date_modified": "2017-03-21T15:27:29",
			"date_modified_gmt": "2017-03-21T18:27:29",
			"discount_type": "percent",
			"description": "",
			"date_expires": null,
			"date_expires_gmt": null,
			"usage_count": 0,
			"individual_use": true,
			"product_ids": [],
			"excluded_product_ids": [],
			"usage_limit": null,
			"usage_limit_per_user": null,
			"limit_usage_to_x_items": null,
			"free_shipping": false,
			"product_categories": [],
			"excluded_product_categories": [],
			"exclude_sale_items": true,
			"minimum_amount": "100.00",
			"maximum_amount": "0.00",
			"email_restrictions": [],
			"used_by": [],
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons/721"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons"
					}
				]
			}
		},
		{
			"id": 722,
			"code": "30off",
			"amount": "30.00",
			"date_created": "2017-03-21T15:27:31",
			"date_created_gmt": "2017-03-21T18:27:31",
			"date_modified": "2017-03-21T15:27:31",
			"date_modified_gmt": "2017-03-21T18:27:31",
			"discount_type": "percent",
			"description": "",
			"date_expires": null,
			"date_expires_gmt": null,
			"usage_count": 0,
			"individual_use": true,
			"product_ids": [],
			"excluded_product_ids": [],
			"usage_limit": null,
			"usage_limit_per_user": null,
			"limit_usage_to_x_items": null,
			"free_shipping": false,
			"product_categories": [],
			"excluded_product_categories": [],
			"exclude_sale_items": true,
			"minimum_amount": "100.00",
			"maximum_amount": "0.00",
			"email_restrictions": [],
			"used_by": [],
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons/722"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 719,
			"code": "10off",
			"amount": "5.00",
			"date_created": "2017-03-21T15:23:00",
			"date_created_gmt": "2017-03-21T18:23:00",
			"date_modified": "2017-03-21T15:27:32",
			"date_modified_gmt": "2017-03-21T18:27:32",
			"discount_type": "percent",
			"description": "",
			"date_expires": null,
			"date_expires_gmt": null,
			"usage_count": 0,
			"individual_use": true,
			"product_ids": [],
			"excluded_product_ids": [],
			"usage_limit": null,
			"usage_limit_per_user": null,
			"limit_usage_to_x_items": null,
			"free_shipping": false,
			"product_categories": [],
			"excluded_product_categories": [],
			"exclude_sale_items": true,
			"minimum_amount": "50.00",
			"maximum_amount": "0.00",
			"email_restrictions": [],
			"used_by": [],
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons/719"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 720,
			"code": "free shipping",
			"amount": "0.00",
			"date_created": "2017-03-21T15:25:02",
			"date_created_gmt": "2017-03-21T18:25:02",
			"date_modified": "2017-03-21T15:25:02",
			"date_modified_gmt": "2017-03-21T18:25:02",
			"discount_type": "fixed_cart",
			"description": "",
			"date_expires": null,
			"date_expires_gmt": null,
			"usage_count": 0,
			"individual_use": true,
			"product_ids": [],
			"excluded_product_ids": [],
			"usage_limit": null,
			"usage_limit_per_user": null,
			"limit_usage_to_x_items": null,
			"free_shipping": true,
			"product_categories": [],
			"excluded_product_categories": [],
			"exclude_sale_items": false,
			"minimum_amount": "0.00",
			"maximum_amount": "0.00",
			"email_restrictions": [],
			"used_by": [],
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons/720"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Customers

*Source: apis/rest-api/v3/customers.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Customers

The customer API allows you to create, view, update, and delete individual, or a batch, of customers.

## Customer properties

| Attribute            | Type      | Description                                                                                                |
| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
| `id`                 | integer   | Unique identifier for the resource. `READ-ONLY`                              |
| `date_created`       | date-time | The date the customer was created, in the site's timezone. `READ-ONLY`       |
| `date_created_gmt`   | date-time | The date the customer was created, as GMT. `READ-ONLY`                       |
| `date_modified`      | date-time | The date the customer was last modified, in the site's timezone. `READ-ONLY` |
| `date_modified_gmt`  | date-time | The date the customer was last modified, as GMT. `READ-ONLY`                 |
| `email`              | string    | The email address for the customer. `MANDATORY`                              |
| `first_name`         | string    | Customer first name.                                                                                       |
| `last_name`          | string    | Customer last name.                                                                                        |
| `role`               | string    | Customer role. `READ-ONLY`                                                   |
| `username`           | string    | Customer login name.                                                                                       |
| `password`           | string    | Customer password. `WRITE-ONLY`                                              |
| `billing`            | object    | List of billing address data. See [Customer - Billing properties](#customer---billing-properties)            |
| `shipping`           | object    | List of shipping address data. See [Customer - Shipping properties](#customer---shipping-properties)         |
| `is_paying_customer` | bool      | Is the customer a paying customer? `READ-ONLY`                               |
| `avatar_url`         | string    | Avatar URL. `READ-ONLY`                                                      |
| `meta_data`          | array     | Meta data. See [Customer - Meta data properties](#customer---meta-data-properties)                           |

### Customer - Billing properties

| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1                                       |
| `address_2`  | string | Address line 2                                       |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | ISO code of the country.                             |
| `email`      | string | Email address.                                       |
| `phone`      | string | Phone number.                                        |

### Customer - Shipping properties

| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1                                       |
| `address_2`  | string | Address line 2                                       |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | ISO code of the country.                             |

### Customer - Meta data properties

| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

## Create a customer

This API helps you to create a new customer.

```http
POST /wp-json/wc/v3/customers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/customers \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "username": "john.doe",
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	email: 'john.doe@example.com',
	first_name: 'John',
	last_name: 'Doe',
	username: 'john.doe',
	billing: {
		first_name: 'John',
		last_name: 'Doe',
		company: '',
		address_1: '969 Market',
		address_2: '',
		city: 'San Francisco',
		state: 'CA',
		postcode: '94103',
		country: 'US',
		email: 'john.doe@example.com',
		phone: '(555) 555-5555',
	},
	shipping: {
		first_name: 'John',
		last_name: 'Doe',
		company: '',
		address_1: '969 Market',
		address_2: '',
		city: 'San Francisco',
		state: 'CA',
		postcode: '94103',
		country: 'US',
	},
};

WooCommerce.post( 'customers', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'email' => 'john.doe@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'username' => 'john.doe',
    'billing' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'company' => '',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US',
        'email' => 'john.doe@example.com',
        'phone' => '(555) 555-5555'
    ],
    'shipping' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'company' => '',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US'
    ]
];

print_r($woocommerce->post('customers', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe",
    "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
    },
    "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
    }
}

print(wcapi.post("customers", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  email: "john.doe@example.com",
  first_name: "John",
  last_name: "Doe",
  username: "john.doe",
  billing: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    company: "",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  }
}

woocommerce.post("customers", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 25,
	"date_created": "2017-03-21T16:09:28",
	"date_created_gmt": "2017-03-21T19:09:28",
	"date_modified": "2017-03-21T16:09:30",
	"date_modified_gmt": "2017-03-21T19:09:30",
	"email": "john.doe@example.com",
	"first_name": "John",
	"last_name": "Doe",
	"role": "customer",
	"username": "john.doe",
	"billing": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US",
		"email": "john.doe@example.com",
		"phone": "(555) 555-5555"
	},
	"shipping": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US"
	},
	"is_paying_customer": false,
	"avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/customers/25"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/customers"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a customer

This API lets you retrieve and view a specific customer by ID.

```http
GET /wp-json/wc/v3/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/customers/25 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'customers/25' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers/25')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers/25").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers/25").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 25,
	"date_created": "2017-03-21T16:09:28",
	"date_created_gmt": "2017-03-21T19:09:28",
	"date_modified": "2017-03-21T16:09:30",
	"date_modified_gmt": "2017-03-21T19:09:30",
	"email": "john.doe@example.com",
	"first_name": "John",
	"last_name": "Doe",
	"role": "customer",
	"username": "john.doe",
	"billing": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US",
		"email": "john.doe@example.com",
		"phone": "(555) 555-5555"
	},
	"shipping": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US"
	},
	"is_paying_customer": false,
	"avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/customers/25"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/customers"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all customers

This API helps you to view all the customers.

```http
GET /wp-json/wc/v3/customers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/customers \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'customers' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 26,
		"date_created": "2017-03-21T16:11:14",
		"date_created_gmt": "2017-03-21T19:11:14",
		"date_modified": "2017-03-21T16:11:16",
		"date_modified_gmt": "2017-03-21T19:11:16",
		"email": "joao.silva@example.com",
		"first_name": "João",
		"last_name": "Silva",
		"role": "customer",
		"username": "joao.silva",
		"billing": {
			"first_name": "João",
			"last_name": "Silva",
			"company": "",
			"address_1": "Av. Brasil, 432",
			"address_2": "",
			"city": "Rio de Janeiro",
			"state": "RJ",
			"postcode": "12345-000",
			"country": "BR",
			"email": "joao.silva@example.com",
			"phone": "(55) 5555-5555"
		},
		"shipping": {
			"first_name": "João",
			"last_name": "Silva",
			"company": "",
			"address_1": "Av. Brasil, 432",
			"address_2": "",
			"city": "Rio de Janeiro",
			"state": "RJ",
			"postcode": "12345-000",
			"country": "BR"
		},
		"is_paying_customer": false,
		"avatar_url": "https://secure.gravatar.com/avatar/be7b5febff88a2d947c3289e90cdf017?s=96",
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/customers/26"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/customers"
				}
			]
		}
	},
	{
		"id": 25,
		"date_created": "2017-03-21T16:09:28",
		"date_created_gmt": "2017-03-21T19:09:28",
		"date_modified": "2017-03-21T16:09:30",
		"date_modified_gmt": "2017-03-21T19:09:30",
		"email": "john.doe@example.com",
		"first_name": "John",
		"last_name": "Doe",
		"role": "customer",
		"username": "john.doe",
		"billing": {
			"first_name": "John",
			"last_name": "Doe",
			"company": "",
			"address_1": "969 Market",
			"address_2": "",
			"city": "San Francisco",
			"state": "CA",
			"postcode": "94103",
			"country": "US",
			"email": "john.doe@example.com",
			"phone": "(555) 555-5555"
		},
		"shipping": {
			"first_name": "John",
			"last_name": "Doe",
			"company": "",
			"address_1": "969 Market",
			"address_2": "",
			"city": "San Francisco",
			"state": "CA",
			"postcode": "94103",
			"country": "US"
		},
		"is_paying_customer": false,
		"avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/customers/25"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/customers"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter  | Type    | Description                                                                                                                                                                                 |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`  | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                                                                |
| `page`     | integer | Current page of the collection. Default is `1`.                                                                                                                                             |
| `per_page` | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                                                                      |
| `search`   | string  | Limit results to those matching a string.                                                                                                                                                   |
| `exclude`  | array   | Ensure result set excludes specific IDs.                                                                                                                                                    |
| `include`  | array   | Limit result set to specific IDs.                                                                                                                                                           |
| `offset`   | integer | Offset the result set by a specific number of items.                                                                                                                                        |
| `order`    | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                                                                  |
| `orderby`  | string  | Sort collection by object attribute. Options: `id`, `include`, `name` and `registered_date`. Default is `name`.                                                                             |
| `email`    | string  | Limit result set to resources with a specific email.                                                                                                                                        |
| `role`     | string  | Limit result set to resources with a specific role. Options: `all`, `administrator`, `editor`, `author`, `contributor`, `subscriber`, `customer` and `shop_manager`. Default is `customer`. |

## Update a customer

This API lets you make changes to a customer.

```http
PUT /wp-json/wc/v3/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/customers/25 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "first_name": "James",
  "billing": {
    "first_name": "James"
  },
  "shipping": {
    "first_name": "James"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	first_name: 'James',
	billing: {
		first_name: 'James',
	},
	shipping: {
		first_name: 'James',
	},
};

WooCommerce.put( 'customers/25', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'first_name' => 'James',
    'billing' => [
        'first_name' => 'James'
    ],
    'shipping' => [
        'first_name' => 'James'
    ]
];

print_r($woocommerce->put('customers/25', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "first_name": "James",
    "billing": {
        "first_name": "James"
    },
    "shipping": {
        "first_name": "James"
    }
}

print(wcapi.put("customers/25", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  first_name: "James",
  billing: {
    first_name: "James"
  },
  shipping: {
    first_name: "James"
  }
}

woocommerce.put("customers/25", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 25,
	"date_created": "2017-03-21T16:09:28",
	"date_created_gmt": "2017-03-21T19:09:28",
	"date_modified": "2017-03-21T16:12:28",
	"date_modified_gmt": "2017-03-21T19:12:28",
	"email": "john.doe@example.com",
	"first_name": "James",
	"last_name": "Doe",
	"role": "customer",
	"username": "john.doe",
	"billing": {
		"first_name": "James",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US",
		"email": "john.doe@example.com",
		"phone": "(555) 555-5555"
	},
	"shipping": {
		"first_name": "James",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US"
	},
	"is_paying_customer": false,
	"avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/customers/25"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/customers"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a customer

This API helps you delete a customer.

```http
DELETE /wp-json/wc/v3/customers/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/customers/25?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'customers/25', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('customers/25', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("customers/25", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("customers/25", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 25,
	"date_created": "2017-03-21T16:09:28",
	"date_created_gmt": "2017-03-21T19:09:28",
	"date_modified": "2017-03-21T16:12:28",
	"date_modified_gmt": "2017-03-21T19:12:28",
	"email": "john.doe@example.com",
	"first_name": "James",
	"last_name": "Doe",
	"role": "customer",
	"username": "john.doe",
	"billing": {
		"first_name": "James",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US",
		"email": "john.doe@example.com",
		"phone": "(555) 555-5555"
	},
	"shipping": {
		"first_name": "James",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US"
	},
	"is_paying_customer": false,
	"avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/customers/25"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/customers"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter  | Type    | Description                                                   |
| ---------- | ------- | ------------------------------------------------------------- |
| `force`    | string  | Required to be `true`, as resource does not support trashing. |
| `reassign` | integer | User ID to reassign posts to.                                 |

## Batch update customers

This API helps you to batch create, update and delete multiple customers.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/customers/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/customers/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "email": "john.doe2@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "username": "john.doe2",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      }
    },
    {
      "email": "joao.silva2@example.com",
      "first_name": "João",
      "last_name": "Silva",
      "username": "joao.silva2",
      "billing": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(55) 5555-5555"
      },
      "shipping": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      }
    }
  ],
  "update": [
    {
      "id": 26,
      "billing": {
        "phone": "(11) 1111-1111"
      }
    }
  ],
  "delete": [
    25
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			email: 'john.doe2@example.com',
			first_name: 'John',
			last_name: 'Doe',
			username: 'john.doe2',
			billing: {
				first_name: 'John',
				last_name: 'Doe',
				company: '',
				address_1: '969 Market',
				address_2: '',
				city: 'San Francisco',
				state: 'CA',
				postcode: '94103',
				country: 'US',
				email: 'john.doe@example.com',
				phone: '(555) 555-5555',
			},
			shipping: {
				first_name: 'John',
				last_name: 'Doe',
				company: '',
				address_1: '969 Market',
				address_2: '',
				city: 'San Francisco',
				state: 'CA',
				postcode: '94103',
				country: 'US',
			},
		},
		{
			email: 'joao.silva2@example.com',
			first_name: 'João',
			last_name: 'Silva',
			username: 'joao.silva2',
			billing: {
				first_name: 'João',
				last_name: 'Silva',
				company: '',
				address_1: 'Av. Brasil, 432',
				address_2: '',
				city: 'Rio de Janeiro',
				state: 'RJ',
				postcode: '12345-000',
				country: 'BR',
				email: 'joao.silva@example.com',
				phone: '(55) 5555-5555',
			},
			shipping: {
				first_name: 'João',
				last_name: 'Silva',
				company: '',
				address_1: 'Av. Brasil, 432',
				address_2: '',
				city: 'Rio de Janeiro',
				state: 'RJ',
				postcode: '12345-000',
				country: 'BR',
			},
		},
	],
	update: [
		{
			id: 26,
			billing: {
				phone: '(11) 1111-1111',
			},
		},
	],
	delete: [ 11 ],
};

WooCommerce.post( 'customers/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'email' => 'john.doe2@example.com',
            'first_name' => 'John',
            'last_name' => 'Doe',
            'username' => 'john.doe2',
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'company' => '',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'company' => '',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ]
        ],
        [
            'email' => 'joao.silva2@example.com',
            'first_name' => 'João',
            'last_name' => 'Silva',
            'username' => 'joao.silva2',
            'billing' => [
                'first_name' => 'João',
                'last_name' => 'Silva',
                'company' => '',
                'address_1' => 'Av. Brasil, 432',
                'address_2' => '',
                'city' => 'Rio de Janeiro',
                'state' => 'RJ',
                'postcode' => '12345-000',
                'country' => 'BR',
                'email' => 'joao.silva@example.com',
                'phone' => '(55) 5555-5555'
            ],
            'shipping' => [
                'first_name' => 'João',
                'last_name' => 'Silva',
                'company' => '',
                'address_1' => 'Av. Brasil, 432',
                'address_2' => '',
                'city' => 'Rio de Janeiro',
                'state' => 'RJ',
                'postcode' => '12345-000',
                'country' => 'BR'
            ]
        ]
    ],
    'update' => [
        [
            'id' => 26,
            'billing' => [
                'phone' => '(11) 1111-1111'
            ]
        ]
    ],
    'delete' => [
        25
    ]
];

print_r($woocommerce->post('customers/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "email": "john.doe2@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "username": "john.doe2",
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "company": "",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "company": "",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            }
        },
        {
            "email": "joao.silva2@example.com",
            "first_name": "João",
            "last_name": "Silva",
            "username": "joao.silva2",
            "billing": {
                "first_name": "João",
                "last_name": "Silva",
                "company": "",
                "address_1": "Av. Brasil, 432",
                "address_2": "",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "postcode": "12345-000",
                "country": "BR",
                "email": "joao.silva@example.com",
                "phone": "(55) 5555-5555"
            },
            "shipping": {
                "first_name": "João",
                "last_name": "Silva",
                "company": "",
                "address_1": "Av. Brasil, 432",
                "address_2": "",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "postcode": "12345-000",
                "country": "BR"
            }
        }
    ],
    "update": [
        {
            "id": 26,
            "billing": {
                "phone": "(11) 1111-1111"
            }
        }
    ],
    "delete": [
        25
    ]
}

print(wcapi.post("customers/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      email: "john.doe2@example.com",
      first_name: "John",
      last_name: "Doe",
      username: "john.doe2",
      billing: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        company: "",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      }
    },
    {
      email: "joao.silva2@example.com",
      first_name: "João",
      last_name: "Silva",
      username: "joao.silva2",
      billing: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR",
        email: "joao.silva@example.com",
        phone: "(55) 5555-5555"
      },
      shipping: {
        first_name: "João",
        last_name: "Silva",
        company: "",
        address_1: "Av. Brasil, 432",
        address_2: "",
        city: "Rio de Janeiro",
        state: "RJ",
        postcode: "12345-000",
        country: "BR"
      }
    }
  ],
  update: [
    {
      id: 26,
      billing: {
        phone: "(11) 1111-1111"
      }
    }
  ],
  delete: [
    25
  ]
}

woocommerce.post("customers/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 27,
			"date_created": "2017-03-21T16:13:58",
			"date_created_gmt": "2017-03-21T19:13:58",
			"date_modified": "2017-03-21T16:13:59",
			"date_modified_gmt": "2017-03-21T19:13:59",
			"email": "john.doe2@example.com",
			"first_name": "John",
			"last_name": "Doe",
			"role": "customer",
			"username": "john.doe2",
			"billing": {
				"first_name": "John",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US",
				"email": "john.doe@example.com",
				"phone": "(555) 555-5555"
			},
			"shipping": {
				"first_name": "John",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US"
			},
			"is_paying_customer": false,
			"avatar_url": "https://secure.gravatar.com/avatar/6ad0b094bac53a85bb282ccdb3958279?s=96",
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers/27"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers"
					}
				]
			}
		},
		{
			"id": 28,
			"date_created": "2017-03-21T16:14:00",
			"date_created_gmt": "2017-03-21T19:14:00",
			"date_modified": "2017-03-21T16:14:01",
			"date_modified_gmt": "2017-03-21T19:14:01",
			"email": "joao.silva2@example.com",
			"first_name": "João",
			"last_name": "Silva",
			"role": "customer",
			"username": "joao.silva2",
			"billing": {
				"first_name": "João",
				"last_name": "Silva",
				"company": "",
				"address_1": "Av. Brasil, 432",
				"address_2": "",
				"city": "Rio de Janeiro",
				"state": "RJ",
				"postcode": "12345-000",
				"country": "BR",
				"email": "joao.silva@example.com",
				"phone": "(55) 5555-5555"
			},
			"shipping": {
				"first_name": "João",
				"last_name": "Silva",
				"company": "",
				"address_1": "Av. Brasil, 432",
				"address_2": "",
				"city": "Rio de Janeiro",
				"state": "RJ",
				"postcode": "12345-000",
				"country": "BR"
			},
			"is_paying_customer": false,
			"avatar_url": "https://secure.gravatar.com/avatar/ea9ad095f2970f27cbff07e7f5e99453?s=96",
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers/28"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 26,
			"date_created": "2017-03-21T16:11:14",
			"date_created_gmt": "2017-03-21T19:11:14",
			"date_modified": "2017-03-21T16:14:03",
			"date_modified_gmt": "2017-03-21T19:14:03",
			"email": "joao.silva@example.com",
			"first_name": "João",
			"last_name": "Silva",
			"role": "customer",
			"username": "joao.silva",
			"billing": {
				"first_name": "João",
				"last_name": "Silva",
				"company": "",
				"address_1": "Av. Brasil, 432",
				"address_2": "",
				"city": "Rio de Janeiro",
				"state": "RJ",
				"postcode": "12345-000",
				"country": "BR",
				"email": "joao.silva@example.com",
				"phone": "(11) 1111-1111"
			},
			"shipping": {
				"first_name": "João",
				"last_name": "Silva",
				"company": "",
				"address_1": "Av. Brasil, 432",
				"address_2": "",
				"city": "Rio de Janeiro",
				"state": "RJ",
				"postcode": "12345-000",
				"country": "BR"
			},
			"is_paying_customer": false,
			"avatar_url": "https://secure.gravatar.com/avatar/be7b5febff88a2d947c3289e90cdf017?s=96",
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers/26"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 25,
			"date_created": "2017-03-21T16:09:28",
			"date_created_gmt": "2017-03-21T19:09:28",
			"date_modified": "2017-03-21T16:12:28",
			"date_modified_gmt": "2017-03-21T19:12:28",
			"email": "john.doe@example.com",
			"first_name": "James",
			"last_name": "Doe",
			"role": "customer",
			"username": "john.doe",
			"billing": {
				"first_name": "James",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US",
				"email": "john.doe@example.com",
				"phone": "(555) 555-5555"
			},
			"shipping": {
				"first_name": "James",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US"
			},
			"is_paying_customer": false,
			"avatar_url": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96",
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers/25"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>

## Retrieve customer downloads

This API lets you retrieve customer downloads permissions.

```http
GET /wp-json/wc/v3/customers/<id>/downloads
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/customers/26/downloads \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'customers/26/downloads' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('customers/26/downloads')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("customers/26/downloads").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("customers/26/downloads").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"download_id": "91447fd1849316bbc89dfb7e986a6006",
		"download_url": "https://example.com/?download_file=87&order=wc_order_58d17c18352&email=joao.silva%40example.com&key=91447fd1849316bbc89dfb7e986a6006",
		"product_id": 87,
		"product_name": "Woo Album #2",
		"download_name": "Woo Album #2 &ndash; Song 2",
		"order_id": 723,
		"order_key": "wc_order_58d17c18352",
		"downloads_remaining": "3",
		"access_expires": "never",
		"access_expires_gmt": "never",
		"file": {
			"name": "Song 2",
			"file": "http://example.com/wp-content/uploads/woocommerce_uploads/2013/06/Song.mp3"
		},
		"_links": {
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/customers/26/downloads"
				}
			],
			"product": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/87"
				}
			],
			"order": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

### Customer downloads properties

| Attribute             | Type    | Description                                                                                                                               |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `download_id`         | string  | Download ID (MD5). `READ-ONLY`                                                                              |
| `download_url`        | string  | Download file URL. `READ-ONLY`                                                                              |
| `product_id`          | integer | Downloadable product ID. `READ-ONLY`                                                                        |
| `product_name`        | string  | Product name. `READ-ONLY`                                                                                   |
| `download_name`       | string  | Downloadable file name. `READ-ONLY`                                                                         |
| `order_id`            | integer | Order ID. `READ-ONLY`                                                                                       |
| `order_key`           | string  | Order key. `READ-ONLY`                                                                                      |
| `downloads_remaining` | string  | Number of downloads remaining. `READ-ONLY`                                                                  |
| `access_expires`      | string  | The date when download access expires, in the site's timezone. `READ-ONLY`                                  |
| `access_expires_gmt`  | string  | The date when download access expires, as GMT. `READ-ONLY`                                                  |
| `file`                | object  | File details. `READ-ONLY` See [Customers downloads - File properties](#customer-downloads---file-properties) |

### Customer downloads - File properties

| Attribute | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `name`    | string | File name. `READ-ONLY` |
| `file`    | string | File URL. `READ-ONLY`  |


---

## Data

*Source: apis/rest-api/v3/data.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Data

The data API allows you to view all types of data available.

## List all data

This API lets you retrieve and view a simple list of available data endpoints.

```http
GET /wp-json/wc/v3/data
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/data \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'data' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('data')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("data").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("data").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"slug": "continents",
		"description": "List of supported continents, countries, and states.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/continents"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/data"
				}
			]
		}
	},
	{
		"slug": "countries",
		"description": "List of supported states in a given country.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/countries"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/data"
				}
			]
		}
	},
	{
		"slug": "currencies",
		"description": "List of supported currencies.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/currencies"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/data"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Data properties

| Attribute     | Type   | Description                                                          |
| ------------- | ------ | -------------------------------------------------------------------- |
| `slug`        | string | Data resource ID. `READ-ONLY`          |
| `description` | string | Data resource description. `READ-ONLY` |

## List all continents

This API helps you to view all the continents.

```http
GET /wp-json/wc/v3/data/continents
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/data/continents \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'data/continents' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('data/continents'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("data/continents").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("data/continents").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"code": "AF",
		"name": "Africa",
		"countries": [
			{
				"code": "AO",
				"name": "Angola",
				"states": [
					{
						"code": "BGO",
						"name": "Bengo"
					},
					{
						"code": "BLU",
						"name": "Benguela"
					},
					{
						"code": "BIE",
						"name": "Bié"
					},
					{
						"code": "CAB",
						"name": "Cabinda"
					},
					{
						"code": "CNN",
						"name": "Cunene"
					},
					{
						"code": "HUA",
						"name": "Huambo"
					},
					{
						"code": "HUI",
						"name": "Huíla"
					},
					{
						"code": "CCU",
						"name": "Kuando Kubango"
					},
					{
						"code": "CNO",
						"name": "Kwanza-Norte"
					},
					{
						"code": "CUS",
						"name": "Kwanza-Sul"
					},
					{
						"code": "LUA",
						"name": "Luanda"
					},
					{
						"code": "LNO",
						"name": "Lunda-Norte"
					},
					{
						"code": "LSU",
						"name": "Lunda-Sul"
					},
					{
						"code": "MAL",
						"name": "Malanje"
					},
					{
						"code": "MOX",
						"name": "Moxico"
					},
					{
						"code": "NAM",
						"name": "Namibe"
					},
					{
						"code": "UIG",
						"name": "Uíge"
					},
					{
						"code": "ZAI",
						"name": "Zaire"
					}
				]
			},
			{
				"code": "BF",
				"name": "Burkina Faso",
				"states": []
			},
			{
				"code": "BI",
				"name": "Burundi",
				"states": []
			}
		],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/continents/af"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/continents"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Continents properties

| Attribute   | Type   | Description                                                                                                                                              |
| ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`      | string | 2 character continent code. `READ-ONLY`                                                                                    |
| `name`      | string | Full name of continent. `READ-ONLY`                                                                                        |
| `countries` | array  | List of countries on this continent. See [Continents - Countries properties](#continents---countries-properties) `READ-ONLY` |

##### Continents - Countries properties

| Attribute        | Type    | Description                                                                                                                                                         |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`           | string  | ISO3166 alpha-2 country code. `READ-ONLY`                                                                                             |
| `currency_code`  | string  | Default ISO4127 alpha-3 currency code for the country. `READ-ONLY`                                                                    |
| `currency_pos`   | string  | Currency symbol position for this country. `READ-ONLY`                                                                                |
| `decimal_sep`    | string  | Decimal separator for displayed prices for this country. `READ-ONLY`                                                                  |
| `dimension_unit` | string  | The unit lengths are defined in for this country. `READ-ONLY`                                                                         |
| `name`           | string  | Full name of country. `READ-ONLY`                                                                                                     |
| `num_decimals`   | integer | Number of decimal points shown in displayed prices for this country. `READ-ONLY`                                                      |
| `states`         | array   | List of states in this country. See [Continents - Countries - States properties](#continents---countries---states-properties) `READ-ONLY` |
| `thousand_sep`   | string  | Thousands separator for displayed prices in this country. `READ-ONLY`                                                                 |
| `weight_unit`    | string  | The unit weights are defined in for this country. `READ-ONLY`                                                                         |

##### Continents - Countries - States properties

| Attribute | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `code`    | string | State code. `READ-ONLY`         |
| `name`    | string | Full name of state. `READ-ONLY` |

## Retrieve continent data

This API lets you retrieve and view a continent data.

```http
GET /wp-json/wc/v3/data/continents/<location>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/data/continents/eu \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'data/continents/eu' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('data/continents/eu'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("data/continents/eu").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("data/continents/eu").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"code": "EU",
	"name": "Europe",
	"countries": [
		{
			"code": "AD",
			"name": "Andorra",
			"states": []
		},
		{
			"code": "AL",
			"name": "Albania",
			"states": []
		},
		{
			"code": "AT",
			"name": "Austria",
			"states": []
		},
		{
			"code": "AX",
			"name": "&#197;land Islands",
			"states": []
		},
		{
			"code": "BA",
			"name": "Bosnia and Herzegovina",
			"states": []
		},
		{
			"code": "BE",
			"name": "Belgium",
			"currency_code": "EUR",
			"currency_pos": "left",
			"decimal_sep": ",",
			"dimension_unit": "cm",
			"num_decimals": 2,
			"thousand_sep": " ",
			"weight_unit": "kg",
			"states": []
		},
		{
			"code": "BG",
			"name": "Bulgaria",
			"states": [
				{
					"code": "BG-01",
					"name": "Blagoevgrad"
				},
				{
					"code": "BG-02",
					"name": "Burgas"
				},
				{
					"code": "BG-08",
					"name": "Dobrich"
				},
				{
					"code": "BG-07",
					"name": "Gabrovo"
				},
				{
					"code": "BG-26",
					"name": "Haskovo"
				},
				{
					"code": "BG-09",
					"name": "Kardzhali"
				},
				{
					"code": "BG-10",
					"name": "Kyustendil"
				},
				{
					"code": "BG-11",
					"name": "Lovech"
				},
				{
					"code": "BG-12",
					"name": "Montana"
				},
				{
					"code": "BG-13",
					"name": "Pazardzhik"
				},
				{
					"code": "BG-14",
					"name": "Pernik"
				},
				{
					"code": "BG-15",
					"name": "Pleven"
				},
				{
					"code": "BG-16",
					"name": "Plovdiv"
				},
				{
					"code": "BG-17",
					"name": "Razgrad"
				},
				{
					"code": "BG-18",
					"name": "Ruse"
				},
				{
					"code": "BG-27",
					"name": "Shumen"
				},
				{
					"code": "BG-19",
					"name": "Silistra"
				},
				{
					"code": "BG-20",
					"name": "Sliven"
				},
				{
					"code": "BG-21",
					"name": "Smolyan"
				},
				{
					"code": "BG-23",
					"name": "Sofia"
				},
				{
					"code": "BG-22",
					"name": "Sofia-Grad"
				},
				{
					"code": "BG-24",
					"name": "Stara Zagora"
				},
				{
					"code": "BG-25",
					"name": "Targovishte"
				},
				{
					"code": "BG-03",
					"name": "Varna"
				},
				{
					"code": "BG-04",
					"name": "Veliko Tarnovo"
				},
				{
					"code": "BG-05",
					"name": "Vidin"
				},
				{
					"code": "BG-06",
					"name": "Vratsa"
				},
				{
					"code": "BG-28",
					"name": "Yambol"
				}
			]
		}
	],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/data/continents/eu"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/data/continents"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Continent properties

See [list of continents properties](#continents-properties).

## List all countries

This API helps you to view all the countries.

```http
GET /wp-json/wc/v3/data/countries
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/data/countries \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'data/countries' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('data/countries'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("data/countries").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("data/countries").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"code": "US",
		"name": "United States (US)",
		"states": [
			{
				"code": "AL",
				"name": "Alabama"
			},
			{
				"code": "AK",
				"name": "Alaska"
			},
			{
				"code": "AZ",
				"name": "Arizona"
			},
			{
				"code": "AR",
				"name": "Arkansas"
			},
			{
				"code": "CA",
				"name": "California"
			},
			{
				"code": "CO",
				"name": "Colorado"
			},
			{
				"code": "CT",
				"name": "Connecticut"
			},
			{
				"code": "DE",
				"name": "Delaware"
			},
			{
				"code": "DC",
				"name": "District Of Columbia"
			},
			{
				"code": "FL",
				"name": "Florida"
			},
			{
				"code": "GA",
				"name": "Georgia"
			},
			{
				"code": "HI",
				"name": "Hawaii"
			},
			{
				"code": "ID",
				"name": "Idaho"
			},
			{
				"code": "IL",
				"name": "Illinois"
			},
			{
				"code": "IN",
				"name": "Indiana"
			},
			{
				"code": "IA",
				"name": "Iowa"
			},
			{
				"code": "KS",
				"name": "Kansas"
			},
			{
				"code": "KY",
				"name": "Kentucky"
			},
			{
				"code": "LA",
				"name": "Louisiana"
			},
			{
				"code": "ME",
				"name": "Maine"
			},
			{
				"code": "MD",
				"name": "Maryland"
			},
			{
				"code": "MA",
				"name": "Massachusetts"
			},
			{
				"code": "MI",
				"name": "Michigan"
			},
			{
				"code": "MN",
				"name": "Minnesota"
			},
			{
				"code": "MS",
				"name": "Mississippi"
			},
			{
				"code": "MO",
				"name": "Missouri"
			},
			{
				"code": "MT",
				"name": "Montana"
			},
			{
				"code": "NE",
				"name": "Nebraska"
			},
			{
				"code": "NV",
				"name": "Nevada"
			},
			{
				"code": "NH",
				"name": "New Hampshire"
			},
			{
				"code": "NJ",
				"name": "New Jersey"
			},
			{
				"code": "NM",
				"name": "New Mexico"
			},
			{
				"code": "NY",
				"name": "New York"
			},
			{
				"code": "NC",
				"name": "North Carolina"
			},
			{
				"code": "ND",
				"name": "North Dakota"
			},
			{
				"code": "OH",
				"name": "Ohio"
			},
			{
				"code": "OK",
				"name": "Oklahoma"
			},
			{
				"code": "OR",
				"name": "Oregon"
			},
			{
				"code": "PA",
				"name": "Pennsylvania"
			},
			{
				"code": "RI",
				"name": "Rhode Island"
			},
			{
				"code": "SC",
				"name": "South Carolina"
			},
			{
				"code": "SD",
				"name": "South Dakota"
			},
			{
				"code": "TN",
				"name": "Tennessee"
			},
			{
				"code": "TX",
				"name": "Texas"
			},
			{
				"code": "UT",
				"name": "Utah"
			},
			{
				"code": "VT",
				"name": "Vermont"
			},
			{
				"code": "VA",
				"name": "Virginia"
			},
			{
				"code": "WA",
				"name": "Washington"
			},
			{
				"code": "WV",
				"name": "West Virginia"
			},
			{
				"code": "WI",
				"name": "Wisconsin"
			},
			{
				"code": "WY",
				"name": "Wyoming"
			},
			{
				"code": "AA",
				"name": "Armed Forces (AA)"
			},
			{
				"code": "AE",
				"name": "Armed Forces (AE)"
			},
			{
				"code": "AP",
				"name": "Armed Forces (AP)"
			}
		],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/countries/us"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/countries"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Countries properties

| Attribute | Type   | Description                                                                                                                                 |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`    | string | ISO3166 alpha-2 country code. `READ-ONLY`                                                                     |
| `name`    | string | Full name of country. `READ-ONLY`                                                                             |
| `states`  | array  | List of states in this country. See [Countries - States properties](#countries---states-properties) `READ-ONLY` |

##### Countries - States properties

| Attribute | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `code`    | string | State code. `READ-ONLY`         |
| `name`    | string | Full name of state. `READ-ONLY` |

## Retrieve country data

This API lets you retrieve and view a country data.

```http
GET /wp-json/wc/v3/data/countries/<location>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/data/countries/br \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'data/countries/br' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('data/countries/br'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("data/countries/br").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("data/countries/br").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"code": "BR",
	"name": "Brazil",
	"states": [
		{
			"code": "AC",
			"name": "Acre"
		},
		{
			"code": "AL",
			"name": "Alagoas"
		},
		{
			"code": "AP",
			"name": "Amap&aacute;"
		},
		{
			"code": "AM",
			"name": "Amazonas"
		},
		{
			"code": "BA",
			"name": "Bahia"
		},
		{
			"code": "CE",
			"name": "Cear&aacute;"
		},
		{
			"code": "DF",
			"name": "Distrito Federal"
		},
		{
			"code": "ES",
			"name": "Esp&iacute;rito Santo"
		},
		{
			"code": "GO",
			"name": "Goi&aacute;s"
		},
		{
			"code": "MA",
			"name": "Maranh&atilde;o"
		},
		{
			"code": "MT",
			"name": "Mato Grosso"
		},
		{
			"code": "MS",
			"name": "Mato Grosso do Sul"
		},
		{
			"code": "MG",
			"name": "Minas Gerais"
		},
		{
			"code": "PA",
			"name": "Par&aacute;"
		},
		{
			"code": "PB",
			"name": "Para&iacute;ba"
		},
		{
			"code": "PR",
			"name": "Paran&aacute;"
		},
		{
			"code": "PE",
			"name": "Pernambuco"
		},
		{
			"code": "PI",
			"name": "Piau&iacute;"
		},
		{
			"code": "RJ",
			"name": "Rio de Janeiro"
		},
		{
			"code": "RN",
			"name": "Rio Grande do Norte"
		},
		{
			"code": "RS",
			"name": "Rio Grande do Sul"
		},
		{
			"code": "RO",
			"name": "Rond&ocirc;nia"
		},
		{
			"code": "RR",
			"name": "Roraima"
		},
		{
			"code": "SC",
			"name": "Santa Catarina"
		},
		{
			"code": "SP",
			"name": "S&atilde;o Paulo"
		},
		{
			"code": "SE",
			"name": "Sergipe"
		},
		{
			"code": "TO",
			"name": "Tocantins"
		}
	],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/data/countries/br"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/data/countries"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Country properties

See [list of countries properties](#countries-properties).

## List all currencies

This API helps you to view all the currencies.

```http
GET /wp-json/wc/v3/data/currencies
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/data/currencies \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'data/currencies' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('data/currencies'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("data/currencies").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("data/currencies").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"code": "BTC",
		"name": "Bitcoin",
		"symbol": "&#3647;",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/currencies/BTC"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/currencies"
				}
			]
		}
	},
	{
		"code": "EUR",
		"name": "Euro",
		"symbol": "&euro;",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/currencies/EUR"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/currencies"
				}
			]
		}
	},
	{
		"code": "USD",
		"name": "United States (US) dollar",
		"symbol": "&#36;",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/currencies/USD"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/data/currencies"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Currencies properties

| Attribute | Type   | Description                                                      |
| --------- | ------ | ---------------------------------------------------------------- |
| `code`    | string | ISO4217 currency code. `READ-ONLY` |
| `name`    | string | Full name of currency. `READ-ONLY` |
| `symbol`  | string | Currency symbol. `READ-ONLY`       |

## Retrieve currency data

This API lets you retrieve and view a currency data.

```http
GET /wp-json/wc/v3/data/currencies/<currency>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/data/currencies/brl \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'data/currencies/brl' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('data/currencies/brl'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("data/currencies/brl").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("data/currencies/brl").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"code": "BRL",
	"name": "Brazilian real",
	"symbol": "&#82;&#36;",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/data/currencies/BRL"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/data/currencies"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Currency properties

See [list of currencies properties](#currencies-properties).

## Retrieve current currency

This API lets you retrieve and view store's current currency data.

```http
GET /wp-json/wc/v3/data/currencies/current
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/data/currencies/current \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'data/currencies/current' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('data/currencies/current'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("data/currencies/current").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("data/currencies/current").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"code": "USD",
	"name": "United States (US) dollar",
	"symbol": "&#36;",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/data/currencies/USD"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/data/currencies"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Currency properties

See [list of currencies properties](#currencies-properties).


---

## REST API v3

*Source: apis/rest-api/v3/index.mdx*

import DocCardList from '@theme/DocCardList';

The current and recommended version of the WooCommerce REST API. Use `/wp-json/wc/v3/` endpoints for all new integrations.

<DocCardList />


---

## Order actions

*Source: apis/rest-api/v3/order-actions.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Order actions

The order actions API allows you to perform specific actions with existing orders like you can from the Edit Order screen in the web app.

_Note: currently only some actions are available, other actions will be introduced at a later time._

## Send order details to customer

This endpoint allows you to trigger an email to the customer with the details of their order. In case the order doesn't yet have a billing email set, you can specify an email recipient. However, if the order does have an existing billing email, this will return an error, unless you also specify that the existing email should be overwritten by using the `force_email_update` parameter.

```http
POST /wp-json/wc/v3/orders/<id>/actions/send_order_details
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/orders/723/actions/send_order_details \
	-u consumer_key:consumer_secret \
	-d '{
	  "email": "somebody@example.com",
	  "force_email_update": true
	}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	email: 'somebody@example.com',
	force_email_update: true,
};

WooCommerce.post( 'orders/723/actions/send_order_details', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'email' => 'somebody@example.com',
    'force_email_update' => true,
];

print_r($woocommerce->post('orders/723/actions/send_order_details', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "email": "somebody@example.com",
    "force_email_update": true
}

print(wcapi.post("orders/723/actions/send_order_details", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
    "email": "somebody@example.com",
    "force_email_update": true
}

woocommerce.post("orders/723/actions/send_order_details", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"message": "Billing email updated to somebody@example.com. Order details sent to somebody@example.com, via REST API."
}
```

  </TabItem>
</Tabs>

```json
{
	"code": "woocommerce_rest_missing_email",
	"message": "Order does not have an email address.",
	"data": {
		"status": 400
	}
}
```

## Send order notification email to customer

This endpoint allows you to trigger an email to a customer about the status of their order. This is similar to the [`send_order_details`](#send-order-details-to-customer) endpoint, but allows you to specify which email template to send, based on which email templates are relevant to the order. For example, an order that is on hold has the `customer_on_hold_order` template available. A completed order that also has a partial refund has both the `customer_completed_order` and `customer_refunded_order` templates available. Specifying the `customer_invoice` template is the same as using the `send_order_details` endpoint.

```http
POST /wp-json/wc/v3/orders/<id>/actions/send_email
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/orders/723/actions/send_email \
	-u consumer_key:consumer_secret \
	-d '{
	  "template_id": "customer_completed_order",
	  "email": "somebody@example.com",
	  "force_email_update": true
	}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	template_id: 'customer_completed_order',
	email: 'somebody@example.com',
	force_email_update: true,
};

WooCommerce.post( 'orders/723/actions/send_email', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'template_id' => 'customer_completed_order',
    'email' => 'somebody@example.com',
    'force_email_update' => true,
];

print_r($woocommerce->post('orders/723/actions/send_email', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "template_id": "customer_completed_order",
    "email": "somebody@example.com",
    "force_email_update": true
}

print(wcapi.post("orders/723/actions/send_email", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
    "template_id": "customer_completed_order",
    "email": "somebody@example.com",
    "force_email_update": true
}

woocommerce.post("orders/723/actions/send_email", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"message": "Billing email updated to somebody@example.com. Email template &quot;Completed order&quot; sent to somebody@example.com, via REST API."
}
```

  </TabItem>
</Tabs>

```json
{
	"code": "woocommerce_rest_invalid_email_template",
	"message": "customer_completed_order is not a valid template for this order.",
	"data": {
		"status": 400
	}
}
```

## Get available email templates for an order

This endpoint allows you to retrieve a list of email templates that are available for the specified order. You can also get this data embedded in the response for the [`orders` endpoint](../orders#list-all-orders).

```http
GET /wp-json/wc/v3/orders/<id>/actions/email_templates
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X GET https://example.com/wp-json/wc/v3/orders/723/actions/email_templates \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'orders/723/actions/email_templates' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('orders/723/actions/email_templates'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/actions/email_templates").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.post("orders/723/actions/email_templates").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": "customer_completed_order",
		"title": "Completed order",
		"description": "Order complete emails are sent to customers when their orders are marked completed and usually indicate that their orders have been shipped."
	},
	{
		"id": "customer_invoice",
		"title": "Order details",
		"description": "Order detail emails can be sent to customers containing their order information and payment links."
	}
]
```

  </TabItem>
</Tabs>


---

## Order notes

*Source: apis/rest-api/v3/order-notes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Order notes

The order notes API allows you to create, view, and delete individual order notes.  
Order notes are added by administrators and programmatically to store data about an order, or order events.

## Order note properties

| Attribute          | Type      | Description                                                                                                                                      |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`               | integer   | Unique identifier for the resource. `READ-ONLY`                                                                    |
| `author`           | string    | Order note author. `READ-ONLY`                                                                                     |
| `date_created`     | date-time | The date the order note was created, in the site's timezone. `READ-ONLY`                                           |
| `date_created_gmt` | date-time | The date the order note was created, as GMT. `READ-ONLY`                                                           |
| `note`             | string    | Order note content. `MANDATORY`                                                                                    |
| `customer_note`    | boolean   | If true, the note will be shown to customers and they will be notified. If false, the note will be for admin reference only. Default is `false`. |
| `added_by_user`    | boolean   | If true, this note will be attributed to the current user. If false, the note will be attributed to the system. Default is `false`.              |

## Create an order note

This API helps you to create a new note for an order.

```http
POST /wp-json/wc/v3/orders/<id>/notes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/orders/723/notes \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "note": "Order ok!!!"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	note: 'Order ok!!!',
};

WooCommerce.post( 'orders/723/notes', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'note' => 'Order ok!!!'
];

print_r($woocommerce->post('orders/723/notes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "note": "Order ok!!!"
}

print(wcapi.post("orders/723/notes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  note: "Order ok!!!"
}

woocommerce.post("orders/723/notes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 281,
	"author": "system",
	"date_created": "2017-03-21T16:46:41",
	"date_created_gmt": "2017-03-21T19:46:41",
	"note": "Order ok!!!",
	"customer_note": false,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/notes/281"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/notes"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve an order note

This API lets you retrieve and view a specific note from an order.

```http
GET /wp-json/wc/v3/orders/<id>/notes/<note_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/orders/723/notes/281 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'orders/723/notes/281' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/723/notes/281')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/notes/281").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/723/notes/281").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 281,
	"author": "system",
	"date_created": "2017-03-21T16:46:41",
	"date_created_gmt": "2017-03-21T19:46:41",
	"note": "Order ok!!!",
	"customer_note": false,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/notes/281"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/notes"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all order notes

This API helps you to view all the notes from an order.

```http
GET /wp-json/wc/v3/orders/<id>/notes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/orders/723/notes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'orders/723/notes' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/723/notes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/notes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/723/notes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 281,
		"author": "system",
		"date_created": "2017-03-21T16:46:41",
		"date_created_gmt": "2017-03-21T19:46:41",
		"note": "Order ok!!!",
		"customer_note": false,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/notes/281"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/notes"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	},
	{
		"id": 280,
		"author": "system",
		"date_created": "2017-03-21T16:16:58",
		"date_created_gmt": "2017-03-21T19:16:58",
		"note": "Order status changed from On hold to Completed.",
		"customer_note": false,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/notes/280"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/notes"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	},
	{
		"id": 279,
		"author": "system",
		"date_created": "2017-03-21T16:16:46",
		"date_created_gmt": "2017-03-21T19:16:46",
		"note": "Awaiting BACS payment Order status changed from Pending payment to On hold.",
		"customer_note": false,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/notes/279"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/notes"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `context` | string | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |
| `type`    | string | Limit result to customers or internal notes. Options: `any`, `customer` and `internal`. Default is `any`.                    |

## Delete an order note

This API helps you delete an order note.

```http
DELETE /wp-json/wc/v3/orders/<id>/notes/<note_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/orders/723/notes/281?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'orders/723/notes/281', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/723/notes/281', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/723/notes/281", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/723/notes/281", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 281,
	"author": "system",
	"date_created": "2017-03-21T16:46:41",
	"date_created_gmt": "2017-03-21T19:46:41",
	"note": "Order ok!!!",
	"customer_note": false,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/notes/281"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/notes"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## Order refunds

*Source: apis/rest-api/v3/order-refunds.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Order refunds

The order refunds API allows you to create, view, and delete individual refunds, based on an existing order.

## Order refund properties

| Attribute          | Type      | Description                                                                                                                                                                   |
| ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                                 |
| `date_created`     | date-time | The date the order refund was created, in the site's timezone. `READ-ONLY`                                                                      |
| `date_created_gmt` | date-time | The date the order refund was created, as GMT. `READ-ONLY`                                                                                      |
| `amount`           | string    | Total refund amount. Optional. If this parameter is provided, it will take precedence over line item totals, even when total of line items does not matches with this amount. |
| `reason`           | string    | Reason for refund.                                                                                                                                                            |
| `refunded_by`      | integer   | User ID of user who created the refund.                                                                                                                                       |
| `refunded_payment` | boolean   | If the payment was refunded via the API. See `api_refund`. `READ-ONLY`                                                                          |
| `meta_data`        | array     | Meta data. See [Order refund - Meta data properties](#order-refund---meta-data-properties)                                                                                      |
| `line_items`       | array     | Line items data. See [Order refund - Line items properties](#order-refund---line-items-properties)                                                                              |
| `tax_lines`        | array     | Tax lines data. See [Order refund - Tax lines properties](#order-refund---tax-lines-properties) `READ-ONLY`                                       |
| `shipping_lines`   | array     | Shipping lines data. See [Order refund - Shipping lines properties](#order-refund---shipping-lines-properties)                                                                  |
| `fee_lines`        | array     | Fee lines data. See [Order refund - Fee lines properties](#order-refund---fee-lines-properties)                                                                                 |
| `api_refund`       | boolean   | When true, the payment gateway API is used to generate the refund. Default is `true`. `WRITE-ONLY`                                              |
| `api_restock`      | boolean   | When true, the selected line items are restocked Default is `true`. `WRITE-ONLY`                                                                |
| `compute_totals`   | boolean   | When true, the server computes per-line refund amounts from quantities and validates the request against the order's refund history. Available since WooCommerce 11.1. See [Server-computed refunds](#server-computed-refunds-compute_totals). Default is `false`. `WRITE-ONLY` |

### Order refund - Meta data properties

| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

### Order refund - Line items properties

| Attribute      | Type    | Description                                                                                                                                     |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | integer | Item ID. `READ-ONLY`                                                                                              |
| `name`         | string  | Product name.                                                                                                                                   |
| `product_id`   | integer | Product ID.                                                                                                                                     |
| `variation_id` | integer | Variation ID, if applicable.                                                                                                                    |
| `quantity`     | integer | Quantity ordered.                                                                                                                               |
| `tax_class`    | string  | Tax class of product.                                                                                                                           |
| `subtotal`     | string  | Line subtotal (before discounts).                                                                                                               |
| `subtotal_tax` | string  | Line subtotal tax (before discounts). `READ-ONLY`                                                                 |
| `total`        | string  | Line total (after discounts).                                                                                                                   |
| `total_tax`    | string  | Line total tax (after discounts). `READ-ONLY`                                                                     |
| `taxes`        | array   | Line taxes. See [Order refund line item - Taxes properties](#order-refund-line-item---taxes-properties) `READ-ONLY` |
| `meta_data`    | array   | Meta data. See [Order refund - Meta data properties](#order-refund---meta-data-properties)                                                        |
| `sku`          | string  | Product SKU. `READ-ONLY`                                                                                          |
| `price`        | string  | Product price. `READ-ONLY`                                                                                        |

#### Order refund line item - Taxes properties

| Attribute  | Type    | Description                                             |
| ---------- | ------- | ------------------------------------------------------- |
| `id`       | integer | Tax rate ID. `READ-ONLY`  |
| `total`    | string  | Tax total. `READ-ONLY`    |
| `subtotal` | string  | Tax subtotal. `READ-ONLY` |

### Order refund - Tax lines properties

| Attribute            | Type    | Description                                                                              |
| -------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`                 | integer | Item ID. `READ-ONLY`                                       |
| `rate_code`          | string  | Tax rate code. `READ-ONLY`                                 |
| `rate_id`            | integer | Tax rate ID. `READ-ONLY`                                   |
| `label`              | string  | Tax rate label. `READ-ONLY`                                |
| `compound`           | boolean | Whether or not this is a compound tax rate. `READ-ONLY`    |
| `tax_total`          | string  | Tax total (not including shipping taxes). `READ-ONLY`      |
| `shipping_tax_total` | string  | Shipping tax total. `READ-ONLY`                            |
| `meta_data`          | array   | Meta data. See [Order refund - Meta data properties](#order-refund---meta-data-properties) |

### Order refund - Shipping lines properties

| Attribute      | Type    | Description                                                                                                                         |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | integer | Item ID. `READ-ONLY`                                                                                  |
| `method_title` | string  | Shipping method name.                                                                                                               |
| `method_id`    | string  | Shipping method ID.                                                                                                                 |
| `total`        | string  | Line total (after discounts).                                                                                                       |
| `total_tax`    | string  | Line total tax (after discounts). `READ-ONLY`                                                         |
| `taxes`        | array   | Line taxes. See [Order refund - Tax lines properties](#order-refund---tax-lines-properties) `READ-ONLY` |
| `meta_data`    | array   | Meta data. See [Order refund - Meta data properties](#order-refund---meta-data-properties)                                            |

### Order refund - Fee lines properties

| Attribute    | Type    | Description                                                                                                                         |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | integer | Item ID. `READ-ONLY`                                                                                  |
| `name`       | string  | Fee name.                                                                                                                           |
| `tax_class`  | string  | Tax class of fee.                                                                                                                   |
| `tax_status` | string  | Tax status of fee. Options: `taxable` and `none`.                                                                                   |
| `total`      | string  | Line total (after discounts).                                                                                                       |
| `total_tax`  | string  | Line total tax (after discounts). `READ-ONLY`                                                         |
| `taxes`      | array   | Line taxes. See [Order refund - Tax lines properties](#order-refund---tax-lines-properties) `READ-ONLY` |
| `meta_data`  | array   | Meta data. See [Order refund - Meta data properties](#order-refund---meta-data-properties)                                            |

## Create a refund

This API helps you to create a new refund for an order.

```http
POST /wp-json/wc/v3/orders/<id>/refunds
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/orders/723/refunds \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "amount": "30",
  "line_items": [
    {
      "id": "111",
      "refund_total": 10,
      "refund_tax": [
        {
          "id": "222",
          "refund_total": 20
        }
      ]
    }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	amount: '30',
	line_items: [
		{
			id: '111',
			refund_total: 10,
			refund_tax: [
				{
					id: '222',
					refund_total: 20,
				},
			],
		},
	],
};

WooCommerce.post( 'orders/723/refunds', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
     'amount' => '30',
     'line_items' => [
       [
           'id' => '111',
           'refund_total' => 10,
           'refund_tax' => [
              [
                 'id' => '222',
                 'amount' => 20
              ]
           ]
       ]
     ]
];

print_r($woocommerce->post('orders/723/refunds', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "amount": "30",
    "line_items": [
      {
         "id": "111",
         "refund_total": 10,
         "refund_tax": [
           {
             "id": "222",
             "refund_total": 20
           }
         ]
      }
   ]
}

print(wcapi.post("orders/723/refunds", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  amount: "30",
  line_items: [
    {
       id: "111",
       refund_total: 10,
       refund_tax: [
         {
           id: "222",
           refund_total: 20
         }
       ]
    }
 ]
}

woocommerce.post("orders/723/refunds", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 726,
	"date_created": "2017-03-21T17:07:11",
	"date_created_gmt": "2017-03-21T20:07:11",
	"amount": "10.00",
	"reason": "",
	"refunded_by": 1,
	"refunded_payment": false,
	"meta_data": [],
	"line_items": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Line item parameters

| Parameter      | Type    | Description                                                                |
| -------------- | ------- | -------------------------------------------------------------------------- |
| `id`           | integer | The ID of the line item in the order.                                      |
| `refund_total` | number  | The amount to refund for this line item, excluding taxes.                  |
| `refund_tax`   | array   | Refunds for tax rates. See [Refund tax parameters](#refund-tax-parameters) |

#### Refund tax parameters

| Parameter      | Type    | Description                                     |
| -------------- | ------- | ----------------------------------------------- |
| `id`           | integer | The ID of the tax rate.                         |
| `refund_total` | number  | The amount of tax to refund for this line item. |

### Server-computed refunds (compute_totals)

Available since WooCommerce 11.1.

Set `compute_totals` to `true` to have the server compute per-line refund amounts instead of supplying them. Line items may then send only `id` and `quantity`: the server derives each line's refund amount from the order's stored unit prices and taxes, caps it to the line's remaining refundable amount, and validates the whole request against the order's refund history. The refund `amount` is derived from the line items unless supplied explicitly.

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/orders/723/refunds \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "compute_totals": true,
  "line_items": [
    {
      "id": 111,
      "quantity": 1
    }
  ]
}'
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 726,
	"date_created": "2026-08-06T17:07:11",
	"date_created_gmt": "2026-08-06T20:07:11",
	"amount": "110.00",
	"reason": "",
	"refunded_by": 1,
	"refunded_payment": false,
	"meta_data": [],
	"line_items": [ ]
}
```

  </TabItem>
</Tabs>

#### Line item parameters with compute_totals

| Parameter      | Type    | Description                                                                                                                                                            |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | integer | The ID of the line item in the order. Each line item may appear only once per request.                                                                                 |
| `quantity`     | integer | The number of units to refund. The server computes the amount for the quantity.                                                                                        |
| `refund_total` | number  | Optional explicit amount for this line. Tax-inclusive when `refund_tax` is omitted (the server splits the tax portion out); tax-exclusive when `refund_tax` is supplied. |
| `refund_tax`   | array   | Optional explicit tax refunds. See [Refund tax parameters](#refund-tax-parameters)                                                                                       |

When `amount` is supplied together with `compute_totals`, it must be at least the computed line items total and no more than the order's remaining refundable amount. Requests that exceed what is still refundable are rejected with HTTP 400 or 422 and error codes such as `woocommerce_rest_invalid_refund_amount`, `woocommerce_rest_refund_exceeds_remaining`, `woocommerce_rest_quantity_exceeds_refundable`, and `woocommerce_rest_duplicate_line_item`.

::::warning Older stores silently ignore compute_totals

Stores running WooCommerce below 11.1 drop the unknown `compute_totals` parameter and process the request with the classic behavior. A quantity-only request then creates a refund of `0.00` instead of the intended amount. Before sending computed-form requests, verify that the store supports the flag:

- Send `OPTIONS /wp-json/wc/v3/orders/<id>/refunds` and check that `compute_totals` is listed in the endpoint arguments, or
- Probe `POST /wp-json/wc/v3/orders/<id>/refunds/preview`, which returns `rest_no_route` with HTTP 404 on stores without support.

::::

## Preview a refund

Available since WooCommerce 11.1.

This API computes the totals a refund would have, without creating it. The preview uses the same calculation engine as refund creation with `compute_totals`, so clients do not have to replicate tax, rounding, and currency-precision logic. It requires the same capability as creating a refund.

```http
POST /wp-json/wc/v3/orders/<id>/refunds/preview
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/orders/723/refunds/preview \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "line_items": [
    {
      "line_item_id": 111,
      "quantity": 1
    }
  ]
}'
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"breakdown": {
		"products": {
			"items": [
				{
					"id": 111,
					"name": "T-Shirt",
					"quantity": 1,
					"subtotal": "100.00",
					"tax": "10.00",
					"total": "110.00",
					"product_id": 93
				}
			],
			"subtotal": "100.00",
			"tax": "10.00",
			"total": "110.00"
		},
		"shipping": {
			"items": [],
			"subtotal": "0.00",
			"tax": "0.00",
			"total": "0.00"
		},
		"fees": {
			"items": [],
			"subtotal": "0.00",
			"tax": "0.00",
			"total": "0.00"
		}
	},
	"subtotal": "100.00",
	"tax": "10.00",
	"total": "110.00",
	"max_refundable": "110.00"
}
```

  </TabItem>
</Tabs>

#### Preview line item parameters

| Parameter      | Type    | Description                                                                                                          |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `line_item_id` | integer | The ID of the line item in the order. Note that the preview keys lines by `line_item_id` where the create endpoint uses `id`. |
| `quantity`     | integer | The number of units to preview. Shipping and fee lines must use a quantity of 1.                                     |
| `refund_total` | number  | Optional explicit tax-inclusive amount for this line.                                                                |

#### Preview response properties

| Attribute        | Type   | Description                                                                                             |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `breakdown`      | object | Refund breakdown by item type: `products`, `shipping`, and `fees`, each with `items`, `subtotal`, `tax`, and `total`. `READ-ONLY` |
| `subtotal`       | string | Grand subtotal of the refund preview, excluding tax. `READ-ONLY`                                        |
| `tax`            | string | Grand tax total of the refund preview. `READ-ONLY`                                                      |
| `total`          | string | Grand total of the refund preview, tax-inclusive. `READ-ONLY`                                           |
| `max_refundable` | string | Maximum refundable amount remaining on the order. `READ-ONLY`                                           |

Invalid requests return the same errors as creation with `compute_totals`, for example `woocommerce_rest_invalid_refund_amount` for a non-positive total and `woocommerce_rest_preview_exceeds_max_refundable` with HTTP 422 when the preview exceeds the remaining refundable amount.

## Retrieve a refund

This API lets you retrieve and view a specific refund from an order.

```http
GET /wp-json/wc/v3/orders/<id>/refunds/<refund_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/orders/723/refunds/726 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'orders/723/refunds/726' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/723/refunds/726')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/refunds/726").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/723/refunds/726").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 726,
	"date_created": "2017-03-21T17:07:11",
	"date_created_gmt": "2017-03-21T20:07:11",
	"amount": "10.00",
	"reason": "",
	"refunded_by": 1,
	"refunded_payment": false,
	"meta_data": [],
	"line_items": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                       |
| --------- | ------ | ------------------------------------------------- |
| `dp`      | string | Number of decimal points to use in each resource. |

## List all refunds

This API helps you to view all the refunds from an order.

Note: To view a list of refunds from your store, regardless of order, check out the [refunds endpoint](../refunds).

```http
GET /wp-json/wc/v3/orders/<id>/refunds
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/orders/723/refunds \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'orders/723/refunds' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/723/refunds')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/723/refunds").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/723/refunds").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 726,
		"date_created": "2017-03-21T17:07:11",
		"date_created_gmt": "2017-03-21T20:07:11",
		"amount": "10.00",
		"reason": "",
		"refunded_by": 1,
		"refunded_payment": false,
		"meta_data": [],
		"line_items": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	},
	{
		"id": 724,
		"date_created": "2017-03-21T16:55:37",
		"date_created_gmt": "2017-03-21T19:55:37",
		"amount": "9.00",
		"reason": "",
		"refunded_by": 1,
		"refunded_payment": false,
		"meta_data": [],
		"line_items": [
			{
				"id": 314,
				"name": "Woo Album #2",
				"product_id": 87,
				"variation_id": 0,
				"quantity": -1,
				"tax_class": "",
				"subtotal": "-9.00",
				"subtotal_tax": "0.00",
				"total": "-9.00",
				"total_tax": "0.00",
				"taxes": [],
				"meta_data": [
					{
						"id": 2076,
						"key": "_refunded_item_id",
						"value": "311"
					}
				],
				"sku": "",
				"price": -9
			}
		],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/724"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter        | Type    | Description                                                                                                                  |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `context`        | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |
| `page`           | integer | Current page of the collection. Default is `1`.                                                                              |
| `per_page`       | integer | Maximum number of items to be returned in result set. Default is `10`.                                                       |
| `search`         | string  | Limit results to those matching a string.                                                                                    |
| `after`          | string  | Limit response to resources published after a given ISO8601 compliant date.                                                  |
| `before`         | string  | Limit response to resources published before a given ISO8601 compliant date.                                                 |
| `dates_are_gmt`  | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                     |
| `exclude`        | array   | Ensure result set excludes specific IDs.                                                                                     |
| `include`        | array   | Limit result set to specific ids.                                                                                            |
| `offset`         | integer | Offset the result set by a specific number of items.                                                                         |
| `order`          | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                  |
| `orderby`        | string  | Sort collection by object attribute. Options: `date`, `modified`, `id`, `include`, `title` and `slug`. Default is `date`.    |
| `parent`         | array   | Limit result set to those of particular parent IDs.                                                                          |
| `parent_exclude` | array   | Limit result set to all items except those of a particular parent ID.                                                        |
| `dp`             | integer | Number of decimal points to use in each resource. Default is `2`.                                                            |

## Delete a refund

This API helps you delete an order refund.

```http
DELETE /wp-json/wc/v3/orders/<id>/refunds/<refund_id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/orders/723/refunds/726?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'orders/723/refunds/726', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/723/refunds/726', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/723/refunds/726", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/723/refunds/726", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 726,
	"date_created": "2017-03-21T17:07:11",
	"date_created_gmt": "2017-03-21T20:07:11",
	"amount": "10.00",
	"reason": "",
	"refunded_by": 1,
	"refunded_payment": false,
	"meta_data": [],
	"line_items": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## Orders

*Source: apis/rest-api/v3/orders.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Orders

The orders API allows you to create, view, update, and delete individual, or a batch, of orders.

## Order properties

| Attribute              | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `parent_id`            | integer   | Parent order ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `number`               | string    | Order number. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `order_key`            | string    | Order key. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `created_via`          | string    | Shows where the order was created. It can only be set during order creation and cannot be modified afterward.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `version`              | string    | Version of WooCommerce which last updated the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `status`               | string    | Order status. Options: `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded`, `failed` and `trash`. Default is `pending`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `currency`             | string    | Currency the order was created with, in ISO format. Options: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BRL`, `BSD`, `BTC`, `BTN`, `BWP`, `BYR`, `BZD`, `CAD`, `CDF`, `CHF`, `CLP`, `CNY`, `COP`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GGP`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `IMP`, `INR`, `IQD`, `IRR`, `IRT`, `ISK`, `JEP`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRO`, `MUR`, `MVR`, `MWK`, `MXN`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PRB`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `STD`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `UYU`, `UZS`, `VEF`, `VND`, `VUV`, `WST`, `XAF`, `XCD`, `XOF`, `XPF`, `YER`, `ZAR` and `ZMW`. Default is `USD`. |
| `date_created`         | date-time | The date the order was created, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `date_created_gmt`     | date-time | The date the order was created, as GMT. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `date_modified`        | date-time | The date the order was last modified, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `date_modified_gmt`    | date-time | The date the order was last modified, as GMT. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `discount_total`       | string    | Total discount amount for the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `discount_tax`         | string    | Total discount tax amount for the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `shipping_total`       | string    | Total shipping amount for the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `shipping_tax`         | string    | Total shipping tax amount for the order. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `cart_tax`             | string    | Sum of line item taxes only. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `total`                | string    | Grand total. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `total_tax`            | string    | Sum of all taxes. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `prices_include_tax`   | boolean   | True the prices included tax during checkout. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `customer_id`          | integer   | User ID who owns the order. 0 for guests. Default is `0`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `customer_ip_address`  | string    | Customer's IP address. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `customer_user_agent`  | string    | User agent of the customer. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `customer_note`        | string    | Note left by customer during checkout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `billing`              | object    | Billing address. See [Order - Billing properties](#order---billing-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `shipping`             | object    | Shipping address. See [Order - Shipping properties](#order---shipping-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `payment_method`       | string    | Payment method ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `payment_method_title` | string    | Payment method title.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `transaction_id`       | string    | Unique transaction ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `date_paid`            | date-time | The date the order was paid, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `date_paid_gmt`        | date-time | The date the order was paid, as GMT. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `date_completed`       | date-time | The date the order was completed, in the site's timezone. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `date_completed_gmt`   | date-time | The date the order was completed, as GMT. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `cart_hash`            | string    | MD5 hash of cart items to ensure orders are not modified. `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `meta_data`            | array     | Meta data. See [Order - Meta data properties](#order---meta-data-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `line_items`           | array     | Line items data. See [Order - Line items properties](#order---line-items-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `tax_lines`            | array     | Tax lines data. See [Order - Tax lines properties](#order---tax-lines-properties) `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `shipping_lines`       | array     | Shipping lines data. See [Order - Shipping lines properties](#order---shipping-lines-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `fee_lines`            | array     | Fee lines data. See [Order - Fee lines properties](#order---fee-lines-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `coupon_lines`         | array     | Coupons line data. See [Order - Coupon lines properties](#order---coupon-lines-properties)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `refunds`              | array     | List of refunds. See [Order - Refunds properties](#order---refunds-properties) `READ-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `set_paid`             | boolean   | Define if the order is paid. It will set the status to processing and reduce stock items. Default is `false`. `WRITE-ONLY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Order - Billing properties

| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1                                       |
| `address_2`  | string | Address line 2                                       |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | Country code in ISO 3166-1 alpha-2 format.           |
| `email`      | string | Email address.                                       |
| `phone`      | string | Phone number.                                        |

### Order - Shipping properties

| Attribute    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `first_name` | string | First name.                                          |
| `last_name`  | string | Last name.                                           |
| `company`    | string | Company name.                                        |
| `address_1`  | string | Address line 1                                       |
| `address_2`  | string | Address line 2                                       |
| `city`       | string | City name.                                           |
| `state`      | string | ISO code or name of the state, province or district. |
| `postcode`   | string | Postal code.                                         |
| `country`    | string | Country code in ISO 3166-1 alpha-2 format.           |

### Order - Meta data properties

| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

### Order - Line items properties

| Attribute      | Type    | Description                                                                                                           |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `id`           | integer | Item ID. `READ-ONLY`                                                                    |
| `name`         | string  | Product name.                                                                                                         |
| `parent_name`  | string or null | Parent product name if the product is a variation; otherwise `null`.                                              |
| `product_id`   | integer | Product ID.                                                                                                           |
| `variation_id` | integer | Variation ID, if applicable.                                                                                          |
| `quantity`     | integer | Quantity ordered.                                                                                                     |
| `tax_class`    | string  | Slug of the tax class of product.                                                                                     |
| `subtotal`     | string  | Line subtotal (before discounts).                                                                                     |
| `subtotal_tax` | string  | Line subtotal tax (before discounts). `READ-ONLY`                                       |
| `total`        | string  | Line total (after discounts).                                                                                         |
| `total_tax`    | string  | Line total tax (after discounts). `READ-ONLY`                                           |
| `taxes`        | array   | Line taxes. See [Order - Tax lines properties](#order---tax-lines-properties) `READ-ONLY` |
| `meta_data`    | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)                                            |
| `sku`          | string  | Product SKU. `READ-ONLY`                                                                |
| `global_unique_id` | string or null | Product GTIN, UPC, EAN or ISBN. An empty string if not set, or `null` if the product no longer exists. `READ-ONLY` |
| `price`        | string  | Product price. `READ-ONLY`                                                              |
| `image`        | object  | Main product image. See [Order - Line item image properties](#order---line-item-image-properties). `READ-ONLY` |

### Order - Line item image properties

| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `id` | integer or string | Image attachment ID, returned as an integer or numeric string. An empty string or `0` if no image is set; `0` if the product no longer exists. `READ-ONLY` |
| `src` | string or boolean | Full-size image URL. An empty string if no image is set or the product no longer exists, or `false` if the attachment cannot be resolved. `READ-ONLY` |

### Order - Tax lines properties

| Attribute            | Type    | Description                                                                           |
| -------------------- | ------- | ------------------------------------------------------------------------------------- |
| `id`                 | integer | Item ID. `READ-ONLY`                                    |
| `rate_code`          | string  | Tax rate code. `READ-ONLY`                              |
| `rate_id`            | integer | Tax rate ID. `READ-ONLY`                                |
| `label`              | string  | Tax rate label. `READ-ONLY`                             |
| `compound`           | boolean | Whether or not this is a compound tax rate. `READ-ONLY` |
| `tax_total`          | string  | Tax total (not including shipping taxes). `READ-ONLY`   |
| `shipping_tax_total` | string  | Shipping tax total. `READ-ONLY`                         |
| `meta_data`          | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)            |

### Order - Shipping lines properties

| Attribute      | Type    | Description                                                                                                           |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `id`           | integer | Item ID. `READ-ONLY`                                                                    |
| `method_title` | string  | Shipping method name.                                                                                                 |
| `method_id`    | string  | Shipping method ID.                                                                                                   |
| `total`        | string  | Line total (after discounts).                                                                                         |
| `total_tax`    | string  | Line total tax (after discounts). `READ-ONLY`                                           |
| `taxes`        | array   | Line taxes. See [Order - Tax lines properties](#order---tax-lines-properties) `READ-ONLY` |
| `meta_data`    | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)                                            |

### Order - Fee lines properties

| Attribute    | Type    | Description                                                                                                           |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `id`         | integer | Item ID. `READ-ONLY`                                                                    |
| `name`       | string  | Fee name.                                                                                                             |
| `tax_class`  | string  | Tax class of fee.                                                                                                     |
| `tax_status` | string  | Tax status of fee. Options: `taxable` and `none`.                                                                     |
| `total`      | string  | Line total (after discounts).                                                                                         |
| `total_tax`  | string  | Line total tax (after discounts). `READ-ONLY`                                           |
| `taxes`      | array   | Line taxes. See [Order - Tax lines properties](#order---tax-lines-properties) `READ-ONLY` |
| `meta_data`  | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties)                                            |

### Order - Coupon lines properties

| Attribute      | Type    | Description                                                                |
| -------------- | ------- | -------------------------------------------------------------------------- |
| `id`           | integer | Item ID. `READ-ONLY`                         |
| `code`         | string  | Coupon code.                                                               |
| `discount`     | string  | Discount total. `READ-ONLY`                  |
| `discount_tax` | string  | Discount total tax. `READ-ONLY`              |
| `meta_data`    | array   | Meta data. See [Order - Meta data properties](#order---meta-data-properties) |

### Order - Refunds properties

| Attribute | Type    | Description                                              |
| --------- | ------- | -------------------------------------------------------- |
| `id`      | integer | Refund ID. `READ-ONLY`     |
| `reason`  | string  | Refund reason. `READ-ONLY` |
| `total`   | string  | Refund total. `READ-ONLY`  |

## Create an order

This API helps you to create a new order.

```http
POST /wp-json/wc/v3/orders
```

> Example of create a paid order:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/orders \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "line_items": [
    {
      "product_id": 93,
      "quantity": 2
    },
    {
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1
    }
  ],
  "shipping_lines": [
    {
      "method_id": "flat_rate",
      "method_title": "Flat Rate",
      "total": "10.00"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	payment_method: 'bacs',
	payment_method_title: 'Direct Bank Transfer',
	set_paid: true,
	billing: {
		first_name: 'John',
		last_name: 'Doe',
		address_1: '969 Market',
		address_2: '',
		city: 'San Francisco',
		state: 'CA',
		postcode: '94103',
		country: 'US',
		email: 'john.doe@example.com',
		phone: '(555) 555-5555',
	},
	shipping: {
		first_name: 'John',
		last_name: 'Doe',
		address_1: '969 Market',
		address_2: '',
		city: 'San Francisco',
		state: 'CA',
		postcode: '94103',
		country: 'US',
	},
	line_items: [
		{
			product_id: 93,
			quantity: 2,
		},
		{
			product_id: 22,
			variation_id: 23,
			quantity: 1,
		},
	],
	shipping_lines: [
		{
			method_id: 'flat_rate',
			method_title: 'Flat Rate',
			total: '10.00',
		},
	],
};

WooCommerce.post( 'orders', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'payment_method' => 'bacs',
    'payment_method_title' => 'Direct Bank Transfer',
    'set_paid' => true,
    'billing' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US',
        'email' => 'john.doe@example.com',
        'phone' => '(555) 555-5555'
    ],
    'shipping' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'address_1' => '969 Market',
        'address_2' => '',
        'city' => 'San Francisco',
        'state' => 'CA',
        'postcode' => '94103',
        'country' => 'US'
    ],
    'line_items' => [
        [
            'product_id' => 93,
            'quantity' => 2
        ],
        [
            'product_id' => 22,
            'variation_id' => 23,
            'quantity' => 1
        ]
    ],
    'shipping_lines' => [
        [
            'method_id' => 'flat_rate',
            'method_title' => 'Flat Rate',
            'total' => '10.00'
        ]
    ]
];

print_r($woocommerce->post('orders', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "payment_method": "bacs",
    "payment_method_title": "Direct Bank Transfer",
    "set_paid": True,
    "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
    },
    "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
    },
    "line_items": [
        {
            "product_id": 93,
            "quantity": 2
        },
        {
            "product_id": 22,
            "variation_id": 23,
            "quantity": 1
        }
    ],
    "shipping_lines": [
        {
            "method_id": "flat_rate",
            "method_title": "Flat Rate",
            "total": "10.00"
        }
    ]
}

print(wcapi.post("orders", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  payment_method: "bacs",
  payment_method_title: "Direct Bank Transfer",
  set_paid: true,
  billing: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US",
    email: "john.doe@example.com",
    phone: "(555) 555-5555"
  },
  shipping: {
    first_name: "John",
    last_name: "Doe",
    address_1: "969 Market",
    address_2: "",
    city: "San Francisco",
    state: "CA",
    postcode: "94103",
    country: "US"
  },
  line_items: [
    {
      product_id: 93,
      quantity: 2
    },
    {
      product_id: 22,
      variation_id: 23,
      quantity: 1
    }
  ],
  shipping_lines: [
    {
      method_id: "flat_rate",
      method_title: "Flat Rate",
      total: "10.00"
    }
  ]
}

woocommerce.post("orders", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 727,
	"parent_id": 0,
	"number": "727",
	"order_key": "wc_order_58d2d042d1d",
	"created_via": "rest-api",
	"version": "3.0.0",
	"status": "processing",
	"currency": "USD",
	"date_created": "2017-03-22T16:28:02",
	"date_created_gmt": "2017-03-22T19:28:02",
	"date_modified": "2017-03-22T16:28:08",
	"date_modified_gmt": "2017-03-22T19:28:08",
	"discount_total": "0.00",
	"discount_tax": "0.00",
	"shipping_total": "10.00",
	"shipping_tax": "0.00",
	"cart_tax": "1.35",
	"total": "29.35",
	"total_tax": "1.35",
	"prices_include_tax": false,
	"customer_id": 0,
	"customer_ip_address": "",
	"customer_user_agent": "",
	"customer_note": "",
	"billing": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US",
		"email": "john.doe@example.com",
		"phone": "(555) 555-5555"
	},
	"shipping": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US"
	},
	"payment_method": "bacs",
	"payment_method_title": "Direct Bank Transfer",
	"transaction_id": "",
	"date_paid": "2017-03-22T16:28:08",
	"date_paid_gmt": "2017-03-22T19:28:08",
	"date_completed": null,
	"date_completed_gmt": null,
	"cart_hash": "",
	"meta_data": [
		{
			"id": 13106,
			"key": "_download_permissions_granted",
			"value": "yes"
		}
	],
	"line_items": [
		{
			"id": 315,
			"name": "Woo Single #1",
			"product_id": 93,
			"variation_id": 0,
			"quantity": 2,
			"tax_class": "",
			"subtotal": "6.00",
			"subtotal_tax": "0.45",
			"total": "6.00",
			"total_tax": "0.45",
			"taxes": [
				{
					"id": 75,
					"total": "0.45",
					"subtotal": "0.45"
				}
			],
			"meta_data": [],
			"sku": "",
			"price": 3
		},
		{
			"id": 316,
			"name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
			"product_id": 22,
			"variation_id": 23,
			"quantity": 1,
			"tax_class": "",
			"subtotal": "12.00",
			"subtotal_tax": "0.90",
			"total": "12.00",
			"total_tax": "0.90",
			"taxes": [
				{
					"id": 75,
					"total": "0.9",
					"subtotal": "0.9"
				}
			],
			"meta_data": [
				{
					"id": 2095,
					"key": "pa_color",
					"value": "black"
				},
				{
					"id": 2096,
					"key": "size",
					"value": "M Test"
				}
			],
			"sku": "Bar3",
			"price": 12
		}
	],
	"tax_lines": [
		{
			"id": 318,
			"rate_code": "US-CA-STATE TAX",
			"rate_id": 75,
			"label": "State Tax",
			"compound": false,
			"tax_total": "1.35",
			"shipping_tax_total": "0.00",
			"meta_data": []
		}
	],
	"shipping_lines": [
		{
			"id": 317,
			"method_title": "Flat Rate",
			"method_id": "flat_rate",
			"total": "10.00",
			"total_tax": "0.00",
			"taxes": [],
			"meta_data": []
		}
	],
	"fee_lines": [],
	"coupon_lines": [],
	"refunds": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/727"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve an order

This API lets you retrieve and view a specific order.

```http
GET /wp-json/wc/v3/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/orders/727 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'orders/727' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders/727')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders/727").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders/727").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 727,
	"parent_id": 0,
	"number": "727",
	"order_key": "wc_order_58d2d042d1d",
	"created_via": "rest-api",
	"version": "3.0.0",
	"status": "processing",
	"currency": "USD",
	"date_created": "2017-03-22T16:28:02",
	"date_created_gmt": "2017-03-22T19:28:02",
	"date_modified": "2017-03-22T16:28:08",
	"date_modified_gmt": "2017-03-22T19:28:08",
	"discount_total": "0.00",
	"discount_tax": "0.00",
	"shipping_total": "10.00",
	"shipping_tax": "0.00",
	"cart_tax": "1.35",
	"total": "29.35",
	"total_tax": "1.35",
	"prices_include_tax": false,
	"customer_id": 0,
	"customer_ip_address": "",
	"customer_user_agent": "",
	"customer_note": "",
	"billing": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US",
		"email": "john.doe@example.com",
		"phone": "(555) 555-5555"
	},
	"shipping": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US"
	},
	"payment_method": "bacs",
	"payment_method_title": "Direct Bank Transfer",
	"transaction_id": "",
	"date_paid": "2017-03-22T16:28:08",
	"date_paid_gmt": "2017-03-22T19:28:08",
	"date_completed": null,
	"date_completed_gmt": null,
	"cart_hash": "",
	"meta_data": [
		{
			"id": 13106,
			"key": "_download_permissions_granted",
			"value": "yes"
		}
	],
	"line_items": [
		{
			"id": 315,
			"name": "Woo Single #1",
			"product_id": 93,
			"variation_id": 0,
			"quantity": 2,
			"tax_class": "",
			"subtotal": "6.00",
			"subtotal_tax": "0.45",
			"total": "6.00",
			"total_tax": "0.45",
			"taxes": [
				{
					"id": 75,
					"total": "0.45",
					"subtotal": "0.45"
				}
			],
			"meta_data": [],
			"sku": "",
			"price": 3
		},
		{
			"id": 316,
			"name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
			"product_id": 22,
			"variation_id": 23,
			"quantity": 1,
			"tax_class": "",
			"subtotal": "12.00",
			"subtotal_tax": "0.90",
			"total": "12.00",
			"total_tax": "0.90",
			"taxes": [
				{
					"id": 75,
					"total": "0.9",
					"subtotal": "0.9"
				}
			],
			"meta_data": [
				{
					"id": 2095,
					"key": "pa_color",
					"value": "black"
				},
				{
					"id": 2096,
					"key": "size",
					"value": "M Test"
				}
			],
			"sku": "Bar3",
			"price": 12
		}
	],
	"tax_lines": [
		{
			"id": 318,
			"rate_code": "US-CA-STATE TAX",
			"rate_id": 75,
			"label": "State Tax",
			"compound": false,
			"tax_total": "1.35",
			"shipping_tax_total": "0.00",
			"meta_data": []
		}
	],
	"shipping_lines": [
		{
			"id": 317,
			"method_title": "Flat Rate",
			"method_id": "flat_rate",
			"total": "10.00",
			"total_tax": "0.00",
			"taxes": [],
			"meta_data": []
		}
	],
	"fee_lines": [],
	"coupon_lines": [],
	"refunds": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/727"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                       |
| --------- | ------ | ------------------------------------------------- |
| `dp`      | string | Number of decimal points to use in each resource. |

## List all orders

This API helps you to view all the orders.

```http
GET /wp-json/wc/v3/orders
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/orders \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'orders' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('orders')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("orders").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("orders").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 727,
		"parent_id": 0,
		"number": "727",
		"order_key": "wc_order_58d2d042d1d",
		"created_via": "rest-api",
		"version": "3.0.0",
		"status": "processing",
		"currency": "USD",
		"date_created": "2017-03-22T16:28:02",
		"date_created_gmt": "2017-03-22T19:28:02",
		"date_modified": "2017-03-22T16:28:08",
		"date_modified_gmt": "2017-03-22T19:28:08",
		"discount_total": "0.00",
		"discount_tax": "0.00",
		"shipping_total": "10.00",
		"shipping_tax": "0.00",
		"cart_tax": "1.35",
		"total": "29.35",
		"total_tax": "1.35",
		"prices_include_tax": false,
		"customer_id": 0,
		"customer_ip_address": "",
		"customer_user_agent": "",
		"customer_note": "",
		"billing": {
			"first_name": "John",
			"last_name": "Doe",
			"company": "",
			"address_1": "969 Market",
			"address_2": "",
			"city": "San Francisco",
			"state": "CA",
			"postcode": "94103",
			"country": "US",
			"email": "john.doe@example.com",
			"phone": "(555) 555-5555"
		},
		"shipping": {
			"first_name": "John",
			"last_name": "Doe",
			"company": "",
			"address_1": "969 Market",
			"address_2": "",
			"city": "San Francisco",
			"state": "CA",
			"postcode": "94103",
			"country": "US"
		},
		"payment_method": "bacs",
		"payment_method_title": "Direct Bank Transfer",
		"transaction_id": "",
		"date_paid": "2017-03-22T16:28:08",
		"date_paid_gmt": "2017-03-22T19:28:08",
		"date_completed": null,
		"date_completed_gmt": null,
		"cart_hash": "",
		"meta_data": [
			{
				"id": 13106,
				"key": "_download_permissions_granted",
				"value": "yes"
			},
			{
				"id": 13109,
				"key": "_order_stock_reduced",
				"value": "yes"
			}
		],
		"line_items": [
			{
				"id": 315,
				"name": "Woo Single #1",
				"product_id": 93,
				"variation_id": 0,
				"quantity": 2,
				"tax_class": "",
				"subtotal": "6.00",
				"subtotal_tax": "0.45",
				"total": "6.00",
				"total_tax": "0.45",
				"taxes": [
					{
						"id": 75,
						"total": "0.45",
						"subtotal": "0.45"
					}
				],
				"meta_data": [],
				"sku": "",
				"price": 3
			},
			{
				"id": 316,
				"name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
				"product_id": 22,
				"variation_id": 23,
				"quantity": 1,
				"tax_class": "",
				"subtotal": "12.00",
				"subtotal_tax": "0.90",
				"total": "12.00",
				"total_tax": "0.90",
				"taxes": [
					{
						"id": 75,
						"total": "0.9",
						"subtotal": "0.9"
					}
				],
				"meta_data": [
					{
						"id": 2095,
						"key": "pa_color",
						"value": "black"
					},
					{
						"id": 2096,
						"key": "size",
						"value": "M Test"
					}
				],
				"sku": "Bar3",
				"price": 12
			}
		],
		"tax_lines": [
			{
				"id": 318,
				"rate_code": "US-CA-STATE TAX",
				"rate_id": 75,
				"label": "State Tax",
				"compound": false,
				"tax_total": "1.35",
				"shipping_tax_total": "0.00",
				"meta_data": []
			}
		],
		"shipping_lines": [
			{
				"id": 317,
				"method_title": "Flat Rate",
				"method_id": "flat_rate",
				"total": "10.00",
				"total_tax": "0.00",
				"taxes": [],
				"meta_data": []
			}
		],
		"fee_lines": [],
		"coupon_lines": [],
		"refunds": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/727"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders"
				}
			],
			"email_templates": [
				{
					"embeddable": true,
					"href": "http://example.com/wp-json/wc/v3/orders/723/actions/email_templates"
				}
			]
		}
	},
	{
		"id": 723,
		"parent_id": 0,
		"number": "723",
		"order_key": "wc_order_58d17c18352",
		"created_via": "checkout",
		"version": "3.0.0",
		"status": "completed",
		"currency": "USD",
		"date_created": "2017-03-21T16:16:00",
		"date_created_gmt": "2017-03-21T19:16:00",
		"date_modified": "2017-03-21T16:54:51",
		"date_modified_gmt": "2017-03-21T19:54:51",
		"discount_total": "0.00",
		"discount_tax": "0.00",
		"shipping_total": "10.00",
		"shipping_tax": "0.00",
		"cart_tax": "0.00",
		"total": "39.00",
		"total_tax": "0.00",
		"prices_include_tax": false,
		"customer_id": 26,
		"customer_ip_address": "127.0.0.1",
		"customer_user_agent": "mozilla/5.0 (x11; ubuntu; linux x86_64; rv:52.0) gecko/20100101 firefox/52.0",
		"customer_note": "",
		"billing": {
			"first_name": "João",
			"last_name": "Silva",
			"company": "",
			"address_1": "Av. Brasil, 432",
			"address_2": "",
			"city": "Rio de Janeiro",
			"state": "RJ",
			"postcode": "12345-000",
			"country": "BR",
			"email": "joao.silva@example.com",
			"phone": "(11) 1111-1111"
		},
		"shipping": {
			"first_name": "João",
			"last_name": "Silva",
			"company": "",
			"address_1": "Av. Brasil, 432",
			"address_2": "",
			"city": "Rio de Janeiro",
			"state": "RJ",
			"postcode": "12345-000",
			"country": "BR"
		},
		"payment_method": "bacs",
		"payment_method_title": "Direct bank transfer",
		"transaction_id": "",
		"date_paid": null,
		"date_paid_gmt": null,
		"date_completed": "2017-03-21T16:54:51",
		"date_completed_gmt": "2017-03-21T19:54:51",
		"cart_hash": "5040ce7273261e31d8bcf79f9be3d279",
		"meta_data": [
			{
				"id": 13023,
				"key": "_download_permissions_granted",
				"value": "yes"
			}
		],
		"line_items": [
			{
				"id": 311,
				"name": "Woo Album #2",
				"product_id": 87,
				"variation_id": 0,
				"quantity": 1,
				"tax_class": "",
				"subtotal": "9.00",
				"subtotal_tax": "0.00",
				"total": "9.00",
				"total_tax": "0.00",
				"taxes": [],
				"meta_data": [],
				"sku": "",
				"price": 9
			},
			{
				"id": 313,
				"name": "Woo Ninja",
				"product_id": 34,
				"variation_id": 0,
				"quantity": 1,
				"tax_class": "",
				"subtotal": "20.00",
				"subtotal_tax": "0.00",
				"total": "20.00",
				"total_tax": "0.00",
				"taxes": [],
				"meta_data": [],
				"sku": "",
				"price": 20
			}
		],
		"tax_lines": [],
		"shipping_lines": [
			{
				"id": 312,
				"method_title": "Flat rate",
				"method_id": "flat_rate:25",
				"total": "10.00",
				"total_tax": "0.00",
				"taxes": [],
				"meta_data": [
					{
						"id": 2057,
						"key": "Items",
						"value": "Woo Album #2 &times; 1"
					}
				]
			}
		],
		"fee_lines": [],
		"coupon_lines": [],
		"refunds": [
			{
				"id": 726,
				"refund": "",
				"total": "-10.00"
			},
			{
				"id": 724,
				"refund": "",
				"total": "-9.00"
			}
		],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders"
				}
			],
			"email_templates": [
				{
					"embeddable": true,
					"href": "http://example.com/wp-json/wc/v3/orders/723/actions/email_templates"
				}
			],
			"customer": [
				{
					"href": "https://example.com/wp-json/wc/v3/customers/26"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter         | Type    | Description                                                                                                                                                                              |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`         | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                                                             |
| `page`            | integer | Current page of the collection. Default is `1`.                                                                                                                                          |
| `per_page`        | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                                                                   |
| `search`          | string  | Limit results to those matching a string.                                                                                                                                                |
| `after`           | string  | Limit response to resources published after a given ISO8601 compliant date.                                                                                                              |
| `before`          | string  | Limit response to resources published before a given ISO8601 compliant date.                                                                                                             |
| `modified_after`  | string  | Limit response to resources modified after a given ISO8601 compliant date.                                                                                                               |
| `modified_before` | string  | Limit response to resources modified after a given ISO8601 compliant date.                                                                                                               |
| `dates_are_gmt`   | boolean | Whether to interpret dates as GMT when limiting response by published or modified date.                                                                                                  |
| `exclude`         | array   | Ensure result set excludes specific IDs.                                                                                                                                                 |
| `include`         | array   | Limit result set to specific ids.                                                                                                                                                        |
| `offset`          | integer | Offset the result set by a specific number of items.                                                                                                                                     |
| `order`           | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                                                                              |
| `orderby`         | string  | Sort collection by object attribute. Options: `date`, `modified`, `id`, `include`, `title` and `slug`. Default is `date`.                                                                |
| `parent`          | array   | Limit result set to those of particular parent IDs.                                                                                                                                      |
| `parent_exclude`  | array   | Limit result set to all items except those of a particular parent ID.                                                                                                                    |
| `status`          | array   | Limit result set to orders assigned a specific status. Options: `any`, `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded`, `failed` and `trash`. Default is `any`. |
| `customer`        | integer | Limit result set to orders assigned a specific customer.                                                                                                                                 |
| `product`         | integer | Limit result set to orders assigned a specific product.                                                                                                                                  |
| `dp`              | integer | Number of decimal points to use in each resource. Default is `2`.                                                                                                                        |
| `created_via`     | string  | Limit result set to orders created via specific sources (e.g. checkout, store-api). Multiple options can be provided as a comma-separated list.                                          |

## Update an Order

This API lets you make changes to an order.

### HTTP Request

```http
PUT /wp-json/wc/v3/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/orders/727 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "status": "completed"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	status: 'completed',
};

WooCommerce.put( 'orders/727', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'status' => 'completed'
];

print_r($woocommerce->put('orders/727', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "status": "completed"
}

print(wcapi.put("orders/727", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  status: "completed"
}

woocommerce.put("orders/727", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 727,
	"parent_id": 0,
	"number": "727",
	"order_key": "wc_order_58d2d042d1d",
	"created_via": "rest-api",
	"version": "3.0.0",
	"status": "completed",
	"currency": "USD",
	"date_created": "2017-03-22T16:28:02",
	"date_created_gmt": "2017-03-22T19:28:02",
	"date_modified": "2017-03-22T16:30:35",
	"date_modified_gmt": "2017-03-22T19:30:35",
	"discount_total": "0.00",
	"discount_tax": "0.00",
	"shipping_total": "10.00",
	"shipping_tax": "0.00",
	"cart_tax": "1.35",
	"total": "29.35",
	"total_tax": "1.35",
	"prices_include_tax": false,
	"customer_id": 0,
	"customer_ip_address": "",
	"customer_user_agent": "",
	"customer_note": "",
	"billing": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US",
		"email": "john.doe@example.com",
		"phone": "(555) 555-5555"
	},
	"shipping": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US"
	},
	"payment_method": "bacs",
	"payment_method_title": "Direct Bank Transfer",
	"transaction_id": "",
	"date_paid": "2017-03-22T16:28:08",
	"date_paid_gmt": "2017-03-22T19:28:08",
	"date_completed": "2017-03-22T16:30:35",
	"date_completed_gmt": "2017-03-22T19:30:35",
	"cart_hash": "",
	"meta_data": [
		{
			"id": 13106,
			"key": "_download_permissions_granted",
			"value": "yes"
		},
		{
			"id": 13109,
			"key": "_order_stock_reduced",
			"value": "yes"
		}
	],
	"line_items": [
		{
			"id": 315,
			"name": "Woo Single #1",
			"product_id": 93,
			"variation_id": 0,
			"quantity": 2,
			"tax_class": "",
			"subtotal": "6.00",
			"subtotal_tax": "0.45",
			"total": "6.00",
			"total_tax": "0.45",
			"taxes": [
				{
					"id": 75,
					"total": "0.45",
					"subtotal": "0.45"
				}
			],
			"meta_data": [],
			"sku": "",
			"price": 3
		},
		{
			"id": 316,
			"name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
			"product_id": 22,
			"variation_id": 23,
			"quantity": 1,
			"tax_class": "",
			"subtotal": "12.00",
			"subtotal_tax": "0.90",
			"total": "12.00",
			"total_tax": "0.90",
			"taxes": [
				{
					"id": 75,
					"total": "0.9",
					"subtotal": "0.9"
				}
			],
			"meta_data": [
				{
					"id": 2095,
					"key": "pa_color",
					"value": "black"
				},
				{
					"id": 2096,
					"key": "size",
					"value": "M Test"
				}
			],
			"sku": "Bar3",
			"price": 12
		}
	],
	"tax_lines": [
		{
			"id": 318,
			"rate_code": "US-CA-STATE TAX",
			"rate_id": 75,
			"label": "State Tax",
			"compound": false,
			"tax_total": "1.35",
			"shipping_tax_total": "0.00",
			"meta_data": []
		}
	],
	"shipping_lines": [
		{
			"id": 317,
			"method_title": "Flat Rate",
			"method_id": "flat_rate",
			"total": "10.00",
			"total_tax": "0.00",
			"taxes": [],
			"meta_data": []
		}
	],
	"fee_lines": [],
	"coupon_lines": [],
	"refunds": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/727"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

### Remove a coupon from an order

To remove an applied coupon, update the order with a `coupon_lines` array containing every coupon code that should remain. Any applied coupon omitted from the array is removed from the order. For example, if the order has `10per` and `20off`, this request removes `20off`:

```shell
curl -X PUT https://example.com/wp-json/wc/v3/orders/727 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{"coupon_lines":[{"code":"10per"}]}'
```

To remove all applied coupons, send `{"coupon_lines":[]}`. Coupon line IDs are read-only; do not send an ID with a null code to remove a coupon. This changes the coupons applied to the order, not the coupon codes available in the store.

## Delete an order

This API helps you delete an order.

```http
DELETE /wp-json/wc/v3/orders/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/orders/727?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'orders/727', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('orders/727', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("orders/727", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("orders/727", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 727,
	"parent_id": 0,
	"number": "727",
	"order_key": "wc_order_58d2d042d1d",
	"created_via": "rest-api",
	"version": "3.0.0",
	"status": "completed",
	"currency": "USD",
	"date_created": "2017-03-22T16:28:02",
	"date_created_gmt": "2017-03-22T19:28:02",
	"date_modified": "2017-03-22T16:30:35",
	"date_modified_gmt": "2017-03-22T19:30:35",
	"discount_total": "0.00",
	"discount_tax": "0.00",
	"shipping_total": "10.00",
	"shipping_tax": "0.00",
	"cart_tax": "1.35",
	"total": "29.35",
	"total_tax": "1.35",
	"prices_include_tax": false,
	"customer_id": 0,
	"customer_ip_address": "",
	"customer_user_agent": "",
	"customer_note": "",
	"billing": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US",
		"email": "john.doe@example.com",
		"phone": "(555) 555-5555"
	},
	"shipping": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "969 Market",
		"address_2": "",
		"city": "San Francisco",
		"state": "CA",
		"postcode": "94103",
		"country": "US"
	},
	"payment_method": "bacs",
	"payment_method_title": "Direct Bank Transfer",
	"transaction_id": "",
	"date_paid": "2017-03-22T16:28:08",
	"date_paid_gmt": "2017-03-22T19:28:08",
	"date_completed": "2017-03-22T16:30:35",
	"date_completed_gmt": "2017-03-22T19:30:35",
	"cart_hash": "",
	"meta_data": [
		{
			"id": 13106,
			"key": "_download_permissions_granted",
			"value": "yes"
		},
		{
			"id": 13109,
			"key": "_order_stock_reduced",
			"value": "yes"
		}
	],
	"line_items": [
		{
			"id": 315,
			"name": "Woo Single #1",
			"product_id": 93,
			"variation_id": 0,
			"quantity": 2,
			"tax_class": "",
			"subtotal": "6.00",
			"subtotal_tax": "0.45",
			"total": "6.00",
			"total_tax": "0.45",
			"taxes": [
				{
					"id": 75,
					"total": "0.45",
					"subtotal": "0.45"
				}
			],
			"meta_data": [],
			"sku": "",
			"price": 3
		},
		{
			"id": 316,
			"name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
			"product_id": 22,
			"variation_id": 23,
			"quantity": 1,
			"tax_class": "",
			"subtotal": "12.00",
			"subtotal_tax": "0.90",
			"total": "12.00",
			"total_tax": "0.90",
			"taxes": [
				{
					"id": 75,
					"total": "0.9",
					"subtotal": "0.9"
				}
			],
			"meta_data": [
				{
					"id": 2095,
					"key": "pa_color",
					"value": "black"
				},
				{
					"id": 2096,
					"key": "size",
					"value": "M Test"
				}
			],
			"sku": "Bar3",
			"price": 12
		}
	],
	"tax_lines": [
		{
			"id": 318,
			"rate_code": "US-CA-STATE TAX",
			"rate_id": 75,
			"label": "State Tax",
			"compound": false,
			"tax_total": "1.35",
			"shipping_tax_total": "0.00",
			"meta_data": []
		}
	],
	"shipping_lines": [
		{
			"id": 317,
			"method_title": "Flat Rate",
			"method_id": "flat_rate",
			"total": "10.00",
			"total_tax": "0.00",
			"taxes": [],
			"meta_data": []
		}
	],
	"fee_lines": [],
	"coupon_lines": [],
	"refunds": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/727"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                             |
| --------- | ------ | ----------------------------------------------------------------------- |
| `force`   | string | Use `true` whether to permanently delete the order, Default is `false`. |

## Batch update orders

This API helps you to batch create, update and delete multiple orders.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/orders/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/orders/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "line_items": [
        {
          "product_id": 79,
          "quantity": 1
        },
        {
          "product_id": 93,
          "quantity": 1
        },
        {
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1
        }
      ],
      "shipping_lines": [
        {
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "30.00"
        }
      ]
    },
    {
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "set_paid": true,
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "line_items": [
        {
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1
        },
        {
          "product_id": 22,
          "variation_id": 24,
          "quantity": 1
        }
      ],
      "shipping_lines": [
        {
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "20.00"
        }
      ]
    }
  ],
  "update": [
    {
      "id": 727,
      "shipping_methods": "Local Delivery"
    }
  ],
  "delete": [
    723
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			payment_method: 'bacs',
			payment_method_title: 'Direct Bank Transfer',
			billing: {
				first_name: 'John',
				last_name: 'Doe',
				address_1: '969 Market',
				address_2: '',
				city: 'San Francisco',
				state: 'CA',
				postcode: '94103',
				country: 'US',
				email: 'john.doe@example.com',
				phone: '(555) 555-5555',
			},
			shipping: {
				first_name: 'John',
				last_name: 'Doe',
				address_1: '969 Market',
				address_2: '',
				city: 'San Francisco',
				state: 'CA',
				postcode: '94103',
				country: 'US',
			},
			line_items: [
				{
					product_id: 79,
					quantity: 1,
				},
				{
					product_id: 93,
					quantity: 1,
				},
				{
					product_id: 22,
					variation_id: 23,
					quantity: 1,
				},
			],
			shipping_lines: [
				{
					method_id: 'flat_rate',
					method_title: 'Flat Rate',
					total: '30.00',
				},
			],
		},
		{
			payment_method: 'bacs',
			payment_method_title: 'Direct Bank Transfer',
			set_paid: true,
			billing: {
				first_name: 'John',
				last_name: 'Doe',
				address_1: '969 Market',
				address_2: '',
				city: 'San Francisco',
				state: 'CA',
				postcode: '94103',
				country: 'US',
				email: 'john.doe@example.com',
				phone: '(555) 555-5555',
			},
			shipping: {
				first_name: 'John',
				last_name: 'Doe',
				address_1: '969 Market',
				address_2: '',
				city: 'San Francisco',
				state: 'CA',
				postcode: '94103',
				country: 'US',
			},
			line_items: [
				{
					product_id: 22,
					variation_id: 23,
					quantity: 1,
				},
				{
					product_id: 22,
					variation_id: 24,
					quantity: 1,
				},
			],
			shipping_lines: [
				{
					method_id: 'flat_rate',
					method_title: 'Flat Rate',
					total: '20.00',
				},
			],
		},
	],
	update: [
		{
			id: 727,
			shipping_methods: 'Local Delivery',
		},
	],
	delete: [ 723 ],
};

WooCommerce.post( 'orders/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'payment_method' => 'bacs',
            'payment_method_title' => 'Direct Bank Transfer',
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ],
            'line_items' => [
                [
                    'product_id' => 79,
                    'quantity' => 1
                ],
                [
                    'product_id' => 93,
                    'quantity' => 1
                ],
                [
                    'product_id' => 22,
                    'variation_id' => 23,
                    'quantity' => 1
                ]
            ],
            'shipping_lines' => [
                [
                    'method_id' => 'flat_rate',
                    'method_title' => 'Flat Rate',
                    'total' => '30.00'
                ]
            ]
        ],
        [
            'payment_method' => 'bacs',
            'payment_method_title' => 'Direct Bank Transfer',
            'set_paid' => true,
            'billing' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US',
                'email' => 'john.doe@example.com',
                'phone' => '(555) 555-5555'
            ],
            'shipping' => [
                'first_name' => 'John',
                'last_name' => 'Doe',
                'address_1' => '969 Market',
                'address_2' => '',
                'city' => 'San Francisco',
                'state' => 'CA',
                'postcode' => '94103',
                'country' => 'US'
            ],
            'line_items' => [
                [
                    'product_id' => 22,
                    'variation_id' => 23,
                    'quantity' => 1
                ],
                [
                    'product_id' => 22,
                    'variation_id' => 24,
                    'quantity' => 1
                ]
            ],
            'shipping_lines' => [
                [
                    'method_id' => 'flat_rate',
                    'method_title' => 'Flat Rate',
                    'total' => '20.00'
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 727,
            'shipping_methods' => 'Local Delivery'
        ]
    ],
    'delete' => [
        723
    ]
];

print_r($woocommerce->post('orders/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "payment_method": "bacs",
            "payment_method_title": "Direct Bank Transfer",
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            },
            "line_items": [
                {
                    "product_id": 79,
                    "quantity": 1
                },
                {
                    "product_id": 93,
                    "quantity": 1
                },
                {
                    "product_id": 22,
                    "variation_id": 23,
                    "quantity": 1
                }
            ],
            "shipping_lines": [
                {
                    "method_id": "flat_rate",
                    "method_title": "Flat Rate",
                    "total": "30.00"
                }
            ]
        },
        {
            "payment_method": "bacs",
            "payment_method_title": "Direct Bank Transfer",
            "set_paid": True,
            "billing": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US",
                "email": "john.doe@example.com",
                "phone": "(555) 555-5555"
            },
            "shipping": {
                "first_name": "John",
                "last_name": "Doe",
                "address_1": "969 Market",
                "address_2": "",
                "city": "San Francisco",
                "state": "CA",
                "postcode": "94103",
                "country": "US"
            },
            "line_items": [
                {
                    "product_id": 22,
                    "variation_id": 23,
                    "quantity": 1
                },
                {
                    "product_id": 22,
                    "variation_id": 24,
                    "quantity": 1
                }
            ],
            "shipping_lines": [
                {
                    "method_id": "flat_rate",
                    "method_title": "Flat Rate",
                    "total": "20.00"
                }
            ]
        }
    ],
    "update": [
        {
            "id": 727,
            "shipping_methods": "Local Delivery"
        }
    ],
    "delete": [
        723
    ]
}

print(wcapi.post("orders/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 79,
          quantity: 1
        },
        {
          product_id: 93,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "30.00"
        }
      ]
    },
    {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      set_paid: true,
      billing: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US",
        email: "john.doe@example.com",
        phone: "(555) 555-5555"
      },
      shipping: {
        first_name: "John",
        last_name: "Doe",
        address_1: "969 Market",
        address_2: "",
        city: "San Francisco",
        state: "CA",
        postcode: "94103",
        country: "US"
      },
      line_items: [
        {
          product_id: 22,
          variation_id: 23,
          quantity: 1
        },
        {
          product_id: 22,
          variation_id: 24,
          quantity: 1
        }
      ],
      shipping_lines: [
        {
          method_id: "flat_rate",
          method_title: "Flat Rate",
          total: "20.00"
        }
      ]
    }
  ],
  update: [
    {
      id: 727,
      shipping_methods: "Local Delivery"
    }
  ],
  delete: [
    723
  ]
}

woocommerce.post("orders/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 728,
			"parent_id": 0,
			"number": "728",
			"order_key": "wc_order_58d2d18e580",
			"created_via": "rest-api",
			"version": "3.0.0",
			"status": "pending",
			"currency": "USD",
			"date_created": "2017-03-22T16:33:34",
			"date_created_gmt": "2017-03-22T19:33:34",
			"date_modified": "2017-03-22T16:33:34",
			"date_modified_gmt": "2017-03-22T19:33:34",
			"discount_total": "0.00",
			"discount_tax": "0.00",
			"shipping_total": "30.00",
			"shipping_tax": "0.00",
			"cart_tax": "2.25",
			"total": "62.25",
			"total_tax": "2.25",
			"prices_include_tax": false,
			"customer_id": 0,
			"customer_ip_address": "",
			"customer_user_agent": "",
			"customer_note": "",
			"billing": {
				"first_name": "John",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US",
				"email": "john.doe@example.com",
				"phone": "(555) 555-5555"
			},
			"shipping": {
				"first_name": "John",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US"
			},
			"payment_method": "bacs",
			"payment_method_title": "Direct Bank Transfer",
			"transaction_id": "",
			"date_paid": null,
			"date_paid_gmt": null,
			"date_completed": null,
			"date_completed_gmt": null,
			"cart_hash": "",
			"meta_data": [],
			"line_items": [
				{
					"id": 319,
					"name": "Woo Logo",
					"product_id": 79,
					"variation_id": 0,
					"quantity": 1,
					"tax_class": "",
					"subtotal": "15.00",
					"subtotal_tax": "1.13",
					"total": "15.00",
					"total_tax": "1.13",
					"taxes": [
						{
							"id": 75,
							"total": "1.125",
							"subtotal": "1.125"
						}
					],
					"meta_data": [],
					"sku": "",
					"price": 15
				},
				{
					"id": 320,
					"name": "Woo Single #1",
					"product_id": 93,
					"variation_id": 0,
					"quantity": 1,
					"tax_class": "",
					"subtotal": "3.00",
					"subtotal_tax": "0.23",
					"total": "3.00",
					"total_tax": "0.23",
					"taxes": [
						{
							"id": 75,
							"total": "0.225",
							"subtotal": "0.225"
						}
					],
					"meta_data": [],
					"sku": "",
					"price": 3
				},
				{
					"id": 321,
					"name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
					"product_id": 22,
					"variation_id": 23,
					"quantity": 1,
					"tax_class": "",
					"subtotal": "12.00",
					"subtotal_tax": "0.90",
					"total": "12.00",
					"total_tax": "0.90",
					"taxes": [
						{
							"id": 75,
							"total": "0.9",
							"subtotal": "0.9"
						}
					],
					"meta_data": [
						{
							"id": 2133,
							"key": "pa_color",
							"value": "black"
						},
						{
							"id": 2134,
							"key": "size",
							"value": "M Test"
						}
					],
					"sku": "Bar3",
					"price": 12
				}
			],
			"tax_lines": [
				{
					"id": 323,
					"rate_code": "US-CA-STATE TAX",
					"rate_id": 75,
					"label": "State Tax",
					"compound": false,
					"tax_total": "2.25",
					"shipping_tax_total": "0.00",
					"meta_data": []
				}
			],
			"shipping_lines": [
				{
					"id": 322,
					"method_title": "Flat Rate",
					"method_id": "flat_rate",
					"total": "30.00",
					"total_tax": "0.00",
					"taxes": [],
					"meta_data": []
				}
			],
			"fee_lines": [],
			"coupon_lines": [],
			"refunds": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/orders/728"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/orders"
					}
				]
			}
		},
		{
			"id": 729,
			"parent_id": 0,
			"number": "729",
			"order_key": "wc_order_58d2d196171",
			"created_via": "rest-api",
			"version": "3.0.0",
			"status": "processing",
			"currency": "USD",
			"date_created": "2017-03-22T16:33:42",
			"date_created_gmt": "2017-03-22T19:33:42",
			"date_modified": "2017-03-22T16:33:47",
			"date_modified_gmt": "2017-03-22T19:33:47",
			"discount_total": "0.00",
			"discount_tax": "0.00",
			"shipping_total": "20.00",
			"shipping_tax": "0.00",
			"cart_tax": "2.40",
			"total": "54.40",
			"total_tax": "2.40",
			"prices_include_tax": false,
			"customer_id": 0,
			"customer_ip_address": "",
			"customer_user_agent": "",
			"customer_note": "",
			"billing": {
				"first_name": "John",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US",
				"email": "john.doe@example.com",
				"phone": "(555) 555-5555"
			},
			"shipping": {
				"first_name": "John",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US"
			},
			"payment_method": "bacs",
			"payment_method_title": "Direct Bank Transfer",
			"transaction_id": "",
			"date_paid": "2017-03-22T16:33:47",
			"date_paid_gmt": "2017-03-22T19:33:47",
			"date_completed": null,
			"date_completed_gmt": null,
			"cart_hash": "",
			"meta_data": [
				{
					"id": 13198,
					"key": "_download_permissions_granted",
					"value": "yes"
				}
			],
			"line_items": [
				{
					"id": 324,
					"name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
					"product_id": 22,
					"variation_id": 23,
					"quantity": 1,
					"tax_class": "",
					"subtotal": "12.00",
					"subtotal_tax": "0.90",
					"total": "12.00",
					"total_tax": "0.90",
					"taxes": [
						{
							"id": 75,
							"total": "0.9",
							"subtotal": "0.9"
						}
					],
					"meta_data": [
						{
							"id": 2153,
							"key": "pa_color",
							"value": "black"
						},
						{
							"id": 2154,
							"key": "size",
							"value": "M Test"
						}
					],
					"sku": "Bar3",
					"price": 12
				},
				{
					"id": 325,
					"name": "Ship Your Idea &ndash; Color: Green, Size: S Test",
					"product_id": 22,
					"variation_id": 24,
					"quantity": 1,
					"tax_class": "",
					"subtotal": "20.00",
					"subtotal_tax": "1.50",
					"total": "20.00",
					"total_tax": "1.50",
					"taxes": [
						{
							"id": 75,
							"total": "1.5",
							"subtotal": "1.5"
						}
					],
					"meta_data": [
						{
							"id": 2164,
							"key": "pa_color",
							"value": "green"
						},
						{
							"id": 2165,
							"key": "size",
							"value": "S Test"
						}
					],
					"sku": "",
					"price": 20
				}
			],
			"tax_lines": [
				{
					"id": 327,
					"rate_code": "US-CA-STATE TAX",
					"rate_id": 75,
					"label": "State Tax",
					"compound": false,
					"tax_total": "2.40",
					"shipping_tax_total": "0.00",
					"meta_data": []
				}
			],
			"shipping_lines": [
				{
					"id": 326,
					"method_title": "Flat Rate",
					"method_id": "flat_rate",
					"total": "20.00",
					"total_tax": "0.00",
					"taxes": [],
					"meta_data": []
				}
			],
			"fee_lines": [],
			"coupon_lines": [],
			"refunds": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/orders/729"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/orders"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 727,
			"parent_id": 0,
			"number": "727",
			"order_key": "wc_order_58d2d042d1d",
			"created_via": "rest-api",
			"version": "3.0.0",
			"status": "completed",
			"currency": "USD",
			"date_created": "2017-03-22T16:28:02",
			"date_created_gmt": "2017-03-22T19:28:02",
			"date_modified": "2017-03-22T16:30:35",
			"date_modified_gmt": "2017-03-22T19:30:35",
			"discount_total": "0.00",
			"discount_tax": "0.00",
			"shipping_total": "10.00",
			"shipping_tax": "0.00",
			"cart_tax": "1.35",
			"total": "29.35",
			"total_tax": "1.35",
			"prices_include_tax": false,
			"customer_id": 0,
			"customer_ip_address": "",
			"customer_user_agent": "",
			"customer_note": "",
			"billing": {
				"first_name": "John",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US",
				"email": "john.doe@example.com",
				"phone": "(555) 555-5555"
			},
			"shipping": {
				"first_name": "John",
				"last_name": "Doe",
				"company": "",
				"address_1": "969 Market",
				"address_2": "",
				"city": "San Francisco",
				"state": "CA",
				"postcode": "94103",
				"country": "US"
			},
			"payment_method": "bacs",
			"payment_method_title": "Direct Bank Transfer",
			"transaction_id": "",
			"date_paid": "2017-03-22T16:28:08",
			"date_paid_gmt": "2017-03-22T19:28:08",
			"date_completed": "2017-03-22T16:30:35",
			"date_completed_gmt": "2017-03-22T19:30:35",
			"cart_hash": "",
			"meta_data": [
				{
					"id": 13106,
					"key": "_download_permissions_granted",
					"value": "yes"
				},
				{
					"id": 13109,
					"key": "_order_stock_reduced",
					"value": "yes"
				}
			],
			"line_items": [
				{
					"id": 315,
					"name": "Woo Single #1",
					"product_id": 93,
					"variation_id": 0,
					"quantity": 2,
					"tax_class": "",
					"subtotal": "6.00",
					"subtotal_tax": "0.45",
					"total": "6.00",
					"total_tax": "0.45",
					"taxes": [
						{
							"id": 75,
							"total": "0.45",
							"subtotal": "0.45"
						}
					],
					"meta_data": [],
					"sku": "",
					"price": 3
				},
				{
					"id": 316,
					"name": "Ship Your Idea &ndash; Color: Black, Size: M Test",
					"product_id": 22,
					"variation_id": 23,
					"quantity": 1,
					"tax_class": "",
					"subtotal": "12.00",
					"subtotal_tax": "0.90",
					"total": "12.00",
					"total_tax": "0.90",
					"taxes": [
						{
							"id": 75,
							"total": "0.9",
							"subtotal": "0.9"
						}
					],
					"meta_data": [
						{
							"id": 2095,
							"key": "pa_color",
							"value": "black"
						},
						{
							"id": 2096,
							"key": "size",
							"value": "M Test"
						}
					],
					"sku": "Bar3",
					"price": 12
				}
			],
			"tax_lines": [
				{
					"id": 318,
					"rate_code": "US-CA-STATE TAX",
					"rate_id": 75,
					"label": "State Tax",
					"compound": false,
					"tax_total": "1.35",
					"shipping_tax_total": "0.00",
					"meta_data": []
				}
			],
			"shipping_lines": [
				{
					"id": 317,
					"method_title": "Flat Rate",
					"method_id": "flat_rate",
					"total": "10.00",
					"total_tax": "0.00",
					"taxes": [],
					"meta_data": []
				}
			],
			"fee_lines": [],
			"coupon_lines": [],
			"refunds": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/orders/727"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/orders"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 723,
			"parent_id": 0,
			"number": "723",
			"order_key": "wc_order_58d17c18352",
			"created_via": "checkout",
			"version": "3.0.0",
			"status": "completed",
			"currency": "USD",
			"date_created": "2017-03-21T16:16:00",
			"date_created_gmt": "2017-03-21T19:16:00",
			"date_modified": "2017-03-21T16:54:51",
			"date_modified_gmt": "2017-03-21T19:54:51",
			"discount_total": "0.00",
			"discount_tax": "0.00",
			"shipping_total": "10.00",
			"shipping_tax": "0.00",
			"cart_tax": "0.00",
			"total": "39.00",
			"total_tax": "0.00",
			"prices_include_tax": false,
			"customer_id": 26,
			"customer_ip_address": "127.0.0.1",
			"customer_user_agent": "mozilla/5.0 (x11; ubuntu; linux x86_64; rv:52.0) gecko/20100101 firefox/52.0",
			"customer_note": "",
			"billing": {
				"first_name": "João",
				"last_name": "Silva",
				"company": "",
				"address_1": "Av. Brasil, 432",
				"address_2": "",
				"city": "Rio de Janeiro",
				"state": "RJ",
				"postcode": "12345-000",
				"country": "BR",
				"email": "joao.silva@example.com",
				"phone": "(11) 1111-1111"
			},
			"shipping": {
				"first_name": "João",
				"last_name": "Silva",
				"company": "",
				"address_1": "Av. Brasil, 432",
				"address_2": "",
				"city": "Rio de Janeiro",
				"state": "RJ",
				"postcode": "12345-000",
				"country": "BR"
			},
			"payment_method": "bacs",
			"payment_method_title": "Direct bank transfer",
			"transaction_id": "",
			"date_paid": null,
			"date_paid_gmt": null,
			"date_completed": "2017-03-21T16:54:51",
			"date_completed_gmt": "2017-03-21T19:54:51",
			"cart_hash": "5040ce7273261e31d8bcf79f9be3d279",
			"meta_data": [
				{
					"id": 13023,
					"key": "_download_permissions_granted",
					"value": "yes"
				}
			],
			"line_items": [
				{
					"id": 311,
					"name": "Woo Album #2",
					"product_id": 87,
					"variation_id": 0,
					"quantity": 1,
					"tax_class": "",
					"subtotal": "9.00",
					"subtotal_tax": "0.00",
					"total": "9.00",
					"total_tax": "0.00",
					"taxes": [],
					"meta_data": [],
					"sku": "",
					"price": 9
				},
				{
					"id": 313,
					"name": "Woo Ninja",
					"product_id": 34,
					"variation_id": 0,
					"quantity": 1,
					"tax_class": "",
					"subtotal": "20.00",
					"subtotal_tax": "0.00",
					"total": "20.00",
					"total_tax": "0.00",
					"taxes": [],
					"meta_data": [],
					"sku": "",
					"price": 20
				}
			],
			"tax_lines": [],
			"shipping_lines": [
				{
					"id": 312,
					"method_title": "Flat rate",
					"method_id": "flat_rate:25",
					"total": "10.00",
					"total_tax": "0.00",
					"taxes": [],
					"meta_data": [
						{
							"id": 2057,
							"key": "Items",
							"value": "Woo Album #2 &times; 1"
						}
					]
				}
			],
			"fee_lines": [],
			"coupon_lines": [],
			"refunds": [
				{
					"id": 726,
					"refund": "",
					"total": "-10.00"
				},
				{
					"id": 724,
					"refund": "",
					"total": "-9.00"
				}
			],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/orders/723"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/orders"
					}
				],
				"customer": [
					{
						"href": "https://example.com/wp-json/wc/v3/customers/26"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Payment gateways

*Source: apis/rest-api/v3/payment-gateways.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Payment gateways

The payment gateways API allows you to view, and update individual payment gateways. Results are not paginated - all gateways will be returned.

## Payment gateway properties

| Attribute            | Type    | Description                                                                                                 |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `id`                 | string  | Payment gateway ID. `READ-ONLY`                                               |
| `title`              | string  | Payment gateway title on checkout.                                                                          |
| `description`        | string  | Payment gateway description on checkout.                                                                    |
| `order`              | integer | Payment gateway sort order.                                                                                 |
| `enabled`            | boolean | Payment gateway enabled status.                                                                             |
| `method_title`       | string  | Payment gateway method title. `READ-ONLY`                                     |
| `method_description` | string  | Payment gateway method description. `READ-ONLY`                               |
| `method_supports`    | array   | Supported features for this payment gateway. `READ-ONLY`                      |
| `settings`           | object  | Payment gateway settings. See [Payment gateway - Settings properties](#payment-gateway---settings-properties) |

### Payment gateway - Settings properties

| Attribute     | Type   | Description                                                                                                                                                                                     |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string | A unique identifier for the setting. `READ-ONLY`                                                                                                                  |
| `label`       | string | A human readable label for the setting used in interfaces. `READ-ONLY`                                                                                            |
| `description` | string | A human readable description for the setting used in interfaces. `READ-ONLY`                                                                                      |
| `type`        | string | Type of setting. Options: `text`, `email`, `number`, `color`, `password`, `textarea`, `select`, `multiselect`, `radio`, `image_width` and `checkbox`. `READ-ONLY` |
| `value`       | string | Setting value.                                                                                                                                                                                  |
| `default`     | string | Default value for the setting. `READ-ONLY`                                                                                                                        |
| `tip`         | string | Additional help text shown to the user about the setting. `READ-ONLY`                                                                                             |
| `placeholder` | string | Placeholder text to be displayed in text inputs. `READ-ONLY`                                                                                                      |

## Retrieve a payment gateway

This API lets you retrieve and view a specific payment gateway.

```http
GET /wp-json/wc/v3/payment_gateways/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/payment_gateways/bacs \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'payment_gateways/bacs' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('payment_gateways/bacs')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("payment_gateways/bacs").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("payment_gateways/bacs").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": "bacs",
	"title": "Direct bank transfer",
	"description": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
	"order": 0,
	"enabled": true,
	"method_title": "BACS",
	"method_description": "Allows payments by BACS, more commonly known as direct bank/wire transfer.",
	"method_supports": [ "products" ],
	"settings": {
		"title": {
			"id": "title",
			"label": "Title",
			"description": "This controls the title which the user sees during checkout.",
			"type": "text",
			"value": "Direct bank transfer",
			"default": "Direct bank transfer",
			"tip": "This controls the title which the user sees during checkout.",
			"placeholder": ""
		},
		"instructions": {
			"id": "instructions",
			"label": "Instructions",
			"description": "Instructions that will be added to the thank you page and emails.",
			"type": "textarea",
			"value": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
			"default": "",
			"tip": "Instructions that will be added to the thank you page and emails.",
			"placeholder": ""
		}
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/payment_gateways/bacs"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/payment_gateways"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all payment gateways

This API helps you to view all the payment gateways.

```http
GET /wp-json/wc/v3/payment_gateways
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/payment_gateways \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'payment_gateways' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('payment_gateways')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("payment_gateways").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("payment_gateways").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": "bacs",
		"title": "Direct bank transfer",
		"description": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
		"order": 0,
		"enabled": true,
		"method_title": "BACS",
		"method_description": "Allows payments by BACS, more commonly known as direct bank/wire transfer.",
		"method_supports": [ "products" ],
		"settings": {
			"title": {
				"id": "title",
				"label": "Title",
				"description": "This controls the title which the user sees during checkout.",
				"type": "text",
				"value": "Direct bank transfer",
				"default": "Direct bank transfer",
				"tip": "This controls the title which the user sees during checkout.",
				"placeholder": ""
			},
			"instructions": {
				"id": "instructions",
				"label": "Instructions",
				"description": "Instructions that will be added to the thank you page and emails.",
				"type": "textarea",
				"value": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
				"default": "",
				"tip": "Instructions that will be added to the thank you page and emails.",
				"placeholder": ""
			}
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/payment_gateways/bacs"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/payment_gateways"
				}
			]
		}
	},
	{
		"id": "cheque",
		"title": "Check payments",
		"description": "Please send a check to Store Name, Store Street, Store Town, Store State / County, Store Postcode.",
		"order": 1,
		"enabled": false,
		"method_title": "Check payments",
		"method_description": "Allows check payments. Why would you take checks in this day and age? Well you probably wouldn't but it does allow you to make test purchases for testing order emails and the 'success' pages etc.",
		"method_supports": [ "products" ],
		"settings": {
			"title": {
				"id": "title",
				"label": "Title",
				"description": "This controls the title which the user sees during checkout.",
				"type": "text",
				"value": "Check payments",
				"default": "Check payments",
				"tip": "This controls the title which the user sees during checkout.",
				"placeholder": ""
			},
			"instructions": {
				"id": "instructions",
				"label": "Instructions",
				"description": "Instructions that will be added to the thank you page and emails.",
				"type": "textarea",
				"value": "",
				"default": "",
				"tip": "Instructions that will be added to the thank you page and emails.",
				"placeholder": ""
			}
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/payment_gateways/cheque"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/payment_gateways"
				}
			]
		}
	},
	{
		"id": "cod",
		"title": "Cash on delivery",
		"description": "Pay with cash upon delivery.",
		"order": 2,
		"enabled": false,
		"method_title": "Cash on delivery",
		"method_description": "Have your customers pay with cash (or by other means) upon delivery.",
		"method_supports": [ "products" ],
		"settings": {
			"title": {
				"id": "title",
				"label": "Title",
				"description": "Payment method description that the customer will see on your checkout.",
				"type": "text",
				"value": "Cash on delivery",
				"default": "Cash on delivery",
				"tip": "Payment method description that the customer will see on your checkout.",
				"placeholder": ""
			},
			"instructions": {
				"id": "instructions",
				"label": "Instructions",
				"description": "Instructions that will be added to the thank you page.",
				"type": "textarea",
				"value": "",
				"default": "Pay with cash upon delivery.",
				"tip": "Instructions that will be added to the thank you page.",
				"placeholder": ""
			},
			"enable_for_methods": {
				"id": "enable_for_methods",
				"label": "Enable for shipping methods",
				"description": "If COD is only available for certain methods, set it up here. Leave blank to enable for all methods.",
				"type": "multiselect",
				"value": "",
				"default": "",
				"tip": "If COD is only available for certain methods, set it up here. Leave blank to enable for all methods.",
				"placeholder": "",
				"options": {
					"flat_rate": "Flat rate",
					"free_shipping": "Free shipping",
					"local_pickup": "Local pickup"
				}
			},
			"enable_for_virtual": {
				"id": "enable_for_virtual",
				"label": "Accept COD if the order is virtual",
				"description": "",
				"type": "checkbox",
				"value": "yes",
				"default": "yes",
				"tip": "",
				"placeholder": ""
			}
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/payment_gateways/cod"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/payment_gateways"
				}
			]
		}
	},
	{
		"id": "paypal",
		"title": "PayPal",
		"description": "Pay via PayPal; you can pay with your credit card if you don't have a PayPal account.",
		"order": 3,
		"enabled": true,
		"method_title": "PayPal",
		"method_description": "PayPal Standard sends customers to PayPal to enter their payment information. PayPal IPN requires fsockopen/cURL support to update order statuses after payment. Check the <a href=\"https://example.com/wp-admin/admin.php?page=wc-status\">system status</a> page for more details.",
		"method_supports": [ "products", "refunds" ],
		"settings": {
			"title": {
				"id": "title",
				"label": "Title",
				"description": "This controls the title which the user sees during checkout.",
				"type": "text",
				"value": "PayPal",
				"default": "PayPal",
				"tip": "This controls the title which the user sees during checkout.",
				"placeholder": ""
			},
			"email": {
				"id": "email",
				"label": "PayPal email",
				"description": "Please enter your PayPal email address; this is needed in order to take payment.",
				"type": "email",
				"value": "me@example.com",
				"default": "me@example.com",
				"tip": "Please enter your PayPal email address; this is needed in order to take payment.",
				"placeholder": "you@youremail.com"
			},
			"testmode": {
				"id": "testmode",
				"label": "Enable PayPal sandbox",
				"description": "PayPal sandbox can be used to test payments. Sign up for a <a href=\"https://developer.paypal.com/\">developer account</a>.",
				"type": "checkbox",
				"value": "yes",
				"default": "no",
				"tip": "PayPal sandbox can be used to test payments. Sign up for a <a href=\"https://developer.paypal.com/\">developer account</a>.",
				"placeholder": ""
			},
			"debug": {
				"id": "debug",
				"label": "Enable logging",
				"description": "Log PayPal events, such as IPN requests, inside <code>/var/www/woocommerce/wp-content/uploads/wc-logs/paypal-de01f7c6894774e7ac8e4207bb8bac2f.log</code>",
				"type": "checkbox",
				"value": "yes",
				"default": "no",
				"tip": "Log PayPal events, such as IPN requests, inside <code>/var/www/woocommerce/wp-content/uploads/wc-logs/paypal-de01f7c6894774e7ac8e4207bb8bac2f.log</code>",
				"placeholder": ""
			},
			"receiver_email": {
				"id": "receiver_email",
				"label": "Receiver email",
				"description": "If your main PayPal email differs from the PayPal email entered above, input your main receiver email for your PayPal account here. This is used to validate IPN requests.",
				"type": "email",
				"value": "me@example.com",
				"default": "",
				"tip": "If your main PayPal email differs from the PayPal email entered above, input your main receiver email for your PayPal account here. This is used to validate IPN requests.",
				"placeholder": "you@youremail.com"
			},
			"identity_token": {
				"id": "identity_token",
				"label": "PayPal identity token",
				"description": "Optionally enable \"Payment Data Transfer\" (Profile > Profile and Settings > My Selling Tools > Website Preferences) and then copy your identity token here. This will allow payments to be verified without the need for PayPal IPN.",
				"type": "text",
				"value": "",
				"default": "",
				"tip": "Optionally enable \"Payment Data Transfer\" (Profile > Profile and Settings > My Selling Tools > Website Preferences) and then copy your identity token here. This will allow payments to be verified without the need for PayPal IPN.",
				"placeholder": ""
			},
			"invoice_prefix": {
				"id": "invoice_prefix",
				"label": "Invoice prefix",
				"description": "Please enter a prefix for your invoice numbers. If you use your PayPal account for multiple stores ensure this prefix is unique as PayPal will not allow orders with the same invoice number.",
				"type": "text",
				"value": "WC-",
				"default": "WC-",
				"tip": "Please enter a prefix for your invoice numbers. If you use your PayPal account for multiple stores ensure this prefix is unique as PayPal will not allow orders with the same invoice number.",
				"placeholder": ""
			},
			"send_shipping": {
				"id": "send_shipping",
				"label": "Send shipping details to PayPal instead of billing.",
				"description": "PayPal allows us to send one address. If you are using PayPal for shipping labels you may prefer to send the shipping address rather than billing.",
				"type": "checkbox",
				"value": "no",
				"default": "no",
				"tip": "PayPal allows us to send one address. If you are using PayPal for shipping labels you may prefer to send the shipping address rather than billing.",
				"placeholder": ""
			},
			"address_override": {
				"id": "address_override",
				"label": "Enable \"address_override\" to prevent address information from being changed.",
				"description": "PayPal verifies addresses therefore this setting can cause errors (we recommend keeping it disabled).",
				"type": "checkbox",
				"value": "no",
				"default": "no",
				"tip": "PayPal verifies addresses therefore this setting can cause errors (we recommend keeping it disabled).",
				"placeholder": ""
			},
			"paymentaction": {
				"id": "paymentaction",
				"label": "Payment action",
				"description": "Choose whether you wish to capture funds immediately or authorize payment only.",
				"type": "select",
				"value": "sale",
				"default": "sale",
				"tip": "Choose whether you wish to capture funds immediately or authorize payment only.",
				"placeholder": "",
				"options": {
					"sale": "Capture",
					"authorization": "Authorize"
				}
			},
			"page_style": {
				"id": "page_style",
				"label": "Page style",
				"description": "Optionally enter the name of the page style you wish to use. These are defined within your PayPal account. This affects classic PayPal checkout screens.",
				"type": "text",
				"value": "",
				"default": "",
				"tip": "Optionally enter the name of the page style you wish to use. These are defined within your PayPal account. This affects classic PayPal checkout screens.",
				"placeholder": "Optional"
			},
			"image_url": {
				"id": "image_url",
				"label": "Image url",
				"description": "Optionally enter the URL to a 150x50px image displayed as your logo in the upper left corner of the PayPal checkout pages.",
				"type": "text",
				"value": "",
				"default": "",
				"tip": "Optionally enter the URL to a 150x50px image displayed as your logo in the upper left corner of the PayPal checkout pages.",
				"placeholder": "Optional"
			},
			"api_username": {
				"id": "api_username",
				"label": "API username",
				"description": "Get your API credentials from PayPal.",
				"type": "text",
				"value": "",
				"default": "",
				"tip": "Get your API credentials from PayPal.",
				"placeholder": "Optional"
			},
			"api_password": {
				"id": "api_password",
				"label": "API password",
				"description": "Get your API credentials from PayPal.",
				"type": "password",
				"value": "",
				"default": "",
				"tip": "Get your API credentials from PayPal.",
				"placeholder": "Optional"
			},
			"api_signature": {
				"id": "api_signature",
				"label": "API signature",
				"description": "Get your API credentials from PayPal.",
				"type": "text",
				"value": "",
				"default": "",
				"tip": "Get your API credentials from PayPal.",
				"placeholder": "Optional"
			}
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/payment_gateways/paypal"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/payment_gateways"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

## Update a payment gateway

This API lets you make changes to a payment gateway.

```http
PUT /wp-json/wc/v3/payment_gateways/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/payment_gateways/bacs \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "enabled": false
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	enabled: true,
};

WooCommerce.put( 'payment_gateways/bacs', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'enabled' => true
];

print_r($woocommerce->put('payment_gateways/bacs', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "enabled": True
}

print(wcapi.put("payment_gateways/bacs", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  enabled: true
}

woocommerce.put("payment_gateways/bacs", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": "bacs",
	"title": "Direct bank transfer",
	"description": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
	"order": 0,
	"enabled": false,
	"method_title": "BACS",
	"method_description": "Allows payments by BACS, more commonly known as direct bank/wire transfer.",
	"method_supports": [ "products" ],
	"settings": {
		"title": {
			"id": "title",
			"label": "Title",
			"description": "This controls the title which the user sees during checkout.",
			"type": "text",
			"value": "Direct bank transfer",
			"default": "Direct bank transfer",
			"tip": "This controls the title which the user sees during checkout.",
			"placeholder": ""
		},
		"instructions": {
			"id": "instructions",
			"label": "Instructions",
			"description": "Instructions that will be added to the thank you page and emails.",
			"type": "textarea",
			"value": "Make your payment directly into our bank account. Please use your Order ID as the payment reference. Your order won't be shipped until the funds have cleared in our account.",
			"default": "",
			"tip": "Instructions that will be added to the thank you page and emails.",
			"placeholder": ""
		}
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/payment_gateways/bacs"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/payment_gateways"
			}
		]
	}
}
```

  </TabItem>
</Tabs>


---

## Product attribute terms

*Source: apis/rest-api/v3/product-attribute-terms.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product attribute terms

The product attribute terms API allows you to create, view, update, and delete individual, or a batch, of attribute terms.

## Product attribute term properties

| Attribute     | Type    | Description                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Term name. `MANDATORY`                                     |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `menu_order`  | integer | Menu order, used to custom sort the resource.                                            |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create an attribute term

This API helps you to create a new product attribute term.

```http
POST /wp-json/wc/v3/products/attributes/<attribute_id>/terms
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/attributes/2/terms \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "XXS"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'XXS',
};

WooCommerce.post( 'products/attributes/2/terms', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'XXS'
];

print_r($woocommerce->post('products/attributes/2/terms', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "XXS"
}

print(wcapi.post("products/attributes/2/terms", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "XXS"
}

woocommerce.post("products/attributes/2/terms", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 23,
	"name": "XXS",
	"slug": "xxs",
	"description": "",
	"menu_order": 1,
	"count": 1,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/23"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve an attribute term

This API lets you retrieve a product attribute term by ID.

```http
GET /wp-json/wc/v3/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/attributes/2/terms/23 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/attributes/2/terms/23' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/2/terms/23')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/2/terms/23").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/2/terms/23").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 23,
	"name": "XXS",
	"slug": "xxs",
	"description": "",
	"menu_order": 1,
	"count": 1,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/23"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all attribute terms

This API lets you retrieve all terms from a product attribute.

```http
GET /wp-json/wc/v3/products/attributes/<attribute_id>/terms
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/attributes/2/terms \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/attributes/2/terms' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/2/terms')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/2/terms").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/2/terms").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 23,
		"name": "XXS",
		"slug": "xxs",
		"description": "",
		"menu_order": 1,
		"count": 1,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/23"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
				}
			]
		}
	},
	{
		"id": 22,
		"name": "XS",
		"slug": "xs",
		"description": "",
		"menu_order": 2,
		"count": 1,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/22"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
				}
			]
		}
	},
	{
		"id": 17,
		"name": "S",
		"slug": "s",
		"description": "",
		"menu_order": 3,
		"count": 1,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/17"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
				}
			]
		}
	},
	{
		"id": 18,
		"name": "M",
		"slug": "m",
		"description": "",
		"menu_order": 4,
		"count": 1,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/18"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
				}
			]
		}
	},
	{
		"id": 19,
		"name": "L",
		"slug": "l",
		"description": "",
		"menu_order": 5,
		"count": 1,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/19"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
				}
			]
		}
	},
	{
		"id": 20,
		"name": "XL",
		"slug": "xl",
		"description": "",
		"menu_order": 6,
		"count": 1,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/20"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
				}
			]
		}
	},
	{
		"id": 21,
		"name": "XXL",
		"slug": "xxl",
		"description": "",
		"menu_order": 7,
		"count": 1,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/21"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter    | Type    | Description                                                                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                 |
| `page`       | integer | Current page of the collection. Default is `1`.                                                                                              |
| `per_page`   | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                       |
| `search`     | string  | Limit results to those matching a string.                                                                                                    |
| `exclude`    | array   | Ensure result set excludes specific ids.                                                                                                     |
| `include`    | array   | Limit result set to specific ids.                                                                                                            |
| `order`      | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                   |
| `orderby`    | string  | Sort collection by resource attribute. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. Default is `name`. |
| `hide_empty` | boolean | Whether to hide resources not assigned to any products. Default is `false`.                                                                  |
| `parent`     | integer | Limit result set to resources assigned to a specific parent.                                                                                 |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                                |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                          |

## Update an attribute term

This API lets you make changes to a product attribute term.

```http
PUT /wp-json/wc/v3/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/products/attributes/2/terms/23 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "XXS"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'XXS',
};

WooCommerce.put( 'products/attributes/2/terms/23', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'XXS'
];

print_r($woocommerce->put('products/attributes/2/terms/23', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "XXS"
}

print(wcapi.put("products/attributes/2/terms/23", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "XXS"
}

woocommerce.put("products/attributes/2/terms/23", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 23,
	"name": "XXS",
	"slug": "xxs",
	"description": "",
	"menu_order": 1,
	"count": 1,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/23"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete an attribute term

This API helps you delete a product attribute term.

```http
DELETE /wp-json/wc/v3/products/attributes/<attribute_id>/terms/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/products/attributes/2/terms/23?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'products/attributes/2/terms/23', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/attributes/2/terms/23', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/attributes/2/terms/23", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/attributes/2/terms/23", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 23,
	"name": "XXS",
	"slug": "xxs",
	"description": "",
	"menu_order": 1,
	"count": 1,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/23"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update attribute terms

This API helps you to batch create, update and delete multiple product attribute terms.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/products/attributes/<attribute_id>/terms/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/attributes/<attribute_id>/terms/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "XXS"
    },
    {
      "name": "S"
    }
  ],
  "update": [
    {
      "id": 19,
      "menu_order": 6
    }
  ],
  "delete": [
    21,
    20
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			name: 'XXS',
		},
		{
			name: 'S',
		},
	],
	update: [
		{
			id: 19,
			menu_order: 6,
		},
	],
	delete: [ 21, 20 ],
};

WooCommerce.post( 'products/attributes/2/terms/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'XXS'
        ],
        [
            'name' => 'S'
        ]
    ],
    'update' => [
        [
            'id' => 19,
            'menu_order' => 6
        ]
    ],
    'delete' => [
        21,
        20
    ]
];

print_r($woocommerce->post('products/attributes/2/terms/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "XXS"
        },
        {
            "name": "S"
        }
    ],
    "update": [
        {
            "id": 19,
            "menu_order": 6
        }
    ],
    "delete": [
        21,
        20
    ]
}

print(wcapi.post("products/attributes/2/terms/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "XXS"
    },
    {
      name: "S"
    }
  ],
  update: [
    {
      id: 19,
      menu_order: 6
    }
  ],
  delete: [
    21,
    20
  ]
}

woocommerce.post("products/attributes/2/terms/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 23,
			"name": "XXS",
			"slug": "xxs",
			"description": "",
			"menu_order": 1,
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/23"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
					}
				]
			}
		},
		{
			"id": 17,
			"name": "S",
			"slug": "s",
			"description": "",
			"menu_order": 3,
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/17"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 19,
			"name": "L",
			"slug": "l",
			"description": "",
			"menu_order": 5,
			"count": 1,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/19"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 21,
			"name": "XXL",
			"slug": "xxl",
			"description": "",
			"menu_order": 7,
			"count": 1,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/21"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
					}
				]
			}
		},
		{
			"id": 20,
			"name": "XL",
			"slug": "xl",
			"description": "",
			"menu_order": 6,
			"count": 1,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms/20"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2/terms"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Product attributes

*Source: apis/rest-api/v3/product-attributes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product attributes

The product attributes API allows you to create, view, update, and delete individual, or a batch, of product attributes.

## Product attribute properties

| Attribute      | Type    | Description                                                                                      |
| -------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `id`           | integer | Unique identifier for the resource. `READ-ONLY`                    |
| `name`         | string  | Attribute name. `MANDATORY`                                        |
| `slug`         | string  | An alphanumeric identifier for the resource unique to its type.                                  |
| `type`         | string  | Type of attribute. By default only `select` is supported.                                        |
| `order_by`     | string  | Default sort order. Options: `menu_order`, `name`, `name_num` and `id`. Default is `menu_order`. |
| `has_archives` | boolean | Enable/Disable attribute archives. Default is `false`.                                           |

## Create a product attribute

This API helps you to create a new product attribute.

```http
POST /wp-json/wc/v3/products/attributes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/attributes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "Color",
  "slug": "pa_color",
  "type": "select",
  "order_by": "menu_order",
  "has_archives": true
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Color',
	slug: 'pa_color',
	type: 'select',
	order_by: 'menu_order',
	has_archives: true,
};

WooCommerce.post( 'products/attributes', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Color',
    'slug' => 'pa_color',
    'type' => 'select',
    'order_by' => 'menu_order',
    'has_archives' => true
];

print_r($woocommerce->post('products/attributes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Color",
    "slug": "pa_color",
    "type": "select",
    "order_by": "menu_order",
    "has_archives": True
}

print(wcapi.post("products/attributes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Color",
  slug: "pa_color",
  type: "select",
  order_by: "menu_order",
  has_archives: true
}

woocommerce.post("products/attributes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 1,
	"name": "Color",
	"slug": "pa_color",
	"type": "select",
	"order_by": "menu_order",
	"has_archives": true,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/6"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a product attribute

This API lets you retrieve and view a specific product attribute by ID.

```http
GET /wp-json/wc/v3/products/attributes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/attributes/1 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/attributes/1' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes/1')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes/1").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes/1").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 1,
	"name": "Color",
	"slug": "pa_color",
	"type": "select",
	"order_by": "menu_order",
	"has_archives": true,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/6"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all product attributes

This API helps you to view all the product attributes.

```http
GET /wp-json/wc/v3/products/attributes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/attributes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/attributes' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/attributes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/attributes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/attributes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 1,
		"name": "Color",
		"slug": "pa_color",
		"type": "select",
		"order_by": "menu_order",
		"has_archives": true,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/6"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes"
				}
			]
		}
	},
	{
		"id": 2,
		"name": "Size",
		"slug": "pa_size",
		"type": "select",
		"order_by": "menu_order",
		"has_archives": false,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes/2"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/attributes"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                                                                                  |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `context` | string | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |

## Update a product attribute

This API lets you make changes to a product attribute.

```http
PUT /wp-json/wc/v3/products/attributes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/products/attributes/1 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "order_by": "name"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	order_by: 'name',
};

WooCommerce.put( 'products/attributes/1', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'order_by' => 'name'
];

print_r($woocommerce->put('products/attributes/1', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "order_by": "name"
}

print(wcapi.put("products/attributes/1", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  order_by: "name"
}

woocommerce.put("products/attributes/1", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 1,
	"name": "Color",
	"slug": "pa_color",
	"type": "select",
	"order_by": "name",
	"has_archives": true,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/6"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a product attribute

This API helps you delete a product attribute.

```http
DELETE /wp-json/wc/v3/products/attributes/<id>
```

:::warning
This also will delete all terms from the selected attribute.
:::

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/products/attributes/1?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'products/attributes/1', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/attributes/1', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/attributes/1", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/attributes/1", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 1,
	"name": "Color",
	"slug": "pa_color",
	"type": "select",
	"order_by": "menu_order",
	"has_archives": true,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes/6"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/attributes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product attributes

This API helps you to batch create, update and delete multiple product attributes.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/products/attributes/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/attributes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Brand"
    },
    {
      "name": "Publisher"
    }
  ],
  "update": [
    {
      "id": 2,
      "order_by": "name"
    }
  ],
  "delete": [
    1
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			name: 'Brand',
		},
		{
			name: 'Publisher',
		},
	],
	update: [
		{
			id: 2,
			order_by: 'name',
		},
	],
	delete: [ 1 ],
};

WooCommerce.post( 'products/attributes/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Brand'
        ],
        [
            'name' => 'Publisher'
        ]
    ],
    'update' => [
        [
            'id' => 2,
            'order_by' => 'name'
        ]
    ],
    'delete' => [
        1
    ]
];

print_r($woocommerce->post('products/attributes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Brand"
        },
        {
            "name": "Publisher"
        }
    ],
    "update": [
        {
            "id": 2,
            "order_by": "name"
        }
    ],
    "delete": [
        1
    ]
}

print(wcapi.post("products/attributes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Round toe"
    },
    {
      name: "Flat"
    }
  ],
  update: [
    {
      id: 2,
      order_by: "name"
    }
  ],
  delete: [
    1
  ]
}

woocommerce.post("products/attributes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 7,
			"name": "Brand",
			"slug": "pa_brand",
			"type": "select",
			"order_by": "menu_order",
			"has_archives": false,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/7"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes"
					}
				]
			}
		},
		{
			"id": 8,
			"name": "Publisher",
			"slug": "pa_publisher",
			"type": "select",
			"order_by": "menu_order",
			"has_archives": false,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/8"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 2,
			"name": "Size",
			"slug": "pa_size",
			"type": "select",
			"order_by": "menu_order",
			"has_archives": false,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/2"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 1,
			"name": "Color",
			"slug": "pa_color",
			"type": "select",
			"order_by": "menu_order",
			"has_archives": true,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes/6"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/attributes"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Product categories

*Source: apis/rest-api/v3/product-categories.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product categories

The product categories API allows you to create, view, update, and delete individual, or a batch, of categories.

## Product category properties

| Attribute     | Type    | Description                                                                                                      |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`                                    |
| `name`        | string  | Category name. `MANDATORY`                                                         |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                                                  |
| `parent`      | integer | The ID for the parent of the resource.                                                                           |
| `description` | string  | HTML description of the resource.                                                                                |
| `display`     | string  | Category archive display type. Options: `default`, `products`, `subcategories` and `both`. Default is `default`. |
| `image`       | object  | Image data. See [Product category - Image properties](#product-category---image-properties)                        |
| `menu_order`  | integer | Menu order, used to custom sort the resource.                                                                    |
| `count`       | integer | Number of published products for the resource. `READ-ONLY`                         |

### Product category - Image properties

| Attribute           | Type      | Description                                                                                             |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `id`                | integer   | Image ID.                                                                                               |
| `date_created`      | date-time | The date the image was created, in the site's timezone. `READ-ONLY`       |
| `date_created_gmt`  | date-time | The date the image was created, as GMT `READ-ONLY`                        |
| `date_modified`     | date-time | The date the image was last modified, in the site's timezone. `READ-ONLY` |
| `date_modified_gmt` | date-time | The date the image was last modified, as GMT. `READ-ONLY`                 |
| `src`               | string    | Image URL.                                                                                              |
| `name`              | string    | Image name.                                                                                             |
| `alt`               | string    | Image alternative text.                                                                                 |

## Create a product category

This API helps you to create a new product category.

```http
POST /wp-json/wc/v3/products/categories
```

> Example of how to create a product category:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/categories \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Clothing",
  "image": {
    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Clothing',
	image: {
		src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg',
	},
};

WooCommerce.post( 'products/categories', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    "name' => 'Clothing',
    'image' => [
        'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg'
    ]
];

print_r($woocommerce->post('products/categories', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Clothing",
    "image": {
        "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
    }
}

print(wcapi.post("products/categories", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Clothing",
  image: {
    src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
  }
}

woocommerce.post("products/categories", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 9,
	"name": "Clothing",
	"slug": "clothing",
	"parent": 0,
	"description": "",
	"display": "default",
	"image": {
		"id": 730,
		"date_created": "2017-03-23T00:01:07",
		"date_created_gmt": "2017-03-23T03:01:07",
		"date_modified": "2017-03-23T00:01:07",
		"date_modified_gmt": "2017-03-23T03:01:07",
		"src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
		"name": "",
		"alt": ""
	},
	"menu_order": 0,
	"count": 36,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/categories/9"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/categories"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a product category

This API lets you retrieve a product category by ID.

```http
GET /wp-json/wc/v3/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/categories/9 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/categories/9' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/categories/9')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/categories/9").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/categories/9").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 9,
	"name": "Clothing",
	"slug": "clothing",
	"parent": 0,
	"description": "",
	"display": "default",
	"image": {
		"id": 730,
		"date_created": "2017-03-23T00:01:07",
		"date_created_gmt": "2017-03-23T03:01:07",
		"date_modified": "2017-03-23T00:01:07",
		"date_modified_gmt": "2017-03-23T03:01:07",
		"src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
		"name": "",
		"alt": ""
	},
	"menu_order": 0,
	"count": 36,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/categories/9"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/categories"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all product categories

This API lets you retrieve all product categories.

```http
GET /wp-json/wc/v3/products/categories
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/categories \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/categories' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/categories')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/categories").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/categories").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 15,
		"name": "Albums",
		"slug": "albums",
		"parent": 11,
		"description": "",
		"display": "default",
		"image": [],
		"menu_order": 0,
		"count": 4,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/15"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/11"
				}
			]
		}
	},
	{
		"id": 9,
		"name": "Clothing",
		"slug": "clothing",
		"parent": 0,
		"description": "",
		"display": "default",
		"image": {
			"id": 730,
			"date_created": "2017-03-23T00:01:07",
			"date_created_gmt": "2017-03-23T03:01:07",
			"date_modified": "2017-03-23T00:01:07",
			"date_modified_gmt": "2017-03-23T03:01:07",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
			"name": "",
			"alt": ""
		},
		"menu_order": 0,
		"count": 36,
		"_links": {
			"self": [
				{
					"href": "https://example/wp-json/wc/v3/products/categories/9"
				}
			],
			"collection": [
				{
					"href": "https://example/wp-json/wc/v3/products/categories"
				}
			]
		}
	},
	{
		"id": 10,
		"name": "Hoodies",
		"slug": "hoodies",
		"parent": 9,
		"description": "",
		"display": "default",
		"image": [],
		"menu_order": 0,
		"count": 6,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/10"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/9"
				}
			]
		}
	},
	{
		"id": 11,
		"name": "Music",
		"slug": "music",
		"parent": 0,
		"description": "",
		"display": "default",
		"image": [],
		"menu_order": 0,
		"count": 7,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/11"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories"
				}
			]
		}
	},
	{
		"id": 12,
		"name": "Posters",
		"slug": "posters",
		"parent": 0,
		"description": "",
		"display": "default",
		"image": [],
		"menu_order": 0,
		"count": 5,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/12"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories"
				}
			]
		}
	},
	{
		"id": 13,
		"name": "Singles",
		"slug": "singles",
		"parent": 11,
		"description": "",
		"display": "default",
		"image": [],
		"menu_order": 0,
		"count": 3,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/13"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/11"
				}
			]
		}
	},
	{
		"id": 14,
		"name": "T-shirts",
		"slug": "t-shirts",
		"parent": 9,
		"description": "",
		"display": "default",
		"image": [],
		"menu_order": 0,
		"count": 6,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/14"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/categories/9"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter    | Type    | Description                                                                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                 |
| `page`       | integer | Current page of the collection. Default is `1`.                                                                                              |
| `per_page`   | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                       |
| `search`     | string  | Limit results to those matching a string.                                                                                                    |
| `exclude`    | array   | Ensure result set excludes specific ids.                                                                                                     |
| `include`    | array   | Limit result set to specific ids.                                                                                                            |
| `order`      | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                   |
| `orderby`    | string  | Sort collection by resource attribute. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. Default is `name`. |
| `hide_empty` | boolean | Whether to hide resources not assigned to any products. Default is `false`.                                                                  |
| `parent`     | integer | Limit result set to resources assigned to a specific parent.                                                                                 |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                                |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                          |

## Update a product category

This API lets you make changes to a product category.

```http
PUT /wp-json/wc/v3/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/products/categories/9 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "All kinds of clothes."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	description: 'All kinds of clothes.',
};

WooCommerce.put( 'products/categories/9', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description' => 'All kinds of clothes.'
];

print_r($woocommerce->put('products/categories/9', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "All kinds of clothes."
}

print(wcapi.put("products/categories/9", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "All kinds of clothes."
}

woocommerce.put("products/categories/9", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 9,
	"name": "Clothing",
	"slug": "clothing",
	"parent": 0,
	"description": "All kinds of clothes.",
	"display": "default",
	"image": {
		"id": 730,
		"date_created": "2017-03-23T00:01:07",
		"date_created_gmt": "2017-03-23T03:01:07",
		"date_modified": "2017-03-23T00:01:07",
		"date_modified_gmt": "2017-03-23T03:01:07",
		"src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
		"name": "",
		"alt": ""
	},
	"menu_order": 0,
	"count": 36,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/categories/9"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/categories"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a product category

This API helps you delete a product category.

```http
DELETE /wp-json/wc/v3/products/categories/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/products/categories/9?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'products/categories/9', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/categories/9', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/categories/9", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/categories/9", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 9,
	"name": "Clothing",
	"slug": "clothing",
	"parent": 0,
	"description": "All kinds of clothes.",
	"display": "default",
	"image": {
		"id": 730,
		"date_created": "2017-03-23T00:01:07",
		"date_created_gmt": "2017-03-23T03:01:07",
		"date_modified": "2017-03-23T00:01:07",
		"date_modified_gmt": "2017-03-23T03:01:07",
		"src": "https://example.com/wp-content/uploads/2017/03/T_2_front.jpg",
		"name": "",
		"alt": ""
	},
	"menu_order": 0,
	"count": 36,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/categories/9"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/categories"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product categories

This API helps you to batch create, update and delete multiple product categories.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/products/categories/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/categories/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Albums"
    },
    {
      "name": "Clothing"
    }
  ],
  "update": [
    {
      "id": 10,
      "description": "Nice hoodies"
    }
  ],
  "delete": [
    11,
    12
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			name: 'Albums',
		},
		{
			name: 'Clothing',
		},
	],
	update: [
		{
			id: 10,
			description: 'Nice hoodies',
		},
	],
	delete: [ 11, 12 ],
};

WooCommerce.post( 'products/categories/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Albums'
        ],
        [
            'name' => 'Clothing'
        ]
    ],
    'update' => [
        [
            'id' => 10,
            'description' => 'Nice hoodies'
        ]
    ],
    'delete' => [
        11,
        12
    ]
];

print_r($woocommerce->post('products/categories/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Albums"
        },
        {
            "name": "Clothing"
        }
    ],
    "update": [
        {
            "id": 10,
            "description": "Nice hoodies"
        }
    ],
    "delete": [
        11,
        12
    ]
}

print(wcapi.post("products/categories/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Albums"
    },
    {
      name: "Clothing"
    }
  ],
  update: [
    {
      id: 10,
      description: "Nice hoodies"
    }
  ],
  delete: [
    11,
    12
  ]
}

woocommerce.post("products/categories/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 15,
			"name": "Albums",
			"slug": "albums",
			"parent": 11,
			"description": "",
			"display": "default",
			"image": [],
			"menu_order": 0,
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories/15"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories/11"
					}
				]
			}
		},
		{
			"id": 9,
			"name": "Clothing",
			"slug": "clothing",
			"parent": 0,
			"description": "",
			"display": "default",
			"image": [],
			"menu_order": 0,
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories/9"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 10,
			"name": "Hoodies",
			"slug": "hoodies",
			"parent": 9,
			"description": "Nice hoodies",
			"display": "default",
			"image": [],
			"menu_order": 0,
			"count": 6,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories/10"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories/9"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 11,
			"name": "Music",
			"slug": "music",
			"parent": 0,
			"description": "",
			"display": "default",
			"image": [],
			"menu_order": 0,
			"count": 7,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories/11"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories"
					}
				]
			}
		},
		{
			"id": 12,
			"name": "Posters",
			"slug": "posters",
			"parent": 0,
			"description": "",
			"display": "default",
			"image": [],
			"menu_order": 0,
			"count": 5,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories/12"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/categories"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Product custom fields

*Source: apis/rest-api/v3/product-custom-fields.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product custom fields

The product custom fields API allows you to view the custom field names that have been recorded.

## Custom fields available parameters

| Parameter  | Type    | Description                                                                                                                  |
| ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `context`  | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |
| `page`     | integer | Current page of the collection. Default is `1`.                                                                              |
| `per_page` | integer | Maximum number of items to be returned in result set. Default is `10`.                                                       |
| `search`   | string  | Limit results to those matching a string.                                                                                    |
| `order`    | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                  |

## Retrieve product custom field names

This API lets you retrieve filtered custom field names.

```http
GET /wp-json/wc/v3/products/custom-fields/names
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/custom-fields/names \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/custom-fields/names' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/custom-fields/names')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/custom-fields/names").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/custom-fields/names").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	"Custom field 1",
	"Custom field 2",
	"Custom field 3",
	"Custom field 4"
]
```

  </TabItem>
</Tabs>


---

## Product reviews

*Source: apis/rest-api/v3/product-reviews.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product reviews

The product reviews API allows you to create, view, update, and delete individual, or a batch, of product reviews.

## Product review properties

| Attribute          | Type    | Description                                                                                                         |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`               | integer | Unique identifier for the resource. `READ-ONLY`                                       |
| `date_created`     | string  | The date the review was created, in the site's timezone. `READ-ONLY`                  |
| `date_created_gmt` | string  | The date the review was created, as GMT. `READ-ONLY`                                  |
| `product_id`       | integer | Unique identifier for the product that the review belongs to.                                                       |
| `status`           | string  | Status of the review. Options: `approved`, `hold`, `spam`, `unspam`, `trash` and `untrash`. Defaults to `approved`. |
| `reviewer`         | string  | Reviewer name.                                                                                                      |
| `reviewer_email`   | string  | Reviewer email.                                                                                                     |
| `review`           | string  | The content of the review.                                                                                          |
| `rating`           | integer | Review rating (0 to 5).                                                                                             |
| `verified`         | boolean | Shows if the reviewer bought the product or not.                                                                    |

## Create a product review

This API helps you to create a new product review.

```http
POST /wp-json/wc/v3/products/reviews
```

> Example of how to create a product review:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/reviews \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "product_id": 22,
  "review": "Nice album!",
  "reviewer": "John Doe",
  "reviewer_email": "john.doe@example.com",
  "rating": 5
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	product_id: 22,
	review: 'Nice album!',
	reviewer: 'John Doe',
	reviewer_email: 'john.doe@example.com',
	rating: 5,
};

WooCommerce.post( 'products/reviews', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'product_id' => 22,
    'review' => 'Nice album!',
    'reviewer' => 'John Doe',
    'reviewer_email' => 'john.doe@example.com',
    'rating' => 5
];

print_r($woocommerce->post('products/reviews', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "product_id": 22,
    "review": "Nice album!",
    "reviewer": "John Doe",
    "reviewer_email": "john.doe@example.com",
    "rating": 5,
}

print(wcapi.post("products/reviews", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  product_id: 22,
  review: "Nice album!",
  reviewer: "John Doe",
  reviewer_email: "john.doe@example.com",
  rating: 5
}

woocommerce.post("products/reviews", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 22,
	"date_created": "2018-10-18T17:59:17",
	"date_created_gmt": "2018-10-18T20:59:17",
	"product_id": 22,
	"status": "approved",
	"reviewer": "John Doe",
	"reviewer_email": "john.doe@example.com",
	"review": "Nice album!",
	"rating": 5,
	"verified": false,
	"reviewer_avatar_urls": {
		"24": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=24&d=mm&r=g",
		"48": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=48&d=mm&r=g",
		"96": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96&d=mm&r=g"
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/reviews/22"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/reviews"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a product review

This API lets you retrieve a product review by ID.

```http
GET /wp-json/wc/v3/products/reviews/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/reviews/22 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/reviews/22' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/reviews/22')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/reviews/22").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/reviews/22").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 22,
	"date_created": "2018-10-18T17:59:17",
	"date_created_gmt": "2018-10-18T20:59:17",
	"product_id": 22,
	"status": "approved",
	"reviewer": "John Doe",
	"reviewer_email": "john.doe@example.com",
	"review": "Nice album!",
	"rating": 5,
	"verified": false,
	"reviewer_avatar_urls": {
		"24": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=24&d=mm&r=g",
		"48": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=48&d=mm&r=g",
		"96": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96&d=mm&r=g"
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/reviews/22"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/reviews"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all product reviews

This API lets you retrieve all product review.

```http
GET /wp-json/wc/v3/products/reviews
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/reviews \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/reviews' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/reviews')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/reviews").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/reviews").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 22,
		"date_created": "2018-10-18T17:59:17",
		"date_created_gmt": "2018-10-18T20:59:17",
		"product_id": 22,
		"status": "approved",
		"reviewer": "John Doe",
		"reviewer_email": "john.doe@example.com",
		"review": "<p>Nice album!</p>\n",
		"rating": 5,
		"verified": false,
		"reviewer_avatar_urls": {
			"24": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=24&d=mm&r=g",
			"48": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=48&d=mm&r=g",
			"96": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96&d=mm&r=g"
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/reviews/22"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/reviews"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/22"
				}
			]
		}
	},
	{
		"id": 20,
		"date_created": "2018-09-08T21:47:19",
		"date_created_gmt": "2018-09-09T00:47:19",
		"product_id": 31,
		"status": "approved",
		"reviewer": "Claudio Sanches",
		"reviewer_email": "john.doe@example.com",
		"review": "<p>Now works just fine.</p>\n",
		"rating": 1,
		"verified": true,
		"reviewer_avatar_urls": {
			"24": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=24&d=mm&r=g",
			"48": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=48&d=mm&r=g",
			"96": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=96&d=mm&r=g"
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/reviews/20"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/reviews"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/31"
				}
			],
			"reviewer": [
				{
					"embeddable": true,
					"href": "https://example.com/wp-json/wp/v2/users/1"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter          | Type    | Description                                                                                                                            |
| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `context`          | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.           |
| `page`             | integer | Current page of the collection. Default is `1`.                                                                                        |
| `per_page`         | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                 |
| `search`           | string  | Limit results to those matching a string.                                                                                              |
| `after`            | string  | Limit response to reviews published after a given ISO8601 compliant date.                                                              |
| `before`           | string  | Limit response to reviews published before a given ISO8601 compliant date.                                                             |
| `dates_are_gmt`    | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                               |
| `exclude`          | array   | Ensure result set excludes specific ids.                                                                                               |
| `include`          | array   | Limit result set to specific ids.                                                                                                      |
| `offset`           | integer | Offset the result set by a specific number of items.                                                                                   |
| `order`            | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                            |
| `orderby`          | string  | Sort collection by resource attribute. Options: `date`, `date_gmt`, `id`, `slug`, `include` and `product`. Default is `date_gmt`.      |
| `reviewer`         | array   | Limit result set to reviews assigned to specific user IDs.                                                                             |
| `reviewer_exclude` | array   | Ensure result set excludes reviews assigned to specific user IDs.                                                                      |
| `reviewer_email`   | array   | Limit result set to that from a specific author email.                                                                                 |
| `product`          | array   | Limit result set to reviews assigned to specific product IDs.                                                                          |
| `status`           | string  | Limit result set to reviews assigned a specific status. Options: `all`, `hold`, `approved`, `spam` and `trash`. Default is `approved`. |

## Update a product review

This API lets you make changes to a product review.

```http
PUT /wp-json/wc/v3/products/reviews/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/products/reviews/20 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "rating": 5
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	rating: 5,
};

WooCommerce.put( 'products/reviews/20', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'rating' => 5
];

print_r($woocommerce->put('products/reviews/20', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "rating": 5
}

print(wcapi.put("products/reviews/20", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  rating: 5
}

woocommerce.put("products/reviews/20", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 20,
	"date_created": "2018-09-08T21:47:19",
	"date_created_gmt": "2018-09-09T00:47:19",
	"product_id": 31,
	"status": "approved",
	"reviewer": "Claudio Sanches",
	"reviewer_email": "john.doe@example.com",
	"review": "Now works just fine.",
	"rating": 5,
	"verified": true,
	"reviewer_avatar_urls": {
		"24": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=24&d=mm&r=g",
		"48": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=48&d=mm&r=g",
		"96": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=96&d=mm&r=g"
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/reviews/20"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/reviews"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/31"
			}
		],
		"reviewer": [
			{
				"embeddable": true,
				"href": "https://example.com/wp-json/wp/v2/users/1"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a product review

This API helps you delete a product review.

```http
DELETE /wp-json/wc/v3/products/reviews/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/products/reviews/34?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'products/reviews/20', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/reviews/20', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/reviews/20", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/reviews/20", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"deleted": true,
	"previous": {
		"id": 20,
		"date_created": "2018-09-08T21:47:19",
		"date_created_gmt": "2018-09-09T00:47:19",
		"product_id": 31,
		"status": "trash",
		"reviewer": "Claudio Sanches",
		"reviewer_email": "john.doe@example.com",
		"review": "Now works just fine.",
		"rating": 5,
		"verified": true,
		"reviewer_avatar_urls": {
			"24": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=24&d=mm&r=g",
			"48": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=48&d=mm&r=g",
			"96": "https://secure.gravatar.com/avatar/908480753c07509e76322dc17d305c8b?s=96&d=mm&r=g"
		}
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product reviews

This API helps you to batch create, update and delete multiple product reviews.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/products/reviews/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/reviews/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "product_id": 22,
      "review": "Looks fine",
      "reviewer": "John Doe",
      "reviewer_email": "john.doe@example.com",
      "rating": 4
    },
    {
      "product_id": 22,
      "review": "I love this album",
      "reviewer": "John Doe",
      "reviewer_email": "john.doe@example.com",
      "rating": 5
    }
  ],
  "update": [
    {
      "id": 7,
      "reviewer": "John Doe",
      "reviewer_email": "john.doe@example.com"
    }
  ],
  "delete": [
    22
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			product_id: 22,
			review: 'Looks fine',
			reviewer: 'John Doe',
			reviewer_email: 'john.doe@example.com',
			rating: 4,
		},
		{
			product_id: 22,
			review: 'I love this album',
			reviewer: 'John Doe',
			reviewer_email: 'john.doe@example.com',
			rating: 5,
		},
	],
	update: [
		{
			id: 7,
			reviewer: 'John Doe',
			reviewer_email: 'john.doe@example.com',
		},
	],
	delete: [ 22 ],
};

WooCommerce.post( 'products/reviews/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'product_id' => 22,
            'review' => 'Looks fine',
            'reviewer' => 'John Doe',
            'reviewer_email' => 'john.doe@example.com',
            'rating' => 4
        ],
        [
            'product_id' => 22,
            'review' => 'I love this album',
            'reviewer' => 'John Doe',
            'reviewer_email' => 'john.doe@example.com',
            'rating' => 5
        ]
    ],
    'update' => [
        [
            'id' => 7,
            'reviewer' => 'John Doe',
            'reviewer_email' => 'john.doe@example.com',
        ]
    ],
    'delete' => [
        22
    ]
];

print_r($woocommerce->post('products/reviews/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "product_id": 22,
            "review": "Looks fine",
            "reviewer": "John Doe",
            "reviewer_email": "john.doe@example.com",
            "rating": 4
        },
        {
            "product_id": 22,
            "review": "I love this album",
            "reviewer": "John Doe",
            "reviewer_email": "john.doe@example.com",
            "rating": 5
        }
    ],
    "update": [
        {
            "id": 7,
            "reviewer": "John Doe",
            "reviewer_email": "john.doe@example.com"
        }
    ],
    "delete": [
        22
    ]
}

print(wcapi.post("products/reviews/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      product_id: "22",
      review: "Looks fine",
      reviewer: "John Doe",
      reviewer_email: "john.doe@example.com",
      rating: "4"
    },
    {
      product_id: "22",
      review: "I love this album",
      reviewer: "John Doe",
      reviewer_email: "john.doe@example.com",
      rating: "5"
    }
  ],
  update: [
    {
      id: 7,
      reviewer: "John Doe",
      reviewer_email: "john.doe@example.com"
    }
  ],
  delete: [
    22
  ]
}

woocommerce.post("products/reviews/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 25,
			"date_created": "2018-10-18T18:37:35",
			"date_created_gmt": "2018-10-18T21:37:35",
			"product_id": 22,
			"status": "approved",
			"reviewer": "John Doe",
			"reviewer_email": "john.doe@example.com",
			"review": "Looks fine",
			"rating": 4,
			"verified": false,
			"reviewer_avatar_urls": {
				"24": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=24&d=mm&r=g",
				"48": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=48&d=mm&r=g",
				"96": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96&d=mm&r=g"
			},
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/reviews/25"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/reviews"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22"
					}
				]
			}
		},
		{
			"id": 26,
			"date_created": "2018-10-18T18:37:35",
			"date_created_gmt": "2018-10-18T21:37:35",
			"product_id": 22,
			"status": "approved",
			"reviewer": "John Doe",
			"reviewer_email": "john.doe@example.com",
			"review": "I love this album",
			"rating": 5,
			"verified": false,
			"reviewer_avatar_urls": {
				"24": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=24&d=mm&r=g",
				"48": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=48&d=mm&r=g",
				"96": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96&d=mm&r=g"
			},
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/reviews/26"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/reviews"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 7,
			"date_created": "2018-07-26T19:29:21",
			"date_created_gmt": "2018-07-26T22:29:21",
			"product_id": 66,
			"status": "approved",
			"reviewer": "John Doe",
			"reviewer_email": "john.doe@example.com",
			"review": "Not so bad :(",
			"rating": 3,
			"verified": false,
			"reviewer_avatar_urls": {
				"24": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=24&d=mm&r=g",
				"48": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=48&d=mm&r=g",
				"96": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96&d=mm&r=g"
			},
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/reviews/7"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/reviews"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/66"
					}
				]
			}
		}
	],
	"delete": [
		{
			"deleted": true,
			"previous": {
				"id": 22,
				"date_created": "2018-10-18T17:59:17",
				"date_created_gmt": "2018-10-18T20:59:17",
				"product_id": 22,
				"status": "approved",
				"reviewer": "John Doe",
				"reviewer_email": "john.doe@example.com",
				"review": "Nice album!",
				"rating": 5,
				"verified": false,
				"reviewer_avatar_urls": {
					"24": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=24&d=mm&r=g",
					"48": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=48&d=mm&r=g",
					"96": "https://secure.gravatar.com/avatar/8eb1b522f60d11fa897de1dc6351b7e8?s=96&d=mm&r=g"
				}
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Product shipping classes

*Source: apis/rest-api/v3/product-shipping-classes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product shipping classes

The product shipping class API allows you to create, view, update, and delete individual, or a batch, of shipping classes.

## Product shipping class properties

| Attribute     | Type    | Description                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Shipping class name. `MANDATORY`                           |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create a shipping class

This API helps you to create a new product shipping class.

```http
POST /wp-json/wc/v3/products/shipping_classes
```

> Example of how to create a product shipping class:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/shipping_classes \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Priority"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Priority',
};

WooCommerce.post( 'products/shipping_classes', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Priority'
];

print_r($woocommerce->post('products/shipping_classes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Priority"
}

print(wcapi.post("products/shipping_classes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Priority"
}

woocommerce.post("products/shipping_classes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 32,
	"name": "Priority",
	"slug": "priority",
	"description": "",
	"count": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/32"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a shipping class

This API lets you retrieve a product shipping class by ID.

```http
GET /wp-json/wc/v3/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/shipping_classes/32 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/shipping_classes/32' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/shipping_classes/32')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/shipping_classes/32").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/shipping_classes/32").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 32,
	"name": "Priority",
	"slug": "priority",
	"description": "",
	"count": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/32"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all shipping classes

This API lets you retrieve all product shipping classes.

```http
GET /wp-json/wc/v3/products/shipping_classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/shipping_classes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/shipping_classes' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/shipping_classes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/shipping_classes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/shipping_classes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 33,
		"name": "Express",
		"slug": "express",
		"description": "",
		"count": 0,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/33"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
				}
			]
		}
	},
	{
		"id": 32,
		"name": "Priority",
		"slug": "priority",
		"description": "",
		"count": 0,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/32"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter    | Type    | Description                                                                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                 |
| `page`       | integer | Current page of the collection. Default is `1`.                                                                                              |
| `per_page`   | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                       |
| `search`     | string  | Limit results to those matching a string.                                                                                                    |
| `exclude`    | array   | Ensure result set excludes specific ids.                                                                                                     |
| `include`    | array   | Limit result set to specific ids.                                                                                                            |
| `offset`     | integer | Offset the result set by a specific number of items.                                                                                         |
| `order`      | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                   |
| `orderby`    | string  | Sort collection by resource attribute. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. Default is `name`. |
| `hide_empty` | boolean | Whether to hide resources not assigned to any products. Default is `false`.                                                                  |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                                |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                          |

## Update a shipping class

This API lets you make changes to a product shipping class.

```http
PUT /wp-json/wc/v3/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/products/shipping_classes/32 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "Priority mail."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	description: 'Priority mail.',
};

WooCommerce.put( 'products/shipping_classes/32', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description' => 'Priority mail.'
];

print_r($woocommerce->put('products/shipping_classes/32', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "Priority mail."
}

print(wcapi.put("products/shipping_classes/32", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "Priority mail."
}

woocommerce.put("products/shipping_classes/32", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 32,
	"name": "Priority",
	"slug": "priority",
	"description": "Priority mail.",
	"count": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/32"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a shipping class

This API helps you delete a product shipping class.

```http
DELETE /wp-json/wc/v3/products/shipping_classes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/products/shipping_classes/32?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'products/shipping_classes/32', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/shipping_classes/32', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/shipping_classes/32", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/shipping_classes/32", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 32,
	"name": "Priority",
	"slug": "priority",
	"description": "Priority mail.",
	"count": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/32"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update shipping classes

This API helps you to batch create, update and delete multiple product shipping classes.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/products/shipping_classes/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/shipping_classes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Small items"
    },
    {
      "name": "Large items"
    }
  ],
  "update": [
    {
      "id": 33,
      "description": "Express shipping"
    }
  ],
  "delete": [
    32
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			name: 'Small items',
		},
		{
			name: 'Large items',
		},
	],
	update: [
		{
			id: 33,
			description: 'Express shipping',
		},
	],
	delete: [ 32 ],
};

WooCommerce.post( 'products/shipping_classes/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Small items'
        ],
        [
            'name' => 'Large items'
        ]
    ],
    'update' => [
        [
            'id' => 33,
            'description' => 'Express shipping'
        ]
    ],
    'delete' => [
        32
    ]
];

print_r($woocommerce->post('products/shipping_classes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Small items"
        },
        {
            "name": "Large items"
        }
    ],
    "update": [
        {
            "id": 33,
            "description": "Express shipping"
        }
    ],
    "delete": [
        32
    ]
}

print(wcapi.post("products/shipping_classes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Small items"
    },
    {
      name: "Large items"
    }
  ],
  update: [
    {
      id: 33,
      description: "Express shipping"
    }
  ],
  delete: [
    32
  ]
}

woocommerce.post("products/shipping_classes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 34,
			"name": "Small items",
			"slug": "small-items",
			"description": "",
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/34"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
					}
				]
			}
		},
		{
			"id": 35,
			"name": "Large items",
			"slug": "large-items",
			"description": "",
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/35"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 33,
			"name": "Express",
			"slug": "express",
			"description": "Express shipping",
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/33"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 32,
			"name": "Priority",
			"slug": "priority",
			"description": "",
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/shipping_classes/32"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/shipping_classes"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Product tags

*Source: apis/rest-api/v3/product-tags.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product tags

The product tags API allows you to create, view, update, and delete individual, or a batch, of product tags.

## Product tag properties

| Attribute     | Type    | Description                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`          | integer | Unique identifier for the resource. `READ-ONLY`            |
| `name`        | string  | Tag name. `MANDATORY`                                      |
| `slug`        | string  | An alphanumeric identifier for the resource unique to its type.                          |
| `description` | string  | HTML description of the resource.                                                        |
| `count`       | integer | Number of published products for the resource. `READ-ONLY` |

## Create a product tag

This API helps you to create a new product tag.

```http
POST /wp-json/wc/v3/products/tags
```

> Example of how to create a product tag:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/tags \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Leather Shoes"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Leather Shoes',
};

WooCommerce.post( 'products/tags', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Leather Shoes'
];

print_r($woocommerce->post('products/tags', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Leather Shoes"
}

print(wcapi.post("products/tags", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Leather Shoes"
}

woocommerce.post("products/tags", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 34,
	"name": "Leather Shoes",
	"slug": "leather-shoes",
	"description": "",
	"count": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/tags/34"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/tags"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a product tag

This API lets you retrieve a product tag by ID.

```http
GET /wp-json/wc/v3/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/tags/34 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/tags/34' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/tags/34')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/tags/34").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/tags/34").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 34,
	"name": "Leather Shoes",
	"slug": "leather-shoes",
	"description": "",
	"count": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/tags/34"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/tags"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all product tags

This API lets you retrieve all product tag.

```http
GET /wp-json/wc/v3/products/tags
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/tags \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/tags' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/tags')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/tags").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/tags").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 34,
		"name": "Leather Shoes",
		"slug": "leather-shoes",
		"description": "",
		"count": 0,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/tags/34"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/tags"
				}
			]
		}
	},
	{
		"id": 35,
		"name": "Oxford Shoes",
		"slug": "oxford-shoes",
		"description": "",
		"count": 0,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/tags/35"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/tags"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter    | Type    | Description                                                                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                 |
| `page`       | integer | Current page of the collection. Default is `1`.                                                                                              |
| `per_page`   | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                       |
| `search`     | string  | Limit results to those matching a string.                                                                                                    |
| `exclude`    | array   | Ensure result set excludes specific ids.                                                                                                     |
| `include`    | array   | Limit result set to specific ids.                                                                                                            |
| `offset`     | integer | Offset the result set by a specific number of items.                                                                                         |
| `order`      | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `asc`.                                                   |
| `orderby`    | string  | Sort collection by resource attribute. Options: `id`, `include`, `name`, `slug`, `term_group`, `description` and `count`. Default is `name`. |
| `hide_empty` | boolean | Whether to hide resources not assigned to any products. Default is `false`.                                                                  |
| `product`    | integer | Limit result set to resources assigned to a specific product.                                                                                |
| `slug`       | string  | Limit result set to resources with a specific slug.                                                                                          |

## Update a product tag

This API lets you make changes to a product tag.

```http
PUT /wp-json/wc/v3/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/products/tags/34 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "description": "Genuine leather."
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	description: 'Genuine leather.',
};

WooCommerce.put( 'products/tags/34', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'description': 'Genuine leather.'
];

print_r($woocommerce->put('products/tags/34', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "description": "Genuine leather."
}

print(wcapi.put("products/tags/34", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  description: "Genuine leather."
}

woocommerce.put("products/tags/34", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 34,
	"name": "Leather Shoes",
	"slug": "leather-shoes",
	"description": "Genuine leather.",
	"count": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/tags/34"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/tags"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a product tag

This API helps you delete a product tag.

```http
DELETE /wp-json/wc/v3/products/tags/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/products/tags/34?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'products/tags/34', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/tags/34', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/tags/34", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/tags/34", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 34,
	"name": "Leather Shoes",
	"slug": "leather-shoes",
	"description": "Genuine leather.",
	"count": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/tags/34"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/tags"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product tags

This API helps you to batch create, update and delete multiple product tags.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/products/tags/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/tags/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Round toe"
    },
    {
      "name": "Flat"
    }
  ],
  "update": [
    {
      "id": 34,
      "description": "Genuine leather."
    }
  ],
  "delete": [
    35
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			name: 'Round toe',
		},
		{
			name: 'Flat',
		},
	],
	update: [
		{
			id: 34,
			description: 'Genuine leather.',
		},
	],
	delete: [ 35 ],
};

WooCommerce.post( 'products/tags/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Round toe'
        ],
        [
            'name' => 'Flat'
        ]
    ],
    'update' => [
        [
            'id' => 34,
            'description' => 'Genuine leather.'
        ]
    ],
    'delete' => [
        35
    ]
];

print_r($woocommerce->post('products/tags/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Round toe"
        },
        {
            "name": "Flat"
        }
    ],
    "update": [
        {
            "id": 34,
            "description": "Genuine leather."
        }
    ],
    "delete": [
        35
    ]
}

print(wcapi.post("products/tags/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Round toe"
    },
    {
      name: "Flat"
    }
  ],
  update: [
    {
      id: 34,
      description: "Genuine leather."
    }
  ],
  delete: [
    35
  ]
}

woocommerce.post("products/tags/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 36,
			"name": "Round toe",
			"slug": "round-toe",
			"description": "",
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/tags/36"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/tags"
					}
				]
			}
		},
		{
			"id": 37,
			"name": "Flat",
			"slug": "flat",
			"description": "",
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/tags/37"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/tags"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 34,
			"name": "Leather Shoes",
			"slug": "leather-shoes",
			"description": "Genuine leather.",
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/tags/34"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/tags"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 35,
			"name": "Oxford Shoes",
			"slug": "oxford-shoes",
			"description": "",
			"count": 0,
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/tags/35"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/tags"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Product variations

*Source: apis/rest-api/v3/product-variations.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Product variations

The product variations API allows you to create, view, update, and delete individual, or a batch, of product variations.

## Product variation properties

| Attribute               | Type            | Description                                                                                                         |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`                    | integer         | Unique identifier for the resource. `READ-ONLY`                                       |
| `date_created`          | date-time       | The date the variation was created, in the site's timezone. `READ-ONLY`               |
| `date_created_gmt`      | date-time       | The date the variation was created, as GMT. `READ-ONLY`                               |
| `date_modified`         | date-time       | The date the variation was last modified, in the site's timezone. `READ-ONLY`         |
| `date_modified_gmt`     | date-time       | The date the variation was last modified, as GMT. `READ-ONLY`                         |
| `description`           | string          | Variation description.                                                                                              |
| `permalink`             | string          | Variation URL. `READ-ONLY`                                                            |
| `sku`                   | string          | Unique identifier.                                                                                                  |
| `global_unique_id`      | string          | GTIN, UPC, EAN or ISBN. A global unique identifier for the variation.                                               |
| `price`                 | string          | Current variation price. `READ-ONLY`                                                  |
| `regular_price`         | string          | Variation regular price.                                                                                            |
| `sale_price`            | string          | Variation sale price.                                                                                               |
| `date_on_sale_from`     | date-time       | Start date of sale price, in the site's timezone.                                                                   |
| `date_on_sale_from_gmt` | date-time       | Start date of sale price, as GMT.                                                                                   |
| `date_on_sale_to`       | date-time       | End date of sale price, in the site's timezone.                                                                     |
| `date_on_sale_to_gmt`   | date-time       | End date of sale price, as GMT.                                                                                     |
| `on_sale`               | boolean         | Shows if the variation is on sale. `READ-ONLY`                                        |
| `status`                | string          | Variation status. Options: `draft`, `pending`, `private` and `publish`. Default is `publish`.                       |
| `purchasable`           | boolean         | Shows if the variation can be bought. `READ-ONLY`                                     |
| `virtual`               | boolean         | If the variation is virtual. Default is `false`.                                                                    |
| `downloadable`          | boolean         | If the variation is downloadable. Default is `false`.                                                               |
| `downloads`             | array           | List of downloadable files. See [Product variation - Downloads properties](#product-variation---downloads-properties) |
| `download_limit`        | integer         | Number of times downloadable files can be downloaded after purchase. Default is `-1`.                               |
| `download_expiry`       | integer         | Number of days until access to downloadable files expires. Default is `-1`.                                         |
| `tax_status`            | string          | Tax status. Options: `taxable`, `shipping` and `none`. Default is `taxable`.                                        |
| `tax_class`             | string          | Tax class.                                                                                                          |
| `manage_stock`          | boolean, string | Stock management at variation level. Possible values are either a boolean or `parent`. Default is `false`.          |
| `stock_quantity`        | integer         | Stock quantity.                                                                                                     |
| `stock_status`          | string          | Controls the stock status of the product. Options: `instock`, `outofstock`, `onbackorder`. Default is `instock`.    |
| `backorders`            | string          | If managing stock, this controls if backorders are allowed. Options: `no`, `notify` and `yes`. Default is `no`.     |
| `backorders_allowed`    | boolean         | Shows if backorders are allowed. `READ-ONLY`                                          |
| `backordered`           | boolean         | Shows if the variation is on backordered. `READ-ONLY`                                 |
| `weight`                | string          | Variation weight.                                                                                                   |
| `dimensions`            | object          | Variation dimensions. See [Product variation - Dimensions properties](#product-variation---dimensions-properties)     |
| `shipping_class`        | string          | Shipping class slug.                                                                                                |
| `shipping_class_id`     | string          | Shipping class ID. `READ-ONLY`                                                        |
| `image`                 | object          | Variation image data. See [Product variation - Image properties](#product-variation---image-properties)               |
| `gallery_image_ids`     | array           | Variation gallery image IDs, excluding the featured image (which is set via `image`).                               |
| `attributes`            | array           | List of attributes. See [Product variation - Attributes properties](#product-variation---attributes-properties)       |
| `menu_order`            | integer         | Menu order, used to custom sort products.                                                                           |
| `meta_data`             | array           | Meta data. See [Product variation - Meta data properties](#product-variation---meta-data-properties)                  |

### Product variation - Downloads properties

| Attribute | Type   | Description |
| --------- | ------ | ----------- |
| `id`      | string | File ID.    |
| `name`    | string | File name.  |
| `file`    | string | File URL.   |

### Product variation - Dimensions properties

| Attribute | Type   | Description       |
| --------- | ------ | ----------------- |
| `length`  | string | Variation length. |
| `width`   | string | Variation width.  |
| `height`  | string | Variation height. |

### Product variation - Image properties

| Attribute           | Type      | Description                                                                                             |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `id`                | integer   | Image ID.                                                                                               |
| `date_created`      | date-time | The date the image was created, in the site's timezone. `READ-ONLY`       |
| `date_created_gmt`  | date-time | The date the image was created, as GMT. `READ-ONLY`                       |
| `date_modified`     | date-time | The date the image was last modified, in the site's timezone. `READ-ONLY` |
| `date_modified_gmt` | date-time | The date the image was last modified, as GMT. `READ-ONLY`                 |
| `src`               | string    | Image URL.                                                                                              |
| `name`              | string    | Image name.                                                                                             |
| `alt`               | string    | Image alternative text.                                                                                 |

### Product variation - Attributes properties

| Attribute | Type    | Description                   |
| --------- | ------- | ----------------------------- |
| `id`      | integer | Attribute ID.                 |
| `name`    | string  | Attribute name.               |
| `option`  | string  | Selected attribute term name. |

### Product variation - Meta data properties

| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

## Create a product variation

This API helps you to create a new product variation.

```http
POST /wp-json/wc/v3/products/<product_id>/variations
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/22/variations \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "9.00",
  "image": {
    "id": 423
  },
  "attributes": [
    {
      "id": 6,
      "option": "Black"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	regular_price: '9.00',
	image: {
		id: 423,
	},
	attributes: [
		{
			id: 9,
			option: 'Black',
		},
	],
};

WooCommerce.post( 'products/22/variations', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'regular_price' => '9.00',
    'image' => [
        'id' => 423
    ],
    'attributes' => [
        [
            'id' => 9,
            'option' => 'Black'
        ]
    ]
];

print_r($woocommerce->post('products/22/variations', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "regular_price": "9.00",
    "image": {
        "id": 423
    },
    "attributes": [
        {
            "id": 9,
            "option": "Black"
        }
    ]
}

print(wcapi.post("products/22/variations", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  regular_price: "9.00",
  image: {
    id: 423
  },
  attributes: [
    {
      id: 9,
      option: "Black"
    }
  ]
}

woocommerce.post("products/22/variations", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 732,
	"date_created": "2017-03-23T00:36:38",
	"date_created_gmt": "2017-03-23T03:36:38",
	"date_modified": "2017-03-23T00:36:38",
	"date_modified_gmt": "2017-03-23T03:36:38",
	"description": "",
	"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=black",
	"sku": "",
	"price": "9.00",
	"regular_price": "9.00",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"on_sale": false,
	"status": true,
	"purchasable": true,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_class": "",
	"shipping_class_id": 0,
	"image": {
		"id": 423,
		"date_created": "2016-10-19T12:21:14",
		"date_created_gmt": "2016-10-19T16:21:14",
		"date_modified": "2016-10-19T12:21:14",
		"date_modified_gmt": "2016-10-19T16:21:14",
		"src": "https://example.com/wp-content/uploads/2016/10/T_4_front-12.jpg",
		"name": "",
		"alt": ""
	},
	"gallery_image_ids": [],
	"attributes": [
		{
			"id": 6,
			"name": "Color",
			"option": "Black"
		}
	],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22/variations/732"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22/variations"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a product variation

This API lets you retrieve and view a specific product variation by ID.

```http
GET /wp-json/wc/v3/products/<product_id>/variations/<id>
```

Optional query parameter: `image_size` (string). Use a specific registered image size for returned variation image `src`. Falls back to the full size when the requested size is not registered. Default is `full`.

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/22/variations/732 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/22/variations/732' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/22/variations/732')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/22/variations/732").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/22/variations/732").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 732,
	"date_created": "2017-03-23T00:36:38",
	"date_created_gmt": "2017-03-23T03:36:38",
	"date_modified": "2017-03-23T00:36:38",
	"date_modified_gmt": "2017-03-23T03:36:38",
	"description": "",
	"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=black",
	"sku": "",
	"price": "9.00",
	"regular_price": "9.00",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"on_sale": false,
	"status": "publish",
	"purchasable": true,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_class": "",
	"shipping_class_id": 0,
	"image": {
		"id": 423,
		"date_created": "2016-10-19T12:21:14",
		"date_created_gmt": "2016-10-19T16:21:14",
		"date_modified": "2016-10-19T12:21:14",
		"date_modified_gmt": "2016-10-19T16:21:14",
		"src": "https://example.com/wp-content/uploads/2016/10/T_4_front-12.jpg",
		"name": "",
		"alt": ""
	},
	"gallery_image_ids": [],
	"attributes": [
		{
			"id": 6,
			"name": "Color",
			"option": "Black"
		}
	],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22/variations/732"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22/variations"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all product variations

This API helps you to view all the product variations.

```http
GET /wp-json/wc/v3/products/<product_id>/variations
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/22/variations \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/22/variations' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/22/variations')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/22/variations").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/22/variations").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 733,
		"date_created": "2017-03-23T00:53:11",
		"date_created_gmt": "2017-03-23T03:53:11",
		"date_modified": "2017-03-23T00:53:11",
		"date_modified_gmt": "2017-03-23T03:53:11",
		"description": "",
		"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=green",
		"sku": "",
		"price": "9.00",
		"regular_price": "9.00",
		"sale_price": "",
		"date_on_sale_from": null,
		"date_on_sale_from_gmt": null,
		"date_on_sale_to": null,
		"date_on_sale_to_gmt": null,
		"on_sale": false,
		"status": "publish",
		"purchasable": true,
		"virtual": false,
		"downloadable": false,
		"downloads": [],
		"download_limit": -1,
		"download_expiry": -1,
		"tax_status": "taxable",
		"tax_class": "",
		"manage_stock": false,
		"stock_quantity": null,
		"stock_status": "instock",
		"backorders": "no",
		"backorders_allowed": false,
		"backordered": false,
		"weight": "",
		"dimensions": {
			"length": "",
			"width": "",
			"height": ""
		},
		"shipping_class": "",
		"shipping_class_id": 0,
		"image": {
			"id": 425,
			"date_created": "2016-10-19T12:21:16",
			"date_created_gmt": "2016-10-19T16:21:16",
			"date_modified": "2016-10-19T12:21:16",
			"date_modified_gmt": "2016-10-19T16:21:16",
			"src": "https://example.com/wp-content/uploads/2016/10/T_3_front-12.jpg",
			"name": "",
			"alt": ""
		},
		"gallery_image_ids": [],
		"attributes": [
			{
				"id": 6,
				"name": "Color",
				"option": "Green"
			}
		],
		"menu_order": 0,
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/22/variations/733"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/22/variations"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/22"
				}
			]
		}
	},
	{
		"id": 732,
		"date_created": "2017-03-23T00:36:38",
		"date_created_gmt": "2017-03-23T03:36:38",
		"date_modified": "2017-03-23T00:36:38",
		"date_modified_gmt": "2017-03-23T03:36:38",
		"description": "",
		"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=black",
		"sku": "",
		"price": "9.00",
		"regular_price": "9.00",
		"sale_price": "",
		"date_on_sale_from": null,
		"date_on_sale_from_gmt": null,
		"date_on_sale_to": null,
		"date_on_sale_to_gmt": null,
		"on_sale": false,
		"status": "publish",
		"purchasable": true,
		"virtual": false,
		"downloadable": false,
		"downloads": [],
		"download_limit": -1,
		"download_expiry": -1,
		"tax_status": "taxable",
		"tax_class": "",
		"manage_stock": false,
		"stock_quantity": null,
		"stock_status": "instock",
		"backorders": "no",
		"backorders_allowed": false,
		"backordered": false,
		"weight": "",
		"dimensions": {
			"length": "",
			"width": "",
			"height": ""
		},
		"shipping_class": "",
		"shipping_class_id": 0,
		"image": {
			"id": 423,
			"date_created": "2016-10-19T12:21:14",
			"date_created_gmt": "2016-10-19T16:21:14",
			"date_modified": "2016-10-19T12:21:14",
			"date_modified_gmt": "2016-10-19T16:21:14",
			"src": "https://example.com/wp-content/uploads/2016/10/T_4_front-12.jpg",
			"name": "",
			"alt": ""
		},
		"gallery_image_ids": [],
		"attributes": [
			{
				"id": 6,
				"name": "Color",
				"option": "Black"
			}
		],
		"menu_order": 0,
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/22/variations/732"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/22/variations"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/22"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter        | Type    | Description                                                                                                                                                                                                                                                                 |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`        | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                                                                                                                                                |
| `page`           | integer | Current page of the collection. Default is `1`.                                                                                                                                                                                                                             |
| `per_page`       | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                                                                                                                                                      |
| `search`         | string  | Limit results to those matching a string.                                                                                                                                                                                                                                   |
| `after`          | string  | Limit response to resources published after a given ISO8601 compliant date.                                                                                                                                                                                                 |
| `before`         | string  | Limit response to resources published before a given ISO8601 compliant date.                                                                                                                                                                                                |
| `dates_are_gmt`  | boolean | Interpret `after` and `before` as UTC dates when `true`.                                                                                                                                                                                                                    |
| `exclude`        | array   | Ensure result set excludes specific IDs.                                                                                                                                                                                                                                    |
| `include`        | array   | Limit result set to specific ids.                                                                                                                                                                                                                                           |
| `offset`         | integer | Offset the result set by a specific number of items.                                                                                                                                                                                                                        |
| `order`          | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                                                                                                                                                                 |
| `orderby`        | string  | Sort collection by object attribute. Options: `date`, `modified`, `id`, `include`, `title` and `slug`. Default is `date`.                                                                                                                                                   |
| `parent`         | array   | Limit result set to those of particular parent IDs.                                                                                                                                                                                                                         |
| `parent_exclude` | array   | Limit result set to all items except those of a particular parent ID.                                                                                                                                                                                                       |
| `slug`           | string  | Limit result set to products with a specific slug.                                                                                                                                                                                                                          |
| `status`         | string  | Limit result set to products assigned a specific status. Options: `any`, `draft`, `pending`, `private` and `publish`. Default is `any`.                                                                                                                                     |
| `include_status` | string  | Limit result set to product variations with any of the specified statuses. Multiple statuses can be provided as a comma-separated list. Takes precedence over the `status` parameter. Options: `any`, `future`, `trash`, `draft`, `pending`, `private`, and `publish`.      |
| `exclude_status` | string  | Exclude product variations from result set with any of the specified statuses. Multiple statuses can be provided as a comma-separated list. Takes precedence over the `include_status` parameter. Options: `future`, `trash`, `draft`, `pending`, `private`, and `publish`. |
| `sku`            | string  | Limit result set to products with a specific SKU.                                                                                                                                                                                                                           |
| `tax_class`      | string  | Limit result set to products with a specific tax class. Default options: `standard`, `reduced-rate` and `zero-rate`.                                                                                                                                                        |
| `on_sale`        | boolean | Limit result set to products on sale.                                                                                                                                                                                                                                       |
| `min_price`      | string  | Limit result set to products based on a minimum price.                                                                                                                                                                                                                      |
| `max_price`      | string  | Limit result set to products based on a maximum price.                                                                                                                                                                                                                      |
| `stock_status`   | string  | Limit result set to products with specified stock status. Options: `instock`, `outofstock` and `onbackorder`.                                                                                                                                                               |
| `virtual`        | boolean | Limit result set to virtual product variations                                                                                                                                                                                                                              |
| `downloadable`   | boolean | Limit result set to downloadable product variations.                                                                                                                                                                                                                        |
| `image_size`     | string  | Use a specific registered image size for the returned variation image `src`. Falls back to the full size if the requested size is not registered. Default is `full`.                                                                                                        |

## Update a product variation

This API lets you make changes to a product variation.

```http
PUT /wp-json/wc/v3/products/<product_id>/variations/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/products/22/variations/733 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "10.00"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	regular_price: '10.00',
};

WooCommerce.put( 'products/22/variations/733', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'regular_price' => '10.00'
];

print_r($woocommerce->put('products/22/variations/733', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "regular_price": "10.00"
}

print(wcapi.put("products/22/variations/733", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  regular_price: "10.00"
}

woocommerce.put("products/22/variations/733", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 733,
	"date_created": "2017-03-23T00:53:11",
	"date_created_gmt": "2017-03-23T03:53:11",
	"date_modified": "2017-03-23T00:53:11",
	"date_modified_gmt": "2017-03-23T03:53:11",
	"description": "",
	"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=green",
	"sku": "",
	"price": "10.00",
	"regular_price": "10.00",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"on_sale": false,
	"status": "publish",
	"purchasable": true,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_class": "",
	"shipping_class_id": 0,
	"image": {
		"id": 425,
		"date_created": "2016-10-19T12:21:16",
		"date_created_gmt": "2016-10-19T16:21:16",
		"date_modified": "2016-10-19T12:21:16",
		"date_modified_gmt": "2016-10-19T16:21:16",
		"src": "https://example.com/wp-content/uploads/2016/10/T_3_front-12.jpg",
		"name": "",
		"alt": ""
	},
	"gallery_image_ids": [],
	"attributes": [
		{
			"id": 6,
			"name": "Color",
			"option": "Green"
		}
	],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22/variations/733"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22/variations"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a product variation

This API helps you delete a product variation.

```http
DELETE /wp-json/wc/v3/products/<product_id>/variations/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/products/22/variations/733?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'products/22/variations/733', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/22/variations/733', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/22/variations/733", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/22/variations/733", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 733,
	"date_created": "2017-03-23T00:53:11",
	"date_created_gmt": "2017-03-23T03:53:11",
	"date_modified": "2017-03-23T00:53:11",
	"date_modified_gmt": "2017-03-23T03:53:11",
	"description": "",
	"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=green",
	"sku": "",
	"price": "10.00",
	"regular_price": "10.00",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"on_sale": false,
	"status": "publish",
	"purchasable": true,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_class": "",
	"shipping_class_id": 0,
	"image": {
		"id": 425,
		"date_created": "2016-10-19T12:21:16",
		"date_created_gmt": "2016-10-19T16:21:16",
		"date_modified": "2016-10-19T12:21:16",
		"date_modified_gmt": "2016-10-19T16:21:16",
		"src": "https://example.com/wp-content/uploads/2016/10/T_3_front-12.jpg",
		"name": "",
		"alt": ""
	},
	"gallery_image_ids": [],
	"attributes": [
		{
			"id": 6,
			"name": "Color",
			"option": "Green"
		}
	],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22/variations/733"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22/variations"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/22"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update product variations

This API helps you to batch create, update and delete multiple product variations.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/products/<product_id>/variations/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/22/variations/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "regular_price": "10.00",
      "attributes": [
        {
          "id": 6,
          "option": "Blue"
        }
      ]
    },
    {
      "regular_price": "10.00",
      "attributes": [
        {
          "id": 6,
          "option": "White"
        }
      ]
    }
  ],
  "update": [
    {
      "id": 733,
      "regular_price": "10.00"
    }
  ],
  "delete": [
    732
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			regular_price: '10.00',
			attributes: [
				{
					id: 6,
					option: 'Blue',
				},
			],
		},
		{
			regular_price: '10.00',
			attributes: [
				{
					id: 6,
					option: 'White',
				},
			],
		},
	],
	update: [
		{
			id: 733,
			regular_price: '10.00',
		},
	],
	delete: [ 732 ],
};

WooCommerce.post( 'products/22/variations/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'regular_price' => '10.00',
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'Blue'
                ]
            ]
        ],
        [
            'regular_price' => '10.00',
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'White'
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 733,
            'regular_price' => '10.00'
        ]
    ],
    'delete' => [
        732
    ]
];

print_r($woocommerce->post('products/22/variations/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "regular_price": "10.00",
            "attributes": [
                {
                    "id": 6,
                    "option": "Blue"
                }
            ]
        },
        {
            "regular_price": "10.00",
            "attributes": [
                {
                    "id": 6,
                    "option": "White"
                }
            ]
        }
    ],
    "update": [
        {
            "id": 733,
            "regular_price": "10.00"
        }
    ],
    "delete": [
        732
    ]
}

print(wcapi.post("products/22/variations/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "Blue"
        }
      ]
    },
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "White"
        }
      ]
    }
  ],
  update: [
    {
      id: 733,
      regular_price: "10.00"
    }
  ],
  delete: [
    732
  ]
}

woocommerce.post("products/22/variations/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 735,
			"date_created": "2017-03-23T01:19:37",
			"date_created_gmt": "2017-03-23T04:19:37",
			"date_modified": "2017-03-23T01:19:37",
			"date_modified_gmt": "2017-03-23T04:19:37",
			"description": "",
			"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=blue",
			"sku": "",
			"price": "10.00",
			"regular_price": "10.00",
			"sale_price": "",
			"date_on_sale_from": null,
			"date_on_sale_from_gmt": null,
			"date_on_sale_to": null,
			"date_on_sale_to_gmt": null,
			"on_sale": false,
			"status": "publish",
			"purchasable": true,
			"virtual": false,
			"downloadable": false,
			"downloads": [],
			"download_limit": -1,
			"download_expiry": -1,
			"tax_status": "taxable",
			"tax_class": "",
			"manage_stock": false,
			"stock_quantity": null,
			"stock_status": "instock",
			"backorders": "no",
			"backorders_allowed": false,
			"backordered": false,
			"weight": "",
			"dimensions": {
				"length": "",
				"width": "",
				"height": ""
			},
			"shipping_class": "",
			"shipping_class_id": 0,
			"image": {
				"id": 0,
				"date_created": "2017-03-22T22:19:40",
				"date_created_gmt": "2017-03-23T04:19:40",
				"date_modified": "2017-03-22T22:19:40",
				"date_modified_gmt": "2017-03-23T04:19:40",
				"src": "https://example.com/wp-content/plugins/woocommerce/assets/images/placeholder.png",
				"name": "Placeholder",
				"alt": "Placeholder"
			},
			"gallery_image_ids": [],
			"attributes": [
				{
					"id": 6,
					"name": "Color",
					"option": "Blue"
				}
			],
			"menu_order": 0,
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22/variations/735"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22/variations"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22"
					}
				]
			}
		},
		{
			"id": 736,
			"date_created": "2017-03-23T01:19:40",
			"date_created_gmt": "2017-03-23T04:19:40",
			"date_modified": "2017-03-23T01:19:40",
			"date_modified_gmt": "2017-03-23T04:19:40",
			"description": "",
			"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=white",
			"sku": "",
			"price": "10.00",
			"regular_price": "10.00",
			"sale_price": "",
			"date_on_sale_from": null,
			"date_on_sale_from_gmt": null,
			"date_on_sale_to": null,
			"date_on_sale_to_gmt": null,
			"on_sale": false,
			"status": "publish",
			"purchasable": true,
			"virtual": false,
			"downloadable": false,
			"downloads": [],
			"download_limit": -1,
			"download_expiry": -1,
			"tax_status": "taxable",
			"tax_class": "",
			"manage_stock": false,
			"stock_quantity": null,
			"stock_status": "instock",
			"backorders": "no",
			"backorders_allowed": false,
			"backordered": false,
			"weight": "",
			"dimensions": {
				"length": "",
				"width": "",
				"height": ""
			},
			"shipping_class": "",
			"shipping_class_id": 0,
			"image": {
				"id": 0,
				"date_created": "2017-03-22T22:19:42",
				"date_created_gmt": "2017-03-23T04:19:42",
				"date_modified": "2017-03-22T22:19:42",
				"date_modified_gmt": "2017-03-23T04:19:42",
				"src": "https://example.com/wp-content/plugins/woocommerce/assets/images/placeholder.png",
				"name": "Placeholder",
				"alt": "Placeholder"
			},
			"gallery_image_ids": [],
			"attributes": [
				{
					"id": 6,
					"name": "Color",
					"option": "White"
				}
			],
			"menu_order": 0,
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22/variations/736"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22/variations"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 733,
			"date_created": "2017-03-23T00:53:11",
			"date_created_gmt": "2017-03-23T03:53:11",
			"date_modified": "2017-03-23T00:53:11",
			"date_modified_gmt": "2017-03-23T03:53:11",
			"description": "",
			"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=green",
			"sku": "",
			"price": "10.00",
			"regular_price": "10.00",
			"sale_price": "",
			"date_on_sale_from": null,
			"date_on_sale_from_gmt": null,
			"date_on_sale_to": null,
			"date_on_sale_to_gmt": null,
			"on_sale": false,
			"status": "publish",
			"purchasable": true,
			"virtual": false,
			"downloadable": false,
			"downloads": [],
			"download_limit": -1,
			"download_expiry": -1,
			"tax_status": "taxable",
			"tax_class": "",
			"manage_stock": false,
			"stock_quantity": null,
			"stock_status": "instock",
			"backorders": "no",
			"backorders_allowed": false,
			"backordered": false,
			"weight": "",
			"dimensions": {
				"length": "",
				"width": "",
				"height": ""
			},
			"shipping_class": "",
			"shipping_class_id": 0,
			"image": {
				"id": 425,
				"date_created": "2016-10-19T12:21:16",
				"date_created_gmt": "2016-10-19T16:21:16",
				"date_modified": "2016-10-19T12:21:16",
				"date_modified_gmt": "2016-10-19T16:21:16",
				"src": "https://example.com/wp-content/uploads/2016/10/T_3_front-12.jpg",
				"name": "",
				"alt": ""
			},
			"gallery_image_ids": [],
			"attributes": [
				{
					"id": 6,
					"name": "Color",
					"option": "Green"
				}
			],
			"menu_order": 0,
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22/variations/733"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22/variations"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 732,
			"date_created": "2017-03-23T00:36:38",
			"date_created_gmt": "2017-03-23T03:36:38",
			"date_modified": "2017-03-23T00:36:38",
			"date_modified_gmt": "2017-03-23T03:36:38",
			"description": "",
			"permalink": "https://example.com/product/ship-your-idea/?attribute_pa_color=black",
			"sku": "",
			"price": "9.00",
			"regular_price": "9.00",
			"sale_price": "",
			"date_on_sale_from": null,
			"date_on_sale_from_gmt": null,
			"date_on_sale_to": null,
			"date_on_sale_to_gmt": null,
			"on_sale": false,
			"status": "publish",
			"purchasable": true,
			"virtual": false,
			"downloadable": false,
			"downloads": [],
			"download_limit": -1,
			"download_expiry": -1,
			"tax_status": "taxable",
			"tax_class": "",
			"manage_stock": false,
			"stock_quantity": null,
			"stock_status": "instock",
			"backorders": "no",
			"backorders_allowed": false,
			"backordered": false,
			"weight": "",
			"dimensions": {
				"length": "",
				"width": "",
				"height": ""
			},
			"shipping_class": "",
			"shipping_class_id": 0,
			"image": {
				"id": 423,
				"date_created": "2016-10-19T12:21:14",
				"date_created_gmt": "2016-10-19T16:21:14",
				"date_modified": "2016-10-19T12:21:14",
				"date_modified_gmt": "2016-10-19T16:21:14",
				"src": "https://example.com/wp-content/uploads/2016/10/T_4_front-12.jpg",
				"name": "",
				"alt": ""
			},
			"gallery_image_ids": [],
			"attributes": [
				{
					"id": 6,
					"name": "Color",
					"option": "Black"
				}
			],
			"menu_order": 0,
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22/variations/732"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22/variations"
					}
				],
				"up": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/22"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>

---

## Products

*Source: apis/rest-api/v3/products.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Products

The products API allows you to create, view, update, and delete individual, or a batch, of products.

## Product properties

| Attribute               | Type      | Description                                                                                                                                                                                                                            |
| ----------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | integer   | Unique identifier for the resource. `READ-ONLY`                                                                                                                                                          |
| `name`                  | string    | Product name.                                                                                                                                                                                                                          |
| `slug`                  | string    | Product slug.                                                                                                                                                                                                                          |
| `permalink`             | string    | Product URL. `READ-ONLY`                                                                                                                                                                                 |
| `date_created`          | date-time | The date the product was created, in the site's timezone. `READ-ONLY`                                                                                                                                    |
| `date_created_gmt`      | date-time | The date the product was created, as GMT. `READ-ONLY`                                                                                                                                                    |
| `date_modified`         | date-time | The date the product was last modified, in the site's timezone. `READ-ONLY`                                                                                                                              |
| `date_modified_gmt`     | date-time | The date the product was last modified, as GMT. `READ-ONLY`                                                                                                                                              |
| `type`                  | string    | Product type. Options: `simple`, `grouped`, `external` and `variable`. Default is `simple`.                                                                                                                                            |
| `status`                | string    | Product status (post status). Options: `draft`, `pending`, `private` and `publish`. Default is `publish`.                                                                                                                              |
| `featured`              | boolean   | Featured product. Default is `false`.                                                                                                                                                                                                  |
| `catalog_visibility`    | string    | Catalog visibility. Options: `visible`, `catalog`, `search` and `hidden`. Default is `visible`.                                                                                                                                        |
| `description`           | string    | Product description.                                                                                                                                                                                                                   |
| `short_description`     | string    | Product short description.                                                                                                                                                                                                             |
| `sku`                   | string    | Unique identifier.                                                                                                                                                                                                                     |
| `global_unique_id`      | string    | GTIN, UPC, EAN or ISBN - a unique identifier for each distinct product and service that can be purchased.                                                                                                                              |
| `price`                 | string    | Current product price. `READ-ONLY`                                                                                                                                                                       |
| `regular_price`         | string    | Product regular price.                                                                                                                                                                                                                 |
| `sale_price`            | string    | Product sale price.                                                                                                                                                                                                                    |
| `date_on_sale_from`     | date-time | Start date of sale price, in the site's timezone.                                                                                                                                                                                      |
| `date_on_sale_from_gmt` | date-time | Start date of sale price, as GMT.                                                                                                                                                                                                      |
| `date_on_sale_to`       | date-time | End date of sale price, in the site's timezone.                                                                                                                                                                                        |
| `date_on_sale_to_gmt`   | date-time | End date of sale price, as GMT.                                                                                                                                                                                                        |
| `price_html`            | string    | Price formatted in HTML. `READ-ONLY`                                                                                                                                                                     |
| `on_sale`               | boolean   | Shows if the product is on sale. `READ-ONLY`                                                                                                                                                             |
| `purchasable`           | boolean   | Shows if the product can be bought. `READ-ONLY`                                                                                                                                                          |
| `total_sales`           | integer   | Amount of sales. `READ-ONLY`                                                                                                                                                                             |
| `virtual`               | boolean   | If the product is virtual. Default is `false`.                                                                                                                                                                                         |
| `downloadable`          | boolean   | If the product is downloadable. Default is `false`.                                                                                                                                                                                    |
| `downloads`             | array     | List of downloadable files. See [Product - Downloads properties](#product---downloads-properties)                                                                                                                                        |
| `download_limit`        | integer   | Number of times downloadable files can be downloaded after purchase. Default is `-1`.                                                                                                                                                  |
| `download_expiry`       | integer   | Number of days until access to downloadable files expires. Default is `-1`.                                                                                                                                                            |
| `external_url`          | string    | Product external URL. Only for external products.                                                                                                                                                                                      |
| `button_text`           | string    | Product external button text. Only for external products.                                                                                                                                                                              |
| `tax_status`            | string    | Tax status. Options: `taxable`, `shipping` and `none`. Default is `taxable`.                                                                                                                                                           |
| `tax_class`             | string    | Tax class.                                                                                                                                                                                                                             |
| `manage_stock`          | boolean   | Stock management at product level. Default is `false`.                                                                                                                                                                                 |
| `stock_quantity`        | integer   | Stock quantity.                                                                                                                                                                                                                        |
| `stock_status`          | string    | Controls the stock status of the product. Options: `instock`, `outofstock`, `onbackorder`. Default is `instock`.                                                                                                                       |
| `backorders`            | string    | If managing stock, this controls if backorders are allowed. Options: `no`, `notify` and `yes`. Default is `no`.                                                                                                                        |
| `backorders_allowed`    | boolean   | Shows if backorders are allowed. `READ-ONLY`                                                                                                                                                             |
| `backordered`           | boolean   | Shows if the product is on backordered. `READ-ONLY`                                                                                                                                                      |
| `sold_individually`     | boolean   | Allow one item to be bought in a single order. Default is `false`.                                                                                                                                                                     |
| `weight`                | string    | Product weight.                                                                                                                                                                                                                        |
| `dimensions`            | object    | Product dimensions. See [Product - Dimensions properties](#product---dimensions-properties)                                                                                                                                              |
| `shipping_required`     | boolean   | Shows if the product need to be shipped. `READ-ONLY`                                                                                                                                                     |
| `shipping_taxable`      | boolean   | Shows whether or not the product shipping is taxable. `READ-ONLY`                                                                                                                                        |
| `shipping_class`        | string    | Shipping class slug.                                                                                                                                                                                                                   |
| `shipping_class_id`     | integer   | Shipping class ID. `READ-ONLY`                                                                                                                                                                           |
| `reviews_allowed`       | boolean   | Allow reviews. Default is `true`.                                                                                                                                                                                                      |
| `average_rating`        | string    | Reviews average rating. `READ-ONLY`                                                                                                                                                                      |
| `rating_count`          | integer   | Amount of reviews that the product have. `READ-ONLY`                                                                                                                                                     |
| `related_ids`           | array     | List of related products IDs. `READ-ONLY`                                                                                                                                                                |
| `upsell_ids`            | array     | List of up-sell products IDs.                                                                                                                                                                                                          |
| `cross_sell_ids`        | array     | List of cross-sell products IDs.                                                                                                                                                                                                       |
| `parent_id`             | integer   | Product parent ID.                                                                                                                                                                                                                     |
| `purchase_note`         | string    | Optional note to send the customer after purchase.                                                                                                                                                                                     |
| `categories`            | array     | List of categories. See [Product - Categories properties](#product---categories-properties)                                                                                                                                              |
| `tags`                  | array     | List of tags. See [Product - Tags properties](#product---tags-properties)                                                                                                                                                                |
| `brands`                | array     | List of product brands. See [Brands Properties](#brands-properties). In write-mode pass an array of brand objects with `id` property ([uses wp_set_object_terms()](http://codex.wordpress.org/Function_Reference/wp_set_object_terms)) |
| `images`                | array     | List of images. See [Product - Images properties](#product---images-properties)                                                                                                                                                          |
| `attributes`            | array     | List of attributes. See [Product - Attributes properties](#product---attributes-properties)                                                                                                                                              |
| `default_attributes`    | array     | Defaults variation attributes. See [Product - Default attributes properties](#product---default-attributes-properties)                                                                                                                   |
| `variations`            | array     | List of variations IDs. `READ-ONLY`                                                                                                                                                                      |
| `grouped_products`      | array     | List of grouped products ID.                                                                                                                                                                                                           |
| `menu_order`            | integer   | Menu order, used to custom sort products.                                                                                                                                                                                              |
| `meta_data`             | array     | Meta data. See [Product - Meta data properties](#product---meta-data-properties)                                                                                                                                                         |

### Product - Downloads properties

| Attribute | Type   | Description |
| --------- | ------ | ----------- |
| `id`      | string | File ID.    |
| `name`    | string | File name.  |
| `file`    | string | File URL.   |

### Product - Dimensions properties

| Attribute | Type   | Description     |
| --------- | ------ | --------------- |
| `length`  | string | Product length. |
| `width`   | string | Product width.  |
| `height`  | string | Product height. |

### Product - Categories properties

| Attribute | Type    | Description                                              |
| --------- | ------- | -------------------------------------------------------- |
| `id`      | integer | Category ID.                                             |
| `name`    | string  | Category name. `READ-ONLY` |
| `slug`    | string  | Category slug. `READ-ONLY` |

### Product - Tags properties

| Attribute | Type    | Description                                         |
| --------- | ------- | --------------------------------------------------- |
| `id`      | integer | Tag ID.                                             |
| `name`    | string  | Tag name. `READ-ONLY` |
| `slug`    | string  | Tag slug. `READ-ONLY` |

### Product - Images properties

| Attribute           | Type      | Description                                                                                             |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `id`                | integer   | The attachment ID from the Media Library.                                                               |
| `date_created`      | date-time | The date the image was created, in the site's timezone. `READ-ONLY`       |
| `date_created_gmt`  | date-time | The date the image was created, as GMT. `READ-ONLY`                       |
| `date_modified`     | date-time | The date the image was last modified, in the site's timezone. `READ-ONLY` |
| `date_modified_gmt` | date-time | The date the image was last modified, as GMT. `READ-ONLY`                 |
| `src`               | string    | Image URL.                                                                                              |
| `name`              | string    | Image name.                                                                                             |
| `alt`               | string    | Image alternative text.                                                                                 |

### Brands Properties

| Attribute | Type    | Description                                                            |
| --------- | ------- | ---------------------------------------------------------------------- |
| `id`      | integer | Brand ID `REQUIRED FOR WRITE OPERATIONS` |
| `name`    | string  | Brand name `READ-ONLY`                   |
| `slug`    | string  | Brand slug `READ-ONLY`                   |

### Product - Attributes properties

| Attribute   | Type    | Description                                                                                                       |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `id`        | integer | Attribute ID.                                                                                                     |
| `name`      | string  | Attribute name.                                                                                                   |
| `position`  | integer | Attribute position.                                                                                               |
| `visible`   | boolean | Define if the attribute is visible on the "Additional information" tab in the product's page. Default is `false`. |
| `variation` | boolean | Define if the attribute can be used as variation. Default is `false`.                                             |
| `options`   | array   | List of available term names of the attribute.                                                                    |

### Product - Default attributes properties

| Attribute | Type    | Description                   |
| --------- | ------- | ----------------------------- |
| `id`      | integer | Attribute ID.                 |
| `name`    | string  | Attribute name.               |
| `option`  | string  | Selected attribute term name. |

### Product - Meta data properties

| Attribute | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `id`      | integer | Meta ID. `READ-ONLY` |
| `key`     | string  | Meta key.                                          |
| `value`   | string  | Meta value.                                        |

## Create a product

This API helps you to create a new product.

```http
POST /wp-json/wc/v3/products
```

> Example of how to create a `simple` product with one existing image and one new image:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Premium Quality",
  "type": "simple",
  "regular_price": "21.99",
  "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "categories": [
    {
      "id": 9
    },
    {
      "id": 14
    }
  ],
  "images": [
    {
      "id": 42
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Premium Quality',
	type: 'simple',
	regular_price: '21.99',
	description:
		'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
	short_description:
		'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
	categories: [
		{
			id: 9,
		},
		{
			id: 14,
		},
	],
	images: [
		{
			id: 42,
		},
		{
			src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg',
		},
	],
};

WooCommerce.post( 'products', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Premium Quality',
    'type' => 'simple',
    'regular_price' => '21.99',
    'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
    'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
    'categories' => [
        [
            'id' => 9
        ],
        [
            'id' => 14
        ]
    ],
    'images' => [
        [
            'id': 42
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg'
        ]
    ]
];

print_r($woocommerce->post('products', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Premium Quality",
    "type": "simple",
    "regular_price": "21.99",
    "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
    "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
    "categories": [
        {
            "id": 9
        },
        {
            "id": 14
        }
    ],
    "images": [
        {
            "id": 42
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg"
        }
    ]
}

print(wcapi.post("products", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Premium Quality",
  type: "simple",
  regular_price: "21.99",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      id: 42
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg",
    }
  ]
}

woocommerce.post("products", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 794,
	"name": "Premium Quality",
	"slug": "premium-quality-19",
	"permalink": "https://example.com/product/premium-quality-19/",
	"date_created": "2017-03-23T17:01:14",
	"date_created_gmt": "2017-03-23T20:01:14",
	"date_modified": "2017-03-23T17:01:14",
	"date_modified_gmt": "2017-03-23T20:01:14",
	"type": "simple",
	"status": "publish",
	"featured": false,
	"catalog_visibility": "visible",
	"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
	"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
	"sku": "",
	"price": "21.99",
	"regular_price": "21.99",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
	"on_sale": false,
	"purchasable": true,
	"total_sales": 0,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"external_url": "",
	"button_text": "",
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"sold_individually": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_required": true,
	"shipping_taxable": true,
	"shipping_class": "",
	"shipping_class_id": 0,
	"reviews_allowed": true,
	"average_rating": "0.00",
	"rating_count": 0,
	"related_ids": [ 53, 40, 56, 479, 99 ],
	"upsell_ids": [],
	"cross_sell_ids": [],
	"parent_id": 0,
	"purchase_note": "",
	"categories": [
		{
			"id": 9,
			"name": "Clothing",
			"slug": "clothing"
		},
		{
			"id": 14,
			"name": "T-shirts",
			"slug": "t-shirts"
		}
	],
	"tags": [],
	"images": [
		{
			"id": 42,
			"date_created": "2017-03-22T14:01:13",
			"date_created_gmt": "2017-03-22T20:01:13",
			"date_modified": "2017-03-22T14:01:13",
			"date_modified_gmt": "2017-03-22T20:01:13",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
			"name": "",
			"alt": ""
		},
		{
			"id": 793,
			"date_created": "2017-03-23T14:01:14",
			"date_created_gmt": "2017-03-23T20:01:14",
			"date_modified": "2017-03-23T14:01:14",
			"date_modified_gmt": "2017-03-23T20:01:14",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
			"name": "",
			"alt": ""
		}
	],
	"attributes": [],
	"default_attributes": [],
	"variations": [],
	"grouped_products": [],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/794"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

> Example of how to create a `variable` product with global and non-global attributes:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Ship Your Idea",
  "type": "variable",
  "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "categories": [
    {
      "id": 9
    },
    {
      "id": 14
    }
  ],
  "images": [
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg"
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg"
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg"
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg"
    }
  ],
  "attributes": [
    {
      "id": 6,
      "position": 0,
      "visible": false,
      "variation": true,
      "options": [
        "Black",
        "Green"
      ]
    },
    {
      "name": "Size",
      "position": 0,
      "visible": true,
      "variation": true,
      "options": [
        "S",
        "M"
      ]
    }
  ],
  "default_attributes": [
    {
      "id": 6,
      "option": "Black"
    },
    {
      "name": "Size",
      "option": "S"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Ship Your Idea',
	type: 'variable',
	description:
		'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
	short_description:
		'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
	categories: [
		{
			id: 9,
		},
		{
			id: 14,
		},
	],
	images: [
		{
			src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg',
		},
		{
			src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg',
		},
		{
			src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg',
		},
		{
			src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg',
		},
	],
	attributes: [
		{
			id: 6,
			position: 0,
			visible: true,
			variation: true,
			options: [ 'Black', 'Green' ],
		},
		{
			name: 'Size',
			position: 0,
			visible: false,
			variation: true,
			options: [ 'S', 'M' ],
		},
	],
	default_attributes: [
		{
			id: 6,
			option: 'Black',
		},
		{
			name: 'Size',
			option: 'S',
		},
	],
};

WooCommerce.post( 'products', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Ship Your Idea',
    'type' => 'variable',
    'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
    'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
    'categories' => [
        [
            'id' => 9
        ],
        [
            'id' => 14
        ]
    ],
    'images' => [
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg'
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg'
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg'
        ],
        [
            'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg'
        ]
    ],
    'attributes' => [
        [
            'id' => 6,
            'position' => 0,
            'visible' => false,
            'variation' => true,
            'options' => [
                'Black',
                'Green'
            ]
        ],
        [
            'name' => 'Size',
            'position' => 0,
            'visible' => true,
            'variation' => true,
            'options' => [
                'S',
                'M'
            ]
        ]
    ],
    'default_attributes' => [
        [
            'id' => 6,
            'option' => 'Black'
        ],
        [
            'name' => 'Size',
            'option' => 'S'
        ]
    ]
];

print_r($woocommerce->post('products', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Ship Your Idea",
    "type": "variable",
    "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
    "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
    "categories": [
        {
            "id": 9
        },
        {
            "id": 14
        }
    ],
    "images": [
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg"
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg"
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg"
        },
        {
            "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg"
        }
    ],
    "attributes": [
        {
            "id": 6,
            "position": 0,
            "visible": False,
            "variation": True,
            "options": [
                "Black",
                "Green"
            ]
        },
        {
            "name": "Size",
            "position": 0,
            "visible": True,
            "variation": True,
            "options": [
                "S",
                "M"
            ]
        }
    ],
    "default_attributes": [
        {
            "id": 6,
            "option": "Black"
        },
        {
            "name": "Size",
            "option": "S"
        }
    ]
}

print(wcapi.post("products", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Ship Your Idea",
  type: "variable",
  description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  categories: [
    {
      id: 9
    },
    {
      id: 14
    }
  ],
  images: [
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_front.jpg"
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_4_back.jpg"
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_front.jpg"
    },
    {
      src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_3_back.jpg"
    }
  ],
  attributes: [
    {
      id: 6,
      position: 0,
      visible: false,
      variation: true,
      options: [
        "Black",
        "Green"
      ]
    },
    {
      name: "Size",
      position: 0,
      visible: true,
      variation: true,
      options: [
        "S",
        "M"
      ]
    }
  ],
  default_attributes: [
    {
      id: 6,
      option: "Black"
    },
    {
      name: "Size",
      option: "S"
    }
  ]
}

woocommerce.post("products", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 799,
	"name": "Ship Your Idea",
	"slug": "ship-your-idea-22",
	"permalink": "https://example.com/product/ship-your-idea-22/",
	"date_created": "2017-03-23T17:03:12",
	"date_created_gmt": "2017-03-23T20:03:12",
	"date_modified": "2017-03-23T17:03:12",
	"date_modified_gmt": "2017-03-23T20:03:12",
	"type": "variable",
	"status": "publish",
	"featured": false,
	"catalog_visibility": "visible",
	"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
	"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
	"sku": "",
	"price": "",
	"regular_price": "",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"price_html": "",
	"on_sale": false,
	"purchasable": false,
	"total_sales": 0,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"external_url": "",
	"button_text": "",
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"sold_individually": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_required": true,
	"shipping_taxable": true,
	"shipping_class": "",
	"shipping_class_id": 0,
	"reviews_allowed": true,
	"average_rating": "0.00",
	"rating_count": 0,
	"related_ids": [ 472, 387, 19, 53, 396 ],
	"upsell_ids": [],
	"cross_sell_ids": [],
	"parent_id": 0,
	"purchase_note": "",
	"categories": [
		{
			"id": 9,
			"name": "Clothing",
			"slug": "clothing"
		},
		{
			"id": 14,
			"name": "T-shirts",
			"slug": "t-shirts"
		}
	],
	"tags": [],
	"images": [
		{
			"id": 795,
			"date_created": "2017-03-23T14:03:08",
			"date_created_gmt": "2017-03-23T20:03:08",
			"date_modified": "2017-03-23T14:03:08",
			"date_modified_gmt": "2017-03-23T20:03:08",
			"src": "https://example.com/wp-content/uploads/2017/03/T_4_front-11.jpg",
			"name": "",
			"alt": ""
		},
		{
			"id": 796,
			"date_created": "2017-03-23T14:03:09",
			"date_created_gmt": "2017-03-23T20:03:09",
			"date_modified": "2017-03-23T14:03:09",
			"date_modified_gmt": "2017-03-23T20:03:09",
			"src": "https://example.com/wp-content/uploads/2017/03/T_4_back-10.jpg",
			"name": "",
			"alt": ""
		},
		{
			"id": 797,
			"date_created": "2017-03-23T14:03:10",
			"date_created_gmt": "2017-03-23T20:03:10",
			"date_modified": "2017-03-23T14:03:10",
			"date_modified_gmt": "2017-03-23T20:03:10",
			"src": "https://example.com/wp-content/uploads/2017/03/T_3_front-10.jpg",
			"name": "",
			"alt": ""
		},
		{
			"id": 798,
			"date_created": "2017-03-23T14:03:11",
			"date_created_gmt": "2017-03-23T20:03:11",
			"date_modified": "2017-03-23T14:03:11",
			"date_modified_gmt": "2017-03-23T20:03:11",
			"src": "https://example.com/wp-content/uploads/2017/03/T_3_back-10.jpg",
			"name": "",
			"alt": ""
		}
	],
	"attributes": [
		{
			"id": 6,
			"name": "Color",
			"position": 0,
			"visible": false,
			"variation": true,
			"options": [ "Black", "Green" ]
		},
		{
			"id": 0,
			"name": "Size",
			"position": 0,
			"visible": true,
			"variation": true,
			"options": [ "S", "M" ]
		}
	],
	"default_attributes": [
		{
			"id": 6,
			"name": "Color",
			"option": "black"
		},
		{
			"id": 0,
			"name": "Size",
			"option": "S"
		}
	],
	"variations": [],
	"grouped_products": [],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/799"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a product

This API lets you retrieve and view a specific product by ID.

```http
GET /wp-json/wc/v3/products/<id>
```

Optional query parameter: `image_size` (string). Use a specific registered image size for returned image `src` values. Falls back to the full size when the requested size is not registered. Default is `full`.

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/794 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products/794' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products/794')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products/794").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products/794").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 794,
	"name": "Premium Quality",
	"slug": "premium-quality-19",
	"permalink": "https://example.com/product/premium-quality-19/",
	"date_created": "2017-03-23T17:01:14",
	"date_created_gmt": "2017-03-23T20:01:14",
	"date_modified": "2017-03-23T17:01:14",
	"date_modified_gmt": "2017-03-23T20:01:14",
	"type": "simple",
	"status": "publish",
	"featured": false,
	"catalog_visibility": "visible",
	"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
	"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
	"sku": "",
	"price": "21.99",
	"regular_price": "21.99",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
	"on_sale": false,
	"purchasable": true,
	"total_sales": 0,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"external_url": "",
	"button_text": "",
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"sold_individually": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_required": true,
	"shipping_taxable": true,
	"shipping_class": "",
	"shipping_class_id": 0,
	"reviews_allowed": true,
	"average_rating": "0.00",
	"rating_count": 0,
	"related_ids": [ 53, 40, 56, 479, 99 ],
	"upsell_ids": [],
	"cross_sell_ids": [],
	"parent_id": 0,
	"purchase_note": "",
	"categories": [
		{
			"id": 9,
			"name": "Clothing",
			"slug": "clothing"
		},
		{
			"id": 14,
			"name": "T-shirts",
			"slug": "t-shirts"
		}
	],
	"tags": [],
	"images": [
		{
			"id": 792,
			"date_created": "2017-03-23T14:01:13",
			"date_created_gmt": "2017-03-23T20:01:13",
			"date_modified": "2017-03-23T14:01:13",
			"date_modified_gmt": "2017-03-23T20:01:13",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
			"name": "",
			"alt": ""
		},
		{
			"id": 793,
			"date_created": "2017-03-23T14:01:14",
			"date_created_gmt": "2017-03-23T20:01:14",
			"date_modified": "2017-03-23T14:01:14",
			"date_modified_gmt": "2017-03-23T20:01:14",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
			"name": "",
			"alt": ""
		}
	],
	"attributes": [],
	"default_attributes": [],
	"variations": [],
	"grouped_products": [],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/794"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all products

This API helps you to view all the products.

```http
GET /wp-json/wc/v3/products
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'products' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('products')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("products").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("products").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 799,
		"name": "Ship Your Idea",
		"slug": "ship-your-idea-22",
		"permalink": "https://example.com/product/ship-your-idea-22/",
		"date_created": "2017-03-23T17:03:12",
		"date_created_gmt": "2017-03-23T20:03:12",
		"date_modified": "2017-03-23T17:03:12",
		"date_modified_gmt": "2017-03-23T20:03:12",
		"type": "variable",
		"status": "publish",
		"featured": false,
		"catalog_visibility": "visible",
		"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
		"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
		"sku": "",
		"price": "",
		"regular_price": "",
		"sale_price": "",
		"date_on_sale_from": null,
		"date_on_sale_from_gmt": null,
		"date_on_sale_to": null,
		"date_on_sale_to_gmt": null,
		"price_html": "",
		"on_sale": false,
		"purchasable": false,
		"total_sales": 0,
		"virtual": false,
		"downloadable": false,
		"downloads": [],
		"download_limit": -1,
		"download_expiry": -1,
		"external_url": "",
		"button_text": "",
		"tax_status": "taxable",
		"tax_class": "",
		"manage_stock": false,
		"stock_quantity": null,
		"stock_status": "instock",
		"backorders": "no",
		"backorders_allowed": false,
		"backordered": false,
		"sold_individually": false,
		"weight": "",
		"dimensions": {
			"length": "",
			"width": "",
			"height": ""
		},
		"shipping_required": true,
		"shipping_taxable": true,
		"shipping_class": "",
		"shipping_class_id": 0,
		"reviews_allowed": true,
		"average_rating": "0.00",
		"rating_count": 0,
		"related_ids": [ 31, 22, 369, 414, 56 ],
		"upsell_ids": [],
		"cross_sell_ids": [],
		"parent_id": 0,
		"purchase_note": "",
		"categories": [
			{
				"id": 9,
				"name": "Clothing",
				"slug": "clothing"
			},
			{
				"id": 14,
				"name": "T-shirts",
				"slug": "t-shirts"
			}
		],
		"tags": [],
		"images": [
			{
				"id": 795,
				"date_created": "2017-03-23T14:03:08",
				"date_created_gmt": "2017-03-23T20:03:08",
				"date_modified": "2017-03-23T14:03:08",
				"date_modified_gmt": "2017-03-23T20:03:08",
				"src": "https://example.com/wp-content/uploads/2017/03/T_4_front-11.jpg",
				"name": "",
				"alt": ""
			},
			{
				"id": 796,
				"date_created": "2017-03-23T14:03:09",
				"date_created_gmt": "2017-03-23T20:03:09",
				"date_modified": "2017-03-23T14:03:09",
				"date_modified_gmt": "2017-03-23T20:03:09",
				"src": "https://example.com/wp-content/uploads/2017/03/T_4_back-10.jpg",
				"name": "",
				"alt": ""
			},
			{
				"id": 797,
				"date_created": "2017-03-23T14:03:10",
				"date_created_gmt": "2017-03-23T20:03:10",
				"date_modified": "2017-03-23T14:03:10",
				"date_modified_gmt": "2017-03-23T20:03:10",
				"src": "https://example.com/wp-content/uploads/2017/03/T_3_front-10.jpg",
				"name": "",
				"alt": ""
			},
			{
				"id": 798,
				"date_created": "2017-03-23T14:03:11",
				"date_created_gmt": "2017-03-23T20:03:11",
				"date_modified": "2017-03-23T14:03:11",
				"date_modified_gmt": "2017-03-23T20:03:11",
				"src": "https://example.com/wp-content/uploads/2017/03/T_3_back-10.jpg",
				"name": "",
				"alt": ""
			}
		],
		"attributes": [
			{
				"id": 6,
				"name": "Color",
				"position": 0,
				"visible": false,
				"variation": true,
				"options": [ "Black", "Green" ]
			},
			{
				"id": 0,
				"name": "Size",
				"position": 0,
				"visible": true,
				"variation": true,
				"options": [ "S", "M" ]
			}
		],
		"default_attributes": [],
		"variations": [],
		"grouped_products": [],
		"menu_order": 0,
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/799"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products"
				}
			]
		}
	},
	{
		"id": 794,
		"name": "Premium Quality",
		"slug": "premium-quality-19",
		"permalink": "https://example.com/product/premium-quality-19/",
		"date_created": "2017-03-23T17:01:14",
		"date_created_gmt": "2017-03-23T20:01:14",
		"date_modified": "2017-03-23T17:01:14",
		"date_modified_gmt": "2017-03-23T20:01:14",
		"type": "simple",
		"status": "publish",
		"featured": false,
		"catalog_visibility": "visible",
		"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
		"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
		"sku": "",
		"price": "21.99",
		"regular_price": "21.99",
		"sale_price": "",
		"date_on_sale_from": null,
		"date_on_sale_from_gmt": null,
		"date_on_sale_to": null,
		"date_on_sale_to_gmt": null,
		"price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
		"on_sale": false,
		"purchasable": true,
		"total_sales": 0,
		"virtual": false,
		"downloadable": false,
		"downloads": [],
		"download_limit": -1,
		"download_expiry": -1,
		"external_url": "",
		"button_text": "",
		"tax_status": "taxable",
		"tax_class": "",
		"manage_stock": false,
		"stock_quantity": null,
		"stock_status": "instock",
		"backorders": "no",
		"backorders_allowed": false,
		"backordered": false,
		"sold_individually": false,
		"weight": "",
		"dimensions": {
			"length": "",
			"width": "",
			"height": ""
		},
		"shipping_required": true,
		"shipping_taxable": true,
		"shipping_class": "",
		"shipping_class_id": 0,
		"reviews_allowed": true,
		"average_rating": "0.00",
		"rating_count": 0,
		"related_ids": [ 463, 47, 31, 387, 458 ],
		"upsell_ids": [],
		"cross_sell_ids": [],
		"parent_id": 0,
		"purchase_note": "",
		"categories": [
			{
				"id": 9,
				"name": "Clothing",
				"slug": "clothing"
			},
			{
				"id": 14,
				"name": "T-shirts",
				"slug": "t-shirts"
			}
		],
		"tags": [],
		"images": [
			{
				"id": 792,
				"date_created": "2017-03-23T14:01:13",
				"date_created_gmt": "2017-03-23T20:01:13",
				"date_modified": "2017-03-23T14:01:13",
				"date_modified_gmt": "2017-03-23T20:01:13",
				"src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
				"name": "",
				"alt": ""
			},
			{
				"id": 793,
				"date_created": "2017-03-23T14:01:14",
				"date_created_gmt": "2017-03-23T20:01:14",
				"date_modified": "2017-03-23T14:01:14",
				"date_modified_gmt": "2017-03-23T20:01:14",
				"src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
				"name": "",
				"alt": ""
			}
		],
		"attributes": [],
		"default_attributes": [
			{
				"id": 6,
				"name": "Color",
				"option": "black"
			},
			{
				"id": 0,
				"name": "Size",
				"option": "S"
			}
		],
		"variations": [],
		"grouped_products": [],
		"menu_order": 0,
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/794"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/products"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter         | Type    | Description                                                                                                                                                                                                                                                                                          |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`         | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.                                                                                                                                                                         |
| `page`            | integer | Current page of the collection. Default is `1`.                                                                                                                                                                                                                                                      |
| `per_page`        | integer | Maximum number of items to be returned in result set. Default is `10`.                                                                                                                                                                                                                               |
| `search`          | string  | Limit results to those matching a string.                                                                                                                                                                                                                                                            |
| `search_fields`   | array   | Fields to search when used with `search` parameter. All search tokens must be found across any of the specified fields. Takes precedence over other search parameters. If empty, uses default `search` behavior. Options: `name`, `sku`, `global_unique_id`, `description`, and `short_description`. |
| `after`           | string  | Limit response to resources published after a given ISO8601 compliant date.                                                                                                                                                                                                                          |
| `before`          | string  | Limit response to resources published before a given ISO8601 compliant date.                                                                                                                                                                                                                         |
| `modified_after`  | string  | Limit response to resources modified after a given ISO8601 compliant date.                                                                                                                                                                                                                           |
| `modified_before` | string  | Limit response to resources modified after a given ISO8601 compliant date.                                                                                                                                                                                                                           |
| `dates_are_gmt`   | boolean | Whether to interpret dates as GMT when limiting response by published or modified date.                                                                                                                                                                                                              |
| `exclude`         | array   | Ensure result set excludes specific IDs.                                                                                                                                                                                                                                                             |
| `include`         | array   | Limit result set to specific ids.                                                                                                                                                                                                                                                                    |
| `offset`          | integer | Offset the result set by a specific number of items.                                                                                                                                                                                                                                                 |
| `order`           | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                                                                                                                                                                                          |
| `orderby`         | string  | Sort collection by object attribute. Options: `date`, `modified`, `id`, `include`, `title`, `slug`, `price`, `popularity`, `rating`, and `menu_order`. Default is `date`.                                                                                                                            |
| `parent`          | array   | Limit result set to those of particular parent IDs.                                                                                                                                                                                                                                                  |
| `parent_exclude`  | array   | Limit result set to all items except those of a particular parent ID.                                                                                                                                                                                                                                |
| `slug`            | string  | Limit result set to products with a specific slug.                                                                                                                                                                                                                                                   |
| `status`          | string  | Limit result set to products assigned a specific status. Options: `any`, `draft`, `pending`, `private` and `publish`. Default is `any`.                                                                                                                                                              |
| `include_status`  | string  | Limit result set to products with any of the specified statuses. Multiple statuses can be provided as a comma-separated list. Takes precedence over the `status` parameter. Options: `any`, `future`, `trash`, `draft`, `pending`, `private`, and `publish`.                                         |
| `exclude_status`  | string  | Exclude products from result set with any of the specified statuses. Multiple statuses can be provided as a comma-separated list. Takes precedence over the `include_status` parameter. Options: `future`, `trash`, `draft`, `pending`, `private`, and `publish`.                                    |
| `type`            | string  | Limit result set to products assigned a specific type. Options: `simple`, `grouped`, `external` and `variable`.                                                                                                                                                                                      |
| `include_types`   | string  | Limit result set to products with any of the types. Multiple statuses can be provided as a comma-separated list. Takes precedence over the `type` parameter. Options: `simple`, `grouped`, `external` and `variable`.                                                                                |
| `exclude_types`   | string  | Exclude products from result set with any of the specified types. Multiple statuses can be provided as a comma-separated list. Takes precedence over the `include_types` parameter. Options: `simple`, `grouped`, `external` and `variable`.                                                         |
| `sku`             | string  | Limit result set to products with a specific SKU.                                                                                                                                                                                                                                                    |
| `featured`        | boolean | Limit result set to featured products.                                                                                                                                                                                                                                                               |
| `category`        | string  | Limit result set to products assigned a specific category ID.                                                                                                                                                                                                                                        |
| `tag`             | string  | Limit result set to products assigned a specific tag ID.                                                                                                                                                                                                                                             |
| `shipping_class`  | string  | Limit result set to products assigned a specific shipping class ID.                                                                                                                                                                                                                                  |
| `attribute`       | string  | Limit result set to products with a specific attribute.                                                                                                                                                                                                                                              |
| `attribute_term`  | string  | Limit result set to products with a specific attribute term ID (required an assigned attribute).                                                                                                                                                                                                     |
| `tax_class`       | string  | Limit result set to products with a specific tax class. Default options: `standard`, `reduced-rate` and `zero-rate`.                                                                                                                                                                                 |
| `on_sale`         | boolean | Limit result set to products on sale.                                                                                                                                                                                                                                                                |
| `min_price`       | string  | Limit result set to products based on a minimum price.                                                                                                                                                                                                                                               |
| `max_price`       | string  | Limit result set to products based on a maximum price.                                                                                                                                                                                                                                               |
| `stock_status`    | string  | Limit result set to products with specified stock status. Options: `instock`, `outofstock` and `onbackorder`.                                                                                                                                                                                        |
| `virtual`         | boolean | Limit result set to virtual products.                                                                                                                                                                                                                                                                |
| `downloadable`    | boolean | Limit result set to downloadable products.                                                                                                                                                                                                                                                           |
| `image_size`      | string  | Use a specific registered image size for the returned image `src` values. Falls back to the full size if the requested size is not registered. Default is `full`.                                                                                                                                    |

## Duplicate product

This API helps you to duplicate a product.

```http
POST /wp-json/wc/v3/products/<product_id>/duplicate
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/products/<product_id>/duplicate \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.post( 'products/2/duplicate' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->post('products/2/duplicate')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.post("products/2/duplicate").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.post("products/2/duplicate").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 824,
	"name": "Premium Quality (Copy)",
	"slug": "",
	"date_created": {
		"date": "2024-05-30 19:16:39.000000",
		"timezone_type": 1,
		"timezone": "+00:00"
	},
	"date_modified": {
		"date": "2024-03-08 15:03:19.000000",
		"timezone_type": 1,
		"timezone": "+00:00"
	},
	"status": "draft",
	"featured": false,
	"catalog_visibility": "visible",
	"description": "",
	"short_description": "",
	"sku": "product-22-1",
	"price": "",
	"regular_price": "",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_to": null,
	"total_sales": 0,
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"low_stock_amount": "",
	"sold_individually": false,
	"weight": "",
	"length": "",
	"width": "",
	"height": "",
	"upsell_ids": [],
	"cross_sell_ids": [],
	"parent_id": 0,
	"reviews_allowed": true,
	"purchase_note": "",
	"attributes": [],
	"default_attributes": [],
	"menu_order": 0,
	"post_password": "",
	"virtual": false,
	"downloadable": false,
	"category_ids": [ 15 ],
	"tag_ids": [],
	"shipping_class_id": 0,
	"downloads": [],
	"image_id": "",
	"gallery_image_ids": [],
	"download_limit": -1,
	"download_expiry": -1,
	"rating_counts": [],
	"average_rating": "0",
	"review_count": 0,
	"meta_data": []
}
```

  </TabItem>
</Tabs>

## Update a product

This API lets you make changes to a product.

```http
PUT /wp-json/wc/v3/products/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/products/794 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "24.54"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	regular_price: '24.54',
};

WooCommerce.put( 'products/794', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'regular_price' => '24.54'
];

print_r($woocommerce->put('products/794', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "regular_price": "24.54"
}

print(wcapi.put("products/794", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  regular_price: "24.54"
}

woocommerce.put("products/794", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 794,
	"name": "Premium Quality",
	"slug": "premium-quality-19",
	"permalink": "https://example.com/product/premium-quality-19/",
	"date_created": "2017-03-23T17:01:14",
	"date_created_gmt": "2017-03-23T20:01:14",
	"date_modified": "2017-03-23T17:01:14",
	"date_modified_gmt": "2017-03-23T20:01:14",
	"type": "simple",
	"status": "publish",
	"featured": false,
	"catalog_visibility": "visible",
	"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
	"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
	"sku": "",
	"price": "24.54",
	"regular_price": "24.54",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>24.54</span>",
	"on_sale": false,
	"purchasable": true,
	"total_sales": 0,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"external_url": "",
	"button_text": "",
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"sold_individually": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_required": true,
	"shipping_taxable": true,
	"shipping_class": "",
	"shipping_class_id": 0,
	"reviews_allowed": true,
	"average_rating": "0.00",
	"rating_count": 0,
	"related_ids": [ 479, 387, 22, 463, 396 ],
	"upsell_ids": [],
	"cross_sell_ids": [],
	"parent_id": 0,
	"purchase_note": "",
	"categories": [
		{
			"id": 9,
			"name": "Clothing",
			"slug": "clothing"
		},
		{
			"id": 14,
			"name": "T-shirts",
			"slug": "t-shirts"
		}
	],
	"tags": [],
	"images": [
		{
			"id": 792,
			"date_created": "2017-03-23T14:01:13",
			"date_created_gmt": "2017-03-23T20:01:13",
			"date_modified": "2017-03-23T14:01:13",
			"date_modified_gmt": "2017-03-23T20:01:13",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
			"name": "",
			"alt": ""
		},
		{
			"id": 793,
			"date_created": "2017-03-23T14:01:14",
			"date_created_gmt": "2017-03-23T20:01:14",
			"date_modified": "2017-03-23T14:01:14",
			"date_modified_gmt": "2017-03-23T20:01:14",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
			"name": "",
			"alt": ""
		}
	],
	"attributes": [],
	"default_attributes": [],
	"variations": [],
	"grouped_products": [],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/794"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a product

This API helps you delete a product.

```http
DELETE /wp-json/wc/v3/products/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/products/794?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'products/794', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('products/794', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("products/794", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("products/794", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 794,
	"name": "Premium Quality",
	"slug": "premium-quality-19",
	"permalink": "https://example.com/product/premium-quality-19/",
	"date_created": "2017-03-23T17:01:14",
	"date_created_gmt": "2017-03-23T20:01:14",
	"date_modified": "2017-03-23T17:01:14",
	"date_modified_gmt": "2017-03-23T20:01:14",
	"type": "simple",
	"status": "publish",
	"featured": false,
	"catalog_visibility": "visible",
	"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
	"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
	"sku": "",
	"price": "24.54",
	"regular_price": "24.54",
	"sale_price": "",
	"date_on_sale_from": null,
	"date_on_sale_from_gmt": null,
	"date_on_sale_to": null,
	"date_on_sale_to_gmt": null,
	"price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>24.54</span>",
	"on_sale": false,
	"purchasable": true,
	"total_sales": 0,
	"virtual": false,
	"downloadable": false,
	"downloads": [],
	"download_limit": -1,
	"download_expiry": -1,
	"external_url": "",
	"button_text": "",
	"tax_status": "taxable",
	"tax_class": "",
	"manage_stock": false,
	"stock_quantity": null,
	"stock_status": "instock",
	"backorders": "no",
	"backorders_allowed": false,
	"backordered": false,
	"sold_individually": false,
	"weight": "",
	"dimensions": {
		"length": "",
		"width": "",
		"height": ""
	},
	"shipping_required": true,
	"shipping_taxable": true,
	"shipping_class": "",
	"shipping_class_id": 0,
	"reviews_allowed": true,
	"average_rating": "0.00",
	"rating_count": 0,
	"related_ids": [ 479, 387, 22, 463, 396 ],
	"upsell_ids": [],
	"cross_sell_ids": [],
	"parent_id": 0,
	"purchase_note": "",
	"categories": [
		{
			"id": 9,
			"name": "Clothing",
			"slug": "clothing"
		},
		{
			"id": 14,
			"name": "T-shirts",
			"slug": "t-shirts"
		}
	],
	"tags": [],
	"images": [
		{
			"id": 792,
			"date_created": "2017-03-23T14:01:13",
			"date_created_gmt": "2017-03-23T20:01:13",
			"date_modified": "2017-03-23T14:01:13",
			"date_modified_gmt": "2017-03-23T20:01:13",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
			"name": "",
			"alt": ""
		},
		{
			"id": 793,
			"date_created": "2017-03-23T14:01:14",
			"date_created_gmt": "2017-03-23T20:01:14",
			"date_modified": "2017-03-23T14:01:14",
			"date_modified_gmt": "2017-03-23T20:01:14",
			"src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
			"name": "",
			"alt": ""
		}
	],
	"attributes": [],
	"default_attributes": [],
	"variations": [],
	"grouped_products": [],
	"menu_order": 0,
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/products/794"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/products"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                               |
| --------- | ------ | ------------------------------------------------------------------------- |
| `force`   | string | Use `true` whether to permanently delete the product, Default is `false`. |

## Batch update products

This API helps you to batch create, update and delete multiple products.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/products/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/products/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Woo Single #1",
      "type": "simple",
      "regular_price": "21.99",
      "virtual": true,
      "downloadable": true,
      "downloads": [
        {
          "name": "Woo Single",
          "file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      "categories": [
        {
          "id": 11
        },
        {
          "id": 13
        }
      ],
      "images": [
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ]
    },
    {
      "name": "New Premium Quality",
      "type": "simple",
      "regular_price": "21.99",
      "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      "categories": [
        {
          "id": 9
        },
        {
          "id": 14
        }
      ],
      "images": [
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
        },
        {
          "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg"
        }
      ]
    }
  ],
  "update": [
    {
      "id": 799,
      "default_attributes": [
        {
          "id": 6,
          "name": "Color",
          "option": "Green"
        },
        {
          "id": 0,
          "name": "Size",
          "option": "M"
        }
      ]
    }
  ],
  "delete": [
    794
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			name: 'Woo Single #1',
			type: 'simple',
			regular_price: '21.99',
			virtual: true,
			downloadable: true,
			downloads: [
				{
					name: 'Woo Single',
					file: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg',
				},
			],
			categories: [
				{
					id: 11,
				},
				{
					id: 13,
				},
			],
			images: [
				{
					src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg',
				},
			],
		},
		{
			name: 'New Premium Quality',
			type: 'simple',
			regular_price: '21.99',
			description:
				'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
			short_description:
				'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
			categories: [
				{
					id: 9,
				},
				{
					id: 14,
				},
			],
			images: [
				{
					src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg',
				},
				{
					src: 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg',
				},
			],
		},
	],
	update: [
		{
			id: 799,
			default_attributes: [
				{
					id: 6,
					name: 'Color',
					option: 'Green',
				},
				{
					id: 0,
					name: 'Size',
					option: 'M',
				},
			],
		},
	],
	delete: [ 794 ],
};

WooCommerce.post( 'products/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Woo Single #1',
            'type' => 'simple',
            'regular_price' => '21.99',
            'virtual' => true,
            'downloadable' => true,
            'downloads' => [
                [
                    'name' => 'Woo Single',
                    'file' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg'
                ]
            ],
            'categories' => [
                [
                    'id' => 11
                ],
                [
                    'id' => 13
                ]
            ],
            'images' => [
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg'
                ]
            ]
        ],
        [
            'name' => 'New Premium Quality',
            'type' => 'simple',
            'regular_price' => '21.99',
            'description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.',
            'short_description' => 'Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.',
            'categories' => [
                [
                    'id' => 9
                ],
                [
                    'id' => 14
                ]
            ],
            'images' => [
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg'
                ],
                [
                    'src' => 'http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg'
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 799,
            'default_attributes' => [
                [
                    'id' => 6,
                    'name' => 'Color',
                    'option' => 'Green'
                ],
                [
                    'id' => 0,
                    'name' => 'Size',
                    'option' => 'M'
                ]
            ]
        ]
    ],
    'delete' => [
        794
    ]
];

print_r($woocommerce->post('products/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Woo Single #1",
            "type": "simple",
            "regular_price": "21.99",
            "virtual": True,
            "downloadable": True,
            "downloads": [
                {
                    "name": "Woo Single",
                    "file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
                }
            ],
            "categories": [
                {
                    "id": 11
                },
                {
                    "id": 13
                }
            ],
            "images": [
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
                }
            ]
        },
        {
            "name": "New Premium Quality",
            "type": "simple",
            "regular_price": "21.99",
            "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
            "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
            "categories": [
                {
                    "id": 9
                },
                {
                    "id": 14
                }
            ],
            "images": [
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
                },
                {
                    "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg"
                }
            ]
        }
    ],
    "update": [
        {
            "id": 799,
            "default_attributes": [
                {
                    "id": 6,
                    "name": "Color",
                    "option": "Green"
                },
                {
                    "id": 0,
                    "name": "Size",
                    "option": "M"
                }
            ]
        }
    ],
    "delete": [
        794
    ]
}

print(wcapi.post("products/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Woo Single #1",
      type: "simple",
      regular_price: "21.99",
      virtual: true,
      downloadable: true,
      downloads: [
        {
          name: "Woo Single",
          file: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ],
      categories: [
        {
          id: 11
        },
        {
          id: 13
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
        }
      ]
    },
    {
      name: "New Premium Quality",
      type: "simple",
      regular_price: "21.99",
      description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      categories: [
        {
          id: 9
        },
        {
          id: 14
        }
      ],
      images: [
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
        },
        {
          src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg"
        }
      ]
    }
  ],
  update: [
    {
      id: 799,
      default_attributes: [
        {
          id: 6,
          name: "Color,
          option: "Green"
        },
        {
          id: 0,
          name: "Size",
          option: "M"
        }
      ]
    }
  ],
  delete: [
    794
  ]
}

woocommerce.post("products/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 801,
			"name": "Woo Single #1",
			"slug": "woo-single-1-4",
			"permalink": "https://example.com/product/woo-single-1-4/",
			"date_created": "2017-03-23T17:35:43",
			"date_created_gmt": "2017-03-23T20:35:43",
			"date_modified": "2017-03-23T17:35:43",
			"date_modified_gmt": "2017-03-23T20:35:43",
			"type": "simple",
			"status": "publish",
			"featured": false,
			"catalog_visibility": "visible",
			"description": "",
			"short_description": "",
			"sku": "",
			"price": "21.99",
			"regular_price": "21.99",
			"sale_price": "",
			"date_on_sale_from": null,
			"date_on_sale_from_gmt": null,
			"date_on_sale_to": null,
			"date_on_sale_to_gmt": null,
			"price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
			"on_sale": false,
			"purchasable": true,
			"total_sales": 0,
			"virtual": true,
			"downloadable": true,
			"downloads": [
				{
					"id": 0,
					"name": "Woo Single",
					"file": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/cd_4_angle.jpg"
				}
			],
			"download_limit": -1,
			"download_expiry": -1,
			"external_url": "",
			"button_text": "",
			"tax_status": "taxable",
			"tax_class": "",
			"manage_stock": false,
			"stock_quantity": null,
			"stock_status": "instock",
			"backorders": "no",
			"backorders_allowed": false,
			"backordered": false,
			"sold_individually": false,
			"weight": "",
			"dimensions": {
				"length": "",
				"width": "",
				"height": ""
			},
			"shipping_required": false,
			"shipping_taxable": true,
			"shipping_class": "",
			"shipping_class_id": 0,
			"reviews_allowed": true,
			"average_rating": "0.00",
			"rating_count": 0,
			"related_ids": [ 588, 87, 573, 96, 329 ],
			"upsell_ids": [],
			"cross_sell_ids": [],
			"parent_id": 0,
			"purchase_note": "",
			"categories": [
				{
					"id": 11,
					"name": "Music",
					"slug": "music"
				},
				{
					"id": 13,
					"name": "Singles",
					"slug": "singles"
				}
			],
			"tags": [],
			"images": [
				{
					"id": 800,
					"date_created": "2017-03-23T14:35:43",
					"date_created_gmt": "2017-03-23T20:35:43",
					"date_modified": "2017-03-23T14:35:43",
					"date_modified_gmt": "2017-03-23T20:35:43",
					"src": "https://example.com/wp-content/uploads/2017/03/cd_4_angle.jpg",
					"name": "",
					"alt": ""
				}
			],
			"attributes": [],
			"default_attributes": [],
			"variations": [],
			"grouped_products": [],
			"menu_order": 0,
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/801"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products"
					}
				]
			}
		},
		{
			"id": 804,
			"name": "New Premium Quality",
			"slug": "new-premium-quality",
			"permalink": "https://example.com/product/new-premium-quality/",
			"date_created": "2017-03-23T17:35:48",
			"date_created_gmt": "2017-03-23T20:35:48",
			"date_modified": "2017-03-23T17:35:48",
			"date_modified_gmt": "2017-03-23T20:35:48",
			"type": "simple",
			"status": "publish",
			"featured": false,
			"catalog_visibility": "visible",
			"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
			"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
			"sku": "",
			"price": "21.99",
			"regular_price": "21.99",
			"sale_price": "",
			"date_on_sale_from": null,
			"date_on_sale_from_gmt": null,
			"date_on_sale_to": null,
			"date_on_sale_to_gmt": null,
			"price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>21.99</span>",
			"on_sale": false,
			"purchasable": true,
			"total_sales": 0,
			"virtual": false,
			"downloadable": false,
			"downloads": [],
			"download_limit": -1,
			"download_expiry": -1,
			"external_url": "",
			"button_text": "",
			"tax_status": "taxable",
			"tax_class": "",
			"manage_stock": false,
			"stock_quantity": null,
			"stock_status": "instock",
			"backorders": "no",
			"backorders_allowed": false,
			"backordered": false,
			"sold_individually": false,
			"weight": "",
			"dimensions": {
				"length": "",
				"width": "",
				"height": ""
			},
			"shipping_required": true,
			"shipping_taxable": true,
			"shipping_class": "",
			"shipping_class_id": 0,
			"reviews_allowed": true,
			"average_rating": "0.00",
			"rating_count": 0,
			"related_ids": [ 458, 56, 99, 34, 378 ],
			"upsell_ids": [],
			"cross_sell_ids": [],
			"parent_id": 0,
			"purchase_note": "",
			"categories": [
				{
					"id": 9,
					"name": "Clothing",
					"slug": "clothing"
				},
				{
					"id": 14,
					"name": "T-shirts",
					"slug": "t-shirts"
				}
			],
			"tags": [],
			"images": [
				{
					"id": 802,
					"date_created": "2017-03-23T14:35:47",
					"date_created_gmt": "2017-03-23T20:35:47",
					"date_modified": "2017-03-23T14:35:47",
					"date_modified_gmt": "2017-03-23T20:35:47",
					"src": "https://example.com/wp-content/uploads/2017/03/T_2_front-5.jpg",
					"name": "",
					"alt": ""
				},
				{
					"id": 803,
					"date_created": "2017-03-23T14:35:48",
					"date_created_gmt": "2017-03-23T20:35:48",
					"date_modified": "2017-03-23T14:35:48",
					"date_modified_gmt": "2017-03-23T20:35:48",
					"src": "https://example.com/wp-content/uploads/2017/03/T_2_back-3.jpg",
					"name": "",
					"alt": ""
				}
			],
			"attributes": [],
			"default_attributes": [],
			"variations": [],
			"grouped_products": [],
			"menu_order": 0,
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/804"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 799,
			"name": "Ship Your Idea",
			"slug": "ship-your-idea-22",
			"permalink": "https://example.com/product/ship-your-idea-22/",
			"date_created": "2017-03-23T17:03:12",
			"date_created_gmt": "2017-03-23T20:03:12",
			"date_modified": "2017-03-23T17:03:12",
			"date_modified_gmt": "2017-03-23T20:03:12",
			"type": "variable",
			"status": "publish",
			"featured": false,
			"catalog_visibility": "visible",
			"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
			"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
			"sku": "",
			"price": "",
			"regular_price": "",
			"sale_price": "",
			"date_on_sale_from": null,
			"date_on_sale_from_gmt": null,
			"date_on_sale_to": null,
			"date_on_sale_to_gmt": null,
			"price_html": "",
			"on_sale": false,
			"purchasable": false,
			"total_sales": 0,
			"virtual": false,
			"downloadable": false,
			"downloads": [],
			"download_limit": -1,
			"download_expiry": -1,
			"external_url": "",
			"button_text": "",
			"tax_status": "taxable",
			"tax_class": "",
			"manage_stock": false,
			"stock_quantity": null,
			"stock_status": "instock",
			"backorders": "no",
			"backorders_allowed": false,
			"backordered": false,
			"sold_individually": false,
			"weight": "",
			"dimensions": {
				"length": "",
				"width": "",
				"height": ""
			},
			"shipping_required": true,
			"shipping_taxable": true,
			"shipping_class": "",
			"shipping_class_id": 0,
			"reviews_allowed": true,
			"average_rating": "0.00",
			"rating_count": 0,
			"related_ids": [ 414, 40, 34, 463, 15 ],
			"upsell_ids": [],
			"cross_sell_ids": [],
			"parent_id": 0,
			"purchase_note": "",
			"categories": [
				{
					"id": 9,
					"name": "Clothing",
					"slug": "clothing"
				},
				{
					"id": 14,
					"name": "T-shirts",
					"slug": "t-shirts"
				}
			],
			"tags": [],
			"images": [
				{
					"id": 795,
					"date_created": "2017-03-23T14:03:08",
					"date_created_gmt": "2017-03-23T20:03:08",
					"date_modified": "2017-03-23T14:03:08",
					"date_modified_gmt": "2017-03-23T20:03:08",
					"src": "https://example.com/wp-content/uploads/2017/03/T_4_front-11.jpg",
					"name": "",
					"alt": ""
				},
				{
					"id": 796,
					"date_created": "2017-03-23T14:03:09",
					"date_created_gmt": "2017-03-23T20:03:09",
					"date_modified": "2017-03-23T14:03:09",
					"date_modified_gmt": "2017-03-23T20:03:09",
					"src": "https://example.com/wp-content/uploads/2017/03/T_4_back-10.jpg",
					"name": "",
					"alt": ""
				},
				{
					"id": 797,
					"date_created": "2017-03-23T14:03:10",
					"date_created_gmt": "2017-03-23T20:03:10",
					"date_modified": "2017-03-23T14:03:10",
					"date_modified_gmt": "2017-03-23T20:03:10",
					"src": "https://example.com/wp-content/uploads/2017/03/T_3_front-10.jpg",
					"name": "",
					"alt": ""
				},
				{
					"id": 798,
					"date_created": "2017-03-23T14:03:11",
					"date_created_gmt": "2017-03-23T20:03:11",
					"date_modified": "2017-03-23T14:03:11",
					"date_modified_gmt": "2017-03-23T20:03:11",
					"src": "https://example.com/wp-content/uploads/2017/03/T_3_back-10.jpg",
					"name": "",
					"alt": ""
				}
			],
			"attributes": [
				{
					"id": 6,
					"name": "Color",
					"position": 0,
					"visible": false,
					"variation": true,
					"options": [ "Black", "Green" ]
				},
				{
					"id": 0,
					"name": "Size",
					"position": 0,
					"visible": true,
					"variation": true,
					"options": [ "S", "M" ]
				}
			],
			"default_attributes": [
				{
					"id": 6,
					"name": "Color",
					"option": "green"
				},
				{
					"id": 0,
					"name": "Size",
					"option": "M"
				}
			],
			"variations": [],
			"grouped_products": [],
			"menu_order": 0,
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/799"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 794,
			"name": "Premium Quality",
			"slug": "premium-quality-19",
			"permalink": "https://example.com/product/premium-quality-19/",
			"date_created": "2017-03-23T17:01:14",
			"date_created_gmt": "2017-03-23T20:01:14",
			"date_modified": "2017-03-23T17:01:14",
			"date_modified_gmt": "2017-03-23T20:01:14",
			"type": "simple",
			"status": "publish",
			"featured": false,
			"catalog_visibility": "visible",
			"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>\n",
			"short_description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>\n",
			"sku": "",
			"price": "24.54",
			"regular_price": "24.54",
			"sale_price": "",
			"date_on_sale_from": null,
			"date_on_sale_from_gmt": null,
			"date_on_sale_to": null,
			"date_on_sale_to_gmt": null,
			"price_html": "<span class=\"woocommerce-Price-amount amount\"><span class=\"woocommerce-Price-currencySymbol\">&#36;</span>24.54</span>",
			"on_sale": false,
			"purchasable": true,
			"total_sales": 0,
			"virtual": false,
			"downloadable": false,
			"downloads": [],
			"download_limit": -1,
			"download_expiry": -1,
			"external_url": "",
			"button_text": "",
			"tax_status": "taxable",
			"tax_class": "",
			"manage_stock": false,
			"stock_quantity": null,
			"stock_status": "instock",
			"backorders": "no",
			"backorders_allowed": false,
			"backordered": false,
			"sold_individually": false,
			"weight": "",
			"dimensions": {
				"length": "",
				"width": "",
				"height": ""
			},
			"shipping_required": true,
			"shipping_taxable": true,
			"shipping_class": "",
			"shipping_class_id": 0,
			"reviews_allowed": true,
			"average_rating": "0.00",
			"rating_count": 0,
			"related_ids": [ 369, 56, 378, 31, 22 ],
			"upsell_ids": [],
			"cross_sell_ids": [],
			"parent_id": 0,
			"purchase_note": "",
			"categories": [
				{
					"id": 9,
					"name": "Clothing",
					"slug": "clothing"
				},
				{
					"id": 14,
					"name": "T-shirts",
					"slug": "t-shirts"
				}
			],
			"tags": [],
			"images": [
				{
					"id": 792,
					"date_created": "2017-03-23T14:01:13",
					"date_created_gmt": "2017-03-23T20:01:13",
					"date_modified": "2017-03-23T14:01:13",
					"date_modified_gmt": "2017-03-23T20:01:13",
					"src": "https://example.com/wp-content/uploads/2017/03/T_2_front-4.jpg",
					"name": "",
					"alt": ""
				},
				{
					"id": 793,
					"date_created": "2017-03-23T14:01:14",
					"date_created_gmt": "2017-03-23T20:01:14",
					"date_modified": "2017-03-23T14:01:14",
					"date_modified_gmt": "2017-03-23T20:01:14",
					"src": "https://example.com/wp-content/uploads/2017/03/T_2_back-2.jpg",
					"name": "",
					"alt": ""
				}
			],
			"attributes": [],
			"default_attributes": [],
			"variations": [],
			"grouped_products": [],
			"menu_order": 0,
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/products/794"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/products"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Refunds

*Source: apis/rest-api/v3/refunds.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Refunds

The refunds API is a simple, read-only endpoint that allows you to retrieve a list of refunds outside the context of an existing order. To create, view, and delete individual refunds, check out the [order refunds API](../order-refunds).

## Refund properties

All properties are the same as those in the [order refunds endpoint](../order-refunds#order-refund-properties), but with one additional property:

| Attribute   | Type    | Description                                        |
| ----------- | ------- | -------------------------------------------------- |
| `parent_id` | integer | The ID of the order the refund is associated with. |

## Retrieve a list of refunds

This API lets you retrieve and view refunds from your store, regardless of which order they are associated with.

```http
GET /wp-json/wc/v3/refunds
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/refunds \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'refunds' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('refunds')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("refunds").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("refunds").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 726,
		"parent_id": 124,
		"date_created": "2017-03-21T17:07:11",
		"date_created_gmt": "2017-03-21T20:07:11",
		"amount": "10.00",
		"reason": "",
		"refunded_by": 1,
		"refunded_payment": false,
		"meta_data": [],
		"line_items": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	},
	{
		"id": 724,
		"parent_id": 63,
		"date_created": "2017-03-21T16:55:37",
		"date_created_gmt": "2017-03-21T19:55:37",
		"amount": "9.00",
		"reason": "",
		"refunded_by": 1,
		"refunded_payment": false,
		"meta_data": [],
		"line_items": [
			{
				"id": 314,
				"name": "Woo Album #2",
				"product_id": 87,
				"variation_id": 0,
				"quantity": -1,
				"tax_class": "",
				"subtotal": "-9.00",
				"subtotal_tax": "0.00",
				"total": "-9.00",
				"total_tax": "0.00",
				"taxes": [],
				"meta_data": [
					{
						"id": 2076,
						"key": "_refunded_item_id",
						"value": "311"
					}
				],
				"sku": "",
				"price": -9
			}
		],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/724"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter        | Type    | Description                                                                                                                  |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `context`        | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`. |
| `page`           | integer | Current page of the collection. Default is `1`.                                                                              |
| `per_page`       | integer | Maximum number of items to be returned in result set. Default is `10`.                                                       |
| `search`         | string  | Limit results to those matching a string.                                                                                    |
| `after`          | string  | Limit response to resources published after a given ISO8601 compliant date.                                                  |
| `before`         | string  | Limit response to resources published before a given ISO8601 compliant date.                                                 |
| `exclude`        | array   | Ensure result set excludes specific IDs.                                                                                     |
| `include`        | array   | Limit result set to specific ids.                                                                                            |
| `offset`         | integer | Offset the result set by a specific number of items.                                                                         |
| `order`          | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                  |
| `orderby`        | string  | Sort collection by object attribute. Options: `date`, `modified`, `id`, `include`, `title` and `slug`. Default is `date`.    |
| `parent`         | array   | Limit result set to those of particular parent IDs.                                                                          |
| `parent_exclude` | array   | Limit result set to all items except those of a particular parent ID.                                                        |
| `dp`             | integer | Number of decimal points to use in each resource. Default is `2`.                                                            |


---

## Reports

*Source: apis/rest-api/v3/reports.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Reports

The reports API allows you to view all types of reports available.

## List all reports

This API lets you retrieve and view a simple list of available reports.

```http
GET /wp-json/wc/v3/reports
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/reports \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'reports' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('reports')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("reports").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"slug": "sales",
		"description": "List of sales reports.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/sales"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "top_sellers",
		"description": "List of top sellers products.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/top_sellers"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "orders/totals",
		"description": "Orders totals.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/orders/totals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "products/totals",
		"description": "Products totals.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/products/totals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "customers/totals",
		"description": "Customers totals.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/customers/totals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "coupons/totals",
		"description": "Coupons totals.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/coupons/totals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "reviews/totals",
		"description": "Reviews totals.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/reviews/totals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "categories/totals",
		"description": "Categories totals.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/categories/totals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "tags/totals",
		"description": "Tags totals.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/tags/totals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	},
	{
		"slug": "attributes/totals",
		"description": "Attributes totals.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports/attributes/totals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

## Retrieve sales report

This API lets you retrieve and view a sales report.

```http
GET /wp-json/wc/v3/reports/sales
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/reports/sales?date_min=2016-05-03&date_max=2016-05-04 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'reports/sales', {
	date_min: '2016-05-03',
	date_max: '2016-05-04',
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$query = [
    'date_min' => '2016-05-03',
    'date_max' => '2016-05-04'
];

print_r($woocommerce->get('reports/sales', $query));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/sales?date_min=2016-05-03&date_max=2016-05-04").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
query = {
  date_min: "2016-05-03",
  date_max: "2016-05-04"
}

woocommerce.get("reports/sales", query).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"total_sales": "14.00",
		"net_sales": "4.00",
		"average_sales": "2.00",
		"total_orders": 3,
		"total_items": 6,
		"total_tax": "0.00",
		"total_shipping": "10.00",
		"total_refunds": 10,
		"total_discount": "0.00",
		"totals_grouped_by": "day",
		"totals": {
			"2016-05-03": {
				"sales": "14.00",
				"orders": 3,
				"items": 6,
				"tax": "0.00",
				"shipping": "10.00",
				"discount": "0.00",
				"refunds": "10.00",
				"customers": 0
			},
			"2016-05-04": {
				"sales": "0.00",
				"orders": 0,
				"items": 0,
				"tax": "0.00",
				"shipping": "0.00",
				"discount": "0.00",
				"refunds": "0.00",
				"customers": 0
			}
		},
		"total_customers": 0,
		"_links": {
			"about": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

:::note Per-period `refunds` vs `total_refunds`
Per-period `refunds` and the top-level `total_refunds` come from different queries and will not always agree. Per-period `refunds` sum each refund record by its own date inside the report range. `total_refunds` instead counts the parent order's full total for any refunded-status order that has *any* refund record falling in the range. When an order's refunds straddle the range boundary (e.g. a partial refund last month and another this month on the same order that ultimately becomes refunded), the two values can diverge. For per-day net sales, prefer `sales - refunds` per bucket.
:::

#### Sales report properties

| Attribute           | Type    | Description                                                           |
| ------------------- | ------- | --------------------------------------------------------------------- |
| `total_sales`       | string  | Gross sales in the period. `READ-ONLY`  |
| `net_sales`         | string  | Net sales in the period. `READ-ONLY`    |
| `average_sales`     | string  | Average net daily sales. `READ-ONLY`    |
| `total_orders`      | integer | Total of orders placed. `READ-ONLY`     |
| `total_items`       | integer | Total of items purchased. `READ-ONLY`   |
| `total_tax`         | string  | Total charged for taxes. `READ-ONLY`    |
| `total_shipping`    | string  | Total charged for shipping. `READ-ONLY` |
| `total_refunds`     | integer | Total of refunded orders. `READ-ONLY`   |
| `total_discount`    | integer | Total of coupons used. `READ-ONLY`      |
| `totals_grouped_by` | string  | Group type. `READ-ONLY`                 |
| `totals`            | array   | Totals. `READ-ONLY`                     |

#### Available parameters

| Parameter  | Type   | Description                                                                                                       |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `context`  | string | Scope under which the request is made; determines fields present in response. Default is `view`. Options: `view`. |
| `period`   | string | Report period. Default is today's date. Options: `week`, `month`, `last_month` and `year`                         |
| `date_min` | string | Return sales for a specific start date, the date need to be in the YYYY-MM-DD format.                             |
| `date_max` | string | Return sales for a specific end date, the date need to be in the YYYY-MM-DD format.                               |

## Retrieve top sellers report

This API lets you retrieve and view a list of top sellers report.

```http
GET /wp-json/wc/v3/reports/top_sellers
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/reports/top_sellers?period=last_month \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'reports/top_sellers', {
	period: 'last_month',
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$query = [
    'period' => 'last_month'
];

print_r($woocommerce->get('reports/top_sellers', $query));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/top_sellers?period=last_month").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
query = {
  period: "last_month"
}

woocommerce.get("reports/top_sellers", query).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"title": "Happy Ninja",
		"product_id": 37,
		"quantity": 1,
		"_links": {
			"about": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			],
			"product": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/37"
				}
			]
		}
	},
	{
		"title": "Woo Album #4",
		"product_id": 96,
		"quantity": 1,
		"_links": {
			"about": [
				{
					"href": "https://example.com/wp-json/wc/v3/reports"
				}
			],
			"product": [
				{
					"href": "https://example.com/wp-json/wc/v3/products/96"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Top sellers report properties

| Attribute    | Type    | Description                                                          |
| ------------ | ------- | -------------------------------------------------------------------- |
| `title`      | string  | Product title. `READ-ONLY`             |
| `product_id` | integer | Product ID. `READ-ONLY`                |
| `quantity`   | integer | Total number of purchases. `READ-ONLY` |

#### Available parameters

| Parameter  | Type   | Description                                                                                                       |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `context`  | string | Scope under which the request is made; determines fields present in response. Default is `view`. Options: `view`. |
| `period`   | string | Report period. Default is `week`. Options: `week`, `month`, `last_month` and `year`                               |
| `date_min` | string | Return sales for a specific start date, the date need to be in the YYYY-MM-DD format.                             |
| `date_max` | string | Return sales for a specific end date, the date need to be in the YYYY-MM-DD format.                               |

## Retrieve coupons totals

This API lets you retrieve and view coupons totals report.

```http
GET /wp-json/wc/v3/reports/coupons/totals
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/reports/coupons/totals \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'reports/coupons/totals' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('reports/coupons/totals'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/coupons/totals").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("reports/coupons/totals").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"slug": "percent",
		"name": "Percentage discount",
		"total": 2
	},
	{
		"slug": "fixed_cart",
		"name": "Fixed cart discount",
		"total": 1
	},
	{
		"slug": "fixed_product",
		"name": "Fixed product discount",
		"total": 1
	}
]
```

  </TabItem>
</Tabs>

#### Coupons totals properties

| Attribute | Type   | Description                                                                            |
| --------- | ------ | -------------------------------------------------------------------------------------- |
| `slug`    | string | An alphanumeric identifier for the resource. `READ-ONLY` |
| `name`    | string | Coupon type name. `READ-ONLY`                            |
| `total`   | string | Amount of coupons. `READ-ONLY`                           |

## Retrieve customers totals

This API lets you retrieve and view customers totals report.

```http
GET /wp-json/wc/v3/reports/customers/totals
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/reports/customers/totals \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'reports/customers/totals' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('reports/customers/totals'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/customers/totals").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("reports/customers/totals").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"slug": "paying",
		"name": "Paying customer",
		"total": 2
	},
	{
		"slug": "non_paying",
		"name": "Non-paying customer",
		"total": 1
	}
]
```

  </TabItem>
</Tabs>

#### Customers totals properties

| Attribute | Type   | Description                                                                            |
| --------- | ------ | -------------------------------------------------------------------------------------- |
| `slug`    | string | An alphanumeric identifier for the resource. `READ-ONLY` |
| `name`    | string | Customer type name. `READ-ONLY`                          |
| `total`   | string | Amount of customers. `READ-ONLY`                         |

## Retrieve orders totals

This API lets you retrieve and view orders totals report.

```http
GET /wp-json/wc/v3/reports/orders/totals
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/reports/orders/totals \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'reports/orders/totals' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('reports/orders/totals'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/orders/totals").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("reports/orders/totals").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"slug": "pending",
		"name": "Pending payment",
		"total": 7
	},
	{
		"slug": "processing",
		"name": "Processing",
		"total": 2
	},
	{
		"slug": "on-hold",
		"name": "On hold",
		"total": 1
	},
	{
		"slug": "completed",
		"name": "Completed",
		"total": 3
	},
	{
		"slug": "cancelled",
		"name": "Cancelled",
		"total": 0
	},
	{
		"slug": "refunded",
		"name": "Refunded",
		"total": 0
	},
	{
		"slug": "failed",
		"name": "Failed",
		"total": 0
	}
]
```

  </TabItem>
</Tabs>

#### Orders totals properties

| Attribute | Type   | Description                                                                            |
| --------- | ------ | -------------------------------------------------------------------------------------- |
| `slug`    | string | An alphanumeric identifier for the resource. `READ-ONLY` |
| `name`    | string | Orders status name. `READ-ONLY`                          |
| `total`   | string | Amount of orders. `READ-ONLY`                            |

## Retrieve products totals

This API lets you retrieve and view products totals report.

```http
GET /wp-json/wc/v3/reports/products/totals
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/reports/products/totals \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'reports/products/totals' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('reports/products/totals'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/products/totals").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("reports/products/totals").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"slug": "external",
		"name": "External/Affiliate product",
		"total": 1
	},
	{
		"slug": "grouped",
		"name": "Grouped product",
		"total": 1
	},
	{
		"slug": "simple",
		"name": "Simple product",
		"total": 21
	},
	{
		"slug": "variable",
		"name": "Variable product",
		"total": 3
	}
]
```

  </TabItem>
</Tabs>

#### Products totals properties

| Attribute | Type   | Description                                                                            |
| --------- | ------ | -------------------------------------------------------------------------------------- |
| `slug`    | string | An alphanumeric identifier for the resource. `READ-ONLY` |
| `name`    | string | Product type name. `READ-ONLY`                           |
| `total`   | string | Amount of products. `READ-ONLY`                          |

## Retrieve reviews totals

This API lets you retrieve and view reviews totals report.

```http
GET /wp-json/wc/v3/reports/reviews/totals
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/reports/reviews/totals \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'reports/reviews/totals' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
print_r($woocommerce->get('reports/reviews/totals'));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("reports/reviews/totals").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("reports/reviews/totals").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"slug": "rated_1_out_of_5",
		"name": "Rated 1 out of 5",
		"total": 1
	},
	{
		"slug": "rated_2_out_of_5",
		"name": "Rated 2 out of 5",
		"total": 0
	},
	{
		"slug": "rated_3_out_of_5",
		"name": "Rated 3 out of 5",
		"total": 3
	},
	{
		"slug": "rated_4_out_of_5",
		"name": "Rated 4 out of 5",
		"total": 0
	},
	{
		"slug": "rated_5_out_of_5",
		"name": "Rated 5 out of 5",
		"total": 4
	}
]
```

  </TabItem>
</Tabs>

#### Reviews totals properties

| Attribute | Type   | Description                                                                            |
| --------- | ------ | -------------------------------------------------------------------------------------- |
| `slug`    | string | An alphanumeric identifier for the resource. `READ-ONLY` |
| `name`    | string | Review type name. `READ-ONLY`                            |
| `total`   | string | Amount of reviews. `READ-ONLY`                           |


---

## Setting options

*Source: apis/rest-api/v3/setting-options.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Setting options

## Setting option properties

| Attribute     | Type   | Description                                                                                                                                                                                     |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string | A unique identifier for the setting. `READ-ONLY`                                                                                                                  |
| `label`       | string | A human readable label for the setting used in interfaces. `READ-ONLY`                                                                                            |
| `description` | string | A human readable description for the setting used in interfaces. `READ-ONLY`                                                                                      |
| `value`       | mixed  | Setting value.                                                                                                                                                                                  |
| `default`     | mixed  | Default value for the setting. `READ-ONLY`                                                                                                                        |
| `tip`         | string | Additional help text shown to the user about the setting. `READ-ONLY`                                                                                             |
| `placeholder` | string | Placeholder text to be displayed in text inputs. `READ-ONLY`                                                                                                      |
| `type`        | string | Type of setting. Options: `text`, `email`, `number`, `color`, `password`, `textarea`, `select`, `multiselect`, `radio`, `image_width` and `checkbox`. `READ-ONLY` |
| `options`     | object | Array of options (key value pairs) for inputs such as select, multiselect, and radio buttons. `READ-ONLY`                                                         |
| `group_id`    | string | An identifier for the group this setting belongs to. `READ-ONLY`                                                                                                  |

## Retrieve a setting option

This API lets you retrieve and view a specific setting option.

```http
GET /wp-json/wc/v3/settings/<group_id>/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/settings/general/woocommerce_allowed_countries \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'settings/general/woocommerce_allowed_countries' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('settings/general/woocommerce_allowed_countries')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("settings/general/woocommerce_allowed_countries").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("settings/general/woocommerce_allowed_countries").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": "woocommerce_allowed_countries",
	"label": "Selling location(s)",
	"description": "This option lets you limit which countries you are willing to sell to.",
	"type": "select",
	"default": "all",
	"options": {
		"all": "Sell to all countries",
		"all_except": "Sell to all countries, except for&hellip;",
		"specific": "Sell to specific countries"
	},
	"tip": "This option lets you limit which countries you are willing to sell to.",
	"value": "all",
	"group_id": "general",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_allowed_countries"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/settings/general"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all setting options

This API helps you to view all the setting options.

```http
GET /wp-json/wc/v3/settings/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/settings/general \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'settings/general' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('settings/general')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("settings/general").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("settings/general").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": "woocommerce_allowed_countries",
		"label": "Selling location(s)",
		"description": "This option lets you limit which countries you are willing to sell to.",
		"type": "select",
		"default": "all",
		"options": {
			"all": "Sell to all countries",
			"all_except": "Sell to all countries, except for&hellip;",
			"specific": "Sell to specific countries"
		},
		"tip": "This option lets you limit which countries you are willing to sell to.",
		"value": "all",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_allowed_countries"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_all_except_countries",
		"label": "Sell to all countries, except for&hellip;",
		"description": "",
		"type": "multiselect",
		"default": "",
		"value": "",
		"options": {
			"AX": "&#197;land Islands",
			"AF": "Afghanistan",
			"AL": "Albania",
			"DZ": "Algeria",
			"AS": "American Samoa",
			"AD": "Andorra",
			"AO": "Angola",
			"AI": "Anguilla",
			"AQ": "Antarctica",
			"AG": "Antigua and Barbuda",
			"AR": "Argentina",
			"AM": "Armenia",
			"AW": "Aruba",
			"AU": "Australia",
			"AT": "Austria",
			"AZ": "Azerbaijan",
			"BS": "Bahamas",
			"BH": "Bahrain",
			"BD": "Bangladesh",
			"BB": "Barbados",
			"BY": "Belarus",
			"PW": "Belau",
			"BE": "Belgium",
			"BZ": "Belize",
			"BJ": "Benin",
			"BM": "Bermuda",
			"BT": "Bhutan",
			"BO": "Bolivia",
			"BQ": "Bonaire, Saint Eustatius and Saba",
			"BA": "Bosnia and Herzegovina",
			"BW": "Botswana",
			"BV": "Bouvet Island",
			"BR": "Brazil",
			"IO": "British Indian Ocean Territory",
			"VG": "British Virgin Islands",
			"BN": "Brunei",
			"BG": "Bulgaria",
			"BF": "Burkina Faso",
			"BI": "Burundi",
			"KH": "Cambodia",
			"CM": "Cameroon",
			"CA": "Canada",
			"CV": "Cape Verde",
			"KY": "Cayman Islands",
			"CF": "Central African Republic",
			"TD": "Chad",
			"CL": "Chile",
			"CN": "China",
			"CX": "Christmas Island",
			"CC": "Cocos (Keeling) Islands",
			"CO": "Colombia",
			"KM": "Comoros",
			"CG": "Congo (Brazzaville)",
			"CD": "Congo (Kinshasa)",
			"CK": "Cook Islands",
			"CR": "Costa Rica",
			"HR": "Croatia",
			"CU": "Cuba",
			"CW": "Cura&ccedil;ao",
			"CY": "Cyprus",
			"CZ": "Czech Republic",
			"DK": "Denmark",
			"DJ": "Djibouti",
			"DM": "Dominica",
			"DO": "Dominican Republic",
			"EC": "Ecuador",
			"EG": "Egypt",
			"SV": "El Salvador",
			"GQ": "Equatorial Guinea",
			"ER": "Eritrea",
			"EE": "Estonia",
			"ET": "Ethiopia",
			"FK": "Falkland Islands",
			"FO": "Faroe Islands",
			"FJ": "Fiji",
			"FI": "Finland",
			"FR": "France",
			"GF": "French Guiana",
			"PF": "French Polynesia",
			"TF": "French Southern Territories",
			"GA": "Gabon",
			"GM": "Gambia",
			"GE": "Georgia",
			"DE": "Germany",
			"GH": "Ghana",
			"GI": "Gibraltar",
			"GR": "Greece",
			"GL": "Greenland",
			"GD": "Grenada",
			"GP": "Guadeloupe",
			"GU": "Guam",
			"GT": "Guatemala",
			"GG": "Guernsey",
			"GN": "Guinea",
			"GW": "Guinea-Bissau",
			"GY": "Guyana",
			"HT": "Haiti",
			"HM": "Heard Island and McDonald Islands",
			"HN": "Honduras",
			"HK": "Hong Kong",
			"HU": "Hungary",
			"IS": "Iceland",
			"IN": "India",
			"ID": "Indonesia",
			"IR": "Iran",
			"IQ": "Iraq",
			"IE": "Ireland",
			"IM": "Isle of Man",
			"IL": "Israel",
			"IT": "Italy",
			"CI": "Ivory Coast",
			"JM": "Jamaica",
			"JP": "Japan",
			"JE": "Jersey",
			"JO": "Jordan",
			"KZ": "Kazakhstan",
			"KE": "Kenya",
			"KI": "Kiribati",
			"KW": "Kuwait",
			"KG": "Kyrgyzstan",
			"LA": "Laos",
			"LV": "Latvia",
			"LB": "Lebanon",
			"LS": "Lesotho",
			"LR": "Liberia",
			"LY": "Libya",
			"LI": "Liechtenstein",
			"LT": "Lithuania",
			"LU": "Luxembourg",
			"MO": "Macao S.A.R., China",
			"MK": "Macedonia",
			"MG": "Madagascar",
			"MW": "Malawi",
			"MY": "Malaysia",
			"MV": "Maldives",
			"ML": "Mali",
			"MT": "Malta",
			"MH": "Marshall Islands",
			"MQ": "Martinique",
			"MR": "Mauritania",
			"MU": "Mauritius",
			"YT": "Mayotte",
			"MX": "Mexico",
			"FM": "Micronesia",
			"MD": "Moldova",
			"MC": "Monaco",
			"MN": "Mongolia",
			"ME": "Montenegro",
			"MS": "Montserrat",
			"MA": "Morocco",
			"MZ": "Mozambique",
			"MM": "Myanmar",
			"NA": "Namibia",
			"NR": "Nauru",
			"NP": "Nepal",
			"NL": "Netherlands",
			"NC": "New Caledonia",
			"NZ": "New Zealand",
			"NI": "Nicaragua",
			"NE": "Niger",
			"NG": "Nigeria",
			"NU": "Niue",
			"NF": "Norfolk Island",
			"KP": "North Korea",
			"MP": "Northern Mariana Islands",
			"NO": "Norway",
			"OM": "Oman",
			"PK": "Pakistan",
			"PS": "Palestinian Territory",
			"PA": "Panama",
			"PG": "Papua New Guinea",
			"PY": "Paraguay",
			"PE": "Peru",
			"PH": "Philippines",
			"PN": "Pitcairn",
			"PL": "Poland",
			"PT": "Portugal",
			"PR": "Puerto Rico",
			"QA": "Qatar",
			"RE": "Reunion",
			"RO": "Romania",
			"RU": "Russia",
			"RW": "Rwanda",
			"ST": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe",
			"BL": "Saint Barth&eacute;lemy",
			"SH": "Saint Helena",
			"KN": "Saint Kitts and Nevis",
			"LC": "Saint Lucia",
			"SX": "Saint Martin (Dutch part)",
			"MF": "Saint Martin (French part)",
			"PM": "Saint Pierre and Miquelon",
			"VC": "Saint Vincent and the Grenadines",
			"WS": "Samoa",
			"SM": "San Marino",
			"SA": "Saudi Arabia",
			"SN": "Senegal",
			"RS": "Serbia",
			"SC": "Seychelles",
			"SL": "Sierra Leone",
			"SG": "Singapore",
			"SK": "Slovakia",
			"SI": "Slovenia",
			"SB": "Solomon Islands",
			"SO": "Somalia",
			"ZA": "South Africa",
			"GS": "South Georgia/Sandwich Islands",
			"KR": "South Korea",
			"SS": "South Sudan",
			"ES": "Spain",
			"LK": "Sri Lanka",
			"SD": "Sudan",
			"SR": "Suriname",
			"SJ": "Svalbard and Jan Mayen",
			"SZ": "Swaziland",
			"SE": "Sweden",
			"CH": "Switzerland",
			"SY": "Syria",
			"TW": "Taiwan",
			"TJ": "Tajikistan",
			"TZ": "Tanzania",
			"TH": "Thailand",
			"TL": "Timor-Leste",
			"TG": "Togo",
			"TK": "Tokelau",
			"TO": "Tonga",
			"TT": "Trinidad and Tobago",
			"TN": "Tunisia",
			"TR": "Turkey",
			"TM": "Turkmenistan",
			"TC": "Turks and Caicos Islands",
			"TV": "Tuvalu",
			"UG": "Uganda",
			"UA": "Ukraine",
			"AE": "United Arab Emirates",
			"GB": "United Kingdom (UK)",
			"US": "United States (US)",
			"UM": "United States (US) Minor Outlying Islands",
			"VI": "United States (US) Virgin Islands",
			"UY": "Uruguay",
			"UZ": "Uzbekistan",
			"VU": "Vanuatu",
			"VA": "Vatican",
			"VE": "Venezuela",
			"VN": "Vietnam",
			"WF": "Wallis and Futuna",
			"EH": "Western Sahara",
			"YE": "Yemen",
			"ZM": "Zambia",
			"ZW": "Zimbabwe"
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_all_except_countries"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_specific_allowed_countries",
		"label": "Sell to specific countries",
		"description": "",
		"type": "multiselect",
		"default": "",
		"value": "",
		"options": {
			"AX": "&#197;land Islands",
			"AF": "Afghanistan",
			"AL": "Albania",
			"DZ": "Algeria",
			"AS": "American Samoa",
			"AD": "Andorra",
			"AO": "Angola",
			"AI": "Anguilla",
			"AQ": "Antarctica",
			"AG": "Antigua and Barbuda",
			"AR": "Argentina",
			"AM": "Armenia",
			"AW": "Aruba",
			"AU": "Australia",
			"AT": "Austria",
			"AZ": "Azerbaijan",
			"BS": "Bahamas",
			"BH": "Bahrain",
			"BD": "Bangladesh",
			"BB": "Barbados",
			"BY": "Belarus",
			"PW": "Belau",
			"BE": "Belgium",
			"BZ": "Belize",
			"BJ": "Benin",
			"BM": "Bermuda",
			"BT": "Bhutan",
			"BO": "Bolivia",
			"BQ": "Bonaire, Saint Eustatius and Saba",
			"BA": "Bosnia and Herzegovina",
			"BW": "Botswana",
			"BV": "Bouvet Island",
			"BR": "Brazil",
			"IO": "British Indian Ocean Territory",
			"VG": "British Virgin Islands",
			"BN": "Brunei",
			"BG": "Bulgaria",
			"BF": "Burkina Faso",
			"BI": "Burundi",
			"KH": "Cambodia",
			"CM": "Cameroon",
			"CA": "Canada",
			"CV": "Cape Verde",
			"KY": "Cayman Islands",
			"CF": "Central African Republic",
			"TD": "Chad",
			"CL": "Chile",
			"CN": "China",
			"CX": "Christmas Island",
			"CC": "Cocos (Keeling) Islands",
			"CO": "Colombia",
			"KM": "Comoros",
			"CG": "Congo (Brazzaville)",
			"CD": "Congo (Kinshasa)",
			"CK": "Cook Islands",
			"CR": "Costa Rica",
			"HR": "Croatia",
			"CU": "Cuba",
			"CW": "Cura&ccedil;ao",
			"CY": "Cyprus",
			"CZ": "Czech Republic",
			"DK": "Denmark",
			"DJ": "Djibouti",
			"DM": "Dominica",
			"DO": "Dominican Republic",
			"EC": "Ecuador",
			"EG": "Egypt",
			"SV": "El Salvador",
			"GQ": "Equatorial Guinea",
			"ER": "Eritrea",
			"EE": "Estonia",
			"ET": "Ethiopia",
			"FK": "Falkland Islands",
			"FO": "Faroe Islands",
			"FJ": "Fiji",
			"FI": "Finland",
			"FR": "France",
			"GF": "French Guiana",
			"PF": "French Polynesia",
			"TF": "French Southern Territories",
			"GA": "Gabon",
			"GM": "Gambia",
			"GE": "Georgia",
			"DE": "Germany",
			"GH": "Ghana",
			"GI": "Gibraltar",
			"GR": "Greece",
			"GL": "Greenland",
			"GD": "Grenada",
			"GP": "Guadeloupe",
			"GU": "Guam",
			"GT": "Guatemala",
			"GG": "Guernsey",
			"GN": "Guinea",
			"GW": "Guinea-Bissau",
			"GY": "Guyana",
			"HT": "Haiti",
			"HM": "Heard Island and McDonald Islands",
			"HN": "Honduras",
			"HK": "Hong Kong",
			"HU": "Hungary",
			"IS": "Iceland",
			"IN": "India",
			"ID": "Indonesia",
			"IR": "Iran",
			"IQ": "Iraq",
			"IE": "Ireland",
			"IM": "Isle of Man",
			"IL": "Israel",
			"IT": "Italy",
			"CI": "Ivory Coast",
			"JM": "Jamaica",
			"JP": "Japan",
			"JE": "Jersey",
			"JO": "Jordan",
			"KZ": "Kazakhstan",
			"KE": "Kenya",
			"KI": "Kiribati",
			"KW": "Kuwait",
			"KG": "Kyrgyzstan",
			"LA": "Laos",
			"LV": "Latvia",
			"LB": "Lebanon",
			"LS": "Lesotho",
			"LR": "Liberia",
			"LY": "Libya",
			"LI": "Liechtenstein",
			"LT": "Lithuania",
			"LU": "Luxembourg",
			"MO": "Macao S.A.R., China",
			"MK": "Macedonia",
			"MG": "Madagascar",
			"MW": "Malawi",
			"MY": "Malaysia",
			"MV": "Maldives",
			"ML": "Mali",
			"MT": "Malta",
			"MH": "Marshall Islands",
			"MQ": "Martinique",
			"MR": "Mauritania",
			"MU": "Mauritius",
			"YT": "Mayotte",
			"MX": "Mexico",
			"FM": "Micronesia",
			"MD": "Moldova",
			"MC": "Monaco",
			"MN": "Mongolia",
			"ME": "Montenegro",
			"MS": "Montserrat",
			"MA": "Morocco",
			"MZ": "Mozambique",
			"MM": "Myanmar",
			"NA": "Namibia",
			"NR": "Nauru",
			"NP": "Nepal",
			"NL": "Netherlands",
			"NC": "New Caledonia",
			"NZ": "New Zealand",
			"NI": "Nicaragua",
			"NE": "Niger",
			"NG": "Nigeria",
			"NU": "Niue",
			"NF": "Norfolk Island",
			"KP": "North Korea",
			"MP": "Northern Mariana Islands",
			"NO": "Norway",
			"OM": "Oman",
			"PK": "Pakistan",
			"PS": "Palestinian Territory",
			"PA": "Panama",
			"PG": "Papua New Guinea",
			"PY": "Paraguay",
			"PE": "Peru",
			"PH": "Philippines",
			"PN": "Pitcairn",
			"PL": "Poland",
			"PT": "Portugal",
			"PR": "Puerto Rico",
			"QA": "Qatar",
			"RE": "Reunion",
			"RO": "Romania",
			"RU": "Russia",
			"RW": "Rwanda",
			"ST": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe",
			"BL": "Saint Barth&eacute;lemy",
			"SH": "Saint Helena",
			"KN": "Saint Kitts and Nevis",
			"LC": "Saint Lucia",
			"SX": "Saint Martin (Dutch part)",
			"MF": "Saint Martin (French part)",
			"PM": "Saint Pierre and Miquelon",
			"VC": "Saint Vincent and the Grenadines",
			"WS": "Samoa",
			"SM": "San Marino",
			"SA": "Saudi Arabia",
			"SN": "Senegal",
			"RS": "Serbia",
			"SC": "Seychelles",
			"SL": "Sierra Leone",
			"SG": "Singapore",
			"SK": "Slovakia",
			"SI": "Slovenia",
			"SB": "Solomon Islands",
			"SO": "Somalia",
			"ZA": "South Africa",
			"GS": "South Georgia/Sandwich Islands",
			"KR": "South Korea",
			"SS": "South Sudan",
			"ES": "Spain",
			"LK": "Sri Lanka",
			"SD": "Sudan",
			"SR": "Suriname",
			"SJ": "Svalbard and Jan Mayen",
			"SZ": "Swaziland",
			"SE": "Sweden",
			"CH": "Switzerland",
			"SY": "Syria",
			"TW": "Taiwan",
			"TJ": "Tajikistan",
			"TZ": "Tanzania",
			"TH": "Thailand",
			"TL": "Timor-Leste",
			"TG": "Togo",
			"TK": "Tokelau",
			"TO": "Tonga",
			"TT": "Trinidad and Tobago",
			"TN": "Tunisia",
			"TR": "Turkey",
			"TM": "Turkmenistan",
			"TC": "Turks and Caicos Islands",
			"TV": "Tuvalu",
			"UG": "Uganda",
			"UA": "Ukraine",
			"AE": "United Arab Emirates",
			"GB": "United Kingdom (UK)",
			"US": "United States (US)",
			"UM": "United States (US) Minor Outlying Islands",
			"VI": "United States (US) Virgin Islands",
			"UY": "Uruguay",
			"UZ": "Uzbekistan",
			"VU": "Vanuatu",
			"VA": "Vatican",
			"VE": "Venezuela",
			"VN": "Vietnam",
			"WF": "Wallis and Futuna",
			"EH": "Western Sahara",
			"YE": "Yemen",
			"ZM": "Zambia",
			"ZW": "Zimbabwe"
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_specific_allowed_countries"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_ship_to_countries",
		"label": "Shipping location(s)",
		"description": "Choose which countries you want to ship to, or choose to ship to all locations you sell to.",
		"type": "select",
		"default": "",
		"options": {
			"": "Ship to all countries you sell to",
			"all": "Ship to all countries",
			"specific": "Ship to specific countries only",
			"disabled": "Disable shipping &amp; shipping calculations"
		},
		"tip": "Choose which countries you want to ship to, or choose to ship to all locations you sell to.",
		"value": "",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_ship_to_countries"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_specific_ship_to_countries",
		"label": "Ship to specific countries",
		"description": "",
		"type": "multiselect",
		"default": "",
		"value": "",
		"options": {
			"AX": "&#197;land Islands",
			"AF": "Afghanistan",
			"AL": "Albania",
			"DZ": "Algeria",
			"AS": "American Samoa",
			"AD": "Andorra",
			"AO": "Angola",
			"AI": "Anguilla",
			"AQ": "Antarctica",
			"AG": "Antigua and Barbuda",
			"AR": "Argentina",
			"AM": "Armenia",
			"AW": "Aruba",
			"AU": "Australia",
			"AT": "Austria",
			"AZ": "Azerbaijan",
			"BS": "Bahamas",
			"BH": "Bahrain",
			"BD": "Bangladesh",
			"BB": "Barbados",
			"BY": "Belarus",
			"PW": "Belau",
			"BE": "Belgium",
			"BZ": "Belize",
			"BJ": "Benin",
			"BM": "Bermuda",
			"BT": "Bhutan",
			"BO": "Bolivia",
			"BQ": "Bonaire, Saint Eustatius and Saba",
			"BA": "Bosnia and Herzegovina",
			"BW": "Botswana",
			"BV": "Bouvet Island",
			"BR": "Brazil",
			"IO": "British Indian Ocean Territory",
			"VG": "British Virgin Islands",
			"BN": "Brunei",
			"BG": "Bulgaria",
			"BF": "Burkina Faso",
			"BI": "Burundi",
			"KH": "Cambodia",
			"CM": "Cameroon",
			"CA": "Canada",
			"CV": "Cape Verde",
			"KY": "Cayman Islands",
			"CF": "Central African Republic",
			"TD": "Chad",
			"CL": "Chile",
			"CN": "China",
			"CX": "Christmas Island",
			"CC": "Cocos (Keeling) Islands",
			"CO": "Colombia",
			"KM": "Comoros",
			"CG": "Congo (Brazzaville)",
			"CD": "Congo (Kinshasa)",
			"CK": "Cook Islands",
			"CR": "Costa Rica",
			"HR": "Croatia",
			"CU": "Cuba",
			"CW": "Cura&ccedil;ao",
			"CY": "Cyprus",
			"CZ": "Czech Republic",
			"DK": "Denmark",
			"DJ": "Djibouti",
			"DM": "Dominica",
			"DO": "Dominican Republic",
			"EC": "Ecuador",
			"EG": "Egypt",
			"SV": "El Salvador",
			"GQ": "Equatorial Guinea",
			"ER": "Eritrea",
			"EE": "Estonia",
			"ET": "Ethiopia",
			"FK": "Falkland Islands",
			"FO": "Faroe Islands",
			"FJ": "Fiji",
			"FI": "Finland",
			"FR": "France",
			"GF": "French Guiana",
			"PF": "French Polynesia",
			"TF": "French Southern Territories",
			"GA": "Gabon",
			"GM": "Gambia",
			"GE": "Georgia",
			"DE": "Germany",
			"GH": "Ghana",
			"GI": "Gibraltar",
			"GR": "Greece",
			"GL": "Greenland",
			"GD": "Grenada",
			"GP": "Guadeloupe",
			"GU": "Guam",
			"GT": "Guatemala",
			"GG": "Guernsey",
			"GN": "Guinea",
			"GW": "Guinea-Bissau",
			"GY": "Guyana",
			"HT": "Haiti",
			"HM": "Heard Island and McDonald Islands",
			"HN": "Honduras",
			"HK": "Hong Kong",
			"HU": "Hungary",
			"IS": "Iceland",
			"IN": "India",
			"ID": "Indonesia",
			"IR": "Iran",
			"IQ": "Iraq",
			"IE": "Ireland",
			"IM": "Isle of Man",
			"IL": "Israel",
			"IT": "Italy",
			"CI": "Ivory Coast",
			"JM": "Jamaica",
			"JP": "Japan",
			"JE": "Jersey",
			"JO": "Jordan",
			"KZ": "Kazakhstan",
			"KE": "Kenya",
			"KI": "Kiribati",
			"KW": "Kuwait",
			"KG": "Kyrgyzstan",
			"LA": "Laos",
			"LV": "Latvia",
			"LB": "Lebanon",
			"LS": "Lesotho",
			"LR": "Liberia",
			"LY": "Libya",
			"LI": "Liechtenstein",
			"LT": "Lithuania",
			"LU": "Luxembourg",
			"MO": "Macao S.A.R., China",
			"MK": "Macedonia",
			"MG": "Madagascar",
			"MW": "Malawi",
			"MY": "Malaysia",
			"MV": "Maldives",
			"ML": "Mali",
			"MT": "Malta",
			"MH": "Marshall Islands",
			"MQ": "Martinique",
			"MR": "Mauritania",
			"MU": "Mauritius",
			"YT": "Mayotte",
			"MX": "Mexico",
			"FM": "Micronesia",
			"MD": "Moldova",
			"MC": "Monaco",
			"MN": "Mongolia",
			"ME": "Montenegro",
			"MS": "Montserrat",
			"MA": "Morocco",
			"MZ": "Mozambique",
			"MM": "Myanmar",
			"NA": "Namibia",
			"NR": "Nauru",
			"NP": "Nepal",
			"NL": "Netherlands",
			"NC": "New Caledonia",
			"NZ": "New Zealand",
			"NI": "Nicaragua",
			"NE": "Niger",
			"NG": "Nigeria",
			"NU": "Niue",
			"NF": "Norfolk Island",
			"KP": "North Korea",
			"MP": "Northern Mariana Islands",
			"NO": "Norway",
			"OM": "Oman",
			"PK": "Pakistan",
			"PS": "Palestinian Territory",
			"PA": "Panama",
			"PG": "Papua New Guinea",
			"PY": "Paraguay",
			"PE": "Peru",
			"PH": "Philippines",
			"PN": "Pitcairn",
			"PL": "Poland",
			"PT": "Portugal",
			"PR": "Puerto Rico",
			"QA": "Qatar",
			"RE": "Reunion",
			"RO": "Romania",
			"RU": "Russia",
			"RW": "Rwanda",
			"ST": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe",
			"BL": "Saint Barth&eacute;lemy",
			"SH": "Saint Helena",
			"KN": "Saint Kitts and Nevis",
			"LC": "Saint Lucia",
			"SX": "Saint Martin (Dutch part)",
			"MF": "Saint Martin (French part)",
			"PM": "Saint Pierre and Miquelon",
			"VC": "Saint Vincent and the Grenadines",
			"WS": "Samoa",
			"SM": "San Marino",
			"SA": "Saudi Arabia",
			"SN": "Senegal",
			"RS": "Serbia",
			"SC": "Seychelles",
			"SL": "Sierra Leone",
			"SG": "Singapore",
			"SK": "Slovakia",
			"SI": "Slovenia",
			"SB": "Solomon Islands",
			"SO": "Somalia",
			"ZA": "South Africa",
			"GS": "South Georgia/Sandwich Islands",
			"KR": "South Korea",
			"SS": "South Sudan",
			"ES": "Spain",
			"LK": "Sri Lanka",
			"SD": "Sudan",
			"SR": "Suriname",
			"SJ": "Svalbard and Jan Mayen",
			"SZ": "Swaziland",
			"SE": "Sweden",
			"CH": "Switzerland",
			"SY": "Syria",
			"TW": "Taiwan",
			"TJ": "Tajikistan",
			"TZ": "Tanzania",
			"TH": "Thailand",
			"TL": "Timor-Leste",
			"TG": "Togo",
			"TK": "Tokelau",
			"TO": "Tonga",
			"TT": "Trinidad and Tobago",
			"TN": "Tunisia",
			"TR": "Turkey",
			"TM": "Turkmenistan",
			"TC": "Turks and Caicos Islands",
			"TV": "Tuvalu",
			"UG": "Uganda",
			"UA": "Ukraine",
			"AE": "United Arab Emirates",
			"GB": "United Kingdom (UK)",
			"US": "United States (US)",
			"UM": "United States (US) Minor Outlying Islands",
			"VI": "United States (US) Virgin Islands",
			"UY": "Uruguay",
			"UZ": "Uzbekistan",
			"VU": "Vanuatu",
			"VA": "Vatican",
			"VE": "Venezuela",
			"VN": "Vietnam",
			"WF": "Wallis and Futuna",
			"EH": "Western Sahara",
			"YE": "Yemen",
			"ZM": "Zambia",
			"ZW": "Zimbabwe"
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_specific_ship_to_countries"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_default_customer_address",
		"label": "Default customer location",
		"description": "",
		"type": "select",
		"default": "geolocation",
		"options": {
			"": "No location by default",
			"base": "Shop base address",
			"geolocation": "Geolocate",
			"geolocation_ajax": "Geolocate (with page caching support)"
		},
		"tip": "This option determines a customers default location. The MaxMind GeoLite Database will be periodically downloaded to your wp-content directory if using geolocation.",
		"value": "geolocation",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_default_customer_address"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_calc_taxes",
		"label": "Enable taxes",
		"description": "Enable taxes and tax calculations",
		"type": "checkbox",
		"default": "no",
		"value": "yes",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_calc_taxes"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_demo_store",
		"label": "Store notice",
		"description": "Enable site-wide store notice text",
		"type": "checkbox",
		"default": "no",
		"value": "no",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_demo_store"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_demo_store_notice",
		"label": "Store notice text",
		"description": "",
		"type": "textarea",
		"default": "This is a demo store for testing purposes &mdash; no orders shall be fulfilled.",
		"value": "This is a demo store for testing purposes &mdash; no orders shall be fulfilled.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_demo_store_notice"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_currency",
		"label": "Currency",
		"description": "This controls what currency prices are listed at in the catalog and which currency gateways will take payments in.",
		"type": "select",
		"default": "GBP",
		"options": {
			"AED": "United Arab Emirates dirham (&#x62f;.&#x625;)",
			"AFN": "Afghan afghani (&#x60b;)",
			"ALL": "Albanian lek (L)",
			"AMD": "Armenian dram (AMD)",
			"ANG": "Netherlands Antillean guilder (&fnof;)",
			"AOA": "Angolan kwanza (Kz)",
			"ARS": "Argentine peso (&#36;)",
			"AUD": "Australian dollar (&#36;)",
			"AWG": "Aruban florin (&fnof;)",
			"AZN": "Azerbaijani manat (AZN)",
			"BAM": "Bosnia and Herzegovina convertible mark (KM)",
			"BBD": "Barbadian dollar (&#36;)",
			"BDT": "Bangladeshi taka (&#2547;&nbsp;)",
			"BGN": "Bulgarian lev (&#1083;&#1074;.)",
			"BHD": "Bahraini dinar (.&#x62f;.&#x628;)",
			"BIF": "Burundian franc (Fr)",
			"BMD": "Bermudian dollar (&#36;)",
			"BND": "Brunei dollar (&#36;)",
			"BOB": "Bolivian boliviano (Bs.)",
			"BRL": "Brazilian real (&#82;&#36;)",
			"BSD": "Bahamian dollar (&#36;)",
			"BTC": "Bitcoin (&#3647;)",
			"BTN": "Bhutanese ngultrum (Nu.)",
			"BWP": "Botswana pula (P)",
			"BYR": "Belarusian ruble (Br)",
			"BZD": "Belize dollar (&#36;)",
			"CAD": "Canadian dollar (&#36;)",
			"CDF": "Congolese franc (Fr)",
			"CHF": "Swiss franc (&#67;&#72;&#70;)",
			"CLP": "Chilean peso (&#36;)",
			"CNY": "Chinese yuan (&yen;)",
			"COP": "Colombian peso (&#36;)",
			"CRC": "Costa Rican col&oacute;n (&#x20a1;)",
			"CUC": "Cuban convertible peso (&#36;)",
			"CUP": "Cuban peso (&#36;)",
			"CVE": "Cape Verdean escudo (&#36;)",
			"CZK": "Czech koruna (&#75;&#269;)",
			"DJF": "Djiboutian franc (Fr)",
			"DKK": "Danish krone (DKK)",
			"DOP": "Dominican peso (RD&#36;)",
			"DZD": "Algerian dinar (&#x62f;.&#x62c;)",
			"EGP": "Egyptian pound (EGP)",
			"ERN": "Eritrean nakfa (Nfk)",
			"ETB": "Ethiopian birr (Br)",
			"EUR": "Euro (&euro;)",
			"FJD": "Fijian dollar (&#36;)",
			"FKP": "Falkland Islands pound (&pound;)",
			"GBP": "Pound sterling (&pound;)",
			"GEL": "Georgian lari (&#x10da;)",
			"GGP": "Guernsey pound (&pound;)",
			"GHS": "Ghana cedi (&#x20b5;)",
			"GIP": "Gibraltar pound (&pound;)",
			"GMD": "Gambian dalasi (D)",
			"GNF": "Guinean franc (Fr)",
			"GTQ": "Guatemalan quetzal (Q)",
			"GYD": "Guyanese dollar (&#36;)",
			"HKD": "Hong Kong dollar (&#36;)",
			"HNL": "Honduran lempira (L)",
			"HRK": "Croatian kuna (Kn)",
			"HTG": "Haitian gourde (G)",
			"HUF": "Hungarian forint (&#70;&#116;)",
			"IDR": "Indonesian rupiah (Rp)",
			"ILS": "Israeli new shekel (&#8362;)",
			"IMP": "Manx pound (&pound;)",
			"INR": "Indian rupee (&#8377;)",
			"IQD": "Iraqi dinar (&#x639;.&#x62f;)",
			"IRR": "Iranian rial (&#xfdfc;)",
			"IRT": "Iranian toman (&#x062A;&#x0648;&#x0645;&#x0627;&#x0646;)",
			"ISK": "Icelandic kr&oacute;na (kr.)",
			"JEP": "Jersey pound (&pound;)",
			"JMD": "Jamaican dollar (&#36;)",
			"JOD": "Jordanian dinar (&#x62f;.&#x627;)",
			"JPY": "Japanese yen (&yen;)",
			"KES": "Kenyan shilling (KSh)",
			"KGS": "Kyrgyzstani som (&#x441;&#x43e;&#x43c;)",
			"KHR": "Cambodian riel (&#x17db;)",
			"KMF": "Comorian franc (Fr)",
			"KPW": "North Korean won (&#x20a9;)",
			"KRW": "South Korean won (&#8361;)",
			"KWD": "Kuwaiti dinar (&#x62f;.&#x643;)",
			"KYD": "Cayman Islands dollar (&#36;)",
			"KZT": "Kazakhstani tenge (KZT)",
			"LAK": "Lao kip (&#8365;)",
			"LBP": "Lebanese pound (&#x644;.&#x644;)",
			"LKR": "Sri Lankan rupee (&#xdbb;&#xdd4;)",
			"LRD": "Liberian dollar (&#36;)",
			"LSL": "Lesotho loti (L)",
			"LYD": "Libyan dinar (&#x644;.&#x62f;)",
			"MAD": "Moroccan dirham (&#x62f;.&#x645;.)",
			"MDL": "Moldovan leu (MDL)",
			"MGA": "Malagasy ariary (Ar)",
			"MKD": "Macedonian denar (&#x434;&#x435;&#x43d;)",
			"MMK": "Burmese kyat (Ks)",
			"MNT": "Mongolian t&ouml;gr&ouml;g (&#x20ae;)",
			"MOP": "Macanese pataca (P)",
			"MRO": "Mauritanian ouguiya (UM)",
			"MUR": "Mauritian rupee (&#x20a8;)",
			"MVR": "Maldivian rufiyaa (.&#x783;)",
			"MWK": "Malawian kwacha (MK)",
			"MXN": "Mexican peso (&#36;)",
			"MYR": "Malaysian ringgit (&#82;&#77;)",
			"MZN": "Mozambican metical (MT)",
			"NAD": "Namibian dollar (&#36;)",
			"NGN": "Nigerian naira (&#8358;)",
			"NIO": "Nicaraguan c&oacute;rdoba (C&#36;)",
			"NOK": "Norwegian krone (&#107;&#114;)",
			"NPR": "Nepalese rupee (&#8360;)",
			"NZD": "New Zealand dollar (&#36;)",
			"OMR": "Omani rial (&#x631;.&#x639;.)",
			"PAB": "Panamanian balboa (B/.)",
			"PEN": "Peruvian nuevo sol (S/.)",
			"PGK": "Papua New Guinean kina (K)",
			"PHP": "Philippine peso (&#8369;)",
			"PKR": "Pakistani rupee (&#8360;)",
			"PLN": "Polish z&#x142;oty (&#122;&#322;)",
			"PRB": "Transnistrian ruble (&#x440;.)",
			"PYG": "Paraguayan guaran&iacute; (&#8370;)",
			"QAR": "Qatari riyal (&#x631;.&#x642;)",
			"RON": "Romanian leu (lei)",
			"RSD": "Serbian dinar (&#x434;&#x438;&#x43d;.)",
			"RUB": "Russian ruble (&#8381;)",
			"RWF": "Rwandan franc (Fr)",
			"SAR": "Saudi riyal (&#x631;.&#x633;)",
			"SBD": "Solomon Islands dollar (&#36;)",
			"SCR": "Seychellois rupee (&#x20a8;)",
			"SDG": "Sudanese pound (&#x62c;.&#x633;.)",
			"SEK": "Swedish krona (&#107;&#114;)",
			"SGD": "Singapore dollar (&#36;)",
			"SHP": "Saint Helena pound (&pound;)",
			"SLL": "Sierra Leonean leone (Le)",
			"SOS": "Somali shilling (Sh)",
			"SRD": "Surinamese dollar (&#36;)",
			"SSP": "South Sudanese pound (&pound;)",
			"STD": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe dobra (Db)",
			"SYP": "Syrian pound (&#x644;.&#x633;)",
			"SZL": "Swazi lilangeni (L)",
			"THB": "Thai baht (&#3647;)",
			"TJS": "Tajikistani somoni (&#x405;&#x41c;)",
			"TMT": "Turkmenistan manat (m)",
			"TND": "Tunisian dinar (&#x62f;.&#x62a;)",
			"TOP": "Tongan pa&#x2bb;anga (T&#36;)",
			"TRY": "Turkish lira (&#8378;)",
			"TTD": "Trinidad and Tobago dollar (&#36;)",
			"TWD": "New Taiwan dollar (&#78;&#84;&#36;)",
			"TZS": "Tanzanian shilling (Sh)",
			"UAH": "Ukrainian hryvnia (&#8372;)",
			"UGX": "Ugandan shilling (UGX)",
			"USD": "United States dollar (&#36;)",
			"UYU": "Uruguayan peso (&#36;)",
			"UZS": "Uzbekistani som (UZS)",
			"VEF": "Venezuelan bol&iacute;var (Bs F)",
			"VND": "Vietnamese &#x111;&#x1ed3;ng (&#8363;)",
			"VUV": "Vanuatu vatu (Vt)",
			"WST": "Samoan t&#x101;l&#x101; (T)",
			"XAF": "Central African CFA franc (Fr)",
			"XCD": "East Caribbean dollar (&#36;)",
			"XOF": "West African CFA franc (Fr)",
			"XPF": "CFP franc (Fr)",
			"YER": "Yemeni rial (&#xfdfc;)",
			"ZAR": "South African rand (&#82;)",
			"ZMW": "Zambian kwacha (K)"
		},
		"tip": "This controls what currency prices are listed at in the catalog and which currency gateways will take payments in.",
		"value": "USD",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_currency"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_currency_pos",
		"label": "Currency position",
		"description": "This controls the position of the currency symbol.",
		"type": "select",
		"default": "left",
		"options": {
			"left": "Left (&#36;99.99)",
			"right": "Right (99.99&#36;)",
			"left_space": "Left with space (&#36; 99.99)",
			"right_space": "Right with space (99.99 &#36;)"
		},
		"tip": "This controls the position of the currency symbol.",
		"value": "left",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_currency_pos"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_price_thousand_sep",
		"label": "Thousand separator",
		"description": "This sets the thousand separator of displayed prices.",
		"type": "text",
		"default": ",",
		"tip": "This sets the thousand separator of displayed prices.",
		"value": ",",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_price_thousand_sep"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_price_decimal_sep",
		"label": "Decimal separator",
		"description": "This sets the decimal separator of displayed prices.",
		"type": "text",
		"default": ".",
		"tip": "This sets the decimal separator of displayed prices.",
		"value": ".",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_price_decimal_sep"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "woocommerce_price_num_decimals",
		"label": "Number of decimals",
		"description": "This sets the number of decimal points shown in displayed prices.",
		"type": "number",
		"default": "2",
		"tip": "This sets the number of decimal points shown in displayed prices.",
		"value": "2",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_price_num_decimals"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

## Update a setting option

This API lets you make changes to a setting option.

```http
PUT /wp-json/wc/v3/settings/<group_id>/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/settings/general/woocommerce_allowed_countries \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "value": "all_except"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	value: 'all_except',
};

WooCommerce.put( 'settings/general/woocommerce_allowed_countries', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'value' => 'all_except'
];

print_r($woocommerce->put('settings/general/woocommerce_allowed_countries', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "value": "all_except"
}

print(wcapi.put("settings/general/woocommerce_allowed_countries", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  value: "all_except"
}

woocommerce.put("settings/general/woocommerce_allowed_countries", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": "woocommerce_allowed_countries",
	"label": "Selling location(s)",
	"description": "This option lets you limit which countries you are willing to sell to.",
	"type": "select",
	"default": "all",
	"options": {
		"all": "Sell to all countries",
		"all_except": "Sell to all countries, except for&hellip;",
		"specific": "Sell to specific countries"
	},
	"tip": "This option lets you limit which countries you are willing to sell to.",
	"value": "all_except",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_allowed_countries"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/settings/general"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Batch update setting options

This API helps you to batch update multiple setting options.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/settings/<id>/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/settings/general/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "update": [
    {
      "id": "woocommerce_allowed_countries",
      "value": "all"
    },
    {
      "id": "woocommerce_demo_store",
      "value": "yes"
    },
    {
      "id": "woocommerce_currency",
      "value": "GBP"
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			regular_price: '10.00',
			attributes: [
				{
					id: 6,
					option: 'Blue',
				},
			],
		},
		{
			regular_price: '10.00',
			attributes: [
				{
					id: 6,
					option: 'White',
				},
			],
		},
	],
	update: [
		{
			id: 733,
			regular_price: '10.00',
		},
	],
	delete: [ 732 ],
};

WooCommerce.post( 'products/22/settings/general/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'regular_price' => '10.00',
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'Blue'
                ]
            ]
        ],
        [
            'regular_price' => '10.00',
            'attributes' => [
                [
                    'id' => 6,
                    'option' => 'White'
                ]
            ]
        ]
    ],
    'update' => [
        [
            'id' => 733,
            'regular_price' => '10.00'
        ]
    ],
    'delete' => [
        732
    ]
];

print_r($woocommerce->post('products/22/settings/general/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "regular_price": "10.00",
            "attributes": [
                {
                    "id": 6,
                    "option": "Blue"
                }
            ]
        },
        {
            "regular_price": "10.00",
            "attributes": [
                {
                    "id": 6,
                    "option": "White"
                }
            ]
        }
    ],
    "update": [
        {
            "id": 733,
            "regular_price": "10.00"
        }
    ],
    "delete": [
        732
    ]
}

print(wcapi.post("products/22/settings/general/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "Blue"
        }
      ]
    },
    {
      regular_price: "10.00",
      attributes: [
        {
          id: 6,
          option: "White"
        }
      ]
    }
  ],
  update: [
    {
      id: 733,
      regular_price: "10.00"
    }
  ],
  delete: [
    732
  ]
}

woocommerce.post("products/22/settings/general/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"update": [
		{
			"id": "woocommerce_allowed_countries",
			"label": "Selling location(s)",
			"description": "This option lets you limit which countries you are willing to sell to.",
			"type": "select",
			"default": "all",
			"options": {
				"all": "Sell to all countries",
				"all_except": "Sell to all countries, except for&hellip;",
				"specific": "Sell to specific countries"
			},
			"tip": "This option lets you limit which countries you are willing to sell to.",
			"value": "all",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_allowed_countries"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/settings/general"
					}
				]
			}
		},
		{
			"id": "woocommerce_demo_store",
			"label": "Store notice",
			"description": "Enable site-wide store notice text",
			"type": "checkbox",
			"default": "no",
			"value": "yes",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_demo_store"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/settings/general"
					}
				]
			}
		},
		{
			"id": "woocommerce_currency",
			"label": "Currency",
			"description": "This controls what currency prices are listed at in the catalog and which currency gateways will take payments in.",
			"type": "select",
			"default": "GBP",
			"options": {
				"AED": "United Arab Emirates dirham (&#x62f;.&#x625;)",
				"AFN": "Afghan afghani (&#x60b;)",
				"ALL": "Albanian lek (L)",
				"AMD": "Armenian dram (AMD)",
				"ANG": "Netherlands Antillean guilder (&fnof;)",
				"AOA": "Angolan kwanza (Kz)",
				"ARS": "Argentine peso (&#36;)",
				"AUD": "Australian dollar (&#36;)",
				"AWG": "Aruban florin (&fnof;)",
				"AZN": "Azerbaijani manat (AZN)",
				"BAM": "Bosnia and Herzegovina convertible mark (KM)",
				"BBD": "Barbadian dollar (&#36;)",
				"BDT": "Bangladeshi taka (&#2547;&nbsp;)",
				"BGN": "Bulgarian lev (&#1083;&#1074;.)",
				"BHD": "Bahraini dinar (.&#x62f;.&#x628;)",
				"BIF": "Burundian franc (Fr)",
				"BMD": "Bermudian dollar (&#36;)",
				"BND": "Brunei dollar (&#36;)",
				"BOB": "Bolivian boliviano (Bs.)",
				"BRL": "Brazilian real (&#82;&#36;)",
				"BSD": "Bahamian dollar (&#36;)",
				"BTC": "Bitcoin (&#3647;)",
				"BTN": "Bhutanese ngultrum (Nu.)",
				"BWP": "Botswana pula (P)",
				"BYR": "Belarusian ruble (Br)",
				"BZD": "Belize dollar (&#36;)",
				"CAD": "Canadian dollar (&#36;)",
				"CDF": "Congolese franc (Fr)",
				"CHF": "Swiss franc (&#67;&#72;&#70;)",
				"CLP": "Chilean peso (&#36;)",
				"CNY": "Chinese yuan (&yen;)",
				"COP": "Colombian peso (&#36;)",
				"CRC": "Costa Rican col&oacute;n (&#x20a1;)",
				"CUC": "Cuban convertible peso (&#36;)",
				"CUP": "Cuban peso (&#36;)",
				"CVE": "Cape Verdean escudo (&#36;)",
				"CZK": "Czech koruna (&#75;&#269;)",
				"DJF": "Djiboutian franc (Fr)",
				"DKK": "Danish krone (DKK)",
				"DOP": "Dominican peso (RD&#36;)",
				"DZD": "Algerian dinar (&#x62f;.&#x62c;)",
				"EGP": "Egyptian pound (EGP)",
				"ERN": "Eritrean nakfa (Nfk)",
				"ETB": "Ethiopian birr (Br)",
				"EUR": "Euro (&euro;)",
				"FJD": "Fijian dollar (&#36;)",
				"FKP": "Falkland Islands pound (&pound;)",
				"GBP": "Pound sterling (&pound;)",
				"GEL": "Georgian lari (&#x10da;)",
				"GGP": "Guernsey pound (&pound;)",
				"GHS": "Ghana cedi (&#x20b5;)",
				"GIP": "Gibraltar pound (&pound;)",
				"GMD": "Gambian dalasi (D)",
				"GNF": "Guinean franc (Fr)",
				"GTQ": "Guatemalan quetzal (Q)",
				"GYD": "Guyanese dollar (&#36;)",
				"HKD": "Hong Kong dollar (&#36;)",
				"HNL": "Honduran lempira (L)",
				"HRK": "Croatian kuna (Kn)",
				"HTG": "Haitian gourde (G)",
				"HUF": "Hungarian forint (&#70;&#116;)",
				"IDR": "Indonesian rupiah (Rp)",
				"ILS": "Israeli new shekel (&#8362;)",
				"IMP": "Manx pound (&pound;)",
				"INR": "Indian rupee (&#8377;)",
				"IQD": "Iraqi dinar (&#x639;.&#x62f;)",
				"IRR": "Iranian rial (&#xfdfc;)",
				"IRT": "Iranian toman (&#x062A;&#x0648;&#x0645;&#x0627;&#x0646;)",
				"ISK": "Icelandic kr&oacute;na (kr.)",
				"JEP": "Jersey pound (&pound;)",
				"JMD": "Jamaican dollar (&#36;)",
				"JOD": "Jordanian dinar (&#x62f;.&#x627;)",
				"JPY": "Japanese yen (&yen;)",
				"KES": "Kenyan shilling (KSh)",
				"KGS": "Kyrgyzstani som (&#x441;&#x43e;&#x43c;)",
				"KHR": "Cambodian riel (&#x17db;)",
				"KMF": "Comorian franc (Fr)",
				"KPW": "North Korean won (&#x20a9;)",
				"KRW": "South Korean won (&#8361;)",
				"KWD": "Kuwaiti dinar (&#x62f;.&#x643;)",
				"KYD": "Cayman Islands dollar (&#36;)",
				"KZT": "Kazakhstani tenge (KZT)",
				"LAK": "Lao kip (&#8365;)",
				"LBP": "Lebanese pound (&#x644;.&#x644;)",
				"LKR": "Sri Lankan rupee (&#xdbb;&#xdd4;)",
				"LRD": "Liberian dollar (&#36;)",
				"LSL": "Lesotho loti (L)",
				"LYD": "Libyan dinar (&#x644;.&#x62f;)",
				"MAD": "Moroccan dirham (&#x62f;.&#x645;.)",
				"MDL": "Moldovan leu (MDL)",
				"MGA": "Malagasy ariary (Ar)",
				"MKD": "Macedonian denar (&#x434;&#x435;&#x43d;)",
				"MMK": "Burmese kyat (Ks)",
				"MNT": "Mongolian t&ouml;gr&ouml;g (&#x20ae;)",
				"MOP": "Macanese pataca (P)",
				"MRO": "Mauritanian ouguiya (UM)",
				"MUR": "Mauritian rupee (&#x20a8;)",
				"MVR": "Maldivian rufiyaa (.&#x783;)",
				"MWK": "Malawian kwacha (MK)",
				"MXN": "Mexican peso (&#36;)",
				"MYR": "Malaysian ringgit (&#82;&#77;)",
				"MZN": "Mozambican metical (MT)",
				"NAD": "Namibian dollar (&#36;)",
				"NGN": "Nigerian naira (&#8358;)",
				"NIO": "Nicaraguan c&oacute;rdoba (C&#36;)",
				"NOK": "Norwegian krone (&#107;&#114;)",
				"NPR": "Nepalese rupee (&#8360;)",
				"NZD": "New Zealand dollar (&#36;)",
				"OMR": "Omani rial (&#x631;.&#x639;.)",
				"PAB": "Panamanian balboa (B/.)",
				"PEN": "Peruvian nuevo sol (S/.)",
				"PGK": "Papua New Guinean kina (K)",
				"PHP": "Philippine peso (&#8369;)",
				"PKR": "Pakistani rupee (&#8360;)",
				"PLN": "Polish z&#x142;oty (&#122;&#322;)",
				"PRB": "Transnistrian ruble (&#x440;.)",
				"PYG": "Paraguayan guaran&iacute; (&#8370;)",
				"QAR": "Qatari riyal (&#x631;.&#x642;)",
				"RON": "Romanian leu (lei)",
				"RSD": "Serbian dinar (&#x434;&#x438;&#x43d;.)",
				"RUB": "Russian ruble (&#8381;)",
				"RWF": "Rwandan franc (Fr)",
				"SAR": "Saudi riyal (&#x631;.&#x633;)",
				"SBD": "Solomon Islands dollar (&#36;)",
				"SCR": "Seychellois rupee (&#x20a8;)",
				"SDG": "Sudanese pound (&#x62c;.&#x633;.)",
				"SEK": "Swedish krona (&#107;&#114;)",
				"SGD": "Singapore dollar (&#36;)",
				"SHP": "Saint Helena pound (&pound;)",
				"SLL": "Sierra Leonean leone (Le)",
				"SOS": "Somali shilling (Sh)",
				"SRD": "Surinamese dollar (&#36;)",
				"SSP": "South Sudanese pound (&pound;)",
				"STD": "S&atilde;o Tom&eacute; and Pr&iacute;ncipe dobra (Db)",
				"SYP": "Syrian pound (&#x644;.&#x633;)",
				"SZL": "Swazi lilangeni (L)",
				"THB": "Thai baht (&#3647;)",
				"TJS": "Tajikistani somoni (&#x405;&#x41c;)",
				"TMT": "Turkmenistan manat (m)",
				"TND": "Tunisian dinar (&#x62f;.&#x62a;)",
				"TOP": "Tongan pa&#x2bb;anga (T&#36;)",
				"TRY": "Turkish lira (&#8378;)",
				"TTD": "Trinidad and Tobago dollar (&#36;)",
				"TWD": "New Taiwan dollar (&#78;&#84;&#36;)",
				"TZS": "Tanzanian shilling (Sh)",
				"UAH": "Ukrainian hryvnia (&#8372;)",
				"UGX": "Ugandan shilling (UGX)",
				"USD": "United States dollar (&#36;)",
				"UYU": "Uruguayan peso (&#36;)",
				"UZS": "Uzbekistani som (UZS)",
				"VEF": "Venezuelan bol&iacute;var (Bs F)",
				"VND": "Vietnamese &#x111;&#x1ed3;ng (&#8363;)",
				"VUV": "Vanuatu vatu (Vt)",
				"WST": "Samoan t&#x101;l&#x101; (T)",
				"XAF": "Central African CFA franc (Fr)",
				"XCD": "East Caribbean dollar (&#36;)",
				"XOF": "West African CFA franc (Fr)",
				"XPF": "CFP franc (Fr)",
				"YER": "Yemeni rial (&#xfdfc;)",
				"ZAR": "South African rand (&#82;)",
				"ZMW": "Zambian kwacha (K)"
			},
			"tip": "This controls what currency prices are listed at in the catalog and which currency gateways will take payments in.",
			"value": "GBP",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/settings/general/woocommerce_currency"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/settings/general"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Settings

*Source: apis/rest-api/v3/settings.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Settings

The settings API allows you to view all groups of settings available.

## Setting group properties

| Attribute     | Type   | Description                                                                                                |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `id`          | string | A unique identifier that can be used to link settings together. `READ-ONLY`  |
| `label`       | string | A human readable label for the setting used in interfaces. `READ-ONLY`       |
| `description` | string | A human readable description for the setting used in interfaces. `READ-ONLY` |
| `parent_id`   | string | ID of parent grouping. `READ-ONLY`                                           |
| `sub_groups`  | string | IDs for settings sub groups. `READ-ONLY`                                     |

## List all settings groups

This API helps you to view all the settings groups.

```http
GET /wp-json/wc/v3/settings
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/settings \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'settings' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('settings')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("settings").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("settings").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": "general",
		"label": "General",
		"description": "",
		"parent_id": "",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/general"
				}
			]
		}
	},
	{
		"id": "products",
		"label": "Products",
		"description": "",
		"parent_id": "",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/products"
				}
			]
		}
	},
	{
		"id": "tax",
		"label": "Tax",
		"description": "",
		"parent_id": "",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/tax"
				}
			]
		}
	},
	{
		"id": "shipping",
		"label": "Shipping",
		"description": "",
		"parent_id": "",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/shipping"
				}
			]
		}
	},
	{
		"id": "checkout",
		"label": "Checkout",
		"description": "",
		"parent_id": "",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/checkout"
				}
			]
		}
	},
	{
		"id": "account",
		"label": "Accounts",
		"description": "",
		"parent_id": "",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/account"
				}
			]
		}
	},
	{
		"id": "email",
		"label": "Emails",
		"description": "",
		"parent_id": "",
		"sub_groups": [
			"email_new_order",
			"email_cancelled_order",
			"email_failed_order",
			"email_customer_on_hold_order",
			"email_customer_processing_order",
			"email_customer_completed_order",
			"email_customer_refunded_order",
			"email_customer_invoice",
			"email_customer_note",
			"email_customer_reset_password",
			"email_customer_new_account"
		],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email"
				}
			]
		}
	},
	{
		"id": "integration",
		"label": "Integration",
		"description": "",
		"parent_id": "",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/integration"
				}
			]
		}
	},
	{
		"id": "api",
		"label": "API",
		"description": "",
		"parent_id": "",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/api"
				}
			]
		}
	},
	{
		"id": "email_new_order",
		"label": "New order",
		"description": "New order emails are sent to chosen recipient(s) when a new order is received.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_new_order"
				}
			]
		}
	},
	{
		"id": "email_cancelled_order",
		"label": "Cancelled order",
		"description": "Cancelled order emails are sent to chosen recipient(s) when orders have been marked cancelled (if they were previously processing or on-hold).",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_cancelled_order"
				}
			]
		}
	},
	{
		"id": "email_failed_order",
		"label": "Failed order",
		"description": "Failed order emails are sent to chosen recipient(s) when orders have been marked failed (if they were previously processing or on-hold).",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_failed_order"
				}
			]
		}
	},
	{
		"id": "email_customer_on_hold_order",
		"label": "Order on-hold",
		"description": "This is an order notification sent to customers containing order details after an order is placed on-hold.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_customer_on_hold_order"
				}
			]
		}
	},
	{
		"id": "email_customer_processing_order",
		"label": "Processing order",
		"description": "This is an order notification sent to customers containing order details after payment.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_customer_processing_order"
				}
			]
		}
	},
	{
		"id": "email_customer_completed_order",
		"label": "Completed order",
		"description": "Order complete emails are sent to customers when their orders are marked completed and usually indicate that their orders have been shipped.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_customer_completed_order"
				}
			]
		}
	},
	{
		"id": "email_customer_refunded_order",
		"label": "Refunded order",
		"description": "Order refunded emails are sent to customers when their orders are marked refunded.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_customer_refunded_order"
				}
			]
		}
	},
	{
		"id": "email_customer_invoice",
		"label": "Customer invoice",
		"description": "Customer invoice emails can be sent to customers containing their order information and payment links.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_customer_invoice"
				}
			]
		}
	},
	{
		"id": "email_customer_note",
		"label": "Customer note",
		"description": "Customer note emails are sent when you add a note to an order.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_customer_note"
				}
			]
		}
	},
	{
		"id": "email_customer_reset_password",
		"label": "Reset password",
		"description": "Customer \"reset password\" emails are sent when customers reset their passwords.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_customer_reset_password"
				}
			]
		}
	},
	{
		"id": "email_customer_new_account",
		"label": "New account",
		"description": "Customer \"new account\" emails are sent to the customer when a customer signs up via checkout or account pages.",
		"parent_id": "email",
		"sub_groups": [],
		"_links": {
			"options": [
				{
					"href": "https://example.com/wp-json/wc/v3/settings/email_customer_new_account"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>


---

## Shipping methods

*Source: apis/rest-api/v3/shipping-methods.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Shipping methods

The shipping methods API allows you to view individual shipping methods.

## Shipping method properties

| Attribute     | Type   | Description                                                            |
| ------------- | ------ | ---------------------------------------------------------------------- |
| `id`          | string | Method ID. `READ-ONLY`                   |
| `title`       | string | Shipping method title. `READ-ONLY`       |
| `description` | string | Shipping method description. `READ-ONLY` |

## Retrieve a shipping method

This API lets you retrieve and view a specific shipping method.

```http
GET /wp-json/wc/v3/shipping_methods/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/shipping_methods/flat_rate \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'shipping_methods/flat_rate' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping_methods/flat_rate')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping_methods/flat_rate").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping_methods/flat_rate").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": "flat_rate",
	"title": "Flat rate",
	"description": "Lets you charge a fixed rate for shipping.",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping_methods/flat_rate"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping_methods"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all shipping methods

This API helps you to view all the shipping methods.

```http
GET /wp-json/wc/v3/shipping_methods
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/shipping_methods \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'shipping_methods' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping_methods')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping_methods").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping_methods").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": "flat_rate",
		"title": "Flat rate",
		"description": "Lets you charge a fixed rate for shipping.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping_methods/flat_rate"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping_methods"
				}
			]
		}
	},
	{
		"id": "free_shipping",
		"title": "Free shipping",
		"description": "Free shipping is a special method which can be triggered with coupons and minimum spends.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping_methods/free_shipping"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping_methods"
				}
			]
		}
	},
	{
		"id": "local_pickup",
		"title": "Local pickup",
		"description": "Allow customers to pick up orders themselves. By default, when using local pickup store base taxes will apply regardless of customer address.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping_methods/local_pickup"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping_methods"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>


---

## Shipping zone locations

*Source: apis/rest-api/v3/shipping-zone-locations.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Shipping zone locations

The shipping zone locations API allows you to view and batch update locations of a shipping zone.

## Shipping location properties

| Attribute | Type   | Description                                                                                                 |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `code`    | string | Shipping zone location code.                                                                                |
| `type`    | string | Shipping zone location type. Options: `postcode`, `state`, `country` and `continent`. Default is `country`. |

## List all locations of a shipping zone

This API helps you to view all the locations of a shipping zone.

```http
GET /wp-json/wc/v3/shipping/zones/<id>/locations
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/shipping/zones/5/locations \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'shipping/zones/5/locations' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones/5/locations')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones/5/locations").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones/5/locations").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"code": "BR",
		"type": "country",
		"_links": {
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/locations"
				}
			],
			"describes": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

## Update a locations of a shipping zone

This API lets you make changes to locations of a shipping zone.

```http
PUT /wp-json/wc/v3/shipping/zones/<id>/locations
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/shipping/zones/5/locations \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '[
  {
    "code": "BR:SP",
    "type": "state"
  },
  {
    "code": "BR:RJ",
    "type": "state"
  }
]'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
var data = [
	{
		code: 'BR:SP',
		type: 'state',
	},
	{
		code: 'BR:RJ',
		type: 'state',
	},
];

WooCommerce.put( 'shipping/zones/5/locations', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    [
        'code' => 'BR:SP',
        'type' => 'state'
    ],
    [
        'code' => 'BR:RJ',
        'type' => 'state'
    ]
];

print_r($woocommerce->put('shipping/zones/5/locations', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = [
    {
        "code": "BR:SP",
        "type": "state"
    },
    {
        "code": "BR:RJ",
        "type": "state"
    }
]

print(wcapi.put("shipping/zones/5/locations", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = [
  {
    code: "BR:SP",
    type: "state"
  },
  {
    code: "BR:RJ",
    type: "state"
  }
]

woocommerce.put("shipping/zones/5/locations", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"code": "BR:SP",
		"type": "state",
		"_links": {
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/locations"
				}
			],
			"describes": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
				}
			]
		}
	},
	{
		"code": "BR:RJ",
		"type": "state",
		"_links": {
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/locations"
				}
			],
			"describes": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>


---

## Shipping zone methods

*Source: apis/rest-api/v3/shipping-zone-methods.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Shipping zone methods

The shipping zone methods API allows you to create, view, update, and delete individual methods of a shipping zone.

## Shipping method properties

| Attribute            | Type    | Description                                                                                                 |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `instance_id`        | integer | Shipping method instance ID. `READ-ONLY`                                      |
| `title`              | string  | Shipping method customer facing title. `READ-ONLY`                            |
| `order`              | integer | Shipping method sort order.                                                                                 |
| `enabled`            | boolean | Shipping method enabled status.                                                                             |
| `method_id`          | string  | Shipping method ID. `READ-ONLY` `MANDATORY`     |
| `method_title`       | string  | Shipping method title. `READ-ONLY`                                            |
| `method_description` | string  | Shipping method description. `READ-ONLY`                                      |
| `settings`           | object  | Shipping method settings. See [Shipping method - Settings properties](#shipping-method---settings-properties) |

### Shipping method - Settings properties

| Attribute     | Type   | Description                                                                                                                                                                                     |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string | A unique identifier for the setting. `READ-ONLY`                                                                                                                  |
| `label`       | string | A human readable label for the setting used in interfaces. `READ-ONLY`                                                                                            |
| `description` | string | A human readable description for the setting used in interfaces. `READ-ONLY`                                                                                      |
| `type`        | string | Type of setting. Options: `text`, `email`, `number`, `color`, `password`, `textarea`, `select`, `multiselect`, `radio`, `image_width` and `checkbox`. `READ-ONLY` |
| `value`       | string | Setting value.                                                                                                                                                                                  |
| `default`     | string | Default value for the setting. `READ-ONLY`                                                                                                                        |
| `tip`         | string | Additional help text shown to the user about the setting. `READ-ONLY`                                                                                             |
| `placeholder` | string | Placeholder text to be displayed in text inputs. `READ-ONLY`                                                                                                      |

## Include a shipping method to a shipping zone

This API helps you to create a new shipping method to a shipping zone.

```http
POST /wp-json/wc/v3/shipping/zones/<id>/methods
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/shipping/zones/5/methods \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "method_id": "flat_rate"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	method_id: 'flat_rate',
};

WooCommerce.post( 'shipping/zones/5/methods', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'method_id' => 'flat_rate'
];

print_r($woocommerce->post('shipping/zones/5/methods', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "method_id": "flat_rate"
}

print(wcapi.post("shipping/zones/5/methods", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  method_id: "flat_rate"
}

woocommerce.post("shipping/zones/5/methods", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"instance_id": 26,
	"title": "Flat rate",
	"order": 1,
	"enabled": true,
	"method_id": "flat_rate",
	"method_title": "Flat rate",
	"method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
	"settings": {
		"title": {
			"id": "title",
			"label": "Method title",
			"description": "This controls the title which the user sees during checkout.",
			"type": "text",
			"value": "Flat rate",
			"default": "Flat rate",
			"tip": "This controls the title which the user sees during checkout.",
			"placeholder": ""
		},
		"tax_status": {
			"id": "tax_status",
			"label": "Tax status",
			"description": "",
			"type": "select",
			"value": "taxable",
			"default": "taxable",
			"tip": "",
			"placeholder": "",
			"options": {
				"taxable": "Taxable",
				"none": "None"
			}
		},
		"cost": {
			"id": "cost",
			"label": "Cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "0",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": ""
		},
		"class_costs": {
			"id": "class_costs",
			"label": "Shipping class costs",
			"description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
			"type": "title",
			"value": "",
			"default": "",
			"tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
			"placeholder": ""
		},
		"class_cost_92": {
			"id": "class_cost_92",
			"label": "\"Express\" shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"class_cost_91": {
			"id": "class_cost_91",
			"label": "\"Priority\" shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"no_class_cost": {
			"id": "no_class_cost",
			"label": "No shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"type": {
			"id": "type",
			"label": "Calculation type",
			"description": "",
			"type": "select",
			"value": "class",
			"default": "class",
			"tip": "",
			"placeholder": "",
			"options": {
				"class": "Per class: Charge shipping for each shipping class individually",
				"order": "Per order: Charge shipping for the most expensive shipping class"
			}
		}
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods/26"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods"
			}
		],
		"describes": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a shipping method from a shipping zone

This API lets you retrieve and view a specific shipping method from a shipping zone by ID.

```http
GET /wp-json/wc/v3/shipping/zones/<zone_id>/methods/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/shipping/zones/5/methods/26 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'shipping/zones/5/methods/26' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones/5/methods/26')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones/5/methods/26").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones/5/methods/26").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"instance_id": 26,
	"title": "Flat rate",
	"order": 1,
	"enabled": true,
	"method_id": "flat_rate",
	"method_title": "Flat rate",
	"method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
	"settings": {
		"title": {
			"id": "title",
			"label": "Method title",
			"description": "This controls the title which the user sees during checkout.",
			"type": "text",
			"value": "Flat rate",
			"default": "Flat rate",
			"tip": "This controls the title which the user sees during checkout.",
			"placeholder": ""
		},
		"tax_status": {
			"id": "tax_status",
			"label": "Tax status",
			"description": "",
			"type": "select",
			"value": "taxable",
			"default": "taxable",
			"tip": "",
			"placeholder": "",
			"options": {
				"taxable": "Taxable",
				"none": "None"
			}
		},
		"cost": {
			"id": "cost",
			"label": "Cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "0",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": ""
		},
		"class_costs": {
			"id": "class_costs",
			"label": "Shipping class costs",
			"description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
			"type": "title",
			"value": "",
			"default": "",
			"tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
			"placeholder": ""
		},
		"class_cost_92": {
			"id": "class_cost_92",
			"label": "\"Express\" shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"class_cost_91": {
			"id": "class_cost_91",
			"label": "\"Priority\" shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"no_class_cost": {
			"id": "no_class_cost",
			"label": "No shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"type": {
			"id": "type",
			"label": "Calculation type",
			"description": "",
			"type": "select",
			"value": "class",
			"default": "class",
			"tip": "",
			"placeholder": "",
			"options": {
				"class": "Per class: Charge shipping for each shipping class individually",
				"order": "Per order: Charge shipping for the most expensive shipping class"
			}
		}
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods/26"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods"
			}
		],
		"describes": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all shipping methods from a shipping zone

This API helps you to view all the shipping methods from a shipping zone.

```http
GET /wp-json/wc/v3/shipping/zones/<id>/methods
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/shipping/zones/5/methods \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'shipping/zones/5/methods' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones/5/methods')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones/5/methods").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones/5/methods").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"instance_id": 26,
		"title": "Flat rate",
		"order": 1,
		"enabled": true,
		"method_id": "flat_rate",
		"method_title": "Flat rate",
		"method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
		"settings": {
			"title": {
				"id": "title",
				"label": "Method title",
				"description": "This controls the title which the user sees during checkout.",
				"type": "text",
				"value": "Flat rate",
				"default": "Flat rate",
				"tip": "This controls the title which the user sees during checkout.",
				"placeholder": ""
			},
			"tax_status": {
				"id": "tax_status",
				"label": "Tax status",
				"description": "",
				"type": "select",
				"value": "taxable",
				"default": "taxable",
				"tip": "",
				"placeholder": "",
				"options": {
					"taxable": "Taxable",
					"none": "None"
				}
			},
			"cost": {
				"id": "cost",
				"label": "Cost",
				"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
				"type": "text",
				"value": "0",
				"default": "",
				"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
				"placeholder": ""
			},
			"class_costs": {
				"id": "class_costs",
				"label": "Shipping class costs",
				"description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
				"type": "title",
				"value": "",
				"default": "",
				"tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
				"placeholder": ""
			},
			"class_cost_92": {
				"id": "class_cost_92",
				"label": "\"Express\" shipping class cost",
				"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
				"type": "text",
				"value": "",
				"default": "",
				"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
				"placeholder": "N/A"
			},
			"class_cost_91": {
				"id": "class_cost_91",
				"label": "\"Priority\" shipping class cost",
				"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
				"type": "text",
				"value": "",
				"default": "",
				"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
				"placeholder": "N/A"
			},
			"no_class_cost": {
				"id": "no_class_cost",
				"label": "No shipping class cost",
				"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
				"type": "text",
				"value": "",
				"default": "",
				"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
				"placeholder": "N/A"
			},
			"type": {
				"id": "type",
				"label": "Calculation type",
				"description": "",
				"type": "select",
				"value": "class",
				"default": "class",
				"tip": "",
				"placeholder": "",
				"options": {
					"class": "Per class: Charge shipping for each shipping class individually",
					"order": "Per order: Charge shipping for the most expensive shipping class"
				}
			}
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods/26"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods"
				}
			],
			"describes": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
				}
			]
		}
	},
	{
		"instance_id": 27,
		"title": "Free shipping",
		"order": 2,
		"enabled": true,
		"method_id": "free_shipping",
		"method_title": "Free shipping",
		"method_description": "<p>Free shipping is a special method which can be triggered with coupons and minimum spends.</p>\n",
		"settings": {
			"title": {
				"id": "title",
				"label": "Title",
				"description": "This controls the title which the user sees during checkout.",
				"type": "text",
				"value": "Free shipping",
				"default": "Free shipping",
				"tip": "This controls the title which the user sees during checkout.",
				"placeholder": ""
			},
			"requires": {
				"id": "requires",
				"label": "Free shipping requires...",
				"description": "",
				"type": "select",
				"value": "",
				"default": "",
				"tip": "",
				"placeholder": "",
				"options": {
					"": "N/A",
					"coupon": "A valid free shipping coupon",
					"min_amount": "A minimum order amount",
					"either": "A minimum order amount OR a coupon",
					"both": "A minimum order amount AND a coupon"
				}
			},
			"min_amount": {
				"id": "min_amount",
				"label": "Minimum order amount",
				"description": "Users will need to spend this amount to get free shipping (if enabled above).",
				"type": "price",
				"value": "0",
				"default": "",
				"tip": "Users will need to spend this amount to get free shipping (if enabled above).",
				"placeholder": ""
			}
		},
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods/27"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods"
				}
			],
			"describes": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

## Update a shipping method of a shipping zone

This API lets you make changes to a shipping method of a shipping zone.

```http
PUT /wp-json/wc/v3/shipping/zones/<zone_id>/methods/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/shipping/zones/5/methods/26 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "settings": {
    "cost": "20.00"
  }
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	settings: {
		cost: '20.00',
	},
};

WooCommerce.put( 'shipping/zones/5/methods/26', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'settings' => [
        'cost' => '20.00'
    ]
];

print_r($woocommerce->put('shipping/zones/5/methods/26', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "settings": {
        "cost": "20.00"
    }
}

print(wcapi.put("shipping/zones/5/methods/26", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  settings: {
    "cost": "20.00"
  }
}

woocommerce.put("shipping/zones/5/methods/26", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"instance_id": 26,
	"title": "Flat rate",
	"order": 1,
	"enabled": true,
	"method_id": "flat_rate",
	"method_title": "Flat rate",
	"method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
	"settings": {
		"title": {
			"id": "title",
			"label": "Method title",
			"description": "This controls the title which the user sees during checkout.",
			"type": "text",
			"value": "Flat rate",
			"default": "Flat rate",
			"tip": "This controls the title which the user sees during checkout.",
			"placeholder": ""
		},
		"tax_status": {
			"id": "tax_status",
			"label": "Tax status",
			"description": "",
			"type": "select",
			"value": "taxable",
			"default": "taxable",
			"tip": "",
			"placeholder": "",
			"options": {
				"taxable": "Taxable",
				"none": "None"
			}
		},
		"cost": {
			"id": "cost",
			"label": "Cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "20.00",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": ""
		},
		"class_costs": {
			"id": "class_costs",
			"label": "Shipping class costs",
			"description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
			"type": "title",
			"value": "",
			"default": "",
			"tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
			"placeholder": ""
		},
		"class_cost_92": {
			"id": "class_cost_92",
			"label": "\"Express\" shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"class_cost_91": {
			"id": "class_cost_91",
			"label": "\"Priority\" shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"no_class_cost": {
			"id": "no_class_cost",
			"label": "No shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"type": {
			"id": "type",
			"label": "Calculation type",
			"description": "",
			"type": "select",
			"value": "class",
			"default": "class",
			"tip": "",
			"placeholder": "",
			"options": {
				"class": "Per class: Charge shipping for each shipping class individually",
				"order": "Per order: Charge shipping for the most expensive shipping class"
			}
		}
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods/26"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods"
			}
		],
		"describes": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a shipping method from a shipping zone

This API helps you delete a shipping method from a shipping zone.

```http
DELETE /wp-json/wc/v3/shipping/zones/<zone_id>/methods/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/shipping/zones/5/methods/26?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'shipping/zones/5/methods/26', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('shipping/zones/5/methods/26', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("shipping/zones/5/methods/26", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("shipping/zones/5/methods/26", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"instance_id": 26,
	"title": "Flat rate",
	"order": 1,
	"enabled": true,
	"method_id": "flat_rate",
	"method_title": "Flat rate",
	"method_description": "<p>Lets you charge a fixed rate for shipping.</p>\n",
	"settings": {
		"title": {
			"id": "title",
			"label": "Method title",
			"description": "This controls the title which the user sees during checkout.",
			"type": "text",
			"value": "Flat rate",
			"default": "Flat rate",
			"tip": "This controls the title which the user sees during checkout.",
			"placeholder": ""
		},
		"tax_status": {
			"id": "tax_status",
			"label": "Tax status",
			"description": "",
			"type": "select",
			"value": "taxable",
			"default": "taxable",
			"tip": "",
			"placeholder": "",
			"options": {
				"taxable": "Taxable",
				"none": "None"
			}
		},
		"cost": {
			"id": "cost",
			"label": "Cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "20.00",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": ""
		},
		"class_costs": {
			"id": "class_costs",
			"label": "Shipping class costs",
			"description": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
			"type": "title",
			"value": "",
			"default": "",
			"tip": "These costs can optionally be added based on the <a href=\"https://example.com/wp-admin/admin.php?page=wc-settings&tab=shipping&section=classes\">product shipping class</a>.",
			"placeholder": ""
		},
		"class_cost_92": {
			"id": "class_cost_92",
			"label": "\"Express\" shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"class_cost_91": {
			"id": "class_cost_91",
			"label": "\"Priority\" shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"no_class_cost": {
			"id": "no_class_cost",
			"label": "No shipping class cost",
			"description": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"type": "text",
			"value": "",
			"default": "",
			"tip": "Enter a cost (excl. tax) or sum, e.g. <code>10.00 * [qty]</code>.<br/><br/>Use <code>[qty]</code> for the number of items, <br/><code>[cost]</code> for the total cost of items, and <code>[fee percent=\"10\" min_fee=\"20\" max_fee=\"\"]</code> for percentage based fees.",
			"placeholder": "N/A"
		},
		"type": {
			"id": "type",
			"label": "Calculation type",
			"description": "",
			"type": "select",
			"value": "class",
			"default": "class",
			"tip": "",
			"placeholder": "",
			"options": {
				"class": "Per class: Charge shipping for each shipping class individually",
				"order": "Per order: Charge shipping for the most expensive shipping class"
			}
		}
	},
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods/26"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/methods"
			}
		],
		"describes": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## Shipping zones

*Source: apis/rest-api/v3/shipping-zones.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Shipping zones

The shipping zones API allows you to create, view, update, and delete individual shipping zones.

## Shipping zone properties

| Attribute | Type    | Description                                                                   |
| --------- | ------- | ----------------------------------------------------------------------------- |
| `id`      | integer | Unique identifier for the resource. `READ-ONLY` |
| `name`    | string  | Shipping zone name. `MANDATORY`                 |
| `order`   | integer | Shipping zone order.                                                          |

## Create a shipping zone

This API helps you to create a new shipping zone.

```http
POST /wp-json/wc/v3/shipping/zones
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/shipping/zones \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Brazil"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Brazil',
};

WooCommerce.post( 'shipping/zones', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Brazil'
];

print_r($woocommerce->post('shipping/zones', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Brazil"
}

print(wcapi.post("shipping/zones", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Brazil"
}

woocommerce.post("shipping/zones", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 5,
	"name": "Brazil",
	"order": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones"
			}
		],
		"describedby": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/locations"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a shipping zone

This API lets you retrieve and view a specific shipping zone by ID.

```http
GET /wp-json/wc/v3/shipping/zones/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/shipping/zones/5 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'shipping/zones/5' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones/5')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones/5").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones/5").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 5,
	"name": "Brazil",
	"order": 0,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones"
			}
		],
		"describedby": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/locations"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all shipping zones

This API helps you to view all the shipping zones.

```http
GET /wp-json/wc/v3/shipping/zones
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/shipping/zones \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'shipping/zones' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('shipping/zones')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("shipping/zones").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("shipping/zones").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 0,
		"name": "Rest of the World",
		"order": 0,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/0"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones"
				}
			],
			"describedby": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/0/locations"
				}
			]
		}
	},
	{
		"id": 5,
		"name": "Brazil",
		"order": 0,
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones"
				}
			],
			"describedby": [
				{
					"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/locations"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

## Update a shipping zone

This API lets you make changes to a shipping zone.

```http
PUT /wp-json/wc/v3/shipping/zones/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/shipping/zones/5 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "order": 1
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	order: 1,
};

WooCommerce.put( 'shipping/zones/5', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'order' => 1
];

print_r($woocommerce->put('shipping/zones/5', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "order": 1
}

print(wcapi.put("shipping/zones/5", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  order: 1
}

woocommerce.put("shipping/zones/5", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 5,
	"name": "Brazil",
	"order": 1,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones"
			}
		],
		"describedby": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/locations"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a shipping zone

This API helps you delete a shipping zone.

```http
DELETE /wp-json/wc/v3/shipping/zones/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/shipping/zones/5?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'shipping/zones/5', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('shipping/zones/5', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("shipping/zones/5", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("shipping/zones/5", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 5,
	"name": "Brazil",
	"order": 1,
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones"
			}
		],
		"describedby": [
			{
				"href": "https://example.com/wp-json/wc/v3/shipping/zones/5/locations"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |


---

## System status tools

*Source: apis/rest-api/v3/system-status-tools.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# System status tools

The system status tools API allows you to view and run tools from system status.

## System status tool properties

| Attribute     | Type    | Description                                                                                                         |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`          | string  | A unique identifier for the tool. `READ-ONLY`                                         |
| `name`        | string  | Tool name. `READ-ONLY`                                                                |
| `action`      | string  | What running the tool will do. `READ-ONLY`                                            |
| `description` | string  | Tool description. `READ-ONLY`                                                         |
| `success`     | boolean | Did the tool run successfully? `READ-ONLY` `WRITE-ONLY` |
| `message`     | string  | Tool return message. `READ-ONLY` `WRITE-ONLY`           |
| `confirm`     | boolean | Confirm execution of the tool. Default is `false`. `WRITE-ONLY`                       |

## Retrieve a tool from system status

This API lets you retrieve and view a specific tool from system status by ID.

```http
GET /wp-json/wc/v3/system_status/tools/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/system_status/tools/clear_transients \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'system_status/tools/clear_transients' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('system_status/tools/clear_transients')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("system_status/tools/clear_transients").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("system_status/tools/clear_transients").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": "clear_transients",
	"name": "WC transients",
	"action": "Clear transients",
	"description": "This tool will clear the product/shop transients cache.",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/system_status/tools/clear_transients"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/system_status/tools"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all tools from system status

This API helps you to view all tools from system status.

```http
GET /wp-json/wc/v3/system_status/tools
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/system_status/tools \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'system_status/tools' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('system_status/tools')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("system_status/tools").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("system_status/tools").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": "clear_transients",
		"name": "WC transients",
		"action": "Clear transients",
		"description": "This tool will clear the product/shop transients cache.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/clear_transients"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "clear_expired_transients",
		"name": "Expired transients",
		"action": "Clear expired transients",
		"description": "This tool will clear ALL expired transients from WordPress.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/clear_expired_transients"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "delete_orphaned_variations",
		"name": "Orphaned variations",
		"action": "Delete orphaned variations",
		"description": "This tool will delete all variations which have no parent.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/delete_orphaned_variations"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "clear_expired_download_permissions",
		"name": "Used-up download permissions",
		"action": "Clean up download permissions",
		"description": "This tool will delete expired download permissions and permissions with 0 remaining downloads.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/clear_expired_download_permissions"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "regenerate_product_lookup_tables",
		"name": "Product lookup tables",
		"action": "Regenerate",
		"description": "This tool will regenerate product lookup table data. This process may take a while.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/regenerate_product_lookup_tables"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "repair_coupons_lookup_table",
		"name": "Coupons lookup table",
		"action": "Repair",
		"description": "This tool will repair the coupons lookup table data with missing discount amounts. This process may take a while.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/repair_coupons_lookup_table"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "recount_terms",
		"name": "Term counts",
		"action": "Recount terms",
		"description": "This tool will recount product terms - useful when changing your settings in a way which hides products from the catalog.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/recount_terms"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "reset_roles",
		"name": "Capabilities",
		"action": "Reset capabilities",
		"description": "This tool will reset the admin, customer and shop_manager roles to default. Use this if your users cannot access all of the WooCommerce admin pages.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/reset_roles"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "clear_sessions",
		"name": "Customer sessions",
		"action": "Clear all sessions",
		"description": "<strong class=\"red\">Note:</strong> This tool will delete all customer session data from the database, including any current live carts.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/clear_sessions"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "clear_template_cache",
		"name": "Clear template cache",
		"action": "Clear",
		"description": "<strong class=\"red\">Note:</strong> This tool will empty the template cache.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/clear_template_cache"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "clear_system_status_theme_info_cache",
		"name": "Clear system status theme info cache",
		"action": "Clear",
		"description": "<strong class=\"red\">Note:</strong> This tool will empty the system status theme info cache.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/clear_system_status_theme_info_cache"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "install_pages",
		"name": "Install WooCommerce pages",
		"action": "Install pages",
		"description": "<strong class=\"red\">Note:</strong> This tool will install all the missing WooCommerce pages. Pages already defined and set up will not be replaced.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/install_pages"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "delete_taxes",
		"name": "Delete all WooCommerce tax rates",
		"action": "Delete ALL tax rates",
		"description": "<strong class=\"red\">Note:</strong> This option will delete ALL of your tax rates, use with caution.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/delete_taxes"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "regenerate_thumbnails",
		"name": "Regenerate shop thumbnails",
		"action": "Regenerate",
		"description": "This will regenerate all shop thumbnails to match your theme and/or image settings.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/regenerate_thumbnails"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "db_update_routine",
		"name": "Update database",
		"action": "Update database",
		"description": "<strong class=\"red\">Note:</strong> This tool will update your WooCommerce database to the latest version. Please ensure you make sufficient backups before proceeding.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/db_update_routine"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "recreate_order_address_fts_index",
		"name": "Re-create Order Address FTS index",
		"action": "Recreate index",
		"description": "This tool will recreate the full text search index for order addresses. If the index does not exist, it will try to create it.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/recreate_order_address_fts_index"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	},
	{
		"id": "verify_db_tables",
		"name": "Verify base database tables",
		"action": "Verify database",
		"description": "Verify if all base database tables are present.",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools/verify_db_tables"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/system_status/tools"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

## Run a tool from system status

This API lets you run a tool from system status.

```http
PUT /wp-json/wc/v3/system_status/tools/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/system_status/tools/clear_transients \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "confirm": true
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	confirm: true,
};

WooCommerce.put( 'system_status/tools/clear_transients', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'confirm' => true
];

print_r($woocommerce->put('system_status/tools/clear_transients', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "confirm": True
}

print(wcapi.put("system_status/tools/clear_transients", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  confirm: true
}

woocommerce.put("system_status/tools/clear_transients", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": "clear_transients",
	"name": "WC transients",
	"action": "Clear transients",
	"description": "This tool will clear the product/shop transients cache.",
	"success": true,
	"message": "Product transients cleared",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/system_status/tools/clear_transients"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/system_status/tools"
			}
		]
	}
}
```

  </TabItem>
</Tabs>


---

## System status

*Source: apis/rest-api/v3/system-status.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# System status

The system status API allows you to view all system status items.

## System status properties

| Attribute        | Type   | Description                                                                                                                                |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `environment`    | object | Environment. See [System status - Environment properties](#system-status---environment-properties) `READ-ONLY` |
| `database`       | object | Database. See [System status - Database properties](#system-status---database-properties) `READ-ONLY`          |
| `active_plugins` | array  | Active plugins. `READ-ONLY`                                                                                  |
| `theme`          | object | Theme. See [System status - Theme properties](#system-status---theme-properties) `READ-ONLY`                   |
| `settings`       | object | Settings. See [System status - Settings properties](#system-status---settings-properties) `READ-ONLY`          |
| `security`       | object | Security. See [System status - Security properties](#system-status---security-properties) `READ-ONLY`          |
| `pages`          | array  | WooCommerce pages. `READ-ONLY`                                                                               |

### System status - Environment properties

| Attribute                   | Type    | Description                                                                |
| --------------------------- | ------- | -------------------------------------------------------------------------- |
| `home_url`                  | string  | Home URL. `READ-ONLY`                        |
| `site_url`                  | string  | Site URL. `READ-ONLY`                        |
| `version`                   | string  | WooCommerce version. `READ-ONLY`             |
| `log_directory`             | string  | Log directory. `READ-ONLY`                   |
| `log_directory_writable`    | boolean | Is log directory writable? `READ-ONLY`       |
| `wp_version`                | string  | WordPress version. `READ-ONLY`               |
| `wp_multisite`              | boolean | Is WordPress multisite? `READ-ONLY`          |
| `wp_memory_limit`           | integer | WordPress memory limit. `READ-ONLY`          |
| `wp_debug_mode`             | boolean | Is WordPress debug mode active? `READ-ONLY`  |
| `wp_cron`                   | boolean | Are WordPress cron jobs enabled? `READ-ONLY` |
| `wp_environment_type`       | string  | WordPress environment type. `READ-ONLY`      |
| `language`                  | string  | WordPress language. `READ-ONLY`              |
| `server_info`               | string  | Server info. `READ-ONLY`                     |
| `php_version`               | string  | PHP version. `READ-ONLY`                     |
| `php_post_max_size`         | integer | PHP post max size. `READ-ONLY`               |
| `php_max_execution_time`    | integer | PHP max execution time. `READ-ONLY`          |
| `php_max_input_vars`        | integer | PHP max input vars. `READ-ONLY`              |
| `curl_version`              | string  | cURL version. `READ-ONLY`                    |
| `suhosin_installed`         | boolean | Is SUHOSIN installed? `READ-ONLY`            |
| `max_upload_size`           | integer | Max upload size. `READ-ONLY`                 |
| `mysql_version`             | string  | MySQL version. `READ-ONLY`                   |
| `default_timezone`          | string  | Default timezone. `READ-ONLY`                |
| `fsockopen_or_curl_enabled` | boolean | Is fsockopen/cURL enabled? `READ-ONLY`       |
| `soapclient_enabled`        | boolean | Is SoapClient class enabled? `READ-ONLY`     |
| `domdocument_enabled`       | boolean | Is DomDocument class enabled? `READ-ONLY`    |
| `gzip_enabled`              | boolean | Is GZip enabled? `READ-ONLY`                 |
| `mbstring_enabled`          | boolean | Is mbstring enabled? `READ-ONLY`             |
| `remote_post_successful`    | boolean | Remote POST successful? `READ-ONLY`          |
| `remote_post_response`      | string  | Remote POST response. `READ-ONLY`            |
| `remote_get_successful`     | boolean | Remote GET successful? `READ-ONLY`           |
| `remote_get_response`       | string  | Remote GET response. `READ-ONLY`             |

### System status - Database properties

| Attribute                | Type   | Description                                                       |
| ------------------------ | ------ | ----------------------------------------------------------------- |
| `wc_database_version`    | string | WC database version. `READ-ONLY`    |
| `database_prefix`        | string | Database prefix. `READ-ONLY`        |
| `maxmind_geoip_database` | string | MaxMind GeoIP database. `READ-ONLY` |
| `database_tables`        | array  | Database tables. `READ-ONLY`        |

### System status - Theme properties

| Attribute                 | Type    | Description                                                                           |
| ------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `name`                    | string  | Theme name. `READ-ONLY`                                 |
| `version`                 | string  | Theme version. `READ-ONLY`                              |
| `version_latest`          | string  | Latest version of theme. `READ-ONLY`                    |
| `author_url`              | string  | Theme author URL. `READ-ONLY`                           |
| `is_child_theme`          | boolean | Is this theme a child theme? `READ-ONLY`                |
| `has_woocommerce_support` | boolean | Does the theme declare WooCommerce support? `READ-ONLY` |
| `has_woocommerce_file`    | boolean | Does the theme have a woocommerce.php file? `READ-ONLY` |
| `has_outdated_templates`  | boolean | Does this theme have outdated templates? `READ-ONLY`    |
| `overrides`               | array   | Template overrides. `READ-ONLY`                         |
| `parent_name`             | string  | Parent theme name. `READ-ONLY`                          |
| `parent_version`          | string  | Parent theme version. `READ-ONLY`                       |
| `parent_author_url`       | string  | Parent theme author URL. `READ-ONLY`                    |

### System status - Settings properties

| Attribute             | Type    | Description                                                                          |
| --------------------- | ------- | ------------------------------------------------------------------------------------ |
| `api_enabled`         | boolean | REST API enabled? `READ-ONLY`                          |
| `force_ssl`           | boolean | SSL forced? `READ-ONLY`                                |
| `currency`            | string  | Currency. `READ-ONLY`                                  |
| `currency_symbol`     | string  | Currency symbol. `READ-ONLY`                           |
| `currency_position`   | string  | Currency position. `READ-ONLY`                         |
| `thousand_separator`  | string  | Thousand separator. `READ-ONLY`                        |
| `decimal_separator`   | string  | Decimal separator. `READ-ONLY`                         |
| `number_of_decimals`  | integer | Number of decimals. `READ-ONLY`                        |
| `geolocation_enabled` | boolean | Geolocation enabled? `READ-ONLY`                       |
| `taxonomies`          | array   | Taxonomy terms for product/order statuses. `READ-ONLY` |

### System status - Security properties

| Attribute           | Type    | Description                                                                       |
| ------------------- | ------- | --------------------------------------------------------------------------------- |
| `secure_connection` | boolean | Is the connection to your store secure? `READ-ONLY` |
| `hide_errors`       | boolean | Hide errors from visitors? `READ-ONLY`              |

## List all system status items

This API helps you to view all the system status items.

```http
GET /wp-json/wc/v3/system_status
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/system_status \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'system_status' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('system_status')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("system_status").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("system_status").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"environment": {
		"home_url": "http://example.com",
		"site_url": "http://example.com",
		"version": "3.0.0",
		"log_directory": "/var/www/woocommerce/wp-content/uploads/wc-logs/",
		"log_directory_writable": true,
		"wp_version": "4.7.3",
		"wp_multisite": false,
		"wp_memory_limit": 134217728,
		"wp_debug_mode": true,
		"wp_cron": true,
		"wp_environment_type": "production",
		"language": "en_US",
		"server_info": "Apache/2.4.18 (Ubuntu)",
		"php_version": "7.1.3-2+deb.sury.org~yakkety+1",
		"php_post_max_size": 8388608,
		"php_max_execution_time": 30,
		"php_max_input_vars": 1000,
		"curl_version": "7.50.1, OpenSSL/1.0.2g",
		"suhosin_installed": false,
		"max_upload_size": 2097152,
		"mysql_version": "5.7.17",
		"default_timezone": "UTC",
		"fsockopen_or_curl_enabled": true,
		"soapclient_enabled": true,
		"domdocument_enabled": true,
		"gzip_enabled": true,
		"mbstring_enabled": true,
		"remote_post_successful": true,
		"remote_post_response": "200",
		"remote_get_successful": true,
		"remote_get_response": "200"
	},
	"database": {
		"wc_database_version": "3.0.0",
		"database_prefix": "wp_",
		"maxmind_geoip_database": "/var/www/woocommerce/wp-content/uploads/GeoIP.dat",
		"database_tables": {
			"woocommerce_sessions": true,
			"woocommerce_api_keys": true,
			"woocommerce_attribute_taxonomies": true,
			"woocommerce_downloadable_product_permissions": true,
			"woocommerce_order_items": true,
			"woocommerce_order_itemmeta": true,
			"woocommerce_tax_rates": true,
			"woocommerce_tax_rate_locations": true,
			"woocommerce_shipping_zones": true,
			"woocommerce_shipping_zone_locations": true,
			"woocommerce_shipping_zone_methods": true,
			"woocommerce_payment_tokens": true,
			"woocommerce_payment_tokenmeta": true
		}
	},
	"active_plugins": [
		{
			"plugin": "woocommerce/woocommerce.php",
			"name": "WooCommerce",
			"version": "3.0.0-rc.1",
			"version_latest": "2.6.14",
			"url": "https://woocommerce.com/",
			"author_name": "Automattic",
			"author_url": "https://woocommerce.com",
			"network_activated": false
		}
	],
	"theme": {
		"name": "Twenty Sixteen",
		"version": "1.3",
		"version_latest": "1.3",
		"author_url": "https://wordpress.org/",
		"is_child_theme": false,
		"has_woocommerce_support": true,
		"has_woocommerce_file": false,
		"has_outdated_templates": false,
		"overrides": [],
		"parent_name": "",
		"parent_version": "",
		"parent_version_latest": "",
		"parent_author_url": ""
	},
	"settings": {
		"api_enabled": true,
		"force_ssl": false,
		"currency": "USD",
		"currency_symbol": "&#36;",
		"currency_position": "left",
		"thousand_separator": ",",
		"decimal_separator": ".",
		"number_of_decimals": 2,
		"geolocation_enabled": false,
		"taxonomies": {
			"external": "external",
			"grouped": "grouped",
			"simple": "simple",
			"variable": "variable"
		}
	},
	"security": {
		"secure_connection": true,
		"hide_errors": true
	},
	"pages": [
		{
			"page_name": "Shop base",
			"page_id": "4",
			"page_set": true,
			"page_exists": true,
			"page_visible": true,
			"shortcode": "",
			"shortcode_required": false,
			"shortcode_present": false
		},
		{
			"page_name": "Cart",
			"page_id": "5",
			"page_set": true,
			"page_exists": true,
			"page_visible": true,
			"shortcode": "[woocommerce_cart]",
			"shortcode_required": true,
			"shortcode_present": true
		},
		{
			"page_name": "Checkout",
			"page_id": "6",
			"page_set": true,
			"page_exists": true,
			"page_visible": true,
			"shortcode": "[woocommerce_checkout]",
			"shortcode_required": true,
			"shortcode_present": true
		},
		{
			"page_name": "My account",
			"page_id": "7",
			"page_set": true,
			"page_exists": true,
			"page_visible": true,
			"shortcode": "[woocommerce_my_account]",
			"shortcode_required": true,
			"shortcode_present": true
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Tax classes

*Source: apis/rest-api/v3/tax-classes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Tax classes

The tax classes API allows you to create, view, and delete individual tax classes.

## Tax class properties

| Attribute | Type   | Description                                                                   |
| --------- | ------ | ----------------------------------------------------------------------------- |
| `slug`    | string | Unique identifier for the resource. `READ-ONLY` |
| `name`    | string | Tax class name. `REQUIRED`                      |

## Create a tax class

This API helps you to create a new tax class.

```http
POST /wp-json/wc/v3/taxes/classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/taxes/classes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "Zero Rate"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Zero Rate',
};

WooCommerce.post( 'taxes/classes', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Zero Rate'
];

print_r($woocommerce->post('taxes/classes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Zero Rate"
}

print(wcapi.post("taxes/classes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Zero Rate"
}

woocommerce.post("taxes/classes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"slug": "zero-rate",
	"name": "Zero Rate",
	"_links": {
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes/classes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all tax classes

This API helps you to view all tax classes.

```http
GET /wp-json/wc/v3/taxes/classes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/taxes/classes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'taxes/classes' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes/classes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes/classes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes/classes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"slug": "standard",
		"name": "Standard Rate",
		"_links": {
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/classes"
				}
			]
		}
	},
	{
		"slug": "reduced-rate",
		"name": "Reduced Rate",
		"_links": {
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/classes"
				}
			]
		}
	},
	{
		"slug": "zero-rate",
		"name": "Zero Rate",
		"_links": {
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/classes"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

## Delete a tax class

This API helps you delete a tax class.

:::warning
This also will delete all tax rates from the selected class.
:::

```http
DELETE /wp-json/wc/v3/taxes/classes/<slug>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/taxes/classes/zero-rate?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'taxes/classes/zero-rate', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('taxes/classes/zero-rate', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("taxes/classes/zero-rate", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("taxes/classes/zero-rate", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"slug": "zero-rate",
	"name": "Zero Rate",
	"_links": {
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes/classes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                           |
| --------- | ------ | --------------------------------------------------------------------- |
| `force`   | string | Required to be `true`, since this resource does not support trashing. |


---

## Tax rates

*Source: apis/rest-api/v3/taxes.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Tax rates

The taxes API allows you to create, view, update, and delete individual tax rates, or a batch of tax rates.

## Tax rate properties

| Attribute   | Type     | Description                                                                                                                                                                     |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | integer  | Unique identifier for the resource. `READ-ONLY`                                                                                                   |
| `country`   | string   | Country ISO 3166 code. See [ISO 3166 Codes (Countries)](http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html) for more details                                              |
| `state`     | string   | State code.                                                                                                                                                                     |
| `postcode`  | string   | Postcode/ZIP, it doesn't support multiple values. Deprecated as of WooCommerce 5.3, `postcodes` should be used instead.                                                         |
| `city`      | string   | City name, it doesn't support multiple values. Deprecated as of WooCommerce 5.3, `postcodes` should be used instead.                                                            |
| `postcodes` | string[] | Postcodes/ZIPs. Introduced in WooCommerce 5.3.                                                                                                                                  |
| `cities`    | string[] | City names. Introduced in WooCommerce 5.3.                                                                                                                                      |
| `rate`      | string   | Tax rate.                                                                                                                                                                       |
| `name`      | string   | Tax rate name.                                                                                                                                                                  |
| `priority`  | integer  | Tax priority. Only 1 matching rate per priority will be used. To define multiple tax rates for a single area you need to specify a different priority per rate. Default is `1`. |
| `compound`  | boolean  | Whether or not this is a compound tax rate. Compound rates are applied on top of other tax rates. Default is `false`.                                                           |
| `shipping`  | boolean  | Whether or not this tax rate also gets applied to shipping. Default is `true`.                                                                                                  |
| `order`     | integer  | Indicates the order that will appear in queries.                                                                                                                                |
| `class`     | string   | Tax class. Default is `standard`.                                                                                                                                               |

## Create a tax rate

This API helps you to create a new tax rate.

```http
POST /wp-json/wc/v3/taxes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/taxes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "country": "US",
  "state": "AL",
  "cities": ["Alpine", "Brookside", "Cardiff"],
  "postcodes": ["35014", "35036", "35041"],
  "rate": "4",
  "name": "State Tax",
  "shipping": false
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	country: 'US',
	state: 'AL',
	cities: [ 'Alpine', 'Brookside', 'Cardiff' ],
	postcodes: [ '35014', '35036', '35041' ],
	rate: '4',
	name: 'State Tax',
	shipping: false,
};

WooCommerce.post( 'taxes', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'country' => 'US',
    'state' => 'AL',
    'cities' => ['Alpine', 'Brookside', 'Cardiff'],
    'postcodes' => ['35014', '35036', '35041'],
    'rate' => '4',
    'name' => 'State Tax',
    'shipping' => false
];

print_r($woocommerce->post('taxes', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "country": "US",
    "state": "AL",
    "cities": ["Alpine", "Brookside", "Cardiff"],
    "postcodes": ["35014", "35036", "35041"],
    "rate": "4",
    "name": "State Tax",
    "shipping": False
}

print(wcapi.post("taxes", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  country: "US",
  state: "AL",
  cities: ["Alpine", "Brookside", "Cardiff"],
  postcodes: ["35014", "35036", "35041"],
  rate: "4",
  name: "State Tax",
  shipping: false
}

woocommerce.post("taxes", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 72,
	"country": "US",
	"state": "AL",
	"postcode": "35041",
	"city": "Cardiff",
	"postcodes": [ "35014", "35036", "35041" ],
	"cities": [ "Alpine", "Brookside", "Cardiff" ],
	"rate": "4.0000",
	"name": "State Tax",
	"priority": 0,
	"compound": false,
	"shipping": false,
	"order": 1,
	"class": "standard",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes/72"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a tax rate

This API lets you retrieve and view a specific tax rate by ID.

```http
GET /wp-json/wc/v3/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/taxes/72 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'taxes/72' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes/72')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes/72").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes/72").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 72,
	"country": "US",
	"state": "AL",
	"postcode": "35041",
	"city": "Cardiff",
	"postcodes": [ "35014", "35036", "35041" ],
	"cities": [ "Alpine", "Brookside", "Cardiff" ],
	"rate": "4.0000",
	"name": "State Tax",
	"priority": 0,
	"compound": false,
	"shipping": false,
	"order": 1,
	"class": "standard",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes/72"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all tax rates

This API helps you to view all the tax rates.

```http
GET /wp-json/wc/v3/taxes
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/taxes \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'taxes' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('taxes')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("taxes").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("taxes").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 72,
		"country": "US",
		"state": "AL",
		"postcode": "35041",
		"city": "Cardiff",
		"postcodes": [ "35014", "35036", "35041" ],
		"cities": [ "Alpine", "Brookside", "Cardiff" ],
		"rate": "4.0000",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": false,
		"order": 1,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/72"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 73,
		"country": "US",
		"state": "AZ",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "5.6000",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": false,
		"order": 2,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/73"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 74,
		"country": "US",
		"state": "AR",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "6.5000",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": true,
		"order": 3,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/74"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 75,
		"country": "US",
		"state": "CA",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "7.5000",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": false,
		"order": 4,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/75"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 76,
		"country": "US",
		"state": "CO",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "2.9000",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": false,
		"order": 5,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/76"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 77,
		"country": "US",
		"state": "CT",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "6.3500",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": true,
		"order": 6,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/77"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 78,
		"country": "US",
		"state": "DC",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "5.7500",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": true,
		"order": 7,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/78"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 79,
		"country": "US",
		"state": "FL",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "6.0000",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": true,
		"order": 8,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/79"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 80,
		"country": "US",
		"state": "GA",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "4.0000",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": true,
		"order": 9,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/80"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	},
	{
		"id": 81,
		"country": "US",
		"state": "GU",
		"postcode": "",
		"city": "",
		"postcodes": [],
		"cities": [],
		"rate": "4.0000",
		"name": "State Tax",
		"priority": 0,
		"compound": false,
		"shipping": false,
		"order": 10,
		"class": "standard",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes/81"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/taxes"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter  | Type    | Description                                                                                               |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `context`  | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. |
| `page`     | integer | Current page of the collection.                                                                           |
| `per_page` | integer | Maximum number of items to be returned in result set.                                                     |
| `offset`   | integer | Offset the result set by a specific number of items.                                                      |
| `order`    | string  | Order sort attribute ascending or descending. Default is `asc`. Options: `asc` and `desc`.                |
| `orderby`  | string  | Sort collection by object attribute. Default is `order`. Options: `id`, `order` and `priority`.           |
| `class`    | string  | Retrieve only tax rates of this Tax class.                                                                |

## Update a tax rate

This API lets you make changes to a tax rate.

```http
PUT /wp-json/wc/v3/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/taxes/72 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "US Tax"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'US Tax',
};

WooCommerce.put( 'taxes/72', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'US Tax'
];

print_r($woocommerce->put('taxes/72', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "US Tax"
}

print(wcapi.put("taxes/72", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "US Tax"
}

woocommerce.put("taxes/72", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 72,
	"country": "US",
	"state": "AL",
	"postcode": "35041",
	"city": "Cardiff",
	"postcodes": [ "35014", "35036", "35041" ],
	"cities": [ "Alpine", "Brookside", "Cardiff" ],
	"rate": "4.0000",
	"name": "US Tax",
	"priority": 0,
	"compound": false,
	"shipping": false,
	"order": 1,
	"class": "standard",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes/72"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a tax rate

This API helps you delete a tax rate.

```http
DELETE /wp-json/wc/v3/taxes/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/taxes/72?force=true \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'taxes/72', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('taxes/72', ['force' => true])); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("taxes/72", params={"force": True}).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("taxes/72", force: true).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 72,
	"country": "US",
	"state": "AL",
	"postcode": "35041",
	"city": "Cardiff",
	"postcodes": [ "35014", "35036", "35041" ],
	"cities": [ "Alpine", "Brookside", "Cardiff" ],
	"rate": "4.0000",
	"name": "US Tax",
	"priority": 0,
	"compound": false,
	"shipping": false,
	"order": 1,
	"class": "standard",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes/72"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/taxes"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `force`   | string | Required to be `true`, as resource does not support trashing. |

## Batch update tax rates

This API helps you to batch create, update and delete multiple tax rates.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/taxes/batch
```

> Example batch creating all US taxes:

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/taxes/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "country": "US",
      "state": "AL",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 1
    },
    {
      "country": "US",
      "state": "AZ",
      "rate": "5.6000",
      "name": "State Tax",
      "shipping": false,
      "order": 2
    },
    {
      "country": "US",
      "state": "AR",
      "rate": "6.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 3
    },
    {
      "country": "US",
      "state": "CA",
      "rate": "7.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 4
    },
    {
      "country": "US",
      "state": "CO",
      "rate": "2.9000",
      "name": "State Tax",
      "shipping": false,
      "order": 5
    },
    {
      "country": "US",
      "state": "CT",
      "rate": "6.3500",
      "name": "State Tax",
      "shipping": true,
      "order": 6
    },
    {
      "country": "US",
      "state": "DC",
      "rate": "5.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 7
    },
    {
      "country": "US",
      "state": "FL",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 8
    },
    {
      "country": "US",
      "state": "GA",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 9
    },
    {
      "country": "US",
      "state": "GU",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 10
    },
    {
      "country": "US",
      "state": "HI",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 11
    },
    {
      "country": "US",
      "state": "ID",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 12
    },
    {
      "country": "US",
      "state": "IL",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": false,
      "order": 13
    },
    {
      "country": "US",
      "state": "IN",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 14
    },
    {
      "country": "US",
      "state": "IA",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 15
    },
    {
      "country": "US",
      "state": "KS",
      "rate": "6.1500",
      "name": "State Tax",
      "shipping": true,
      "order": 16
    },
    {
      "country": "US",
      "state": "KY",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 17
    },
    {
      "country": "US",
      "state": "LA",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 18
    },
    {
      "country": "US",
      "state": "ME",
      "rate": "5.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 19
    },
    {
      "country": "US",
      "state": "MD",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 20
    },
    {
      "country": "US",
      "state": "MA",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": false,
      "order": 21
    },
    {
      "country": "US",
      "state": "MI",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 22
    },
    {
      "country": "US",
      "state": "MN",
      "rate": "6.8750",
      "name": "State Tax",
      "shipping": true,
      "order": 23
    },
    {
      "country": "US",
      "state": "MS",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 24
    },
    {
      "country": "US",
      "state": "MO",
      "rate": "4.2250",
      "name": "State Tax",
      "shipping": false,
      "order": 25
    },
    {
      "country": "US",
      "state": "NE",
      "rate": "5.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 26
    },
    {
      "country": "US",
      "state": "NV",
      "rate": "6.8500",
      "name": "State Tax",
      "shipping": false,
      "order": 27
    },
    {
      "country": "US",
      "state": "NJ",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 28
    },
    {
      "country": "US",
      "state": "NM",
      "rate": "5.1250",
      "name": "State Tax",
      "shipping": true,
      "order": 29
    },
    {
      "country": "US",
      "state": "NY",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 30
    },
    {
      "country": "US",
      "state": "NC",
      "rate": "4.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 31
    },
    {
      "country": "US",
      "state": "ND",
      "rate": "5.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 32
    },
    {
      "country": "US",
      "state": "OH",
      "rate": "5.7500",
      "name": "State Tax",
      "shipping": true,
      "order": 33
    },
    {
      "country": "US",
      "state": "OK",
      "rate": "4.5000",
      "name": "State Tax",
      "shipping": false,
      "order": 34
    },
    {
      "country": "US",
      "state": "PA",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 35
    },
    {
      "country": "US",
      "state": "PR",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 36
    },
    {
      "country": "US",
      "state": "RI",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": false,
      "order": 37
    },
    {
      "country": "US",
      "state": "SC",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 38
    },
    {
      "country": "US",
      "state": "SD",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 39
    },
    {
      "country": "US",
      "state": "TN",
      "rate": "7.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 40
    },
    {
      "country": "US",
      "state": "TX",
      "rate": "6.2500",
      "name": "State Tax",
      "shipping": true,
      "order": 41
    },
    {
      "country": "US",
      "state": "UT",
      "rate": "5.9500",
      "name": "State Tax",
      "shipping": false,
      "order": 42
    },
    {
      "country": "US",
      "state": "VT",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 43
    },
    {
      "country": "US",
      "state": "VA",
      "rate": "5.3000",
      "name": "State Tax",
      "shipping": false,
      "order": 44
    },
    {
      "country": "US",
      "state": "WA",
      "rate": "6.5000",
      "name": "State Tax",
      "shipping": true,
      "order": 45
    },
    {
      "country": "US",
      "state": "WV",
      "rate": "6.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 46
    },
    {
      "country": "US",
      "state": "WI",
      "rate": "5.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 47
    },
    {
      "country": "US",
      "state": "WY",
      "rate": "4.0000",
      "name": "State Tax",
      "shipping": true,
      "order": 48
    }
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			country: 'US',
			state: 'AL',
			rate: '4.0000',
			name: 'State Tax',
			shipping: false,
			order: 1,
		},
		{
			country: 'US',
			state: 'AZ',
			rate: '5.6000',
			name: 'State Tax',
			shipping: false,
			order: 2,
		},
		{
			country: 'US',
			state: 'AR',
			rate: '6.5000',
			name: 'State Tax',
			shipping: true,
			order: 3,
		},
		{
			country: 'US',
			state: 'CA',
			rate: '7.5000',
			name: 'State Tax',
			shipping: false,
			order: 4,
		},
		{
			country: 'US',
			state: 'CO',
			rate: '2.9000',
			name: 'State Tax',
			shipping: false,
			order: 5,
		},
		{
			country: 'US',
			state: 'CT',
			rate: '6.3500',
			name: 'State Tax',
			shipping: true,
			order: 6,
		},
		{
			country: 'US',
			state: 'DC',
			rate: '5.7500',
			name: 'State Tax',
			shipping: true,
			order: 7,
		},
		{
			country: 'US',
			state: 'FL',
			rate: '6.0000',
			name: 'State Tax',
			shipping: true,
			order: 8,
		},
		{
			country: 'US',
			state: 'GA',
			rate: '4.0000',
			name: 'State Tax',
			shipping: true,
			order: 9,
		},
		{
			country: 'US',
			state: 'GU',
			rate: '4.0000',
			name: 'State Tax',
			shipping: false,
			order: 10,
		},
		{
			country: 'US',
			state: 'HI',
			rate: '4.0000',
			name: 'State Tax',
			shipping: true,
			order: 11,
		},
		{
			country: 'US',
			state: 'ID',
			rate: '6.0000',
			name: 'State Tax',
			shipping: false,
			order: 12,
		},
		{
			country: 'US',
			state: 'IL',
			rate: '6.2500',
			name: 'State Tax',
			shipping: false,
			order: 13,
		},
		{
			country: 'US',
			state: 'IN',
			rate: '7.0000',
			name: 'State Tax',
			shipping: false,
			order: 14,
		},
		{
			country: 'US',
			state: 'IA',
			rate: '6.0000',
			name: 'State Tax',
			shipping: false,
			order: 15,
		},
		{
			country: 'US',
			state: 'KS',
			rate: '6.1500',
			name: 'State Tax',
			shipping: true,
			order: 16,
		},
		{
			country: 'US',
			state: 'KY',
			rate: '6.0000',
			name: 'State Tax',
			shipping: true,
			order: 17,
		},
		{
			country: 'US',
			state: 'LA',
			rate: '4.0000',
			name: 'State Tax',
			shipping: false,
			order: 18,
		},
		{
			country: 'US',
			state: 'ME',
			rate: '5.5000',
			name: 'State Tax',
			shipping: false,
			order: 19,
		},
		{
			country: 'US',
			state: 'MD',
			rate: '6.0000',
			name: 'State Tax',
			shipping: false,
			order: 20,
		},
		{
			country: 'US',
			state: 'MA',
			rate: '6.2500',
			name: 'State Tax',
			shipping: false,
			order: 21,
		},
		{
			country: 'US',
			state: 'MI',
			rate: '6.0000',
			name: 'State Tax',
			shipping: true,
			order: 22,
		},
		{
			country: 'US',
			state: 'MN',
			rate: '6.8750',
			name: 'State Tax',
			shipping: true,
			order: 23,
		},
		{
			country: 'US',
			state: 'MS',
			rate: '7.0000',
			name: 'State Tax',
			shipping: true,
			order: 24,
		},
		{
			country: 'US',
			state: 'MO',
			rate: '4.2250',
			name: 'State Tax',
			shipping: false,
			order: 25,
		},
		{
			country: 'US',
			state: 'NE',
			rate: '5.5000',
			name: 'State Tax',
			shipping: true,
			order: 26,
		},
		{
			country: 'US',
			state: 'NV',
			rate: '6.8500',
			name: 'State Tax',
			shipping: false,
			order: 27,
		},
		{
			country: 'US',
			state: 'NJ',
			rate: '7.0000',
			name: 'State Tax',
			shipping: true,
			order: 28,
		},
		{
			country: 'US',
			state: 'NM',
			rate: '5.1250',
			name: 'State Tax',
			shipping: true,
			order: 29,
		},
		{
			country: 'US',
			state: 'NY',
			rate: '4.0000',
			name: 'State Tax',
			shipping: true,
			order: 30,
		},
		{
			country: 'US',
			state: 'NC',
			rate: '4.7500',
			name: 'State Tax',
			shipping: true,
			order: 31,
		},
		{
			country: 'US',
			state: 'ND',
			rate: '5.0000',
			name: 'State Tax',
			shipping: true,
			order: 32,
		},
		{
			country: 'US',
			state: 'OH',
			rate: '5.7500',
			name: 'State Tax',
			shipping: true,
			order: 33,
		},
		{
			country: 'US',
			state: 'OK',
			rate: '4.5000',
			name: 'State Tax',
			shipping: false,
			order: 34,
		},
		{
			country: 'US',
			state: 'PA',
			rate: '6.0000',
			name: 'State Tax',
			shipping: true,
			order: 35,
		},
		{
			country: 'US',
			state: 'PR',
			rate: '6.0000',
			name: 'State Tax',
			shipping: false,
			order: 36,
		},
		{
			country: 'US',
			state: 'RI',
			rate: '7.0000',
			name: 'State Tax',
			shipping: false,
			order: 37,
		},
		{
			country: 'US',
			state: 'SC',
			rate: '6.0000',
			name: 'State Tax',
			shipping: true,
			order: 38,
		},
		{
			country: 'US',
			state: 'SD',
			rate: '4.0000',
			name: 'State Tax',
			shipping: true,
			order: 39,
		},
		{
			country: 'US',
			state: 'TN',
			rate: '7.0000',
			name: 'State Tax',
			shipping: true,
			order: 40,
		},
		{
			country: 'US',
			state: 'TX',
			rate: '6.2500',
			name: 'State Tax',
			shipping: true,
			order: 41,
		},
		{
			country: 'US',
			state: 'UT',
			rate: '5.9500',
			name: 'State Tax',
			shipping: false,
			order: 42,
		},
		{
			country: 'US',
			state: 'VT',
			rate: '6.0000',
			name: 'State Tax',
			shipping: true,
			order: 43,
		},
		{
			country: 'US',
			state: 'VA',
			rate: '5.3000',
			name: 'State Tax',
			shipping: false,
			order: 44,
		},
		{
			country: 'US',
			state: 'WA',
			rate: '6.5000',
			name: 'State Tax',
			shipping: true,
			order: 45,
		},
		{
			country: 'US',
			state: 'WV',
			rate: '6.0000',
			name: 'State Tax',
			shipping: true,
			order: 46,
		},
		{
			country: 'US',
			state: 'WI',
			rate: '5.0000',
			name: 'State Tax',
			shipping: true,
			order: 47,
		},
		{
			country: 'US',
			state: 'WY',
			rate: '4.0000',
			name: 'State Tax',
			shipping: true,
			order: 48,
		},
	],
};

WooCommerce.post( 'taxes/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'country' => 'US',
            'state' => 'AL',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 1
        ],
        [
            'country' => 'US',
            'state' => 'AZ',
            'rate' => '5.6000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 2
        ],
        [
            'country' => 'US',
            'state' => 'AR',
            'rate' => '6.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 3
        ],
        [
            'country' => 'US',
            'state' => 'CA',
            'rate' => '7.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 4
        ],
        [
            'country' => 'US',
            'state' => 'CO',
            'rate' => '2.9000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 5
        ],
        [
            'country' => 'US',
            'state' => 'CT',
            'rate' => '6.3500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 6
        ],
        [
            'country' => 'US',
            'state' => 'DC',
            'rate' => '5.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 7
        ],
        [
            'country' => 'US',
            'state' => 'FL',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 8
        ],
        [
            'country' => 'US',
            'state' => 'GA',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 9
        ],
        [
            'country' => 'US',
            'state' => 'GU',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 10
        ],
        [
            'country' => 'US',
            'state' => 'HI',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 11
        ],
        [
            'country' => 'US',
            'state' => 'ID',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 12
        ],
        [
            'country' => 'US',
            'state' => 'IL',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 13
        ],
        [
            'country' => 'US',
            'state' => 'IN',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 14
        ],
        [
            'country' => 'US',
            'state' => 'IA',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 15
        ],
        [
            'country' => 'US',
            'state' => 'KS',
            'rate' => '6.1500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 16
        ],
        [
            'country' => 'US',
            'state' => 'KY',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 17
        ],
        [
            'country' => 'US',
            'state' => 'LA',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 18
        ],
        [
            'country' => 'US',
            'state' => 'ME',
            'rate' => '5.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 19
        ],
        [
            'country' => 'US',
            'state' => 'MD',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 20
        ],
        [
            'country' => 'US',
            'state' => 'MA',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 21
        ],
        [
            'country' => 'US',
            'state' => 'MI',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 22
        ],
        [
            'country' => 'US',
            'state' => 'MN',
            'rate' => '6.8750',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 23
        ],
        [
            'country' => 'US',
            'state' => 'MS',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 24
        ],
        [
            'country' => 'US',
            'state' => 'MO',
            'rate' => '4.2250',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 25
        ],
        [
            'country' => 'US',
            'state' => 'NE',
            'rate' => '5.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 26
        ],
        [
            'country' => 'US',
            'state' => 'NV',
            'rate' => '6.8500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 27
        ],
        [
            'country' => 'US',
            'state' => 'NJ',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 28
        ],
        [
            'country' => 'US',
            'state' => 'NM',
            'rate' => '5.1250',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 29
        ],
        [
            'country' => 'US',
            'state' => 'NY',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 30
        ],
        [
            'country' => 'US',
            'state' => 'NC',
            'rate' => '4.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 31
        ],
        [
            'country' => 'US',
            'state' => 'ND',
            'rate' => '5.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 32
        ],
        [
            'country' => 'US',
            'state' => 'OH',
            'rate' => '5.7500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 33
        ],
        [
            'country' => 'US',
            'state' => 'OK',
            'rate' => '4.5000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 34
        ],
        [
            'country' => 'US',
            'state' => 'PA',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 35
        ],
        [
            'country' => 'US',
            'state' => 'PR',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 36
        ],
        [
            'country' => 'US',
            'state' => 'RI',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 37
        ],
        [
            'country' => 'US',
            'state' => 'SC',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 38
        ],
        [
            'country' => 'US',
            'state' => 'SD',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 39
        ],
        [
            'country' => 'US',
            'state' => 'TN',
            'rate' => '7.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 40
        ],
        [
            'country' => 'US',
            'state' => 'TX',
            'rate' => '6.2500',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 41
        ],
        [
            'country' => 'US',
            'state' => 'UT',
            'rate' => '5.9500',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 42
        ],
        [
            'country' => 'US',
            'state' => 'VT',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 43
        ],
        [
            'country' => 'US',
            'state' => 'VA',
            'rate' => '5.3000',
            'name' => 'State Tax',
            'shipping' => false,
            'order' => 44
        ],
        [
            'country' => 'US',
            'state' => 'WA',
            'rate' => '6.5000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 45
        ],
        [
            'country' => 'US',
            'state' => 'WV',
            'rate' => '6.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 46
        ],
        [
            'country' => 'US',
            'state' => 'WI',
            'rate' => '5.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 47
        ],
        [
            'country' => 'US',
            'state' => 'WY',
            'rate' => '4.0000',
            'name' => 'State Tax',
            'shipping' => true,
            'order' => 48
        ]
    ]
];

print_r($woocommerce->post('taxes/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "country": "US",
            "state": "AL",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 1
        },
        {
            "country": "US",
            "state": "AZ",
            "rate": "5.6000",
            "name": "State Tax",
            "shipping": False,
            "order": 2
        },
        {
            "country": "US",
            "state": "AR",
            "rate": "6.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 3
        },
        {
            "country": "US",
            "state": "CA",
            "rate": "7.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 4
        },
        {
            "country": "US",
            "state": "CO",
            "rate": "2.9000",
            "name": "State Tax",
            "shipping": False,
            "order": 5
        },
        {
            "country": "US",
            "state": "CT",
            "rate": "6.3500",
            "name": "State Tax",
            "shipping": True,
            "order": 6
        },
        {
            "country": "US",
            "state": "DC",
            "rate": "5.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 7
        },
        {
            "country": "US",
            "state": "FL",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 8
        },
        {
            "country": "US",
            "state": "GA",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 9
        },
        {
            "country": "US",
            "state": "GU",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 10
        },
        {
            "country": "US",
            "state": "HI",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 11
        },
        {
            "country": "US",
            "state": "ID",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 12
        },
        {
            "country": "US",
            "state": "IL",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": False,
            "order": 13
        },
        {
            "country": "US",
            "state": "IN",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 14
        },
        {
            "country": "US",
            "state": "IA",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 15
        },
        {
            "country": "US",
            "state": "KS",
            "rate": "6.1500",
            "name": "State Tax",
            "shipping": True,
            "order": 16
        },
        {
            "country": "US",
            "state": "KY",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 17
        },
        {
            "country": "US",
            "state": "LA",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 18
        },
        {
            "country": "US",
            "state": "ME",
            "rate": "5.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 19
        },
        {
            "country": "US",
            "state": "MD",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 20
        },
        {
            "country": "US",
            "state": "MA",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": False,
            "order": 21
        },
        {
            "country": "US",
            "state": "MI",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 22
        },
        {
            "country": "US",
            "state": "MN",
            "rate": "6.8750",
            "name": "State Tax",
            "shipping": True,
            "order": 23
        },
        {
            "country": "US",
            "state": "MS",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 24
        },
        {
            "country": "US",
            "state": "MO",
            "rate": "4.2250",
            "name": "State Tax",
            "shipping": False,
            "order": 25
        },
        {
            "country": "US",
            "state": "NE",
            "rate": "5.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 26
        },
        {
            "country": "US",
            "state": "NV",
            "rate": "6.8500",
            "name": "State Tax",
            "shipping": False,
            "order": 27
        },
        {
            "country": "US",
            "state": "NJ",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 28
        },
        {
            "country": "US",
            "state": "NM",
            "rate": "5.1250",
            "name": "State Tax",
            "shipping": True,
            "order": 29
        },
        {
            "country": "US",
            "state": "NY",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 30
        },
        {
            "country": "US",
            "state": "NC",
            "rate": "4.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 31
        },
        {
            "country": "US",
            "state": "ND",
            "rate": "5.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 32
        },
        {
            "country": "US",
            "state": "OH",
            "rate": "5.7500",
            "name": "State Tax",
            "shipping": True,
            "order": 33
        },
        {
            "country": "US",
            "state": "OK",
            "rate": "4.5000",
            "name": "State Tax",
            "shipping": False,
            "order": 34
        },
        {
            "country": "US",
            "state": "PA",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 35
        },
        {
            "country": "US",
            "state": "PR",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 36
        },
        {
            "country": "US",
            "state": "RI",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": False,
            "order": 37
        },
        {
            "country": "US",
            "state": "SC",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 38
        },
        {
            "country": "US",
            "state": "SD",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 39
        },
        {
            "country": "US",
            "state": "TN",
            "rate": "7.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 40
        },
        {
            "country": "US",
            "state": "TX",
            "rate": "6.2500",
            "name": "State Tax",
            "shipping": True,
            "order": 41
        },
        {
            "country": "US",
            "state": "UT",
            "rate": "5.9500",
            "name": "State Tax",
            "shipping": False,
            "order": 42
        },
        {
            "country": "US",
            "state": "VT",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 43
        },
        {
            "country": "US",
            "state": "VA",
            "rate": "5.3000",
            "name": "State Tax",
            "shipping": False,
            "order": 44
        },
        {
            "country": "US",
            "state": "WA",
            "rate": "6.5000",
            "name": "State Tax",
            "shipping": True,
            "order": 45
        },
        {
            "country": "US",
            "state": "WV",
            "rate": "6.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 46
        },
        {
            "country": "US",
            "state": "WI",
            "rate": "5.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 47
        },
        {
            "country": "US",
            "state": "WY",
            "rate": "4.0000",
            "name": "State Tax",
            "shipping": True,
            "order": 48
        }
    ]
}

print(wcapi.post("taxes/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      country: "US",
      state: "AL",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 1
    },
    {
      country: "US",
      state: "AZ",
      rate: "5.6000",
      name: "State Tax",
      shipping: false,
      order: 2
    },
    {
      country: "US",
      state: "AR",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 3
    },
    {
      country: "US",
      state: "CA",
      rate: "7.5000",
      name: "State Tax",
      shipping: false,
      order: 4
    },
    {
      country: "US",
      state: "CO",
      rate: "2.9000",
      name: "State Tax",
      shipping: false,
      order: 5
    },
    {
      country: "US",
      state: "CT",
      rate: "6.3500",
      name: "State Tax",
      shipping: true,
      order: 6
    },
    {
      country: "US",
      state: "DC",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 7
    },
    {
      country: "US",
      state: "FL",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 8
    },
    {
      country: "US",
      state: "GA",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 9
    },
    {
      country: "US",
      state: "GU",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 10
    },
    {
      country: "US",
      state: "HI",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 11
    },
    {
      country: "US",
      state: "ID",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 12
    },
    {
      country: "US",
      state: "IL",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 13
    },
    {
      country: "US",
      state: "IN",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 14
    },
    {
      country: "US",
      state: "IA",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 15
    },
    {
      country: "US",
      state: "KS",
      rate: "6.1500",
      name: "State Tax",
      shipping: true,
      order: 16
    },
    {
      country: "US",
      state: "KY",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 17
    },
    {
      country: "US",
      state: "LA",
      rate: "4.0000",
      name: "State Tax",
      shipping: false,
      order: 18
    },
    {
      country: "US",
      state: "ME",
      rate: "5.5000",
      name: "State Tax",
      shipping: false,
      order: 19
    },
    {
      country: "US",
      state: "MD",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 20
    },
    {
      country: "US",
      state: "MA",
      rate: "6.2500",
      name: "State Tax",
      shipping: false,
      order: 21
    },
    {
      country: "US",
      state: "MI",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 22
    },
    {
      country: "US",
      state: "MN",
      rate: "6.8750",
      name: "State Tax",
      shipping: true,
      order: 23
    },
    {
      country: "US",
      state: "MS",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 24
    },
    {
      country: "US",
      state: "MO",
      rate: "4.2250",
      name: "State Tax",
      shipping: false,
      order: 25
    },
    {
      country: "US",
      state: "NE",
      rate: "5.5000",
      name: "State Tax",
      shipping: true,
      order: 26
    },
    {
      country: "US",
      state: "NV",
      rate: "6.8500",
      name: "State Tax",
      shipping: false,
      order: 27
    },
    {
      country: "US",
      state: "NJ",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 28
    },
    {
      country: "US",
      state: "NM",
      rate: "5.1250",
      name: "State Tax",
      shipping: true,
      order: 29
    },
    {
      country: "US",
      state: "NY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 30
    },
    {
      country: "US",
      state: "NC",
      rate: "4.7500",
      name: "State Tax",
      shipping: true,
      order: 31
    },
    {
      country: "US",
      state: "ND",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 32
    },
    {
      country: "US",
      state: "OH",
      rate: "5.7500",
      name: "State Tax",
      shipping: true,
      order: 33
    },
    {
      country: "US",
      state: "OK",
      rate: "4.5000",
      name: "State Tax",
      shipping: false,
      order: 34
    },
    {
      country: "US",
      state: "PA",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 35
    },
    {
      country: "US",
      state: "PR",
      rate: "6.0000",
      name: "State Tax",
      shipping: false,
      order: 36
    },
    {
      country: "US",
      state: "RI",
      rate: "7.0000",
      name: "State Tax",
      shipping: false,
      order: 37
    },
    {
      country: "US",
      state: "SC",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 38
    },
    {
      country: "US",
      state: "SD",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 39
    },
    {
      country: "US",
      state: "TN",
      rate: "7.0000",
      name: "State Tax",
      shipping: true,
      order: 40
    },
    {
      country: "US",
      state: "TX",
      rate: "6.2500",
      name: "State Tax",
      shipping: true,
      order: 41
    },
    {
      country: "US",
      state: "UT",
      rate: "5.9500",
      name: "State Tax",
      shipping: false,
      order: 42
    },
    {
      country: "US",
      state: "VT",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 43
    },
    {
      country: "US",
      state: "VA",
      rate: "5.3000",
      name: "State Tax",
      shipping: false,
      order: 44
    },
    {
      country: "US",
      state: "WA",
      rate: "6.5000",
      name: "State Tax",
      shipping: true,
      order: 45
    },
    {
      country: "US",
      state: "WV",
      rate: "6.0000",
      name: "State Tax",
      shipping: true,
      order: 46
    },
    {
      country: "US",
      state: "WI",
      rate: "5.0000",
      name: "State Tax",
      shipping: true,
      order: 47
    },
    {
      country: "US",
      state: "WY",
      rate: "4.0000",
      name: "State Tax",
      shipping: true,
      order: 48
    }
  ]
}

woocommerce.post("taxes/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 72,
			"country": "US",
			"state": "AL",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 1,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/72"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 73,
			"country": "US",
			"state": "AZ",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.6000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 2,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/73"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 74,
			"country": "US",
			"state": "AR",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.5000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 3,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/74"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 75,
			"country": "US",
			"state": "CA",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "7.5000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 4,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/75"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 76,
			"country": "US",
			"state": "CO",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "2.9000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 5,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/76"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 77,
			"country": "US",
			"state": "CT",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.3500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 6,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/77"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 78,
			"country": "US",
			"state": "DC",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.7500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 7,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/78"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 79,
			"country": "US",
			"state": "FL",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 8,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/79"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 80,
			"country": "US",
			"state": "GA",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 9,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/80"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 81,
			"country": "US",
			"state": "GU",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 10,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/81"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 82,
			"country": "US",
			"state": "HI",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 11,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/82"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 83,
			"country": "US",
			"state": "ID",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 12,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/83"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 84,
			"country": "US",
			"state": "IL",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.2500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 13,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/84"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 85,
			"country": "US",
			"state": "IN",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "7.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 14,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/85"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 86,
			"country": "US",
			"state": "IA",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 15,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/86"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 87,
			"country": "US",
			"state": "KS",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.1500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 16,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/87"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 88,
			"country": "US",
			"state": "KY",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 17,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/88"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 89,
			"country": "US",
			"state": "LA",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 18,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/89"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 90,
			"country": "US",
			"state": "ME",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.5000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 19,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/90"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 91,
			"country": "US",
			"state": "MD",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 20,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/91"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 92,
			"country": "US",
			"state": "MA",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.2500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 21,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/92"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 93,
			"country": "US",
			"state": "MI",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 22,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/93"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 94,
			"country": "US",
			"state": "MN",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.8750",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 23,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/94"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 95,
			"country": "US",
			"state": "MS",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "7.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 24,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/95"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 96,
			"country": "US",
			"state": "MO",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.2250",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 25,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/96"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 97,
			"country": "US",
			"state": "NE",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.5000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 26,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/97"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 98,
			"country": "US",
			"state": "NV",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.8500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 27,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/98"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 99,
			"country": "US",
			"state": "NJ",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "7.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 28,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/99"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 100,
			"country": "US",
			"state": "NM",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.1250",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 29,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/100"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 101,
			"country": "US",
			"state": "NY",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 30,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/101"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 102,
			"country": "US",
			"state": "NC",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.7500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 31,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/102"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 103,
			"country": "US",
			"state": "ND",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 32,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/103"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 104,
			"country": "US",
			"state": "OH",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.7500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 33,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/104"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 105,
			"country": "US",
			"state": "OK",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.5000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 34,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/105"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 106,
			"country": "US",
			"state": "PA",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 35,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/106"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 107,
			"country": "US",
			"state": "PR",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 36,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/107"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 108,
			"country": "US",
			"state": "RI",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "7.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 37,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/108"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 109,
			"country": "US",
			"state": "SC",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 38,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/109"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 110,
			"country": "US",
			"state": "SD",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 39,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/110"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 111,
			"country": "US",
			"state": "TN",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "7.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 40,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/111"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 112,
			"country": "US",
			"state": "TX",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.2500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 41,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/112"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 113,
			"country": "US",
			"state": "UT",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.9500",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 42,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/113"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 114,
			"country": "US",
			"state": "VT",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 43,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/114"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 115,
			"country": "US",
			"state": "VA",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.3000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": false,
			"order": 44,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/115"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 116,
			"country": "US",
			"state": "WA",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.5000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 45,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/116"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 117,
			"country": "US",
			"state": "WV",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "6.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 46,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/117"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 118,
			"country": "US",
			"state": "WI",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "5.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 47,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/118"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		},
		{
			"id": 119,
			"country": "US",
			"state": "WY",
			"postcode": "",
			"city": "",
			"postcodes": [],
			"cities": [],
			"rate": "4.0000",
			"name": "State Tax",
			"priority": 0,
			"compound": false,
			"shipping": true,
			"order": 48,
			"class": "standard",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes/119"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/taxes"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## Webhooks

*Source: apis/rest-api/v3/webhooks.mdx*

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Webhooks

The webhooks API allows you to create, view, update, and delete individual, or a batch, of webhooks.

Webhooks can be managed via the WooCommerce settings screen or by using the REST API endpoints. The `WC_Webhook` class manages all data storage and retrieval of the webhook custom post type, as well as enqueuing webhook actions and processing/delivering/logging webhooks. On `woocommerce_init`, active webhooks are loaded.

Each webhook has:

-   `status`: active (delivers payload), paused (delivery paused by admin), disabled (delivery paused by failure).
-   `topic`: determines which resource events the webhook is triggered for.
-   `delivery URL`: URL where the payload is delivered, must be HTTP or HTTPS.
-   `secret`: an optional secret key that is used to generate a HMAC-SHA256 hash of the request body so the receiver can verify authenticity of the webhook.
-   `hooks`: an array of hook names that are added and bound to the webhook for processing.

### Topics

The topic is a combination resource (e.g. order) and event (e.g. created) and maps to one or more hook names (e.g. `woocommerce_checkout_order_processed`). Webhooks can be created using the topic name and the appropriate hooks are automatically added.

Core topics are:

-   Coupons: `coupon.created`, `coupon.updated` and `coupon.deleted`.
-   Customers: `customer.created`, `customer.updated` and `customer.deleted`.
-   Orders: `order.created`, `order.updated` and `order.deleted`.
-   Products: `product.created`, `product.updated` and `product.deleted`.

Custom topics can also be used which map to a single hook name, for example you could add a webhook with topic `action.woocommerce_add_to_cart` that is triggered on that event. Custom topics pass the first hook argument to the payload, so in this example the `cart_item_key` would be included in the payload.

### Delivery/payload

Delivery is performed using `wp_remote_post()` (HTTP POST) and processed in the background by default using wp-cron. A few custom headers are added to the request to help the receiver process the webhook:

-   `X-WC-Webhook-Source`: `http://example.com/`.
-   `X-WC-Webhook-Topic` - e.g. `order.updated`.
-   `X-WC-Webhook-Resource` - e.g. `order`.
-   `X-WC-Webhook-Event` - e.g. `updated`.
-   `X-WC-Webhook-Signature` - a base64 encoded HMAC-SHA256 hash of the payload.
-   `X-WC-Webhook-ID` - webhook's post ID.
-   `X-WC-Webhook-Delivery-ID` - delivery log ID (a comment).

The payload is JSON encoded and for API resources (coupons, customers, orders, products), the response is exactly the same as if requested via the REST API.

### Logging

Requests/responses are logged using the WooCommerce logging system. Each delivery log includes:

-   Request duration.
-   Request URL, method, headers, and body.
-   Response Code, message, headers, and body.

After 5 consecutive failed deliveries (as defined by a non HTTP 2xx response code), the webhook is disabled and must be edited via the REST API to re-enable.

Delivery logs can be accessed in "WooCommerce" > "Status" > "Logs".

### Visual interface

You can find the Webhooks interface going to "WooCommerce" > "Settings" > "Advanced" > "Webhooks", see our [Visual Webhooks docs](https://docs.woocommerce.com/document/webhooks/) for more details.

## Webhook properties

| Attribute           | Type      | Description                                                                                                                                                 |
| ------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `id`                | integer   | Unique identifier for the resource. `READ-ONLY`                                                                               |
| `name`              | string    | A friendly name for the webhook.                                                                                                                            |
| `status`            | string    | Webhook status. Options: `active`, `paused` and `disabled`. Default is `active`.                                                                            |
| `topic`             | string    | Webhook topic. `MANDATORY`                                                                                                    |
| `resource`          | string    | Webhook resource. `READ-ONLY`                                                                                                 |
| `event`             | string    | Webhook event. `READ-ONLY`                                                                                                    |
| `hooks`             | array     | WooCommerce action names associated with the webhook. `READ-ONLY`                                                             |
| `delivery_url`      | string    | The URL where the webhook payload is delivered. `READ-ONLY` `MANDATORY`                         |
| `secret`            | string    | Secret key used to generate a hash of the delivered webhook and provided in the request headers. This will default is a MD5 hash from the current user's ID | username if not provided. `WRITE-ONLY` `MANDATORY` |
| `date_created`      | date-time | The date the webhook was created, in the site's timezone. `READ-ONLY`                                                         |
| `date_created_gmt`  | date-time | The date the webhook was created, as GMT. `READ-ONLY`                                                                         |
| `date_modified`     | date-time | The date the webhook was last modified, in the site's timezone. `READ-ONLY`                                                   |
| `date_modified_gmt` | date-time | The date the webhook was last modified, as GMT. `READ-ONLY`                                                                   |

## Create a webhook

This API helps you to create a new webhook.

```http
POST /wp-json/wc/v3/webhooks
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/webhooks \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "name": "Order updated",
  "topic": "order.updated",
  "delivery_url": "http://requestb.in/1g0sxmo1"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	name: 'Order updated',
	topic: 'order.updated',
	delivery_url: 'http://requestb.in/1g0sxmo1',
};

WooCommerce.post( 'webhooks', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'name' => 'Order updated',
    'topic' => 'order.updated',
    'delivery_url' => 'http://requestb.in/1g0sxmo1'
];

print_r($woocommerce->post('webhooks', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "name": "Order updated",
    "topic": "order.updated",
    "delivery_url": "http://requestb.in/1g0sxmo1"
}

print(wcapi.post("webhooks", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  name: "Order updated",
  topic: "order.updated",
  delivery_url: "http://requestb.in/1g0sxmo1"
}

woocommerce.post("webhooks", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 142,
	"name": "Order updated",
	"status": "active",
	"topic": "order.updated",
	"resource": "order",
	"event": "updated",
	"hooks": [
		"woocommerce_process_shop_order_meta",
		"woocommerce_api_edit_order",
		"woocommerce_order_edit_status",
		"woocommerce_order_status_changed"
	],
	"delivery_url": "http://requestb.in/1g0sxmo1",
	"date_created": "2016-05-15T23:17:52",
	"date_created_gmt": "2016-05-15T20:17:52",
	"date_modified": "2016-05-15T23:17:52",
	"date_modified_gmt": "2016-05-15T20:17:52",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/webhooks/142"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/webhooks"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Retrieve a webhook

This API lets you retrieve and view a specific webhook.

```http
GET /wp-json/wc/v3/webhooks/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/webhooks/142 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'webhooks/142' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks/142')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks/142").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks/142").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 142,
	"name": "Order updated",
	"status": "active",
	"topic": "order.updated",
	"resource": "order",
	"event": "updated",
	"hooks": [
		"woocommerce_process_shop_order_meta",
		"woocommerce_api_edit_order",
		"woocommerce_order_edit_status",
		"woocommerce_order_status_changed"
	],
	"delivery_url": "http://requestb.in/1g0sxmo1",
	"date_created": "2016-05-15T23:17:52",
	"date_created_gmt": "2016-05-15T20:17:52",
	"date_modified": "2016-05-15T23:17:52",
	"date_modified_gmt": "2016-05-15T20:17:52",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/webhooks/142"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/webhooks"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## List all webhooks

This API helps you to view all the webhooks.

```http
GET /wp-json/wc/v3/webhooks
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl https://example.com/wp-json/wc/v3/webhooks \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.get( 'webhooks' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->get('webhooks')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.get("webhooks").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.get("webhooks").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
[
	{
		"id": 143,
		"name": "Customer created",
		"status": "active",
		"topic": "customer.created",
		"resource": "customer",
		"event": "created",
		"hooks": [
			"user_register",
			"woocommerce_created_customer",
			"woocommerce_api_create_customer"
		],
		"delivery_url": "http://requestb.in/1g0sxmo1",
		"date_created": "2016-05-15T23:17:52",
		"date_created_gmt": "2016-05-15T20:17:52",
		"date_modified": "2016-05-15T23:17:52",
		"date_modified_gmt": "2016-05-15T20:17:52",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/webhooks/143"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/webhooks"
				}
			]
		}
	},
	{
		"id": 142,
		"name": "Order updated",
		"status": "active",
		"topic": "order.updated",
		"resource": "order",
		"event": "updated",
		"hooks": [
			"woocommerce_process_shop_order_meta",
			"woocommerce_api_edit_order",
			"woocommerce_order_edit_status",
			"woocommerce_order_status_changed"
		],
		"delivery_url": "http://requestb.in/1g0sxmo1",
		"date_created": "2016-05-15T23:17:52",
		"date_created_gmt": "2016-05-15T20:17:52",
		"date_modified": "2016-05-15T23:17:52",
		"date_modified_gmt": "2016-05-15T20:17:52",
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/webhooks/142"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/webhooks"
				}
			]
		}
	}
]
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter       | Type    | Description                                                                                                                   |
| --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `context`       | string  | Scope under which the request is made; determines fields present in response. Options: `view` and `edit`. Default is `view`.  |
| `page`          | integer | Current page of the collection. Default is `1`.                                                                               |
| `per_page`      | integer | Maximum number of items to be returned in result set. Default is `10`.                                                        |
| `search`        | string  | Limit results to those matching a string.                                                                                     |
| `after`         | string  | Limit response to resources published after a given ISO8601 compliant date.                                                   |
| `before`        | string  | Limit response to resources published before a given ISO8601 compliant date.                                                  |
| `dates_are_gmt` | boolean | Whether to interpret dates as GMT dates when limiting response by published date.                                             |
| `exclude`       | array   | Ensure result set excludes specific IDs.                                                                                      |
| `include`       | array   | Limit result set to specific ids.                                                                                             |
| `offset`        | integer | Offset the result set by a specific number of items.                                                                          |
| `order`         | string  | Order sort attribute ascending or descending. Options: `asc` and `desc`. Default is `desc`.                                   |
| `orderby`       | string  | Sort collection by object attribute. Options: `date`, `id`, `include`, `title` and `slug`. Default is `date`.                 |
| `status`        | string  | Limit result set to webhooks assigned a specific status. Options: `all`, `active`, `paused` and `disabled`. Default is `all`. |

## Update a webhook

This API lets you make changes to a webhook.

```http
PUT /wp-json/wc/v3/webhooks/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X PUT https://example.com/wp-json/wc/v3/webhooks/142 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "status": "paused"
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	status: 'paused',
};

WooCommerce.put( 'webhooks/142', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'status' => 'paused'
];

print_r($woocommerce->put('webhooks/142', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "status": "paused"
}

print(wcapi.put("webhooks/142", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  status: "paused"
}

woocommerce.put("webhooks/142", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 142,
	"name": "Order updated",
	"status": "paused",
	"topic": "order.updated",
	"resource": "order",
	"event": "updated",
	"hooks": [
		"woocommerce_process_shop_order_meta",
		"woocommerce_api_edit_order",
		"woocommerce_order_edit_status",
		"woocommerce_order_status_changed"
	],
	"delivery_url": "http://requestb.in/1g0sxmo1",
	"date_created": "2016-05-15T23:17:52",
	"date_created_gmt": "2016-05-15T20:17:52",
	"date_modified": "2016-05-15T17:30:12",
	"date_modified_gmt": "2016-05-15T20:30:12",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/webhooks/142"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/webhooks"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

## Delete a webhook

This API helps you delete a webhook.

```http
DELETE /wp-json/wc/v3/webhooks/<id>
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X DELETE https://example.com/wp-json/wc/v3/webhooks/142 \
	-u consumer_key:consumer_secret
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
WooCommerce.delete( 'webhooks/142' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php print_r($woocommerce->delete('webhooks/142')); ?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
print(wcapi.delete("webhooks/142").json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
woocommerce.delete("webhooks/142").parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"id": 142,
	"name": "Order updated",
	"status": "paused",
	"topic": "order.updated",
	"resource": "order",
	"event": "updated",
	"hooks": [
		"woocommerce_process_shop_order_meta",
		"woocommerce_api_edit_order",
		"woocommerce_order_edit_status",
		"woocommerce_order_status_changed"
	],
	"delivery_url": "http://requestb.in/1g0sxmo1",
	"date_created": "2016-05-15T23:17:52",
	"date_created_gmt": "2016-05-15T20:17:52",
	"date_modified": "2016-05-15T23:30:12",
	"date_modified_gmt": "2016-05-15T20:30:12",
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/webhooks/142"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/webhooks"
			}
		]
	}
}
```

  </TabItem>
</Tabs>

#### Available parameters

| Parameter | Type   | Description                                                                |
| --------- | ------ | -------------------------------------------------------------------------- |
| `force`   | string | Use `true` whether to permanently delete the webhook, Defaults is `false`. |

## Batch update webhooks

This API helps you to batch create, update and delete multiple webhooks.

:::note
Note: By default it's limited to up to 100 objects to be created, updated or
	deleted.
:::

```http
POST /wp-json/wc/v3/webhooks/batch
```

<Tabs>
  <TabItem value="curl" label="cURL">

```shell
curl -X POST https://example.com/wp-json/wc/v3/webhooks/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "name": "Coupon created",
      "topic": "coupon.created",
      "delivery_url": "http://requestb.in/1g0sxmo1"
    },
    {
      "name": "Customer deleted",
      "topic": "customer.deleted",
      "delivery_url": "http://requestb.in/1g0sxmo1"
    }
  ],
  "delete": [
    143
  ]
}'
```

  </TabItem>
  <TabItem value="js" label="JavaScript">

```javascript
const data = {
	create: [
		{
			name: 'Round toe',
			topic: 'coupon.created',
			delivery_url: 'http://requestb.in/1g0sxmo1',
		},
		{
			name: 'Customer deleted',
			topic: 'customer.deleted',
			delivery_url: 'http://requestb.in/1g0sxmo1',
		},
	],
	delete: [ 143 ],
};

WooCommerce.post( 'webhooks/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );
```

  </TabItem>
  <TabItem value="php" label="PHP">

```php
<?php
$data = [
    'create' => [
        [
            'name' => 'Round toe',
            'topic' => 'coupon.created',
            'delivery_url' => 'http://requestb.in/1g0sxmo1'
        ],
        [
            'name' => 'Customer deleted',
            'topic' => 'customer.deleted',
            'delivery_url' => 'http://requestb.in/1g0sxmo1'
        ]
    ],
    'delete' => [
        143
    ]
];

print_r($woocommerce->post('webhooks/batch', $data));
?>
```

  </TabItem>
  <TabItem value="python" label="Python">

```python
data = {
    "create": [
        {
            "name": "Round toe",
            "topic": "coupon.created",
            "delivery_url": "http://requestb.in/1g0sxmo1"
        },
        {
            "name": "Customer deleted",
            "topic": "customer.deleted",
            "delivery_url": "http://requestb.in/1g0sxmo1"
        }
    ],
    "delete": [
        143
    ]
}

print(wcapi.post("webhooks/batch", data).json())
```

  </TabItem>
  <TabItem value="ruby" label="Ruby">

```ruby
data = {
  create: [
    {
      name: "Round toe",
      topic: "coupon.created",
      delivery_url: "http://requestb.in/1g0sxmo1"
    },
    {
      name: "Customer deleted",
      topic: "customer.deleted",
      delivery_url: "http://requestb.in/1g0sxmo1"
    }
  ],
  delete: [
    143
  ]
}

woocommerce.post("webhooks/batch", data).parsed_response
```

  </TabItem>
  <TabItem value="response" label="JSON Response">

```json
{
	"create": [
		{
			"id": 146,
			"name": "Coupon created",
			"status": "active",
			"topic": "coupon.created",
			"resource": "coupon",
			"event": "created",
			"hooks": [
				"woocommerce_process_shop_coupon_meta",
				"woocommerce_api_create_coupon"
			],
			"delivery_url": "http://requestb.in/1g0sxmo1",
			"date_created": "2016-05-25T01:56:26",
			"date_created_gmt": "2016-05-24T22:56:26",
			"date_modified": "2016-05-25T01:56:26",
			"date_modified_gmt": "2016-05-24T22:56:26",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/webhooks/146"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/webhooks"
					}
				]
			}
		},
		{
			"id": 147,
			"name": "Customer deleted",
			"status": "active",
			"topic": "customer.deleted",
			"resource": "customer",
			"event": "deleted",
			"hooks": [ "delete_user" ],
			"delivery_url": "http://requestb.in/1g0sxmo1",
			"date_created": "2016-05-25T01:56:30",
			"date_created_gmt": "2016-05-24T22:56:30",
			"date_modified": "2016-05-25T01:56:30",
			"date_modified_gmt": "2016-05-24T22:56:30",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/webhooks/147"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/webhooks"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 143,
			"name": "Webhook created on May 24, 2016 @ 03:20 AM",
			"status": "active",
			"topic": "customer.created",
			"resource": "customer",
			"event": "created",
			"hooks": [
				"user_register",
				"woocommerce_created_customer",
				"woocommerce_api_create_customer"
			],
			"delivery_url": "http://requestb.in/1g0sxmo1",
			"date_created": "2016-05-15T23:17:52",
			"date_created_gmt": "2016-05-15T20:17:52",
			"date_modified": "2016-05-15T23:17:52",
			"date_modified_gmt": "2016-05-15T20:17:52",
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/webhooks/143"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/webhooks"
					}
				]
			}
		}
	]
}
```

  </TabItem>
</Tabs>


---

## WooCommerce Store API

*Source: apis/store-api/README.md*

# WooCommerce Store API

**The Store API provides public Rest API endpoints for the development of customer-facing cart, checkout, and product functionality. It follows many of the patterns used in the [WordPress REST API](https://developer.wordpress.org/rest-api/key-concepts/).**

In contrast to the WooCommerce REST API, the Store API is unauthenticated and does not provide access to sensitive store data or other customer information.

Example of a valid API request using cURL:

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products"
```

Possible uses of the Store API include:

1. Obtaining a list of products to display that can be searched or filtered
2. Adding products to the cart and returning an updated cart object for display
3. Obtaining shipping rates for a cart
4. Converting a customer’s cart to an Order, collecting addresses, and then facilitating payment

## Requirements and limitations

* This is an unauthenticated API. It does not require API keys or authentication tokens for access.
* All API responses return JSON-formatted data.
* Data returned from the API is reflective of the current user (customer). Customer sessions in WooCommerce are cookie-based.
* Store API cannot be used to look up other customers and orders by ID; only data belonging to the current user.
* Likewise, Store API cannot be used to write store data e.g. settings. For more extensive access, use the authenticated [WC REST API.](/docs/apis/rest-api/)
* Endpoints that do allow writes, for example, updating the current customer address, require a [nonce-token](https://developer.wordpress.org/plugins/security/nonces/).
* Store API is render-target agnostic and should not make assumptions about where content will be displayed. For example, returning HTML would be discouraged unless the data type itself is HTML.

## Store API Namespace

Resources in the Store API are all found within the `wc/store/v1` namespace, and since this API extends the WordPress API, accessing it requires the `/wp-json/` base. Currently, the only version is `v1`. If the version is omitted, `v1` will be served.

Examples:

```http
GET /wp-json/wc/store/v1/products
GET /wp-json/wc/store/v1/cart
```

The API uses JSON to serialize data. You don’t need to specify `.json` at the end of an API URL.

## Resources and endpoints

Available resources in the Store API are listed below, with links to more detailed documentation.

| Resource | Methods | Endpoints |
| --- | --- | --- |
| [`Cart`](/docs/apis/store-api/resources-endpoints/cart) | `GET` | [`/wc/store/v1/cart`](/docs/apis/store-api/resources-endpoints/cart#get-cart) |
| | `POST` | [`/wc/store/v1/cart/add-item`](/docs/apis/store-api/resources-endpoints/cart#add-item) |
| | `POST` | [`/wc/store/v1/cart/remove-item`](/docs/apis/store-api/resources-endpoints/cart#remove-item) |
| | `POST` | [`/wc/store/v1/cart/update-item`](/docs/apis/store-api/resources-endpoints/cart#update-item) |
| | `POST` | [`/wc/store/v1/cart/apply-coupon`](/docs/apis/store-api/resources-endpoints/cart#apply-coupon) |
| | `POST` | [`/wc/store/v1/cart/remove-coupon`](/docs/apis/store-api/resources-endpoints/cart#remove-coupon) |
| | `POST` | [`/wc/store/v1/cart/update-customer`](/docs/apis/store-api/resources-endpoints/cart#update-customer) |
| | `POST` | [`/wc/store/v1/cart/select-shipping-rate`](/docs/apis/store-api/resources-endpoints/cart#select-shipping-rate) |
| [`Cart Items`](/docs/apis/store-api/resources-endpoints/cart-items) | `GET`, `POST`, `DELETE` | [`/wc/store/v1/cart/items`](/docs/apis/store-api/resources-endpoints/cart-items#list-cart-items) |
| | `GET`, `POST`, `PUT`, `DELETE` | [`/wc/store/v1/cart/items/:key`](/docs/apis/store-api/resources-endpoints/cart-items#single-cart-item) |
| [`Cart Coupons`](/docs/apis/store-api/resources-endpoints/cart-coupons) | `GET`, `POST`, `DELETE` | [`/wc/store/v1/cart/coupons`](/docs/apis/store-api/resources-endpoints/cart-coupons#list-cart-coupons) |
| | `GET`, `DELETE` | [`/wc/store/v1/cart/coupon/:code`](/docs/apis/store-api/resources-endpoints/cart-coupons#single-cart-coupon) |
| [`Checkout`](/docs/apis/store-api/resources-endpoints/checkout) | `GET`, `POST`, `PUT` | [`/wc/store/v1/checkout`](/docs/apis/store-api/resources-endpoints/checkout) |
| [`Checkout order`](/docs/apis/store-api/resources-endpoints/checkout-order) | `POST` | [`/wc/store/v1/checkout/:id`](/docs/apis/store-api/resources-endpoints/checkout-order) |
| [`Order`](/docs/apis/store-api/resources-endpoints/order) | `GET` | [`/wc/store/v1/order/:id`](/docs/apis/store-api/resources-endpoints/order) |
| [`Products`](/docs/apis/store-api/resources-endpoints/products) | `GET` | [`/wc/store/v1/products`](/docs/apis/store-api/resources-endpoints/products#list-products) |
| | `GET` | [`/wc/store/v1/products/:id`](/docs/apis/store-api/resources-endpoints/products#single-product-by-id) |
| [`Product Collection Data`](/docs/apis/store-api/resources-endpoints/product-collection-data) | `GET` | [`/wc/store/v1/products/collection-data`](/docs/apis/store-api/resources-endpoints/product-collection-data) |
| [`Product Attributes`](/docs/apis/store-api/resources-endpoints/product-attributes) | `GET` | [`/wc/store/v1/products/attributes`](/docs/apis/store-api/resources-endpoints/product-attributes#list-product-attributes) |
| | `GET` | [`/wc/store/v1/products/attributes/:id`](/docs/apis/store-api/resources-endpoints/product-attributes#single-product-attribute) |
| [`Product Attribute Terms`](/docs/apis/store-api/resources-endpoints/product-attribute-terms) | `GET` | [`/wc/store/v1/products/attributes/:id/terms`](/docs/apis/store-api/resources-endpoints/product-attribute-terms) |
| [`Product Categories`](/docs/apis/store-api/resources-endpoints/product-categories) | `GET` | [`/wc/store/v1/products/categories`](/docs/apis/store-api/resources-endpoints/product-categories) |
| [`Product Brands`](/docs/apis/store-api/resources-endpoints/product-brands) | `GET` | [`/wc/store/v1/products/brands`](/docs/apis/store-api/resources-endpoints/product-brands) |
| [`Product Reviews`](/docs/apis/store-api/resources-endpoints/product-reviews) | `GET` | [`/wc/store/v1/products/reviews`](/docs/apis/store-api/resources-endpoints/product-reviews) |
| [`Product Tags`](/docs/apis/store-api/resources-endpoints/product-tags) | `GET` | [`/wc/store/v1/products/tags`](/docs/apis/store-api/resources-endpoints/product-tags) |

## Pagination

If collections contain many results, they may be paginated. When listing resources you can pass the following parameters:

| Parameter  | Description                                                                            |
| :--------- | :------------------------------------------------------------------------------------- |
| `page`     | Current page of the collection. Defaults to `1`.                                       |
| `per_page` | Maximum number of items to be returned in result set. Defaults to `10`. Maximum `100`. |

In the example below, we list 20 products per page and return page 2.

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products?page=2&per_page=20"
```

Additional pagination headers are also sent back with extra information.

| Header            | Description                                                               |
| :---------------- | :------------------------------------------------------------------------ |
| `X-WP-Total`      | The total number of items in the collection.                              |
| `X-WP-TotalPages` | The total number of pages in the collection.                              |
| `Link`            | Contains links to other pages; `next`, `prev`, and `up` where applicable. |

## Status codes

The following table gives an overview of how the API functions generally behave.

| Request type | Description                                                                                                 |
| :----------- | :---------------------------------------------------------------------------------------------------------- |
| `GET`        | Access one or more resources and return `200 OK` and the result as JSON.                                    |
| `POST`       | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
| `PUT`        | Return `200 OK` if the resource is modified successfully. The modified result is returned as JSON.          |
| `DELETE`     | Returns `204 No Content` if the resource was deleted successfully.                                          |

The following table shows the possible return codes for API requests.

| Response code            | Description                                                                                                                                 |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `200 OK`                 | The request was successful, the resource(s) itself is returned as JSON.                                                                     |
| `204 No Content`         | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body.             |
| `201 Created`            | The POST request was successful and the resource is returned as JSON.                                                                       |
| `400 Bad Request`        | A required attribute of the API request is missing.                                                                                         |
| `403 Forbidden`          | The request is not allowed.                                                                                                                 |
| `404 Not Found`          | A resource could not be accessed, for example it doesn't exist.                                                                             |
| `405 Method Not Allowed` | The request is not supported.                                                                                                               |
| `409 Conflict`           | The request could not be completed due to a conflict with the current state of the target resource. The current state may also be returned. |
| `500 Server Error`       | While handling the request something went wrong server-side.                                                                                |

## Contributing

There are 3 main parts to each route in the Store API:

1. Route - Responsible for mapping requests to endpoints. Routes in the Store API extend the `AbstractRoute` class; this class contains shared functionality for handling requests and returning JSON responses. Routes ensure a valid response is returned and handle collections, errors, and pagination.
2. Schema - Routes do not format resources. Instead we use _Schema_ classes that represent each type of resource, for example, a Product, a Cart, or a Cart Item. Schema classes in the Store API should extend the `AbstractSchema` class.
3. Utility - In more advanced cases where the Store API needs to access complex data from WooCommerce core, or where multiple routes need access to the same data, routes should use a Controller or Utility class. For example, the Store API has an Order Controller and a Cart Controller for looking up order and cart data respectfully.

Typically, routes handle the following types of requests:

* `GET` requests to read product, cart, or checkout data.
* `POST` and `PUT` requests to update cart and checkout data.
* `DELETE` requests to remove cart data.
* `OPTIONS` requests to retrieve the JSON schema for the current route.

Please review the [Store API Guiding principles](/docs/apis/store-api/guiding-principles). This covers our approach to development, and topics such as versioning, what data is safe to include, and how to build new routes.

## Extensibility

The approach to extensibility within the Store API is to expose certain routes and schema to the ExtendSchema class. [Documentation for contributors on this can be found here](/docs/apis/store-api/extending-store-api/).

If a route includes the extensibility interface, 3rd party developers can use the shared `ExtendSchema::class` instance to register additional endpoint data and additional schema.

This differs from the traditional filter hook approach in that it is more limiting, but it reduces the likelihood of a 3rd party extension breaking routes and endpoints or overwriting returned data which other apps may rely upon.

If new schema is required, and any of the following statements are true, choose to _extend_ the Store API rather than introducing new schema to existing Store API schemas:

* The data is part of an extension, not core
* The data is related to a resource, but not technically part of it
* The data is difficult to query (performance wise) or has a very narrow or niche use-case

If the data is sensitive (for example, a core setting that should be private), or not related to the current user (for example, looking up an order by order ID), [choose to use the authenticated WC REST API](/docs/apis/rest-api/).

If you're looking to add _new routes and endpoints_, rather than extending the Store API _schema_, extending the Store API is not necessary. You can instead utilize core WordPress functionality to create new routes, choosing to use the same pattern of Store API if you wish. See:

* [`register_rest_route()`](https://developer.wordpress.org/reference/functions/register_rest_route/)
* [Rest API Permissions Callbacks](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/#permissions-callback)


---

## Cart Tokens

*Source: apis/store-api/cart-tokens.md*

# Cart Tokens 

Cart tokens can be used instead of cookies based sessions for headless interaction with carts. When using a `Cart-Token` a  [Nonce Token](/docs/apis/store-api/nonce-tokens) is not required.

## Obtaining a Cart Token

Successful requests to `/cart` endpoints return a `Cart-Token` header alongside the response. This contains a token which can later be sent as a request header to the Store API Cart and Checkout endpoints to identify the cart. Error responses caused by a cart session loading failure do not include `Cart-Token` or `Cart-Hash` headers.

The quickest method of obtaining a Cart Token is to make a GET request `/wp-json/wc/store/v1/cart` and observe the response headers. You should see a `Cart-Token` header there.

## How to use a Cart-Token

To use a `Cart-Token`, include it as a header with your request. The response will contain the current cart state from the session associated with the `Cart-Token`.

**Example:**

```sh
curl --header "Cart-Token: 12345" --request GET https://example-store.com/wp-json/wc/store/v1/cart
```

The same method will allow you to checkout using a `Cart-Token` on the `/checkout` route.


---

## Extending the Store API

*Source: apis/store-api/extending-store-api/README.md*

# Extending the Store API

Your application can change the way the Store API works by extending certain endpoints. It can add data to certain endpoints to make your server-side data available to the client-side.

You can also use the Store API trigger a server-side cart update from the client which will then update the client-side cart with the data returned by the API.

The documents listed below contain further details on how to achieve the above.

| Document | Description |
|----------|-------------|
| [Exposing your data](./extend-store-api-add-data/) | Explains how you can add additional data to Store API endpoints. |
| [Available extensible endpoints](./available-endpoints-to-extend/) | A list of all available endpoints to extend. |
| [Available Formatters](./extend-store-api-formatters/) | Available `Formatters` to format data for use in the Store API. |
| [Updating the cart on-demand](./extend-store-api-update-cart/) | Update the server-side cart following an action from the front-end. |
| [Adding fields and passing values](./extend-store-api-add-custom-fields/) | How to add custom fields to Store API endpoints. | 


---

## Available extensible endpoints

*Source: apis/store-api/extending-store-api/available-endpoints-to-extend.md*

# Available extensible endpoints

Some endpoints of the Store API are extensible via a class called `ExtendSchema`. This allows you to customise the data (including the schema) that is returned by the Store API so that it can be consumed by your application or plugin.

For more information about extending the Store API, you may also be interested in:

-   [How to add your data to Store API using `ExtendSchema`](./extend-store-api-add-data.md)
-   [How to add a new endpoint](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/internal-developers/rest-api/extend-rest-api-new-endpoint.md)

Below is a list of available endpoints that you can extend using `ExtendSchema`, as well as some example use-cases.

## Products

The main `wc/store/products` endpoint is extensible via ExtendSchema. The data is available via the `extensions` key for each `product` in the response array.

This endpoint can be extended using the `ProductSchema::IDENTIFIER` key. For this endpoint, your `data_callback` callback function is passed `$product` as a parameter. Your `schema_callback` function is passed no additional parameters; all products should share the same schema.

### Use Cases

This endpoint is useful for adding additional data about individual products. This could be some meta data, additional pricing, or anything else to support custom blocks or components on the products page.

### Example

```php
woocommerce_store_api_register_endpoint_data(
	array(
		'endpoint'        => ProductSchema::IDENTIFIER,
		'namespace'       => 'my_plugin_namespace',
		'data_callback'   => function( $product ) {
			return array(
				'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ),
			);
		},
		'schema_callback' => function() {
			return array(
				'properties' => array(
					'my_meta_data' => array(
						'type' => 'string',
					),
				),
			);
		},
		'schema_type'     => ARRAY_A,
	)
);
```

## Cart

The main `wc/store/cart` endpoint is extensible via ExtendSchema. The data is available via the `extensions` key in the response.

This endpoint can be extended using the `CartSchema::IDENTIFIER` key. For this endpoint, your `data_callback` and `schema_callback` functions are passed no additional parameters.

### Use Cases

This endpoint is useful for adding additional data to the cart page, for example, extra data about the cart items, or anything else needed to support custom blocks displayed on the cart page.

### Example

```php
woocommerce_store_api_register_endpoint_data(
	array(
		'endpoint'        => CartSchema::IDENTIFIER,
		'namespace'       => 'my_plugin_namespace',
		'data_callback'   => function() {
			return array(
				'foo' => 'bar',
			);
		},
		'schema_callback' => function() {
			return array(
				'properties' => array(
					'foo' => array(
						'type' => 'string',
					),
				),
			);
		},
		'schema_type'     => ARRAY_A,
	)
);
```

## Cart Items

The `wc/store/cart/items` endpoint, which is also available on `wc/store/cart` inside the `items` key. The data would be available inside each item of the `items` array.

This endpoint can be extended using the `CartItemSchema::IDENTIFIER` key. For this endpoint, your `data_callback` callback function is passed `$cart_item` as a parameter. Your `schema_callback` function is passed no additional parameters; all cart items should share the same schema.

### Use Cases

This endpoint is useful for adding additional data about individual cart items. This could be some meta data, additional pricing, or anything else to support custom blocks or components on the cart page.

### Example

```php
woocommerce_store_api_register_endpoint_data(
	array(
		'endpoint'        => CartItemSchema::IDENTIFIER,
		'namespace'       => 'my_plugin_namespace',
		'data_callback'   => function( $cart_item ) {
			$product = $cart_item['data'];
			return array(
				'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ),
			);
		},
		'schema_callback' => function() {
			return array(
				'properties' => array(
					'my_meta_data' => array(
						'type' => 'string',
					),
				),
			);
		},
		'schema_type'     => ARRAY_A,
	)
);
```

## Checkout

The `wc/store/checkout` endpoint is extensible via ExtendSchema. Additional data is available via the `extensions` key in the response.

This endpoint can be extended using the `CheckoutSchema::IDENTIFIER` key. For this endpoint, your `data_callback` and `schema_callback` functions are passed no additional parameters.

### Use Cases

This endpoint is useful for adding additional data to the checkout page, such as a custom payment method which requires additional data to be collected from the user or server.

⚠ **Important: Do **not** reveal any sensitive data in this endpoint, as it is publicly accessible. This includes private keys for payment services.**

### Example

```php
woocommerce_store_api_register_endpoint_data(
	array(
		'endpoint'        => CheckoutSchema::IDENTIFIER,
		'namespace'       => 'my_plugin_namespace',
		'data_callback'   => function() {
			return array(
				'foo' => 'bar',
			);
		},
		'schema_callback' => function() {
			return array(
				'properties' => array(
					'foo' => array(
						'type' => 'string',
					),
				),
			);
		},
		'schema_type'     => ARRAY_A,
	)
);
```


---

## Adding fields and passing values

*Source: apis/store-api/extending-store-api/extend-store-api-add-custom-fields.md*

# Adding fields and passing values

This document describes how a developer can insert an input field into the Checkout block and have its value passed to the Store API so it's available when processing the checkout.

## Overview

Developers can extend the Checkout block to add new inner blocks and process additional data through the checkout POST request. This involves leveraging the extensibility interfaces provided by Gutenberg and WooCommerce Blocks. This is demonstrated in more detail in our tutorial: [Tutorial: Extending the WooCommerce Checkout Block
](https://developer.woocommerce.com/2023/08/07/extending-the-woocommerce-checkout-block-to-add-custom-shipping-options/).

## Prerequisites

- Basic understanding of React and the Gutenberg block editor.
- Familiarity with WooCommerce Blocks' extensibility interfaces and the Store API.

## Step-by-Step Guide

### 1. Set Up Your Development Environment

Ensure you have the following files in your project:

- `index.js`: Entry point for Webpack, imports, and registers the block type.
- `edit.js`: Handles the rendering of the block in the editor interface.
- `block.json`: Provides metadata and configurations for the block.
- `block.js`: Manages the block's state and user interactions.
- `frontend.js`: Registers the checkout block component for the frontend.

Refer to [this tutorial](https://developer.woocommerce.com/2023/08/07/extending-the-woocommerce-checkout-block-to-add-custom-shipping-options/) for an example of adding a custom shipping option to the checkout block.

### 2. Add a new field block to the Checkout Block

To add a field block to the Checkout Block you will need to add the following entries to the `block.json` file of your block:

```json
"parent": [ "woocommerce/checkout-shipping-methods-block" ],
"attributes": {
	"lock": {
		"type": "object",
		"default": {
			"remove": true,
			"move": true
		}
	}
}
```

- The [lock attribute](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-templates/#individual-block-locking) is an object that controls whether the block can be removed or moved. By default, the lock attribute is set to allow the block to be removed and moved. However, by modifying the lock attribute, you can “force” the block to be non-removable. For example, you can set both remove and move properties to false in order to prevent the block from being removed or moved.
- The [parent attribute](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#parent) specifies the parent block that this block should be nested within it. It determines where the block will render. In our example, the block is a child of the `woocommerce/checkout-shipping-methods-block`. This means that your block will be rendered within the `woocommerce/checkout-shipping-methods-block`. If the shipping methods block is not required, your block will not be rendered.

### 3. Setting custom checkout data

We can set the added field data to send it to the `wc/store/checkout` endpoint when processing orders using the function `setExtensionData`:

```JavaScript
setExtensionData(
	'namespace-of-your-block',
	'key-of-your-data',
	value
);
```

#### Parameters

- namespace `string` - The namespace of your block.
- key `string` - The key of your data.
- value `any` - The value of your data.

#### How it works

 1. `setExtensionData` is passed to inner blocks via props.
 2. It updates the `extensionData` key of the `wc/store/checkout` data store.
 3. This key is passed as part of the request body when POSTing to the checkout endpoint.

#### Code Example

```JavaScript
// block.js
export const Block = ( { checkoutExtensionData, extensions } ) => {
/**
	 * setExtensionData will update the wc/store/checkout data store with the values supplied. It
	 * can be used to pass data from the client to the server when submitting the checkout form.
	 */
	const { setExtensionData } = checkoutExtensionData;
}

// ... Some code here

useEffect( () => {
/**
	* This code should use `setExtensionData` to update the `key-of-your-data` key
	* in the `namespace-of-your-block` namespace of the checkout data store.
*/
setExtensionData(
	'namespace-of-your-block',
	'key-of-your-data',
	value
);
}, [ setExtensionData, value ] );
```

#### Screenshots

Screenshots of Redux Dev tool showing the data store before and after the setExtensionData call:

| Before | After |
| ------ | ----- |
| ![Redux Dev tool before setExtensionData call](https://github.com/woocommerce/woocommerce-blocks/assets/14235870/948581f5-fdc2-4df1-963f-9aeb4b18b042) | ![Redux Dev tool after setExtensionData call](https://github.com/woocommerce/woocommerce-blocks/assets/14235870/ddc7dbe7-3fad-44cd-bd19-ce78bc49b951) |

### 4. Processing the Checkout POST Request

To process the added field data, we'll need extend the Store API to tell it to expect additional data. See more details in the [Exposing your data in the Store API](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/rest-api/extend-store-api-add-data.md)

#### Code Example

We will use the following PHP files in our example:

- The `custom-inner-block-blocks-integration.php` file: Enqueue scripts, styles, and data on the frontend when the Checkout blocks is being used. See more details in the [IntegrationInterface](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/checkout-block/integration-interface.md) documentation.

```php
use Automattic\WooCommerce\Blocks\Integrations\IntegrationInterface;

/**
 * Class for integrating with WooCommerce Blocks
 */
class Custom_Inner_Block_Blocks_Integration implements IntegrationInterface {

	/**
	 * The name of the integration.
	 *
	 * @return string
	 */
	public function get_name() {
		return 'new-field-block';
	}

	/**
	 * When called invokes any initialization/setup for the integration.
	 */
	public function initialize() {
		// ... Some code here: (e.g. init functions that registers scripts and styles, and other instructions)
	}

	// ... Other functions here
}
```

- The `custom-inner-block-extend-store-endpoint.php` file: extends the [Store API](https://github.com/woocommerce/woocommerce-blocks/tree/trunk/src/StoreApi) and adds hooks to save and display your new field block instructions. This doesn't save the data from the custom block anywhere by default, but you can add your own logic to save the data to the database.

```php
use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\StoreApi\Schemas\CartSchema;
use Automattic\WooCommerce\Blocks\StoreApi\Schemas\CheckoutSchema;

/**
 * Your New Field Block Extend Store API.
 */
class Custom_Inner_Block_Extend_Store_Endpoint {
	/**
	 * Stores Rest Extending instance.
	 *
	 * @var ExtendRestApi
	 */
	private static $extend;

	/**
	 * Plugin Identifier, unique to each plugin.
	 *
	 * @var string
	 */
	const IDENTIFIER = 'new-field-block';

	/**
	 * Bootstraps the class and hooks required data.
	 *
	 */
	public static function init() {
		self::$extend = Automattic\WooCommerce\StoreApi\StoreApi::container()->get( Automattic\WooCommerce\StoreApi\Schemas\ExtendSchema::class );
		self::extend_store();
	}

	/**
	 * Registers the actual data into each endpoint.
	 */
	public static function extend_store() {
		if ( is_callable( [ self::$extend, 'register_endpoint_data' ] ) ) {
			self::$extend->register_endpoint_data(
				[
					'endpoint'        => CheckoutSchema::IDENTIFIER,
					'namespace'       => self::IDENTIFIER,
					'schema_callback' => [ 'Custom_Inner_Block_Extend_Store_Endpoint', 'extend_checkout_schema' ],
					'schema_type'     => ARRAY_A,
				]
			);
		}
	}

	/**
	 * Register the new field block schema into the Checkout endpoint.
	 *
	 * @return array Registered schema.
	 *
	 */
	public static function extend_checkout_schema() {
		return [
            'Value_1'   => [
                'description' => 'A description of the field',
                'type'        => 'string', // ... type of the field, this should be a string
                'context'     => [ 'view', 'edit' ], // ... context of the field, this should be an array containing 'view' and 'edit'
                'readonly'    => true, // ... whether the field is readonly or not, this should be a boolean
                'optional'    => true, // ... whether the field is optional or not, this should be a boolean
            ],
			// ... other values
        ];
	}
}
```

- The `new-field-block.php` file: the main plugin file that loads the `custom-inner-block-blocks-integration.php` and `custom-inner-block-extend-store-endpoint.php` files.

```php
<?php
/**
 * Plugin Name:     New Field Block
 * Version:         1.0
 * Author:          Your Name Here
 * License:         GPL-2.0-or-later
 * License URI:     https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:     new-field-block
 *
 * @package         create-block
 */

// ... Some code here

/**
 * Include the dependencies needed to instantiate the block.
 */
add_action(
	'woocommerce_blocks_loaded',
	function() {
		require_once __DIR__ . '/custom-inner-block-blocks-integration.php';

		// Initialize our store endpoint extension when WC Blocks is loaded.
		Custom_Inner_Block_Extend_Store_Endpoint::init();

		add_action(
			'woocommerce_blocks_checkout_block_registration',
			function( $integration_registry ) {
				$integration_registry->register( new Custom_Inner_Block_Blocks_Integration() );
			}
		);
	}
);

// ... Some code here
```

Here is an example from our [tutorial](https://developer.woocommerce.com/2023/08/07/extending-the-woocommerce-checkout-block-to-add-custom-shipping-options/) of how to get this custom field's data while processing the checkout. This example is from the `shipping-workshop-blocks-integration.php` file. The complete code can be found in this [GitHub repository](https://github.com/woocommerce/wceu23-shipping-workshop-final/blob/main/shipping-workshop-blocks-integration.php#L42-L83).

```php
private function save_shipping_instructions() {
	/**
	 * We write a hook, using the `woocommerce_store_api_checkout_update_order_from_request` action
	 * that will update the order metadata with the shipping-workshop alternate shipping instruction.
	 *
	 * The documentation for this hook is at: https://github.com/woocommerce/woocommerce-blocks/blob/b73fbcacb68cabfafd7c3e7557cf962483451dc1/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_store_api_checkout_update_order_from_request
	 */
	add_action(
		'woocommerce_store_api_checkout_update_order_from_request',
		function( \WC_Order $order, \WP_REST_Request $request ) {
			$shipping_workshop_request_data = $request['extensions'][$this->get_name()];
			$alternate_shipping_instruction = $shipping_workshop_request_data['alternateShippingInstruction'];
			$other_shipping_value           = $shipping_workshop_request_data['otherShippingValue'];
			$order->update_meta_data( 'shipping_workshop_alternate_shipping_instruction', $alternate_shipping_instruction );
			$order->save();
		},
		10,
		2
	);
}
```

## Conclusion

By following the steps above, you can add and process new field blocks in the WooCommerce checkout block. For complete implementation and additional examples, refer to the provided [tutorial](https://developer.woocommerce.com/2023/08/07/extending-the-woocommerce-checkout-block-to-add-custom-shipping-options/) and the corresponding [GitHub repository](https://github.com/woocommerce/wceu23-shipping-workshop-final/).


---

## Exposing your data

*Source: apis/store-api/extending-store-api/extend-store-api-add-data.md*

# Exposing your data

## The problem

You want to extend the Mini-Cart, Cart and Checkout blocks, but you want to use some custom data not available on Store API or the context. You don't want to create your own endpoints or Ajax actions. You want to piggyback on the existing StoreAPI calls.

## Solution

ExtendSchema offers the possibility to add contextual custom data to Store API endpoints, like `wc/store/cart` and `wc/store/cart/items` endpoints. That data is namespaced to your plugin and protected from other plugins causing it to malfunction. The data is available on all frontend filters and slotFills for you to consume.

## Basic usage

You can use ExtendSchema by registering a couple of functions, `schema_callback` and `data_callback` on a specific endpoint namespace. ExtendSchema will call them at execution time and will pass them relevant data as well.

This example below uses the Cart endpoint, [see passed parameters.](./available-endpoints-to-extend.md)

**Note: Make sure to read the "Things to consider" section below.**

```php
use Automattic\WooCommerce\StoreApi\Schemas\V1\CartSchema;

add_action('woocommerce_blocks_loaded', function() {
 woocommerce_store_api_register_endpoint_data(
	array(
		'endpoint' => CartSchema::IDENTIFIER,
		'namespace' => 'plugin_namespace',
		'data_callback' => 'my_data_callback',
		'schema_callback' => 'my_schema_callback',
		'schema_type' => ARRAY_A,
		)
	);
});


function my_data_callback() {
	return [
		'custom-key' => 'custom-value',
	];
}

function my_schema_callback() {
	return [
		'custom-key' => [
			'description' => __( 'My custom data', 'plugin-namespace' ),
			'type' => 'string',
			'readonly' => true,
		]
	];
}
```

Data callback and Schema callback can also receive parameters:

```php

function my_cart_item_callback( $cart_item ) {
$product = $cart_item['data'];
	if ( is_my_custom_product_type( $product ) ) {
		$custom_value = get_custom_value( $product );
		return [
			'custom-key' => $custom_value,
		];
	}
}

```

## Things To Consider

### ExtendSchema is a shared instance

The ExtendSchema is stored as a shared instance between the API and consumers (third-party developers). So you shouldn't initiate the class yourself with `new ExtendSchema` because it would not work. Instead, you should always use the shared instance from the StoreApi dependency injection container like this.

```php
$extend = StoreApi::container()->get( ExtendSchema::class );
```

Also note that the dependency injection container is not available until after the `woocommerce_blocks_loaded` action has been fired, so you should hook your file that action:

```php
use Automattic\WooCommerce\StoreApi\StoreApi;
use Automattic\WooCommerce\StoreApi\Schemas\ExtendSchema;

add_action( 'woocommerce_blocks_loaded', function() {
	$extend = StoreApi::container()->get( ExtendSchema::class );
	// my logic.
});
```

Or use the global helper functions:

-   `woocommerce_store_api_register_endpoint_data( $args )`
-   `woocommerce_store_api_register_update_callback( $args )`
-   `woocommerce_store_api_register_payment_requirements( $args )`
-   `woocommerce_store_api_get_formatter( $name )`

### Errors and fatals are silence for non-admins

If your callback functions `data_callback` and `schema_callback` throw an exception or an error, or you passed the incorrect type of parameter to `register_endpoint_data`; that error would be caught and logged into WooCommerce error logs. If the current user is a shop manager or an admin, and has WP_DEBUG enabled, the error would be surfaced to the frontend.

### Callbacks should always return an array

To reduce the chances of breaking your client code or passing the wrong type, and also to keep a consistent REST API response, callbacks like `data_callback` and `schema_callback` should always return an array, even if it was empty.

## API Definition

-   `ExtendSchema::register_endpoint_data`: Used to register data to a custom endpoint. It takes an array of arguments:

| Attribute         | Type     |         Required         | Description                                                                                                                                          |
| :---------------- | :------- | :----------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| `endpoint`        | string   |           Yes            | The endpoint you're trying to extend. It is suggested that you use the `::IDENTIFIER` available on the route Schema class to avoid typos.            |
| `namespace`       | string   |           Yes            | Your plugin namespace, the data will be available under this namespace in the StoreAPI response.                                                     |
| `data_callback`   | callback |           Yes            | A callback that returns an array with your data.                                                                                                     |
| `schema_callback` | callback |           Yes            | A callback that returns the shape of your data.                                                                                                      |
| `schema_type`     | string   | No (default: `ARRAY_A` ) | The type of your data. If you're adding an object (key => values), it should be `ARRAY_A`. If you're adding a list of items, it should be `ARRAY_N`. |

## Putting it all together

This is a complete example that shows how you can register contextual WooCommerce Subscriptions data in each cart item (simplified). This example uses [Formatters](./extend-store-api-formatters.md), utility classes that allow you to format values so that they are compatible with the StoreAPI.

```php
<?php
/**
 * WooCommerce Subscriptions Extend Store API.
 *
 * A class to extend the store public API with subscription related data
 * for each subscription item
 *
 * @package WooCommerce Subscriptions
 */
use Automattic\WooCommerce\StoreApi\StoreApi;
use Automattic\WooCommerce\StoreApi\Schemas\ExtendSchema;
use Automattic\WooCommerce\StoreApi\Schemas\V1\CartItemSchema;

add_action( 'woocommerce_blocks_loaded', function() {
	$extend = StoreApi::container()->get( ExtendSchema::class );
	WC_Subscriptions_Extend_Store_Endpoint::init( $extend );
});

class WC_Subscriptions_Extend_Store_Endpoint {
	/**
	 * Stores Rest Extending instance.
	 *
	 * @var ExtendSchema
	 */
	private static $extend;

	/**
	 * Plugin Identifier, unique to each plugin.
	 *
	 * @var string
	 */
	const IDENTIFIER = 'subscriptions';

	/**
	 * Bootstraps the class and hooks required data.
	 *
	 * @param ExtendSchema $extend_rest_api An instance of the ExtendSchema class.
	 *
	 * @since 3.1.0
	 */
	public static function init( ExtendSchema $extend_rest_api ) {
		self::$extend = $extend_rest_api;
		self::extend_store();
	}

	/**
	 * Registers the actual data into each endpoint.
	 */
	public static function extend_store() {

		// Register into `cart/items`
		self::$extend->register_endpoint_data(
			array(
				'endpoint'        => CartItemSchema::IDENTIFIER,
				'namespace'       => self::IDENTIFIER,
				'data_callback'   => array( 'WC_Subscriptions_Extend_Store_Endpoint', 'extend_cart_item_data' ),
				'schema_callback' => array( 'WC_Subscriptions_Extend_Store_Endpoint', 'extend_cart_item_schema' ),
				'schema_type'       => ARRAY_A,
			)
		);
	}

	/**
	 * Register subscription product data into cart/items endpoint.
	 *
	 * @param array $cart_item Current cart item data.
	 *
	 * @return array $item_data Registered data or empty array if condition is not satisfied.
	 */
	public static function extend_cart_item_data( $cart_item ) {
		$product   = $cart_item['data'];
		$item_data = array(
			'billing_period'      => null,
			'billing_interval'    => null,
			'subscription_length' => null,
			'trial_length'        => null,
			'trial_period'        => null,
			'sign_up_fees'        => null,
			'sign_up_fees_tax'    => null,

		);

		if ( in_array( $product->get_type(), array( 'subscription', 'subscription_variation' ), true ) ) {
			$item_data = array_merge(
				array(
					'billing_period'      => WC_Subscriptions_Product::get_period( $product ),
					'billing_interval'    => (int) WC_Subscriptions_Product::get_interval( $product ),
					'subscription_length' => (int) WC_Subscriptions_Product::get_length( $product ),
					'trial_length'        => (int) WC_Subscriptions_Product::get_trial_length( $product ),
					'trial_period'        => WC_Subscriptions_Product::get_trial_period( $product ),
				),
				self::format_sign_up_fees( $product )
			);
		}

		return $item_data;
	}

	/**
	 * Register subscription product schema into cart/items endpoint.
	 *
	 * @return array Registered schema.
	 */
	public static function extend_cart_item_schema() {
		return array(
			'billing_period'      => array(
				'description' => __( 'Billing period for the subscription.', 'woocommerce-subscriptions' ),
				'type'        => array( 'string', 'null' ),
				'enum'        => array_keys( wcs_get_subscription_period_strings() ),
				'context'     => array( 'view', 'edit' ),
				'readonly'    => true,
			),
			'billing_interval'    => array(
				'description' => __( 'The number of billing periods between subscription renewals.', 'woocommerce-subscriptions' ),
				'type'        => array( 'integer', 'null' ),
				'context'     => array( 'view', 'edit' ),
				'readonly'    => true,
			),
			'subscription_length' => array(
				'description' => __( 'Subscription Product length.', 'woocommerce-subscriptions' ),
				'type'        => array( 'integer', 'null' ),
				'context'     => array( 'view', 'edit' ),
				'readonly'    => true,
			),
			'trial_period'        => array(
				'description' => __( 'Subscription Product trial period.', 'woocommerce-subscriptions' ),
				'type'        => array( 'string', 'null' ),
				'enum'        => array_keys( wcs_get_subscription_period_strings() ),
				'context'     => array( 'view', 'edit' ),
				'readonly'    => true,
			),
			'trial_length'        => array(
				'description' => __( 'Subscription Product trial interval.', 'woocommerce-subscriptions' ),
				'type'        => array( 'integer', 'null' ),
				'context'     => array( 'view', 'edit' ),
				'readonly'    => true,
			),
			'sign_up_fees'        => array(
				'description' => __( 'Subscription Product signup fees.', 'woocommerce-subscriptions' ),
				'type'        => array( 'string', 'null' ),
				'context'     => array( 'view', 'edit' ),
				'readonly'    => true,
			),
			'sign_up_fees_tax'    => array(
				'description' => __( 'Subscription Product signup fees taxes.', 'woocommerce-subscriptions' ),
				'type'        => array( 'string', 'null' ),
				'context'     => array( 'view', 'edit' ),
				'readonly'    => true,
			),
		);
	}


	/**
	 * Format sign-up fees.
	 *
	 * @param \WC_Product $product current product.
	 * @return array
	 */
	private static function format_sign_up_fees( $product ) {
		$fees_excluding_tax = wcs_get_price_excluding_tax(
			$product,
			array(
				'qty'   => 1,
				'price' => WC_Subscriptions_Product::get_sign_up_fee( $product ),
			)
		);

		$fees_including_tax = wcs_get_price_including_tax(
			$product,
			array(
				'qty'   => 1,
				'price' => WC_Subscriptions_Product::get_sign_up_fee( $product ),
			)
		);

		$money_formatter = self::$extend->get_formatter( 'money' );

		return array(
			'sign_up_fees'     => $money_formatter->format(
				$fees_excluding_tax
			),
			'sign_up_fees_tax' => $money_formatter->format(
				$fees_including_tax
				- $fees_excluding_tax
			),

		);
	}
}
```

## Formatting your data

You may wish to use our pre-existing Formatters to ensure your data is passed through the Store API in the correct format. More information on the Formatters can be found in the [StoreApi Formatters documentation](./extend-store-api-formatters.md).



---

## Available Formatters

*Source: apis/store-api/extending-store-api/extend-store-api-formatters.md*

# Available Formatters 

`Formatters` are utility classes that allow you to format values to so that they are compatible with the StoreAPI. Default formatters handle values such as monetary amounts, currency information, or HTML.

It is recommended that you use these formatters when you are extending the StoreAPI.

## Why are formatters useful?

Using the formatter utilities when returning certain types of data will ensure that your custom data is consistent and compatible with other endpoints. They also take care of any store specific settings that may affect the formatting of the data, such as currency settings.

Store API includes formatters for:

-   [Money](#moneyformatter)
-   [Currency](#currencyformatter)
-   [HTML](#htmlformatter)

## How to use formatters

To get a formatter, you can use the `get_formatter` method of the `ExtendSchema` class. This method accepts a string, which is the name of the formatter you want to use.

```php
get_formatter('money'); // For the MoneyFormatter
get_formatter('html'); // For the HtmlFormatter
get_formatter('currency'); // CurrencyFormatter
```

This returns a `FormatterInterface` which has the `format` method. The `format` method signature is:

```php
format( $value, array $options = [] );
```

Only `MoneyFormatter`'s behavior can be controlled by the `$options` parameter. This parameter is optional.

### Real world example

Let's say we're going to be returning some extra price data via the API. We want to return the price in cents, and also the currency data for the store. We can use the `MoneyFormatter` and `CurrencyFormatter` to do this.

First we need to ensure we can access the formatter classes. We can do this by using the `use` keyword:

```php
use Automattic\WooCommerce\StoreApi\StoreApi;
use Automattic\WooCommerce\StoreApi\Utilities\ExtendSchema;

$extend = StoreApi::container()->get( ExtendSchema::class );

$my_custom_price = $extend->get_formatter( 'money' )->format( '10.00', [
  'rounding_mode' => PHP_ROUND_HALF_DOWN,
  'decimals'      => 2
] );

$price_response = $extend->get_formatter( 'currency' )->format( [
	'price'         => $my_custom_price,
] );
```

The above code would result in `$price_response` being set to:

```text
[
    'price' => '1000'
    'currency_code' => 'GBP'
    'currency_symbol' => '£'
    'currency_minor_unit' => 2
    'currency_decimal_separator' => '.'
    'currency_thousand_separator' => ','
    'currency_prefix' => '£'
    'currency_suffix' => ''
]
```

## MoneyFormatter

The [`MoneyFormatter`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Formatters/MoneyFormatter.php) class can be used to format a monetary value using the store settings. The store settings may be overridden by passing options to this formatter's `format` method.

Values are returned in cents to avoid floating point rounding errors, so when using this formatter you'll most likely also be returning the currency data using the [`CurrencyFormatter`](#currencyformatter) alongside it. This will allow the consumer of the API to display the value in the intended format.

### Arguments

| Argument                    | Type     | Description                                                                                                                                                                                                                      |
| --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$value`                    | `number` | The number you want to format into a monetary value                                                                                                                                                                              |
| `$options`                  | `array`  | Should contain two keys, `decimals` which should be an `integer`,                                                                                                                                                                |
| `$options['decimals']`      | `number` | Used to control how many decimal places should be displayed in the monetary value. Defaults to the store setting.                                                                                                                |
| `$options['rounding_mode']` | `number` | Used to determine how to round the monetary value. This should be one of the PHP rounding modes described in the [PHP round() documentation](https://www.php.net/manual/en/function.round.php). Defaults to `PHP_ROUND_HALF_UP`. |

### Example use and returned value

```php
get_formatter( 'money' )->format( 10.443, [
  'rounding_mode' => PHP_ROUND_HALF_DOWN,
  'decimals'      => 2
] );
```

returns `1044`

## CurrencyFormatter

This formatter takes an array of prices, and returns the same array but with currency data appended to it. The currency data added is:

| Key                           | Type     | Description                                                                                       |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `currency_code`               | `string` | The string representation of the currency, e.g. GBP or USD                                        |
| `currency_symbol`             | `string` | The symbol of the currency, e.g. &pound; or \$                                                    |
| `currency_minor_unit`         | `number` | How many decimal places will be shown in the currency                                             |
| `currency_decimal_separator`  | `string` | The string used to separate the whole value and the decimal value in the currency.                |
| `currency_thousand_separator` | `string` | The string used to separate thousands in the currency, for example: &pound;10,000 or &euro;10.000 |
| `currency_prefix`             | `string` | A string that should appear before the currency value.                                            |
| `currency_suffix`             | `string` | A string that should appear after the currency value.                                             |

This data can then be used by the client/consumer to format prices correctly according to store settings. Important: the array of prices passed to this formatted should already be in monetary format so you should use the [`MoneyFormatter`](#moneyformatter) first.

### Arguments

| Argument | Type       | Description                                                                  |
| -------- | ---------- | ---------------------------------------------------------------------------- |
| `$value` | `number[]` | An array of prices that you want to merge with the store's currency settings |

### Example use and returned value

```php
get_formatter( 'currency' )->format( [
  'price'         => 1800,
  'regular_price' => 1800,
  'sale_price'    => 1800,
] );
```

returns

```text
'price' => '1800'
'regular_price' => '1800'
'sale_price' => '1800'
'price_range' => null
'currency_code' => 'GBP'
'currency_symbol' => '£'
'currency_minor_unit' => 2
'currency_decimal_separator' => '.'
'currency_thousand_separator' => ','
'currency_prefix' => '£'
'currency_suffix' => ''
```

## HtmlFormatter

This formatter will take an HTML value, run it through: [`wptexturize`](https://developer.wordpress.org/reference/functions/wptexturize/),
[`convert_chars`](https://developer.wordpress.org/reference/functions/convert_chars/),
[`trim`](https://www.php.net/manual/en/function.trim.php), and [`wp_kses_post`](https://developer.wordpress.org/reference/functions/wp_kses_post/)
before returning it. The purpose of this formatter is to make HTML "safe" (in terms of correctly formatted characters).
`wp_kses_post` will ensure only HTML tags allowed in the context of a `post` are present in the string.

### Arguments

| Argument | Type     | Description                                     |
| -------- | -------- | ----------------------------------------------- |
| `$value` | `string` | The string you want to format into "safe" HTML. |

### Example use and returned value

```php
get_formatter( 'html' )->format(
  "<script>alert('bad script!')</script> This \"coffee\" is <strong>very strong</strong>."
);
```

returns:

```text
alert('bad script!') This &#8220;coffee&#8221; is <strong>very strong</strong>.
```

This formatter should be used when returning HTML from the StoreAPI regardless of whether the HTML is user generated or not. This will ensure the consumer/client can display the HTML safely and without encoding issues.



---

## Updating the cart on-demand

*Source: apis/store-api/extending-store-api/extend-store-api-update-cart.md*

# Updating the cart on-demand

## The problem

You're an extension developer, and your extension does some server-side processing as a result of some client-side input, i.e. a shopper filling in an input field in the Cart sidebar, and then pressing a button.

This server-side processing causes the state of the cart to change, and you want to update the data displayed in the client-side Cart or Checkout block.

You can't simply update the client-side cart state yourself. This is restricted to prevent malfunctioning extensions inadvertently updating it with malformed or invalid data which will cause the whole block to break.

## The solution

`ExtendSchema` offers the ability for extensions to register callback functions to be executed when signalled to do so by the client-side Cart or Checkout.

WooCommerce Blocks also provides a front-end function called `extensionCartUpdate` which can be called by client-side code, this will send data (specified by you when calling `extensionCartUpdate`) to the `cart/extensions` endpoint. When this endpoint gets hit, any relevant (based on the namespace provided to `extensionCartUpdate`) callbacks get executed, and the latest server-side cart data gets returned and the block is updated with this new data.

## Basic usage

In your extension's server-side integration code:

```php
add_action('woocommerce_blocks_loaded', function() {
  woocommerce_store_api_register_update_callback(
    [
      'namespace' => 'extension-unique-namespace',
      'callback'  => /* Add your callable here */
    ]
  );
} );
```

and on the client side:

```ts
const { extensionCartUpdate } = wc.blocksCheckout;
const { processErrorResponse } = wc.wcBlocksData;

extensionCartUpdate( {
	namespace: 'extension-unique-namespace',
	data: {
		key: 'value',
		another_key: 100,
		third_key: {
			fourth_key: true,
		},
	},
} ).then( () => {
	// Cart has been updated.
} ).catch( ( error ) => {
	// Handle error.
	processErrorResponse(error);
} );
```

## Things to consider

### Extensions cannot update the client-side cart state themselves

You may be wondering why it's not possible to just make a custom AJAX endpoint for your extension that will update the cart. As mentioned, extensions are not permitted to update the client-side cart's state, because doing this incorrectly would cause the entire block to break, preventing the user from continuing their checkout. Instead you _must_ do this through the `extensionCartUpdate` function.

### Only one callback for a given namespace may be registered

With this in mind, if your extension has several client-side interactions that result in different code paths being executed on the server-side, you may wish to pass additional data through in `extensionCartUpdate`. For example if you have two actions the user can take, one to _add_ a discount, and the other to _remove_ it, you may wish to pass a key called `action` along with the other data to `extensionCartUpdate`. Then in your callback, you can check this value to distinguish which code path you should execute.

Example:

```php
<?php
function add_discount() {
  /* Do some processing here */
}

function remove_discount() {
  /* Do some processing here */
}

add_action('woocommerce_blocks_loaded', function() {
  woocommerce_store_api_register_update_callback(
    [
      'namespace' => 'extension-unique-namespace',
      'callback'  => function( $data ) {
        if ( $data['action'] === 'add' ) {
          add_discount( );
        }
        if ( $data['action'] === 'remove' ) {
          remove_discount();
        }
      }
    ]
  );
} );
```

If you try to register again, under the same namespace, the previously registered callback will be overwritten.

## API Definition

### PHP

`ExtendSchema::register_update_callback`: Used to register a callback to be executed when the `cart/extensions` endpoint gets hit with a given namespace. It takes an array of arguments

| Attribute   | Type       | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `namespace` | `string`   | Yes      | The namespace of your extension. This is used to determine which extension's callbacks should be executed.                                                                                                                                                                                                                                                                                                                  |
| `callback`  | `Callable` | Yes      | The function/method (or Callable) that will be executed when the `cart/extensions` endpoint is hit with a `namespace` that matches the one supplied. The callable should take a single argument. The data passed into the callback via this argument will be an array containing whatever data you choose to pass to it. The callable does not need to return anything, if it does, then its return value will not be used. |

### JavaScript

`extensionCartUpdate`: Used to signal that you want your registered callback to be executed, and to pass data to the callback. It takes an object as its only argument.

| Attribute   | Type      | Required | Description                                                                                                                                                      |
| ----------- |-----------|----------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `namespace` | `string`  | Yes      | The namespace of your extension. This is used to determine which extension's callbacks should be executed.                                                       |
| `data`      | `Object`  | No       | The data you want to pass to your callback. Anything in the `data` key will be passed as the first (and only) argument to your callback as an associative array. |
| `overwriteDirtyCustomerData`      | `boolean` | No       | Whether to overwrite the customer data in the client with the data returned from the server, even if it is dirty (i.e. it hasn't been pushed to the server yet). |

## Putting it all together

You are the author of an extension that lets the shopper redeem points that they earn on your website for a discount on their order. There is a text field where the shopper can enter how many points they want to redeem, and a submit button that will apply the redemption.

Your extension adds these UI elements to the sidebar in the Cart and Checkout blocks using the [`DiscountsMeta`](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/available-slot-fills/) Slot.

More information on how to use Slots is available in our [Slots and Fills documentation](/docs/block-development/reference/slot-fills/).

Once implemented, the sidebar has a control added to it like this:

![image](https://user-images.githubusercontent.com/5656702/125109827-bf7c8300-e0db-11eb-9e51-59921b38a0c2.png)

### The "Redeem" button

In your UI, you are tracking the value the shopper enters into the `Enter amount` box using a React `useState` variable. The variable in this example shall be called `pointsInputValue`.

When the `Redeem` button gets clicked, you want to tell the server how many points to apply to the shopper's basket, based on what they entered into the box, apply the relevant discount, update the server-side cart, and then show the updated price in the client-side sidebar.

To do this, you will need to use `extensionCartUpdate` to tell the server you want to execute your callback, and have the new cart state loaded into the UI. The `onClick` handler of the button may look like this:

```js
const { extensionCartUpdate } = window.wc.blocksCheckout;

const buttonClickHandler = () => {
	extensionCartUpdate( {
		namespace: 'super-coupons',
		data: {
			pointsInputValue,
		},
	} );
};
```

### Registering a callback to run when the `cart/extensions` endpoint is hit

So far, we haven't registered a callback with WooCommerce Blocks yet, so when `extensionCartUpdate` causes the `cart/extensions` endpoint to get hit, nothing will happen.

Much like adding data to the Store API (described in more detail in [Exposing your data in the Store API](./extend-store-api-add-data.md).) we can add the callback by invoking the `register_update_callback` method on the `ExtendSchema` class from WooCommerce Blocks.

We have written a function called `redeem_points` which applies a discount to the WooCommerce cart. This function does not return anything. Note, the actual implementation of this function is not the focus of this document, so has been omitted. All that is important to note is that it modifies the WooCommerce cart.

```php
<?php
function redeem_points( $points ) {
  /* Do some processing here that applies a discount to the WC cart based on the value of $points */
}

add_action('woocommerce_blocks_loaded', function() {
  woocommerce_store_api_register_update_callback(
    [
      'namespace' => 'super-coupons',
      'callback'  => function( $data ) {
        redeem_points( $data['points'] );
      },
    ]
  );
} );
```

Now that this is registered, when the button is pressed, the `cart/extensions` endpoint is hit, with a `namespace` of `super-coupons` our `redeem_points` function will be executed. After this has finished processing, the client-side cart will be updated by WooCommerce Blocks.



---

## Store API Guiding principles

*Source: apis/store-api/guiding-principles.md*

# Store API Guiding principles 

The following principles should be considered when extending, creating, or updating endpoints in the Store API.

## Routes must include a [well-defined JSON schema](https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/)

Each route/endpoint requires a particular structure of input data and should return data using a defined and predictable structure. This is defined in the JSON schema, which contains a comprehensive list of all of the properties the API can return and which input parameters it can accept.

Well-defined schema also provides a layer of security, as it enables us to validate and sanitize the requests being made to the API.

When defining schema, take note of the [WordPress REST API handbook](https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/) which documents available properties and types, as well as the [JSON schema standard](http://json-schema.org/). In addition to this:

* Properties should use snake_case 🐍
* Ambiguous terms should be avoided, and property names should try to use understandable language, rather than "WooCommerce" terminology or setting names
* Properties should be defined using US English, but the descriptions of fields should be localized
* Multiple types are permitted, for example, using a `null` type if a value is not applicable
* `sanitize_callback` and `validate_callback` are encouraged where possible to ensure data is received in the correct format before processing requests

If you’re struggling to define a consistent schema, your approach may be flawed. A common real-world example of this would be representing something like _Post Tags_. It may be tempting to use the Slug as the property field name in the response:

```php
tags: [
  "my-tag": {
    // ...tag data
  },
  "my-other-tag": {
    // ...tag data
  }
]
```

However, this is difficult to represent in Schema and is not predictable for the client. A better approach would be to use an array of data, with one of the properties being the Slug:

```php
tags: [
  {
    "slug": "my-tag",
    // ...tag data
  },
  {
    "slug": "my-other-tag",
    // ...tag data
  }
]
```

## Routes should be designed around resources with a single type of schema

Routes should be designed around resources (nouns) rather than operations (verbs). Routes should also return only one type of data defined by their Schema. For example:

| Route                    | Resource type | Expected data               |
| ------------------------ | ------------- | --------------------------- |
| `wc/store/v1/cart`       | Cart          | A cart object               |
| `wc/store/v1/cart/items` | Cart Item     | A list of cart item objects |
| `wc/store/v1/products`   | Product       | A list of product objects   |
| `wc/store/v1/products/1` | Product       | A product object            |

There are 2 notable exceptions to this rule in the Store API; _Errors_ and _Cart Operations_.

### Error Handling

Errors, including validation errors, should return an error response code (4xx or 5xx) and a [`WP_Error` object](https://developer.wordpress.org/reference/classes/wp_error/). The `AbstractRoute` class will handle the conversion of the `WP_Error` object into a valid JSON response.

Error messages should be localized, but do not need to be written with language aimed at customers (clients should use the given error code to create customer-facing notices as needed).

Error codes should have the prefix `woocommerce_rest_`.

### Cart Operations

Some endpoints are designed around operations to avoid clients needing to make multiple round trips to the API. This is purely for convenience.

An example would be the `wc/store/v1/cart/add-item` endpoint which accepts a quantity and product ID, but returns a full cart object, rather than just an updated list of items.

## Exposed data must belong to the current user or be non-sensitive

Resources, including customer and order data, should reflect only the current session. Do not return data for other customers as this would be a breach of privacy and security issue.

Store data such as settings (for example, store currency) is permitted in responses, but _private or sensitive data_ must be avoided. To allow more extensive access to data, you must use the authenticated [WC REST API](/docs/apis/rest-api/).

Data returned from the API should not be [escaped](https://developer.wordpress.org/themes/theme-security/data-sanitization-escaping/) (this is left to the client rendering it), but it should be sanitized. For example, HTML should be run through [`wp_kses_post`](https://developer.wordpress.org/reference/functions/wp_kses_post/).

It is the client’s responsibility to properly escape data that comes from the API, but we should try to avoid returning data that is potentially unsafe.

## Collections of resources should be paginated

Large volumes of data should be paginated to avoid overwhelming the server. For example, returning a collection of products.

* Use the response Headers `X-WP-Total`, `X-WP-TotalPages`, and Link to indicate available resources.
* Use parameters `page` and `per_page` to retrieve certain pages.
* The maximum allowed value for `per_page` is 100.

## API Responses should use standard HTTP status codes

When returning content, use a valid HTTP response code such as:

* `200 OK` for successful responses (this is the default response code).
* `201 Created` when creating a resource, for example, adding a new cart item or applying a new coupon.
* `204 No Content` for successful deletes.
* `400 Bad Request` when a required parameter is not set.
* `403 Forbidden` when a request is not allowed, for example, if the provided security nonce is invalid.
* `404 Not Found` if a resource does not exist.
* `409 Conflict` if a resource cannot be updated, for example, if something in the cart is invalid and removed during the request.

A note on `DELETE` requests, a common pattern in the WordPress REST API is to return the deleted object. In the case of the Store API, we opt to return an empty response with status code `204 No Content` instead. This is more efficient.

[A full list of HTTP status codes can be found here.](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)

## Breaking changes should be avoided where possible

The Store API establishes a contract between itself and API consumers via the use of Schema. This contract should not be broken unless absolutely necessary. If a breaking change were necessary, a new version of the Store API would need to be released.

A breaking change is anything that changes the format of existing Schema, removes a Schema property, removes an existing route, or makes a backwards-incompatible change to anything public that may already be in use by consumers. Breaking changes can be avoided by [deprecating existing properties](http://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.3) rather than removing them, or [deprecating routes](https://datatracker.ietf.org/doc/html/rfc8594) and replacing them with a different route if major changes are needed.

Non-breaking changes are always permitted without the need to increase the API version. Some examples of these include:

* Adding new properties to schema
* Adding new routes, endpoints, methods
* Adding optional request parameters
* Re-ordering response fields

The version will not increase for bug fixes unless the scope of the bug causes a backwards-incompatible change. Fixes would not be rolled back to past API versions with the exception of security issues that require backporting.


---

## Nonce Tokens

*Source: apis/store-api/nonce-tokens.md*

# Nonce Tokens 

Nonces are generated numbers used to verify origin and intent of requests for security purposes. You can read more about [nonces in the WordPress codex](https://developer.wordpress.org/apis/security/nonces/).

## Store API Endpoints that Require Nonces

POST requests to the `/cart` endpoints and all requests to the `/checkout` endpoints require a nonce to function. Failure to provide a valid nonce will return an error response, unless you're using [Cart Tokens](/docs/apis/store-api/cart-tokens) instead.

## Sending Nonce Tokens with requests

Nonce tokens are included with the request headers. Create a request header named `Nonce`. This will be validated by the API.

**Example:**

```sh
curl --header "Nonce: 12345" --request GET https://example-store.com/wp-json/wc/store/v1/checkout
```

After making a successful request, an updated `Nonce` header will be sent back--this needs to be stored and updated by the client to make subsequent requests.

## Generating security nonces from WordPress

Nonces must be created using the [`wp_create_nonce` function](https://developer.wordpress.org/reference/functions/wp_create_nonce/) with the key `wc_store_api`.

```php
wp_create_nonce( 'wc_store_api' )
```

There is no other mechanism in place for creating nonces.

## Disabling Nonces for Development

If you want to test REST endpoints without providing a nonce, you can use the following filter:

```php
add_filter( 'woocommerce_store_api_disable_nonce_check', '__return_true' );
```

Nonce checks will be bypassed if `woocommerce_store_api_disable_nonce_check` evaluates to `true`.

NOTE: This should only be done on development sites where security is not important. Do not enable this in production.


---

## Rate Limiting for Store API endpoints

*Source: apis/store-api/rate-limiting.md*

# Rate Limiting for Store API endpoints 

[Rate Limiting](https://github.com/woocommerce/woocommerce-blocks/pull/5962) is available for Store API endpoints. This is optional and disabled by default. It can be enabled by following [these instructions](#rate-limiting-options-filter).

The main purpose prevent abuse on endpoints from excessive calls and performance degradation on the machine running the store.

Rate limit tracking is controlled by either `USER ID` (logged in), `IP ADDRESS` (unauthenticated requests) or filter defined logic to fingerprint and group requests.

It also offers standard support for running behind a proxy, load balancer, etc. This also optional and disabled by default.

## UI Control

Currently, this feature is only controlled via the `woocommerce_store_api_rate_limit_options` filter. To control it via a UI, you can use the following community plugin: [Rate Limiting UI for WooCommerce](https://wordpress.org/plugins/rate-limiting-ui-for-woocommerce/).

## Checkout rate limiting

You can enable rate limiting for Checkout place order and `POST /checkout` endpoint only via the UI by going to WooCommerce -> Settings -> Advanced -> Features and enabling "Rate limiting Checkout block and Store API".

When enabled via the UI, the rate limiting will only be applied to the `POST /checkout` and Place Order flow for Checkout block. The limit will be a maximum of 3 requests per 60 seconds.

## Limit information

A default maximum of 25 requests can be made within a 10-second time frame. These can be changed through an [options filter](#rate-limiting-options-filter).

## Methods restricted by Rate Limiting

Only `POST` requests are rate limited. Requests using the `X-HTTP-Method-Override` header (such as `PUT`, `PATCH` requests sent via `wp.apiFetch`) are excluded from rate limiting.

## Rate Limiting options filter

A filter is available for setting options for rate limiting:

```php
add_filter( 'woocommerce_store_api_rate_limit_options', function() {
	return [
		'enabled' => false, // enables/disables Rate Limiting. Default: false
		'proxy_support' => false, // enables/disables Proxy support. Default: false
		'limit' => 25, // limit of request per timeframe. Default: 25
		'seconds' => 10, // timeframe in seconds. Default: 10
	];
} );
```

## Proxy standard support

If the Store is running behind a proxy, load balancer, cache service, CDNs, etc. keying limits by IP is supported through standard IP forwarding headers, namely:

* `X_REAL_IP`|`CLIENT_IP` _Custom popular implementations that simplify obtaining the origin IP for the request_
* `X_FORWARDED_FOR` _De-facto standard header for identifying the originating IP, [Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)_
* `X_FORWARDED` _[Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [RFC 7239](https://datatracker.ietf.org/doc/html/rfc7239)_

This is disabled by default.

## Enable Rate Limit by request custom fingerprinting

For more advanced use cases, you can enable rate limiting by custom fingerprinting.
This allows for a custom implementation to group requests without relying on logged-in User ID or IP Address.

### Custom basic example for grouping requests by User-Agent and Accept-Language combination

```php
add_filter( 'woocommerce_store_api_rate_limit_id', function() {
    $accept_language = isset( $_SERVER['HTTP_ACCEPT_LANGUAGE'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_ACCEPT_LANGUAGE'] ) ) : '';
    
    return md5( wc_get_user_agent() . $accept_language );
} );
```

## Limit usage information observability

Current limit information can be observed via custom response headers:

* `RateLimit-Limit` _Maximum requests per time frame._
* `RateLimit-Remaining` _Requests available during current time frame._
* `RateLimit-Reset` _Unix timestamp of next time frame reset._
* `RateLimit-Retry-After` _Seconds until requests are unblocked again. Only shown when the limit is reached._

### Response headers example

```http
RateLimit-Limit: 5
RateLimit-Remaining: 0
RateLimit-Reset: 1654880642
RateLimit-Retry-After: 28
```

## Tracking limit abuses

This uses a modified wc_rate_limit table with an additional remaining column for tracking the request count in any given request window.
A custom action `woocommerce_store_api_rate_limit_exceeded` was implemented for extendability in tracking such abuses.

### Custom tracking usage example

```php
add_action(
    'woocommerce_store_api_rate_limit_exceeded',
    function ( $offending_ip, $action_id ) { /* Custom tracking implementation */ }
);
```


---

## Cart Coupons API

*Source: apis/store-api/resources-endpoints/cart-coupons.md*

# Cart Coupons API 

## List Cart Coupons

```http
GET /cart/coupons
```

There are no parameters required for this endpoint.

```sh
curl "https://example-store.com/wp-json/wc/store/v1/cart/coupons"
```

**Example response:**

```json
[
	{
		"code": "20off",
		"type": "fixed_cart",
		"totals": {
			"currency_code": "GBP",
			"currency_symbol": "£",
			"currency_minor_unit": 2,
			"currency_decimal_separator": ".",
			"currency_thousand_separator": ",",
			"currency_prefix": "£",
			"currency_suffix": "",
			"total_discount": "1667",
			"total_discount_tax": "333"
		},
		"_links": {
			"self": [
				{
					"href": "http://local.wordpress.test/wp-json/wc/store/v1/cart/coupons/20off"
				}
			],
			"collection": [
				{
					"href": "http://local.wordpress.test/wp-json/wc/store/v1/cart/coupons"
				}
			]
		}
	}
]
```

## Single Cart Coupon

Get a single cart coupon.

```http
GET /cart/coupons/:code
```

| Attribute | Type   | Required | Description                                     |
| :-------- | :----- | :------: | :---------------------------------------------- |
| `code`    | string |   Yes    | The coupon code of the cart coupon to retrieve. |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/cart/coupons/20off"
```

**Example response:**

```json
{
	"code": "halfprice",
	"type": "percent",
	"totals": {
		"currency_code": "GBP",
		"currency_symbol": "£",
		"currency_minor_unit": 2,
		"currency_decimal_separator": ".",
		"currency_thousand_separator": ",",
		"currency_prefix": "£",
		"currency_suffix": "",
		"total_discount": "9950",
		"total_discount_tax": "0"
	}
}
```

## Add Cart Coupon

Apply a coupon to the cart. Returns the new coupon object that was applied, or an error if it was not applied.

```http
POST /cart/coupons/
```

| Attribute | Type   | Required | Description                                    |
| :-------- | :----- | :------: | :--------------------------------------------- |
| `code`    | string |   Yes    | The coupon code you wish to apply to the cart. |

```sh
curl --request POST https://example-store.com/wp-json/wc/store/v1/cart/coupons?code=20off
```

**Example response:**

```json
{
	"code": "20off",
	"type": "percent",
	"totals": {
		"currency_code": "GBP",
		"currency_symbol": "£",
		"currency_minor_unit": 2,
		"currency_decimal_separator": ".",
		"currency_thousand_separator": ",",
		"currency_prefix": "£",
		"currency_suffix": "",
		"total_discount": "1667",
		"total_discount_tax": "333"
	}
}
```

## Delete Single Cart Coupon

Delete/remove a coupon from the cart.

```http
DELETE /cart/coupons/:code
```

| Attribute | Type   | Required | Description                                       |
| :-------- | :----- | :------: | :------------------------------------------------ |
| `code`    | string |   Yes    | The coupon code you wish to remove from the cart. |

```sh
curl --request DELETE https://example-store.com/wp-json/wc/store/v1/cart/coupons/20off
```

## Delete All Cart Coupons

Delete/remove all coupons from the cart.

```http
DELETE /cart/coupons/
```

There are no parameters required for this endpoint.

```sh
curl --request DELETE https://example-store.com/wp-json/wc/store/v1/cart/coupons
```

**Example response:**

```json
[]
```


---

## Cart Items API

*Source: apis/store-api/resources-endpoints/cart-items.md*

# Cart Items API

## List Cart Items

```http
GET /cart/items
```

There are no extra parameters needed to use this endpoint.

```sh
curl "https://example-store.com/wp-json/wc/store/v1/cart/items"
```

**Example response:**

```json
[
	{
		"key": "c74d97b01eae257e44aa9d5bade97baf",
		"id": 16,
		"quantity": 1,
		"type": "simple",
		"quantity_limits": {
			"minimum": 1,
			"maximum": 1,
			"multiple_of": 1,
			"editable": false
		},
		"name": "Beanie",
		"short_description": "<p>This is a simple product.</p>",
		"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
		"sku": "woo-beanie",
		"low_stock_remaining": null,
		"backorders_allowed": false,
		"show_backorder_badge": false,
		"sold_individually": true,
		"permalink": "https://store.local/product/beanie/",
		"images": [
			{
				"id": 45,
				"src": "https://store.local/wp-content/uploads/2023/01/beanie-2.jpg",
				"thumbnail": "https://store.local/wp-content/uploads/2023/01/beanie-2-450x450.jpg",
				"srcset": "https://store.local/wp-content/uploads/2023/01/beanie-2.jpg 801w, https://store.local/wp-content/uploads/2023/01/beanie-2-450x450.jpg 450w, https://store.local/wp-content/uploads/2023/01/beanie-2-100x100.jpg 100w, https://store.local/wp-content/uploads/2023/01/beanie-2-600x600.jpg 600w, https://store.local/wp-content/uploads/2023/01/beanie-2-300x300.jpg 300w, https://store.local/wp-content/uploads/2023/01/beanie-2-150x150.jpg 150w, https://store.local/wp-content/uploads/2023/01/beanie-2-768x768.jpg 768w",
				"sizes": "(max-width: 801px) 100vw, 801px",
				"name": "beanie-2.jpg",
				"alt": ""
			}
		],
		"variation": [],
		"item_data": [],
		"prices": {
			"price": "1800",
			"regular_price": "2000",
			"sale_price": "1800",
			"price_range": null,
			"currency_code": "USD",
			"currency_symbol": "$",
			"currency_minor_unit": 2,
			"currency_decimal_separator": ".",
			"currency_thousand_separator": ",",
			"currency_prefix": "$",
			"currency_suffix": "",
			"raw_prices": {
				"precision": 6,
				"price": "18000000",
				"regular_price": "20000000",
				"sale_price": "18000000"
			}
		},
		"totals": {
			"line_subtotal": "1800",
			"line_subtotal_tax": "360",
			"line_total": "1800",
			"line_total_tax": "360",
			"currency_code": "USD",
			"currency_symbol": "$",
			"currency_minor_unit": 2,
			"currency_decimal_separator": ".",
			"currency_thousand_separator": ",",
			"currency_prefix": "$",
			"currency_suffix": ""
		},
		"catalog_visibility": "visible",
		"extensions": {},
		"_links": {
			"self": [
				{
					"href": "https://store.local/wp-json/wc/store/v1/cart/items/c74d97b01eae257e44aa9d5bade97baf"
				}
			],
			"collection": [
				{
					"href": "https://store.local/wp-json/wc/store/v1/cart/items"
				}
			]
		}
	},
	{
		"key": "e03e407f41901484125496b5ec69a76f",
		"id": 29,
		"quantity": 1,
		"type": "variation",
		"quantity_limits": {
			"minimum": 1,
			"maximum": 9999,
			"multiple_of": 1,
			"editable": true
		},
		"name": "Hoodie",
		"short_description": "",
		"description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum sagittis orci ac odio dictum tincidunt. Donec ut metus leo. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed luctus, dui eu sagittis sodales, nulla nibh sagittis augue, vel porttitor diam enim non metus. Vestibulum aliquam augue neque. Phasellus tincidunt odio eget ullamcorper efficitur. Cras placerat ut turpis pellentesque vulputate. Nam sed consequat tortor. Curabitur finibus sapien dolor. Ut eleifend tellus nec erat pulvinar dignissim. Nam non arcu purus. Vivamus et massa massa.</p>",
		"sku": "woo-hoodie-red",
		"low_stock_remaining": null,
		"backorders_allowed": false,
		"show_backorder_badge": false,
		"sold_individually": false,
		"permalink": "https://store.local/product/hoodie/?attribute_pa_color=red&attribute_logo=No",
		"images": [
			{
				"id": 40,
				"src": "https://store.local/wp-content/uploads/2023/01/hoodie-2.jpg",
				"thumbnail": "https://store.local/wp-content/uploads/2023/01/hoodie-2-450x450.jpg",
				"srcset": "https://store.local/wp-content/uploads/2023/01/hoodie-2.jpg 801w, https://store.local/wp-content/uploads/2023/01/hoodie-2-450x450.jpg 450w, https://store.local/wp-content/uploads/2023/01/hoodie-2-100x100.jpg 100w, https://store.local/wp-content/uploads/2023/01/hoodie-2-600x600.jpg 600w, https://store.local/wp-content/uploads/2023/01/hoodie-2-300x300.jpg 300w, https://store.local/wp-content/uploads/2023/01/hoodie-2-150x150.jpg 150w, https://store.local/wp-content/uploads/2023/01/hoodie-2-768x768.jpg 768w",
				"sizes": "(max-width: 801px) 100vw, 801px",
				"name": "hoodie-2.jpg",
				"alt": ""
			}
		],
		"variation": [
			{
				"raw_attribute": "attribute_pa_color",
				"attribute": "Color",
				"value": "Red"
			},
			{
				"raw_attribute": "attribute_logo",
				"attribute": "Logo",
				"value": "No"
			}
		],
		"item_data": [],
		"prices": {
			"price": "4200",
			"regular_price": "4500",
			"sale_price": "4200",
			"price_range": null,
			"currency_code": "USD",
			"currency_symbol": "$",
			"currency_minor_unit": 2,
			"currency_decimal_separator": ".",
			"currency_thousand_separator": ",",
			"currency_prefix": "$",
			"currency_suffix": "",
			"raw_prices": {
				"precision": 6,
				"price": "42000000",
				"regular_price": "45000000",
				"sale_price": "42000000"
			}
		},
		"totals": {
			"line_subtotal": "4200",
			"line_subtotal_tax": "840",
			"line_total": "4200",
			"line_total_tax": "840",
			"currency_code": "USD",
			"currency_symbol": "$",
			"currency_minor_unit": 2,
			"currency_decimal_separator": ".",
			"currency_thousand_separator": ",",
			"currency_prefix": "$",
			"currency_suffix": ""
		},
		"catalog_visibility": "visible",
		"extensions": {},
		"_links": {
			"self": [
				{
					"href": "https://store.local/wp-json/wc/store/v1/cart/items/e03e407f41901484125496b5ec69a76f"
				}
			],
			"collection": [
				{
					"href": "https://store.local/wp-json/wc/store/v1/cart/items"
				}
			]
		}
	}
]
```

## Item data

Each cart item carries display metadata in `item_data`, a list of entries built by callbacks on the `woocommerce_get_item_data` filter:

| Property | Type | Description |
| --- | --- | --- |
| `raw_key` | string | Machine-readable name for the entry, set by the extension that added it. Never translated, so clients can match on it. |
| `name` | string | Name of the metadata, for display. Some extensions send `key` instead. |
| `value` | string | Value of the metadata. |
| `display` | string | Optionally, how the value should be displayed. |

`raw_key` was added in WooCommerce 11.2.0. Entries that omit it are unchanged.

Most stores return an empty list. Entries appear when an extension adds them, as Product Add-Ons, Bookings, Deposits and Gift Cards do.

Both `name` and `key` hold a label meant for a shopper to read, so both can be translated and neither is safe to match on. Use `raw_key` to find your own entry.

Every value in an entry, `raw_key` included, is passed through [`wp_kses_post()`](https://developer.wordpress.org/reference/functions/wp_kses_post/). That rewrites some characters — a bare `&` arrives as `&amp;`, so an equality check against the value you set will not match. Keep `raw_key` to lowercase letters, digits, `_`, `-` and `/`.

Extensions can add properties beyond the four above through the same filter. Note that the endpoint checks each entry as a whole: if any one property holds a value that is not a scalar (an array, an object, `null`), the **entire entry** is dropped, not just that property.

The order endpoint has an `item_data` list too, and it uses the opposite convention: there `key` is the raw metadata key and `display_key` is the label. See [Order](./order.md#item-data).

### Data you do not want displayed

`item_data` is for metadata shown next to the cart item. Anything else belongs in your `extensions` namespace on the cart item, which the Store API is built to carry. See [Cart Items](../extending-store-api/available-endpoints-to-extend.md#cart-items).

Setting `hidden` on an entry keeps it out of the cart, the mini-cart and the classic templates, so this is not broken — but it leaves the data identified only by a label field, which is a poor fit for something never shown, and any client written against the schema still receives it.

## Single Cart Item

Get a single cart item by its key.

```http
GET /cart/items/:key
```

| Attribute | Type   | Required | Description                           |
| :-------- | :----- | :------: | :------------------------------------ |
| `key`     | string |   Yes    | The key of the cart item to retrieve. |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/cart/items/c74d97b01eae257e44aa9d5bade97baf"
```

**Example response:**

```json
{
	"key": "c74d97b01eae257e44aa9d5bade97baf",
	"id": 16,
	"quantity": 1,
	"quantity_limits": {
		"minimum": 1,
		"maximum": 1,
		"multiple_of": 1,
		"editable": false
	},
	"name": "Beanie",
	"short_description": "<p>This is a simple product.</p>",
	"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
	"sku": "woo-beanie",
	"low_stock_remaining": null,
	"backorders_allowed": false,
	"show_backorder_badge": false,
	"sold_individually": true,
	"permalink": "https://store.local/product/beanie/",
	"images": [
		{
			"id": 45,
			"src": "https://store.local/wp-content/uploads/2023/01/beanie-2.jpg",
			"thumbnail": "https://store.local/wp-content/uploads/2023/01/beanie-2-450x450.jpg",
			"srcset": "https://store.local/wp-content/uploads/2023/01/beanie-2.jpg 801w, https://store.local/wp-content/uploads/2023/01/beanie-2-450x450.jpg 450w, https://store.local/wp-content/uploads/2023/01/beanie-2-100x100.jpg 100w, https://store.local/wp-content/uploads/2023/01/beanie-2-600x600.jpg 600w, https://store.local/wp-content/uploads/2023/01/beanie-2-300x300.jpg 300w, https://store.local/wp-content/uploads/2023/01/beanie-2-150x150.jpg 150w, https://store.local/wp-content/uploads/2023/01/beanie-2-768x768.jpg 768w",
			"sizes": "(max-width: 801px) 100vw, 801px",
			"name": "beanie-2.jpg",
			"alt": ""
		}
	],
	"variation": [],
	"item_data": [],
	"prices": {
		"price": "1800",
		"regular_price": "2000",
		"sale_price": "1800",
		"price_range": null,
		"currency_code": "USD",
		"currency_symbol": "$",
		"currency_minor_unit": 2,
		"currency_decimal_separator": ".",
		"currency_thousand_separator": ",",
		"currency_prefix": "$",
		"currency_suffix": "",
		"raw_prices": {
			"precision": 6,
			"price": "18000000",
			"regular_price": "20000000",
			"sale_price": "18000000"
		}
	},
	"totals": {
		"line_subtotal": "1800",
		"line_subtotal_tax": "360",
		"line_total": "1800",
		"line_total_tax": "360",
		"currency_code": "USD",
		"currency_symbol": "$",
		"currency_minor_unit": 2,
		"currency_decimal_separator": ".",
		"currency_thousand_separator": ",",
		"currency_prefix": "$",
		"currency_suffix": ""
	},
	"catalog_visibility": "visible",
	"extensions": {},
	"_links": {
		"self": [
			{
				"href": "https://store.local/wp-json/wc/store/v1/cart/items/(?P<key>[\\w-]{32})/c74d97b01eae257e44aa9d5bade97baf"
			}
		],
		"collection": [
			{
				"href": "https://store.local/wp-json/wc/store/v1/cart/items/(?P<key>[\\w-]{32})"
			}
		]
	}
}
```

## Add Cart Item

Add an item to the cart. Returns the new cart item that was added, or an error response.

```http
POST /cart/items/
```

| Attribute   | Type    | Required | Description                                                                                          |
| :---------- | :------ | :------: | :--------------------------------------------------------------------------------------------------- |
| `id`        | integer |   Yes    | The cart item product or variation ID.                                                               |
| `quantity`  | integer |   Yes    | Quantity of this item in the cart.                                                                   |
| `variation` | array   |   Yes    | Chosen attributes (for variations) containing an array of objects with keys `attribute` and `value`. |

```sh
curl --request POST https://example-store.com/wp-json/wc/store/v1/cart/items?id=100&quantity=1
```

For an example response, see [Single Cart Item](#single-cart-item).

If you're looking to add multiple items to the cart at once, please take a look at [batching](/docs/apis/store-api/resources-endpoints/cart#add-item).

## Edit Single Cart Item

Edit an item in the cart.

```http
PUT /cart/items/:key
```

| Attribute  | Type    | Required | Description                        |
| :--------- | :------ | :------: | :--------------------------------- |
| `key`      | string  |   Yes    | The key of the cart item to edit.  |
| `quantity` | integer |   Yes    | Quantity of this item in the cart. |

```sh
curl --request PUT https://example-store.com/wp-json/wc/store/v1/cart/items/e369853df766fa44e1ed0ff613f563bd?quantity=10
```

For an example response, see [Single Cart Item](#single-cart-item).

## Delete Single Cart Item

Removes an item from the cart by its key.

```http
DELETE /cart/items/:key
```

| Attribute | Type   | Required | Description                       |
| :-------- | :----- | :------: | :-------------------------------- |
| `key`     | string |   Yes    | The key of the cart item to edit. |

```sh
curl --request DELETE https://example-store.com/wp-json/wc/store/v1/cart/items/e369853df766fa44e1ed0ff613f563bd
```

## Delete All Cart Items

Removes all items from the cart at once.

```http
DELETE /cart/items/
```

There are no extra parameters needed to use this endpoint.

```sh
curl --request DELETE https://example-store.com/wp-json/wc/store/v1/cart/items
```

**Example response:**

```json
[]
```


---

## Cart API

*Source: apis/store-api/resources-endpoints/cart.md*

# Cart API 

The cart API returns the current state of the cart for the current session or logged in user.

All POST endpoints require a [Nonce Token](/docs/apis/store-api/nonce-tokens) or a [Cart Token](/docs/apis/store-api/cart-tokens) and return the updated state of the full cart once complete.

## Get Cart

```http
GET /cart
```

There are no parameters required for this endpoint.

```sh
curl "https://example-store.com/wp-json/wc/store/v1/cart"
```

Returns the full cart object response (see [Cart Response](#cart-response)).

## Responses

All endpoints under `/cart` (listed in this doc) return responses in the same format; a cart object which includes cart items, applied coupons, shipping addresses and rates, and non-sensitive customer data.

### Cart Response

```json
{
	"items": [
		{
			"key": "a5771bce93e200c36f7cd9dfd0e5deaa",
			"id": 38,
			"quantity": 1,
			"quantity_limits": {
				"minimum": 1,
				"maximum": 9999,
				"multiple_of": 1,
				"editable": true
			},
			"name": "Beanie with Logo",
			"short_description": "<p>This is a simple product.</p>",
			"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
			"sku": "Woo-beanie-logo",
			"low_stock_remaining": null,
			"backorders_allowed": false,
			"show_backorder_badge": false,
			"sold_individually": false,
			"permalink": "https://local.wordpress.test/product/beanie-with-logo/",
			"images": [
				{
					"id": 61,
					"src": "https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1.jpg",
					"thumbnail": "https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1-450x450.jpg",
					"srcset": "https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1.jpg 800w, https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1-450x450.jpg 450w, https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1-600x600.jpg 600w, https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2023/03/beanie-with-logo-1-768x768.jpg 768w",
					"sizes": "(max-width: 800px) 100vw, 800px",
					"name": "beanie-with-logo-1.jpg",
					"alt": ""
				}
			],
			"variation": [],
			"item_data": [],
			"prices": {
				"price": "1800",
				"regular_price": "2000",
				"sale_price": "1800",
				"price_range": null,
				"currency_code": "USD",
				"currency_symbol": "$",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "$",
				"currency_suffix": "",
				"raw_prices": {
					"precision": 6,
					"price": "18000000",
					"regular_price": "20000000",
					"sale_price": "18000000"
				}
			},
			"totals": {
				"line_subtotal": "1800",
				"line_subtotal_tax": "180",
				"line_total": "1530",
				"line_total_tax": "153",
				"currency_code": "USD",
				"currency_symbol": "$",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "$",
				"currency_suffix": ""
			},
			"catalog_visibility": "visible",
			"extensions": {}
		},
		{
			"key": "b6d767d2f8ed5d21a44b0e5886680cb9",
			"id": 22,
			"quantity": 1,
			"quantity_limits": {
				"minimum": 1,
				"maximum": 9999,
				"multiple_of": 1,
				"editable": true
			},
			"name": "Belt",
			"short_description": "<p>This is a simple product.</p>",
			"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
			"sku": "woo-belt",
			"low_stock_remaining": null,
			"backorders_allowed": false,
			"show_backorder_badge": false,
			"sold_individually": false,
			"permalink": "https://local.wordpress.test/product/belt/",
			"images": [
				{
					"id": 51,
					"src": "https://local.wordpress.test/wp-content/uploads/2023/03/belt-2.jpg",
					"thumbnail": "https://local.wordpress.test/wp-content/uploads/2023/03/belt-2-450x450.jpg",
					"srcset": "https://local.wordpress.test/wp-content/uploads/2023/03/belt-2.jpg 801w, https://local.wordpress.test/wp-content/uploads/2023/03/belt-2-450x450.jpg 450w, https://local.wordpress.test/wp-content/uploads/2023/03/belt-2-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2023/03/belt-2-600x600.jpg 600w, https://local.wordpress.test/wp-content/uploads/2023/03/belt-2-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2023/03/belt-2-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2023/03/belt-2-768x768.jpg 768w",
					"sizes": "(max-width: 801px) 100vw, 801px",
					"name": "belt-2.jpg",
					"alt": ""
				}
			],
			"variation": [],
			"item_data": [],
			"prices": {
				"price": "5500",
				"regular_price": "6500",
				"sale_price": "5500",
				"price_range": null,
				"currency_code": "USD",
				"currency_symbol": "$",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "$",
				"currency_suffix": "",
				"raw_prices": {
					"precision": 6,
					"price": "55000000",
					"regular_price": "65000000",
					"sale_price": "55000000"
				}
			},
			"totals": {
				"line_subtotal": "5500",
				"line_subtotal_tax": "550",
				"line_total": "4675",
				"line_total_tax": "468",
				"currency_code": "USD",
				"currency_symbol": "$",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "$",
				"currency_suffix": ""
			},
			"catalog_visibility": "visible",
			"extensions": {}
		}
	],
	"coupons": [
		{
			"code": "test",
			"discount_type": "percent",
			"totals": {
				"total_discount": "1095",
				"total_discount_tax": "109",
				"currency_code": "USD",
				"currency_symbol": "$",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "$",
				"currency_suffix": ""
			}
		}
	],
	"fees": [],
	"totals": {
		"total_items": "7300",
		"total_items_tax": "730",
		"total_fees": "0",
		"total_fees_tax": "0",
		"total_discount": "1095",
		"total_discount_tax": "110",
		"total_shipping": "1300",
		"total_shipping_tax": "130",
		"total_price": "8256",
		"total_tax": "751",
		"tax_lines": [
			{
				"name": "Tax",
				"price": "751",
				"rate": "10%"
			}
		],
		"currency_code": "USD",
		"currency_symbol": "$",
		"currency_minor_unit": 2,
		"currency_decimal_separator": ".",
		"currency_thousand_separator": ",",
		"currency_prefix": "$",
		"currency_suffix": ""
	},
	"shipping_address": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "Hello street",
		"address_2": "",
		"city": "beverly hills",
		"state": "CA",
		"postcode": "90211",
		"country": "US",
		"phone": "123456778"
	},
	"billing_address": {
		"first_name": "John",
		"last_name": "Doe",
		"company": "",
		"address_1": "Hello street",
		"address_2": "",
		"city": "beverly hills",
		"state": "CA",
		"postcode": "90211",
		"country": "US",
		"email": "checkout@templates.com",
		"phone": "123456778"
	},
	"needs_payment": true,
	"needs_shipping": true,
	"payment_requirements": [ "products" ],
	"has_calculated_shipping": true,
	"shipping_rates": [
		{
			"package_id": 0,
			"name": "Shipment 1",
			"destination": {
				"address_1": "Hello street",
				"address_2": "",
				"city": "beverly hills",
				"state": "CA",
				"postcode": "90211",
				"country": "US"
			},
			"items": [
				{
					"key": "a5771bce93e200c36f7cd9dfd0e5deaa",
					"name": "Beanie with Logo",
					"quantity": 1
				},
				{
					"key": "b6d767d2f8ed5d21a44b0e5886680cb9",
					"name": "Belt",
					"quantity": 1
				}
			],
			"shipping_rates": [
				{
					"rate_id": "flat_rate:10",
					"name": "Flat rate",
					"description": "",
					"delivery_time": "",
					"price": "1300",
					"taxes": "130",
					"instance_id": 10,
					"method_id": "flat_rate",
					"meta_data": [
						{
							"key": "Items",
							"value": "Beanie with Logo &times; 1, Belt &times; 1"
						}
					],
					"selected": true,
					"currency_code": "USD",
					"currency_symbol": "$",
					"currency_minor_unit": 2,
					"currency_decimal_separator": ".",
					"currency_thousand_separator": ",",
					"currency_prefix": "$",
					"currency_suffix": ""
				},
				{
					"rate_id": "free_shipping:12",
					"name": "Free shipping",
					"description": "",
					"delivery_time": "",
					"price": "0",
					"taxes": "0",
					"instance_id": 12,
					"method_id": "free_shipping",
					"meta_data": [
						{
							"key": "Items",
							"value": "Beanie with Logo &times; 1, Belt &times; 1"
						}
					],
					"selected": false,
					"currency_code": "USD",
					"currency_symbol": "$",
					"currency_minor_unit": 2,
					"currency_decimal_separator": ".",
					"currency_thousand_separator": ",",
					"currency_prefix": "$",
					"currency_suffix": ""
				},
				{
					"rate_id": "local_pickup:13",
					"name": "Local pickup",
					"description": "",
					"delivery_time": "",
					"price": "0",
					"taxes": "0",
					"instance_id": 13,
					"method_id": "local_pickup",
					"meta_data": [
						{
							"key": "Items",
							"value": "Beanie with Logo &times; 1, Belt &times; 1"
						}
					],
					"selected": false,
					"currency_code": "USD",
					"currency_symbol": "$",
					"currency_minor_unit": 2,
					"currency_decimal_separator": ".",
					"currency_thousand_separator": ",",
					"currency_prefix": "$",
					"currency_suffix": ""
				}
			]
		}
	],
	"items_count": 2,
	"items_weight": 0,
	"cross_sells": [],
	"errors": [],
	"payment_methods": [ "bacs", "cod" ],
	"extensions": {}
}
```

### Error Response

If a cart action cannot be performed, an error response will be returned. This will include a reason code and an error message:

```json
{
	"code": "woocommerce_rest_cart_invalid_product",
	"message": "This product cannot be added to the cart.",
	"data": {
		"status": 400
	}
}
```

Some error responses indicate conflicts (error 409), for example, when an item cannot be found or a coupon is no longer applied. When this type of response is returned, the current state of the cart from the server is also returned as part of the error data:

```json
{
  "code": "woocommerce_rest_cart_invalid_key",
  "message": "Cart item no longer exists or is invalid.",
  "data": {
    "status": 409,
    "cart": { ... }
  }
}
```

This allows the client to remain in sync with the cart data without additional requests, should the cart change or become outdated.

## Add Item

Add an item to the cart and return the full cart response, or an error.

This endpoint will return an error unless a valid [Nonce Token](/docs/apis/store-api/nonce-tokens) or [Cart Token](/docs/apis/store-api/cart-tokens) is provided.

```http
POST /cart/add-item
```

| Attribute   | Type    | Required | Description                                                                                                                               |
| :---------- | :------ | :------: | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | integer |   Yes    | The cart item product or variation ID.                                                                                                    |
| `quantity`  | integer |   Yes    | Quantity of this item in the cart.                                                                                                        |
| `variation` | array   |   Yes    | Chosen attributes (for variations) containing an array of objects with keys `attribute` and `value`. See notes on attribute naming below. |

```sh
curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/cart/add-item?id=100&quantity=1
```

Returns the full [Cart Response](#cart-response) on success, or an [Error Response](#error-response) on failure.

If you want to add supplemental cart item data before it is passed into `CartController::add_to_cart` use the [`woocommerce_store_api_add_to_cart_data`](https://github.com/woocommerce/woocommerce-blocks/blob/4d1c295a2bace9a4f6397cfd5469db31083d477a/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_store_api_add_to_cart_data) filter. For example:

```php
add_filter( 'woocommerce_store_api_add_to_cart_data', function( $add_to_cart_data, \WP_REST_Request $request ) {
	if ( ! empty( $request['custom-request-param'] ) ) {
		$add_to_cart_data['cart_item_data']['custom-request-data'] = sanitize_text_field( $request['custom-request-param'] );
	}
	return $add_to_cart_data;
}, 10, 2 );
```

**Variation attribute naming:**

When adding variations to the cart, the naming of the attribute is important.

For global attributes, the attribute posted to the API should be the slug of the attribute. This should have a `pa_` prefix. For example, if you have an attribute named `Color`, the slug will be `pa_color`.

For product specific attributes, the attribute posted to the API can be one of the following:

- the name of the attribute. For example, if you have an attribute named `Size`, the name will be `Size`. This is case-sensitive.
- the slug of the attribute. For example, if you have an attribute named `Autograph ✏️`, the name will be `attribute_autograph-%e2%9c%8f%ef%b8%8f`. This is case-sensitive. You can get this slug from the related `select` on the product page.

**Example POST body:**

```json
{
	"id": 13,
	"quantity": 1,
	"variation": [
		{
			"attribute": "pa_color",
			"value": "blue"
		},
		{
			"attribute": "attribute_autograph-%e2%9c%8f%ef%b8%8f",
			"value": "Yes"
		},
		{
			"attribute": "Logo",
			"value": "Yes"
		}
	]
}
```

The above example adds a product variation to the cart with attributes size and color.

**Batching:**

If you want to add multiple items at once, you need to use the batch endpoint:

```http
POST /wc/store/v1/batch
```

The JSON payload for adding multiple items to the cart would look like this:

```json
{
	"requests": [
		{
			"path": "/wc/store/v1/cart/add-item",
			"method": "POST",
			"cache": "no-store",
			"body": {
				"id": 26,
				"quantity": 1
			},
			"headers": {
				"Nonce": "1db1d13784"
			}
		},
		{
			"path": "/wc/store/v1/cart/add-item",
			"method": "POST",
			"cache": "no-store",
			"body": {
				"id": 27,
				"quantity": 1
			},
			"headers": {
				"Nonce": "1db1d13784"
			}
		}
	]
}
```

If a cart subrequest fails while loading its session, it returns a `500` response with the `woocommerce_rest_unknown_server_error` error code. Later cart subrequests in the same batch also return `500` instead of using the incomplete cart, while non-cart subrequests continue normally. These failed cart responses do not include `Cart-Token` or `Cart-Hash` headers.

## Remove Item

Remove an item from the cart and return the full cart response, or an error.

This endpoint will return an error unless a valid [Nonce Token](/docs/apis/store-api/nonce-tokens) or [Cart Token](/docs/apis/store-api/cart-tokens) is provided.

```http
POST /cart/remove-item
```

| Attribute | Type   | Required | Description                       |
| :-------- | :----- | :------: | :-------------------------------- |
| `key`     | string |   Yes    | The key of the cart item to edit. |

```sh
curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/cart/remove-item?key=e369853df766fa44e1ed0ff613f563bd
```

Returns the full [Cart Response](#cart-response) on success, or an [Error Response](#error-response) on failure.

## Update Item

Update an item in the cart and return the full cart response, or an error.

This endpoint will return an error unless a valid [Nonce Token](/docs/apis/store-api/nonce-tokens) or [Cart Token](/docs/apis/store-api/cart-tokens) is provided.

```http
POST /cart/update-item
```

| Attribute  | Type    | Required | Description                        |
| :--------- | :------ | :------: | :--------------------------------- |
| `key`      | string  |   Yes    | The key of the cart item to edit.  |
| `quantity` | integer |   Yes    | Quantity of this item in the cart. |

```sh
curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/cart/update-item?key=e369853df766fa44e1ed0ff613f563bd&quantity=10
```

Returns the full [Cart Response](#cart-response) on success, or an [Error Response](#error-response) on failure.

## Apply Coupon

Apply a coupon to the cart and return the full cart response, or an error.

This endpoint will return an error unless a valid [Nonce Token](/docs/apis/store-api/nonce-tokens) or [Cart Token](/docs/apis/store-api/cart-tokens) is provided.

```http
POST /cart/apply-coupon/
```

| Attribute | Type   | Required | Description                                    |
| :-------- | :----- | :------: | :--------------------------------------------- |
| `code`    | string |   Yes    | The coupon code you wish to apply to the cart. |

```sh
curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/cart/apply-coupon?code=20off
```

Returns the full [Cart Response](#cart-response) on success, or an [Error Response](#error-response) on failure.

## Remove Coupon

Remove a coupon from the cart and return the full cart response, or an error.

This endpoint will return an error unless a valid [Nonce Token](/docs/apis/store-api/nonce-tokens) or [Cart Token](/docs/apis/store-api/cart-tokens) is provided.

```http
POST /cart/remove-coupon/
```

| Attribute | Type   | Required | Description                                       |
| :-------- | :----- | :------: | :------------------------------------------------ |
| `code`    | string |   Yes    | The coupon code you wish to remove from the cart. |

```sh
curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/cart/remove-coupon?code=20off
```

Returns the full [Cart Response](#cart-response) on success, or an [Error Response](#error-response) on failure.

## Update Customer

Update customer data and return the full cart response, or an error.

This endpoint will return an error unless a valid [Nonce Token](/docs/apis/store-api/nonce-tokens) or [Cart Token](/docs/apis/store-api/cart-tokens) is provided.

```http
POST /cart/update-customer
```

| Attribute                     | Type   | Required | Description                                                                              |
| :---------------------------- | :----- | :------: | :--------------------------------------------------------------------------------------- |
| `billing_address`             | object |    no    | Customer billing address.                                                                |
| `billing_address.first_name`  | string |    no    | Customer first name.                                                                     |
| `billing_address.last_name`   | string |    no    | Customer last name.                                                                      |
| `billing_address.address_1`   | string |    no    | First line of the address being shipped to.                                              |
| `billing_address.address_2`   | string |    no    | Second line of the address being shipped to.                                             |
| `billing_address.city`        | string |    no    | City of the address being shipped to.                                                    |
| `billing_address.state`       | string |    no    | ISO code, or name, for the state, province, or district of the address being shipped to. |
| `billing_address.postcode`    | string |    no    | Zip or Postcode of the address being shipped to.                                         |
| `billing_address.country`     | string |    no    | ISO code for the country of the address being shipped to.                                |
| `billing_address.email`       | string |    no    | Email for the customer.                                                                  |
| `billing_address.phone`       | string |    no    | Phone number of the customer.                                                            |
| `shipping_address`            | object |    no    | Customer shipping address.                                                               |
| `shipping_address.first_name` | string |    no    | Customer first name.                                                                     |
| `shipping_address.last_name`  | string |    no    | Customer last name.                                                                      |
| `shipping_address.address_1`  | string |    no    | First line of the address being shipped to.                                              |
| `shipping_address.address_2`  | string |    no    | Second line of the address being shipped to.                                             |
| `shipping_address.city`       | string |    no    | City of the address being shipped to.                                                    |
| `shipping_address.state`      | string |    no    | ISO code, or name, for the state, province, or district of the address being shipped to. |
| `shipping_address.postcode`   | string |    no    | Zip or Postcode of the address being shipped to.                                         |
| `shipping_address.country`    | string |    no    | ISO code for the country of the address being shipped to.                                |

Returns the full [Cart Response](#cart-response) on success, or an [Error Response](#error-response) on failure.

## Select Shipping Rate

Selects an available shipping rate for a package, then returns the full cart response, or an error.

This endpoint will return an error unless a valid [Nonce Token](/docs/apis/store-api/nonce-tokens) or [Cart Token](/docs/apis/store-api/cart-tokens) is provided.

```http
POST /cart/select-shipping-rate
```

| Attribute    | Type    | Required | Description                                     |
| :----------- | :------ | :------: | :---------------------------------------------- |
| `package_id` | integer |   yes    | The ID of the shipping package within the cart. |
| `rate_id`    | string  |   yes    | The chosen rate ID for the package.             |

```sh
curl --header "Nonce: 12345" --request POST /cart/select-shipping-rate?package_id=1&rate_id=flat_rate:1
```

Returns the full [Cart Response](#cart-response) on success, or an [Error Response](#error-response) on failure.


---

## Checkout order API

*Source: apis/store-api/resources-endpoints/checkout-order.md*

# Checkout order API 

The checkout order API facilitates the processing of existing orders and handling payments.

All checkout order endpoints require a [Nonce Token](/docs/apis/store-api/nonce-tokens) or a [Cart Token](/docs/apis/store-api/cart-tokens) otherwise these endpoints will return an error.

## Process Order and Payment

Accepts the final chosen payment method, and any additional payment data, then attempts payment and
returns the result.

```http
POST /wc/store/v1/checkout/{ORDER_ID}
```

| Attribute          | Type   | Required | Description                                                         |
| :----------------- | :----- | :------: | :------------------------------------------------------------------ |
| `key`              | string |   Yes    | The key for the order verification.                                 |
| `billing_email`    | string |   No     | The email address used to verify guest orders.                      |
| `billing_address`  | object |   Yes    | Object of updated billing address data for the customer.            |
| `shipping_address` | object |   Yes    | Object of updated shipping address data for the customer.           |
| `payment_method`   | string |   Yes    | The ID of the payment method being used to process the payment.     |
| `payment_data`     | array  |    No    | Data to pass through to the payment method when processing payment. |

```sh
curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/checkout/{ORDER_ID} -d '{"key":"wc_order_oFmQYREzh9Tfv","billing_email":"admin@example.com","payment_method":"cheque","billing_address":{...},"shipping_address":{...}'
```

**Example request:**

```json
{
	"key": "wc_order_oFmQYREzh9Tfv",
	"billing_email": "admin@example.com",
	"billing_address": {
		"first_name": "Peter",
		"last_name": "Venkman",
		"company": "",
		"address_1": "550 Central Park West",
		"address_2": "Corner Penthouse Spook Central",
		"city": "New York",
		"state": "NY",
		"postcode": "10023",
		"country": "US",
		"email": "admin@example.com",
		"phone": "555-2368"
	},
	"shipping_address": {
		"first_name": "Peter",
		"last_name": "Venkman",
		"company": "",
		"address_1": "550 Central Park West",
		"address_2": "Corner Penthouse Spook Central",
		"city": "New York",
		"state": "NY",
		"postcode": "10023",
		"country": "US",
		"phone": "555-2368"
	},
	"payment_method": "cheque",
	"payment_data": []
}
```

**Example response:**

```json
{
	"order_id": 146,
	"status": "on-hold",
	"order_key": "wc_order_oFmQYREzh9Tfv",
	"customer_note": "",
	"customer_id": 1,
	"billing_address": {
		"first_name": "Peter",
		"last_name": "Venkman",
		"company": "",
		"address_1": "550 Central Park West",
		"address_2": "Corner Penthouse Spook Central",
		"city": "New York",
		"state": "NY",
		"postcode": "10023",
		"country": "US",
		"email": "admin@example.com",
		"phone": "555-2368"
	},
	"shipping_address": {
		"first_name": "Peter",
		"last_name": "Venkman",
		"company": "",
		"address_1": "550 Central Park West",
		"address_2": "Corner Penthouse Spook Central",
		"city": "New York",
		"state": "NY",
		"postcode": "10023",
		"country": "US",
		"phone": "555-2368"
	},
	"payment_method": "cheque",
	"payment_result": {
		"payment_status": "success",
		"payment_details": [],
		"redirect_url": "https://local.wordpress.test/block-checkout/order-received/146/?key=wc_order_VPffqyvgWVqWL"
	}
}
```

## Payment Data

There are many payment gateways available for merchants to use, and each one will be expecting different `payment_data`. We cannot comprehensively list all expected requests for all payment gateways, and we would recommend reaching out to the authors of the payment gateway plugins you're working with for further information.

An example of the payment data sent to the Checkout Order endpoint when using the [WooCommerce Stripe Payment Gateway](https://wordpress.org/plugins/woocommerce-gateway-stripe/) is shown below.

For further information on generating a `stripe_source` please check [the Stripe documentation](https://stripe.com/docs).

```json
{
	"payment_data": [
		{
			"key": "stripe_source",
			"value": "src_xxxxxxxxxxxxx"
		},
		{
			"key": "billing_email",
			"value": "myemail@email.com"
		},
		{
			"key": "billing_first_name",
			"value": "Jane"
		},
		{
			"key": "billing_last_name",
			"value": "Doe"
		},
		{
			"key": "paymentMethod",
			"value": "stripe"
		},
		{
			"key": "paymentRequestType",
			"value": "cc"
		},
		{
			"key": "wc-stripe-new-payment-method",
			"value": true
		}
	]
}
```


---

## Checkout API

*Source: apis/store-api/resources-endpoints/checkout.md*

# Checkout API 

The checkout API facilitates the creation of orders (from the current cart) and handling payments for payment methods.

All checkout endpoints require either a [Nonce Token](/docs/apis/store-api/nonce-tokens) or a [Cart Token](/docs/apis/store-api/cart-tokens) otherwise these endpoints will return an error.

## Get Checkout Data

Returns data required for the checkout. This includes a draft order (created from the current cart) and customer billing and shipping addresses. The payment information will be empty, as it's only persisted when the order gets updated via POST requests (right before payment processing).

```http
GET /wc/store/v1/checkout
```

There are no parameters required for this endpoint.

```sh
curl --header "Nonce: 12345" --request GET https://example-store.com/wp-json/wc/store/v1/checkout
```

### Example Response

```json
{
  "order_id": 146,
  "status": "checkout-draft",
  "order_key": "wc_order_VPffqyvgWVqWL",
  "customer_note": "",
  "customer_id": 1,
  "billing_address": {
    "first_name": "Peter",
    "last_name": "Venkman",
    "company": "",
    "address_1": "550 Central Park West",
    "address_2": "Corner Penthouse Spook Central",
    "city": "New York",
    "state": "NY",
    "postcode": "10023",
    "country": "US",
    "email": "admin@example.com",
    "phone": "555-2368"
  },
  "shipping_address": {
    "first_name": "Peter",
    "last_name": "Venkman",
    "company": "",
    "address_1": "550 Central Park West",
    "address_2": "Corner Penthouse Spook Central",
    "city": "New York",
    "state": "NY",
    "postcode": "10023",
    "country": "US"
  },
  "payment_method": "",
  "payment_result": {
    "payment_status": "",
    "payment_details": [],
    "redirect_url": ""
  }
}
```

## Update checkout data

This endpoint allows you to update the checkout data for the current order. This can be called from the frontend to persist checkout fields, for example.

```http
PUT /wc/store/v1/checkout?__experimental_calc_totals=true
```

Note the `__experimental_calc_totals` parameter. This is used to determine if the cart totals should be recalculated. This should be set to true if the cart totals are being updated in response to a PUT request, false otherwise.

| Attribute           | Type   | Required | Description                                         |
| :------------------ | :----- | :------: | :-------------------------------------------------- |
| `additional_fields` | object |    No    | Name => value pairs of additional fields to update. |
| `payment_method`    | string |    No    | The ID of the payment method selected.              |
| `order_notes`       | string |    No    | Order notes.                                        |

```sh
curl --header "Nonce: 12345" --request PUT https://example-store.com/wp-json/wc/store/v1/checkout?additional_fields[plugin-namespace/leave-on-porch]=true&additional_fields[plugin-namespace/location-on-porch]=dsdd&payment_method=bacs&order_notes=Please%20leave%20package%20on%20back%20porch
```

### Example Request

```json
{
  "additional_fields": {
    "plugin-namespace/leave-on-porch": true,
    "plugin-namespace/location-on-porch": "dsdd"
  },
  "payment_method": "bacs",
  "order_notes": "Please leave package on back porch"
}
```

### Example Response

```json
{
    "order_id": 1486,
    "status": "checkout-draft",
    "order_key": "wc_order_KLpMaJ054PVlb",
    "order_number": "1486",
    "customer_note": "",
    "customer_id": 1,
    "billing_address": {
        "first_name": "Peter",
        "last_name": "Venkman",
        "company": "",
        "address_1": "550 Central Park West",
        "address_2": "Corner Penthouse Spook Central",
        "city": "New York",
        "state": "NY",
        "postcode": "10023",
        "country": "US",
        "email": "admin@example.com",
        "phone": "555-2368"
    },
    "shipping_address": {
        "first_name": "Peter",
        "last_name": "Venkman",
        "company": "",
        "address_1": "550 Central Park West",
        "address_2": "Corner Penthouse Spook Central",
        "city": "New York",
        "state": "NY",
        "postcode": "10023",
        "country": "US"
    },
    "payment_method": "bacs",
    "payment_result": null,
    "additional_fields": {
        "plugin-namespace/leave-on-porch": true,
        "plugin-namespace/location-on-porch": "dsdd"
    },
    "__experimentalCart": { ... },
    "extensions": {}
}
```

Note the `__experimentalCart` field that is returned as part of the response. Totals will be updated on the front-end following a PUT request. This makes it possible to manipulate cart totals in response to fields persisted via the PUT request.

## Process Order and Payment

Accepts the final customer addresses and chosen payment method, and any additional payment data, then attempts payment and
returns the result.

```http
POST /wc/store/v1/checkout
```

| Attribute           | Type   | Required | Description                                                         |
| :------------------ | :----- | :------: | :------------------------------------------------------------------ |
| `billing_address`   | object |   Yes    | Object of updated billing address data for the customer.            |
| `shipping_address`  | object |   Yes    | Object of updated shipping address data for the customer.           |
| `customer_note`     | string |    No    | Note added to the order by the customer during checkout.            |
| `payment_method`    | string |   Yes    | The ID of the payment method being used to process the payment.     |
| `payment_data`      | array  |    No    | Data to pass through to the payment method when processing payment. |
| `customer_password` | string |    No    | Optionally define a password for new accounts.                      |
| `expected_total`    | string |    No    | Total the shopper confirmed, in minor units. See note below.        |

`expected_total` is a string in the smallest unit of the store currency (e.g. cents), matching the cart `totals.total_price` format. When provided, the order is rejected with a `409` (`woocommerce_rest_checkout_total_mismatch`) if the total the server calculates for the request no longer matches it, and the refreshed cart is returned so the client can display the updated total. Omit it to skip the check — e.g. for flows that cannot know the final total up front, such as some express payment methods.

```sh
curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/checkout?payment_method=paypal&payment_data[0][key]=test-key&payment_data[0][value]=test-value
```

### Example Request

```json
{
  "billing_address": {
    "first_name": "Peter",
    "last_name": "Venkman",
    "company": "",
    "address_1": "550 Central Park West",
    "address_2": "Corner Penthouse Spook Central",
    "city": "New York",
    "state": "NY",
    "postcode": "10023",
    "country": "US",
    "email": "admin@example.com",
    "phone": "555-2368"
  },
  "shipping_address": {
    "first_name": "Peter",
    "last_name": "Venkman",
    "company": "",
    "address_1": "550 Central Park West",
    "address_2": "Corner Penthouse Spook Central",
    "city": "New York",
    "state": "NY",
    "postcode": "10023",
    "country": "US"
  },
  "customer_note": "Test notes on order.",
  "create_account": false,
  "payment_method": "cheque",
  "payment_data": [],
  "extensions": {
    "some-extension-name": {
      "some-data-key": "some data value"
    }
  }
}
```

### Example Response

```json
{
  "order_id": 146,
  "status": "on-hold",
  "order_key": "wc_order_VPffqyvgWVqWL",
  "customer_note": "",
  "customer_id": 1,
  "billing_address": {
    "first_name": "Peter",
    "last_name": "Venkman",
    "company": "",
    "address_1": "550 Central Park West",
    "address_2": "Corner Penthouse Spook Central",
    "city": "New York",
    "state": "NY",
    "postcode": "10023",
    "country": "US",
    "email": "admin@example.com",
    "phone": "555-2368"
  },
  "shipping_address": {
    "first_name": "Peter",
    "last_name": "Venkman",
    "company": "",
    "address_1": "550 Central Park West",
    "address_2": "Corner Penthouse Spook Central",
    "city": "New York",
    "state": "NY",
    "postcode": "10023",
    "country": "US"
  },
  "payment_method": "cheque",
  "payment_result": {
    "payment_status": "success",
    "payment_details": [],
    "redirect_url": "https://local.wordpress.test/block-checkout/order-received/146/?key=wc_order_VPffqyvgWVqWL"
  }
}
```

## Payment Data

There are many payment gateways available for merchants to use, and each one will be expecting different `payment_data`. We cannot comprehensively list all expected requests for all payment gateways, and we would recommend reaching out to the authors of the payment gateway plugins you're working with for further information.

An example of the payment data sent to the Checkout endpoint when using the [WooCommerce Stripe Payment Gateway](https://wordpress.org/plugins/woocommerce-gateway-stripe/) is shown below.

For further information on generating a `stripe_source` please check [the Stripe documentation](https://stripe.com/docs).

```json
{
  "payment_data": [
    {
      "key": "stripe_source",
      "value": "src_xxxxxxxxxxxxx"
    },
    {
      "key": "billing_email",
      "value": "myemail@email.com"
    },
    {
      "key": "billing_first_name",
      "value": "Jane"
    },
    {
      "key": "billing_last_name",
      "value": "Doe"
    },
    {
      "key": "paymentMethod",
      "value": "stripe"
    },
    {
      "key": "paymentRequestType",
      "value": "cc"
    },
    {
      "key": "wc-stripe-new-payment-method",
      "value": true
    }
  ]
}
```


---

## Order API

*Source: apis/store-api/resources-endpoints/order.md*

# Order API 

The order API returns the pay-for-order order.

## Get Order

```http
GET /order/{ORDER_ID}?key={KEY}&billing_email={BILLING_EMAIL}
```

There is one required parameter for this endpoint which is `key`. `billing_email` must be added for guest orders.

```sh
curl "https://example-store.com/wp-json/wc/store/v1/order/{ORDER_ID}?key={KEY}&billing_email={BILLING_EMAIL}"
```

Returns the full order object response (see [Order Response](#order-response)).

## Responses

Order endpoints return responses in the same format as `/cart`; an order object which includes order items, applied coupons, shipping addresses and rates, and non-sensitive customer data.

One difference worth calling out is `item_data`. Order items carry stored order item metadata; cart items carry display data from the `woocommerce_get_item_data` filter. Both are lists, but the entries hold different properties. See [Item data](#item-data).

### Order Response

```json
{
	"id": 147,
	"status": "pending",
	"coupons": [
		{
			"code": "discount20",
			"totals": {
				"currency_code": "GBP",
				"currency_symbol": "£",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "£",
				"currency_suffix": "",
				"total_discount": "421",
				"total_discount_tax": "0"
			}
		}
	],
	"shipping_address": {
		"first_name": "Peter",
		"last_name": "Venkman",
		"company": "",
		"address_1": "550 Central Park West",
		"address_2": "Corner Penthouse Spook Central",
		"city": "New York",
		"state": "NY",
		"postcode": "10023",
		"country": "US",
		"phone": "555-2368"
	},
	"billing_address": {
		"first_name": "Peter",
		"last_name": "Venkman",
		"company": "",
		"address_1": "550 Central Park West",
		"address_2": "Corner Penthouse Spook Central",
		"city": "New York",
		"state": "NY",
		"postcode": "10023",
		"country": "US",
		"email": "admin@example.com",
		"phone": "555-2368"
	},
	"items": [
		{
			"key": "9bf31c7ff062936a96d3c8bd1f8f2ff3",
			"id": 15,
			"quantity": 1,
			"quantity_limits": {
				"minimum": 1,
				"maximum": 99,
				"multiple_of": 1,
				"editable": true
			},
			"name": "Beanie",
			"short_description": "<p>This is a simple product.</p>",
			"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
			"sku": "woo-beanie",
			"low_stock_remaining": null,
			"backorders_allowed": false,
			"show_backorder_badge": false,
			"sold_individually": false,
			"permalink": "https://local.wordpress.test/product/beanie/",
			"images": [
				{
					"id": 44,
					"src": "https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2.jpg",
					"thumbnail": "https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-324x324.jpg",
					"srcset": "https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2.jpg 801w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-324x324.jpg 324w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-416x416.jpg 416w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-768x768.jpg 768w",
					"sizes": "(max-width: 801px) 100vw, 801px",
					"name": "beanie-2.jpg",
					"alt": ""
				}
			],
			"variation": [],
			"prices": {
				"currency_code": "GBP",
				"currency_symbol": "£",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "£",
				"currency_suffix": "",
				"price": "1000",
				"regular_price": "2000",
				"sale_price": "1000",
				"price_range": null,
				"raw_prices": {
					"precision": 6,
					"price": "10000000",
					"regular_price": "20000000",
					"sale_price": "10000000"
				}
			},
			"item_data": [
				{
					"id": 1234,
					"key": "Gift message",
					"value": "Happy birthday",
					"display_key": "Gift message",
					"display_value": "<p>Happy birthday</p>\n"
				}
			],
			"totals": {
				"currency_code": "GBP",
				"currency_symbol": "£",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "£",
				"currency_suffix": "",
				"line_subtotal": "1000",
				"line_subtotal_tax": "0",
				"line_total": "800",
				"line_total_tax": "0"
			},
			"catalog_visibility": "view"
		},
		{
			"key": "e369853df766fa44e1ed0ff613f563bd",
			"id": 34,
			"quantity": 1,
			"quantity_limits": {
				"minimum": 1,
				"maximum": 99,
				"multiple_of": 1,
				"editable": true
			},
			"name": "WordPress Pennant",
			"short_description": "<p>This is an external product.</p>",
			"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
			"sku": "wp-pennant",
			"low_stock_remaining": null,
			"backorders_allowed": false,
			"show_backorder_badge": false,
			"sold_individually": false,
			"permalink": "https://local.wordpress.test/product/wordpress-pennant/",
			"images": [
				{
					"id": 57,
					"src": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg",
					"thumbnail": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg",
					"srcset": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg 800w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg 324w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-416x416.jpg 416w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-768x768.jpg 768w",
					"sizes": "(max-width: 800px) 100vw, 800px",
					"name": "pennant-1.jpg",
					"alt": ""
				}
			],
			"variation": [],
			"prices": {
				"currency_code": "GBP",
				"currency_symbol": "£",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "£",
				"currency_suffix": "",
				"price": "1105",
				"regular_price": "1105",
				"sale_price": "1105",
				"price_range": null,
				"raw_prices": {
					"precision": 6,
					"price": "11050000",
					"regular_price": "11050000",
					"sale_price": "11050000"
				}
			},
			"item_data": [],
			"totals": {
				"currency_code": "GBP",
				"currency_symbol": "£",
				"currency_minor_unit": 2,
				"currency_decimal_separator": ".",
				"currency_thousand_separator": ",",
				"currency_prefix": "£",
				"currency_suffix": "",
				"line_subtotal": "1105",
				"line_subtotal_tax": "0",
				"line_total": "884",
				"line_total_tax": "0"
			},
			"catalog_visibility": "view"
		}
	],
	"needs_payment": true,
	"needs_shipping": true,
	"totals": {
		"subtotal":"2105",
		"total_discount": "421",
		"total_shipping": "500",
		"total_fees": "0",
		"total_tax": "0",
		"total_refund": "0",
		"total_price": "2184",
		"total_items": "2105",
		"total_items_tax": "0",
		"total_fees_tax": "0",
		"total_discount_tax": "0",
		"total_shipping_tax": "0",
		"tax_lines": []
	},
	"errors": [],
	"payment_requirements": [ "products" ],
}
```

### Item data

Each order item carries its metadata in `item_data`, a list of entries:

| Property | Type | Description |
| --- | --- | --- |
| `id` | integer \| null | The order item metadata row ID. `null` when no displayed metadata row backs the entry, which is the case for anything an extension added through `woocommerce_order_item_get_formatted_meta_data`. |
| `key` | string | Metadata key. |
| `value` | string | Metadata value. |
| `display_key` | string | Key, formatted for display. |
| `display_value` | string | Value, formatted for display. |

Most stores return an empty list. Entries appear when an extension writes metadata to the line item, as Product Add-Ons, Deposits, Bundles and Gift Cards do.

Extensions can add properties beyond the five above through the same filter. The endpoint passes them through.

### Error Response

If an order action cannot be performed, an error response will be returned. This will include a reason code and an error message:

```json
{
	"code": "woocommerce_rest_invalid_order",
	"message": "Invalid order ID or key provided.",
	"data": {
		"status": 401
	}
}
```


---

## Product Attribute Terms API

*Source: apis/store-api/resources-endpoints/product-attribute-terms.md*

# Product Attribute Terms API

```http
GET /products/attributes/:id/terms
GET /products/attributes/:id/terms?orderby=slug
```

| Attribute               | Type    | Required | Description                                                                                                   |
| :---------------------- | :------ | :------: | :------------------------------------------------------------------------------------------------------------ |
| `id`                    | integer |   Yes    | The ID of the attribute to retrieve terms for.                                                                |
| `order`                 | string  |    no    | Order ascending or descending. Allowed values: `asc`, `desc`                                                  |
| `orderby`               | string  |    no    | Sort collection by object attribute. Allowed values: `id`, `name`, `name_num`, `slug`, `count`, `menu_order`. |
| `__experimental_visual` | boolean |    no    | If true, include experimental visual swatch data for `wc-visual` attribute terms.                             |

## Visual response fields

The following fields are included only when `__experimental_visual=true` is passed for `wc-visual` attribute terms.
Other attribute types keep the default term response without `__experimentalVisual`.

| Attribute                    | Type   | Description                                                                                                    |
| :--------------------------- | :----- | :------------------------------------------------------------------------------------------------------------- |
| `__experimentalVisual`       | object | Experimental visual swatch data for `wc-visual` attribute terms.                                               |
| `__experimentalVisual.type`  | string | Visual swatch type. Allowed values: `color`, `image`, `none`.                                                  |
| `__experimentalVisual.value` | string | Visual swatch value. Returns a hex color for `color`, an image URL for `image`, or an empty string for `none`. |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/attributes/1/terms?__experimental_visual=true"
```

**Example response for visual attribute terms:**

```json
[
	{
		"id": 22,
		"name": "Blue",
		"slug": "blue",
		"description": "",
		"parent": 0,
		"count": 5,
		"__experimentalVisual": {
			"type": "color",
			"value": "#1e73be"
		}
	},
	{
		"id": 48,
		"name": "Burgundy",
		"slug": "burgundy",
		"description": "",
		"parent": 0,
		"count": 1,
		"__experimentalVisual": {
			"type": "image",
			"value": "https://example-store.com/wp-content/uploads/2026/06/burgundy-swatch.jpg"
		}
	}
]
```

**Example response for non-visual attribute terms:**

```json
[
	{
		"id": 12,
		"name": "Large",
		"slug": "large",
		"description": "",
		"parent": 0,
		"count": 7
	}
]
```


---

## Product Attributes API

*Source: apis/store-api/resources-endpoints/product-attributes.md*

# Product Attributes API 

## List Product Attributes

```http
GET /products/attributes
```

There are no parameters required for this endpoint.

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/attributes"
```

Example response:

```json
[
	{
		"id": 1,
		"name": "Color",
		"taxonomy": "pa_color",
		"type": "select",
		"order": "menu_order",
		"has_archives": false
	},
	{
		"id": 2,
		"name": "Size",
		"taxonomy": "pa_size",
		"type": "select",
		"order": "menu_order",
		"has_archives": false
	}
]
```

## Single Product Attribute

Get a single attribute taxonomy.

```http
GET /products/attributes/:id
```

| Attribute | Type    | Required | Description                          |
| :-------- | :------ | :------: | :----------------------------------- |
| `id`      | integer |   Yes    | The ID of the attribute to retrieve. |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/attributes/1"
```

**Example response:**

```json
{
	"id": 1,
	"name": "Color",
	"taxonomy": "pa_color",
	"type": "select",
	"order": "menu_order",
	"has_archives": false
}
```


---

## Product Brands API

*Source: apis/store-api/resources-endpoints/product-brands.md*

# Product Brands API 

## List Product Brands

```http
GET /products/brands
```

| Attribute    | Type    | Required | Description                                                                                                           |
| :----------- | :------ | :------: | :-------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  |    No    | Scope under which the request is made; determines fields present in response.                                         |
| `page`       | integer |    No    | Current page of the collection. Defaults to `1`.                                                                      |
| `per_page`   | integer |    No    | Maximum number of items to be returned in result set. Defaults to no limit. Values between `0` and `100` are allowed. |
| `search`     | string  |    No    | Limit results to those matching a string.                                                                             |
| `exclude`    | array   |    No    | Ensure result set excludes specific IDs.                                                                              |
| `include`    | array   |    No    | Limit result set to specific IDs.                                                                                     |
| `order`      | string  |    No    | Sort ascending or descending. Allowed values: `asc`, `desc`. Defaults to `asc`.                                       |
| `orderby`    | string  |    No    | Sort by term property. Allowed values: `name`, `slug`, `count`. Defaults to `name`.                                   |
| `hide_empty` | boolean |    No    | If true, empty terms will not be returned. Defaults to `true`.                                                        |
| `parent`     | integer |    No    | Limit results to those with a specific parent ID.                                                                     |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/brands"
```

Example response:

```json
[
	{
		"id": 16,
		"name": "Nike",
		"slug": "nike",
		"description": "This is the Nike brand.",
		"parent": 0,
		"count": 11,
		"image": {
			"id": 55,
			"src": "https://store.local/wp-content/uploads/2021/11/nike-logo.jpg",
			"thumbnail": "https://store.local/wp-content/uploads/2021/11/nike-logo-324x324.jpg",
			"srcset": "https://store.local/wp-content/uploads/2021/11/nike-logo.jpg 800w, https://store.local/wp-content/uploads/2021/11/nike-logo-324x324.jpg 324w, https://store.local/wp-content/uploads/2021/11/nike-logo-100x100.jpg 100w, https://store.local/wp-content/uploads/2021/11/nike-logo-416x416.jpg 416w, https://store.local/wp-content/uploads/2021/11/nike-logo-300x300.jpg 300w, https://store.local/wp-content/uploads/2021/11/nike-logo-150x150.jpg 150w, https://store.local/wp-content/uploads/2021/11/nike-logo-768x768.jpg 768w",
			"sizes": "(max-width: 800px) 100vw, 800px",
			"name": "nike-logo.jpg",
			"alt": ""
		},
		"review_count": 2,
		"permalink": "https://store.local/product-brand/nike/"
	},
	{
		"id": 21,
		"name": "Adidas",
		"slug": "adidas",
		"description": "",
		"parent": 0,
		"count": 1,
		"image": null,
		"review_count": 1,
		"permalink": "https://store.local/product-brand/adidas/"
	}
]
```

## Single Product Brand

Get a single brand.

```http
GET /products/brands/:id
```

or 

```http
GET /products/brands/:slug
```

| Parameter    | Type    | Required | Description                                                          |
| :--------    | :------ | :------: |:---------------------------------------------------------------------|
| `identifier` | string  |   Yes    | The identifier of the brand to retrieve. Can be a brand ID or slug.  |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/brands/1"
```

or

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/brands/adidas"
```

**Example response:**

```json
{
	"id": 1,
	"name": "Adidas",
	"slug": "adidas",
	"description": "",
	"parent": 0,
	"count": 1,
	"image": null,
	"review_count": 1,
	"permalink": "https://store.local/product-brand/adidas/"
}
```


---

## Product Categories API

*Source: apis/store-api/resources-endpoints/product-categories.md*

# Product Categories API 

## List Product Categories

```http
GET /products/categories
```

| Attribute    | Type    | Required | Description                                                                                                           |
| :----------- | :------ | :------: | :-------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  |    No    | Scope under which the request is made; determines fields present in response.                                         |
| `page`       | integer |    No    | Current page of the collection. Defaults to `1`.                                                                      |
| `per_page`   | integer |    No    | Maximum number of items to be returned in result set. Defaults to no limit. Values between `0` and `100` are allowed. |
| `search`     | string  |    No    | Limit results to those matching a string.                                                                             |
| `exclude`    | array   |    No    | Ensure result set excludes specific IDs.                                                                              |
| `include`    | array   |    No    | Limit result set to specific IDs.                                                                                     |
| `order`      | string  |    No    | Sort ascending or descending. Allowed values: `asc`, `desc`. Defaults to `asc`.                                       |
| `orderby`    | string  |    No    | Sort by term property. Allowed values: `name`, `slug`, `count`. Defaults to `name`.                                   |
| `hide_empty` | boolean |    No    | If true, empty terms will not be returned. Defaults to `true`.                                                        |
| `parent`     | integer |    No    | Limit results to those with a specific parent ID.                                                                     |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/categories"
```

Example response:

```json
[
	{
		"id": 16,
		"name": "Clothing",
		"slug": "clothing",
		"description": "This is the clothing category.",
		"parent": 0,
		"count": 11,
		"image": {
			"id": 55,
			"src": "https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1.jpg",
			"thumbnail": "https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1-324x324.jpg",
			"srcset": "https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1.jpg 800w, https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1-324x324.jpg 324w, https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1-100x100.jpg 100w, https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1-416x416.jpg 416w, https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1-300x300.jpg 300w, https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1-150x150.jpg 150w, https://store.local/wp-content/uploads/2021/11/t-shirt-with-logo-1-768x768.jpg 768w",
			"sizes": "(max-width: 800px) 100vw, 800px",
			"name": "t-shirt-with-logo-1.jpg",
			"alt": ""
		},
		"review_count": 2,
		"permalink": "https://store.local/product-category/clothing/"
	},
	{
		"id": 21,
		"name": "Decor",
		"slug": "decor",
		"description": "",
		"parent": 0,
		"count": 1,
		"image": null,
		"review_count": 1,
		"permalink": "https://store.local/product-category/decor/"
	}
]
```

## Single Product Category

Get a single category.

```http
GET /products/categories/:id
```

| Category | Type    | Required | Description                         |
| :------- | :------ | :------: | :---------------------------------- |
| `id`     | integer |   Yes    | The ID of the category to retrieve. |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/categories/1"
```

**Example response:**

```json
{
	"id": 1,
	"name": "Decor",
	"slug": "decor",
	"description": "",
	"parent": 0,
	"count": 1,
	"image": null,
	"review_count": 1,
	"permalink": "https://store.local/product-category/decor/"
}
```


---

## Product Collection Data API

*Source: apis/store-api/resources-endpoints/product-collection-data.md*

# Product Collection Data API

This endpoint allows you to get aggregate data from a collection of products, for example, the min and max price in a collection of products (ignoring pagination). This is used by blocks for product filtering widgets, since counts are based on the product catalog being viewed.

```http
GET /products/collection-data
GET /products/collection-data?calculate_price_range=true
GET /products/collection-data?calculate_attribute_counts[0][query_type]=or&calculate_attribute_counts[0][taxonomy]=pa_color
GET /products/collection-data?calculate_rating_counts=true
GET /products/collection-data?calculate_taxonomy_counts=product_cat
```

| Attribute                       | Type   | Required | Description                                                                                                                                                                                                |
| :------------------------------ | :----- | :------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `calculate_price_range`         | bool   |    No    | Returns the min and max price for the product collection. If false, only `null` will be returned.                                                                                                          |
| `calculate_attribute_counts`    | object |    No    | Returns attribute counts for a list of attribute taxonomies you pass in via this parameter. Each should be provided as an object with keys "taxonomy" and "query_type". If empty, `null` will be returned. |
| `calculate_rating_counts`       | bool   |    No    | Returns the counts of products with a certain average rating, 1-5. If false, only `null` will be returned.                                                                                                 |
| `calculate_stock_status_counts` | bool   |    No    | Returns counts of products with each stock status (in stock, out of stock, on backorder). If false, only `null` will be returned.                                                                         |
| `calculate_taxonomy_counts`     | array  |    No    | Returns taxonomy counts for a list of taxonomies you pass in via this parameter. Each should be provided as a taxonomy name string. If empty, `null` will be returned.                                 |


**In addition to the above attributes**, all product list attributes are supported. This allows you to get data for a certain subset of products. See [the products API list products section](/docs/apis/store-api/resources-endpoints/products#list-products) for the full list.

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/collection-data?calculate_price_range=true&calculate_attribute_counts=pa_size,pa_color&calculate_rating_counts=true&calculate_taxonomy_counts=product_cat,product_tag"
```

**Example response:**

```json
{
	"price_range": [
		"currency_minor_unit": 2,
		"min_price": "0",
		"max_price": "9000",
		"currency_code": "USD",
		"currency_decimal_separator": ".",
		"currency_minor_unit": 2,
		"currency_prefix": "$",
		"currency_suffix": "",
		"currency_symbol": "$",
		"currency_thousand_separator": ",",
	],
	"attribute_counts": [
		{
			"term": 22,
			"count": 4
		},
		{
			"term": 23,
			"count": 3
		},
		{
			"term": 24,
			"count": 4
		}
	],
	"rating_counts": [
		{
			"rating": 3,
			"count": 1
		},
		{
			"rating": 4,
			"count": 1
		}
	],
	"taxonomy_counts": [
		{
			"term": 25,
			"count": 8
		},
		{
			"term": 26,
			"count": 6
		},
		{
			"term": 27,
			"count": 2
		}
	]
}
```


---

## Product Reviews API

*Source: apis/store-api/resources-endpoints/product-reviews.md*

# Product Reviews API 

## List Product Reviews

This endpoint returns product reviews (comments) and can also show results from either specific products or specific categories.

```http
GET /products/reviews
GET /products/reviews?category_id=1,2,3
GET /products/reviews?product_id=1,2,3
GET /products/reviews?orderby=rating&order=desc
```

| Attribute     | Type    | Required | Description                                                                                         |
| :------------ | :------ | :------: | :-------------------------------------------------------------------------------------------------- |
| `page`        | integer |    no    | Current page of the collection.                                                                     |
| `per_page`    | integer |    no    | Maximum number of items to be returned in result set.                                               |
| `offset`      | integer |    no    | Offset the result set by a specific number of items.                                                |
| `order`       | string  |    no    | Order sort attribute ascending or descending. Allowed values: `asc`, `desc`                         |
| `orderby`     | string  |    no    | Sort collection by object attribute. Allowed values : `date`, `date_gmt`, `id`, `rating`, `product` |
| `category_id` | string  |    no    | Limit result set to reviews from specific category IDs.                                             |
| `product_id`  | string  |    no    | Limit result set to reviews from specific product IDs.                                              |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/collection-data?calculate_price_range=true&calculate_attribute_counts=pa_size,pa_color&calculate_rating_counts=true"
```

**Example response:**

```json
[
	{
		"id": 83,
		"date_created": "2022-01-12T15:42:14",
		"formatted_date_created": "January 12, 2022",
		"date_created_gmt": "2022-01-12T15:42:14",
		"product_id": 33,
		"product_name": "Beanie with Logo",
		"product_permalink": "https://store.local/product/beanie-with-logo/",
		"product_image": {
			"id": 56,
			"src": "https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1.jpg",
			"thumbnail": "https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1-324x324.jpg",
			"srcset": "https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1.jpg 800w, https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1-324x324.jpg 324w, https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1-100x100.jpg 100w, https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1-416x416.jpg 416w, https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1-300x300.jpg 300w, https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1-150x150.jpg 150w, https://store.local/wp-content/uploads/2021/11/beanie-with-logo-1-768x768.jpg 768w",
			"sizes": "(max-width: 800px) 100vw, 800px",
			"name": "beanie-with-logo-1.jpg",
			"alt": ""
		},
		"reviewer": "reviewer-name",
		"review": "<p>This is a fantastic product.</p>\n",
		"rating": 5,
		"verified": true,
		"reviewer_avatar_urls": {
			"24": "https://secure.gravatar.com/avatar/12345?s=24&d=mm&r=g",
			"48": "https://secure.gravatar.com/avatar/12345?s=48&d=mm&r=g",
			"96": "https://secure.gravatar.com/avatar/12345?s=96&d=mm&r=g"
		}
	}
]
```

### Password-protected products

Reviews of password-protected products are excluded until the visitor has submitted the correct password. They are omitted from both the collection and the pagination totals.

Password verification uses WordPress's native `wp-postpass_*` cookie, set when a user submits the password form on the frontend. The Store API does not accept passwords directly.

A request that targets a locked product via `product_id` returns an empty collection with status `200`.


---

## Product Tags API

*Source: apis/store-api/resources-endpoints/product-tags.md*

# Product Tags API 

## List Product Tags

```http
GET /products/tags
```

| Attribute    | Type    | Required | Description                                                                                                           |
| :----------- | :------ | :------: | :-------------------------------------------------------------------------------------------------------------------- |
| `context`    | string  |    No    | Scope under which the request is made; determines fields present in response.                                         |
| `page`       | integer |    No    | Current page of the collection. Defaults to `1`.                                                                      |
| `per_page`   | integer |    No    | Maximum number of items to be returned in result set. Defaults to no limit. Values between `0` and `100` are allowed. |
| `search`     | string  |    No    | Limit results to those matching a string.                                                                             |
| `exclude`    | array   |    No    | Ensure result set excludes specific IDs.                                                                              |
| `include`    | array   |    No    | Limit result set to specific IDs.                                                                                     |
| `order`      | string  |    No    | Sort ascending or descending. Allowed values: `asc`, `desc`. Defaults to `asc`.                                       |
| `orderby`    | string  |    No    | Sort by term property. Allowed values: `name`, `slug`, `count`. Defaults to `name`.                                   |
| `hide_empty` | boolean |    No    | If true, empty terms will not be returned. Defaults to `true`.                                                        |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/tags"
```

Example response:

```json
[
	{
		"id": 1,
		"name": "Test Tag",
		"slug": "test-tag",
		"description": "",
		"parent": 0,
		"count": 1
	},
	{
		"id": 2,
		"name": "Another Tag",
		"slug": "another-tag",
		"description": "",
		"parent": 0,
		"count": 1
	}
]
```


---

## Products API

*Source: apis/store-api/resources-endpoints/products.md*

# Products API 

The store products API provides public product data so it can be rendered on the client side.

## Product Visibility

### Draft and non-published products

Only published products are accessible via the Store API. Requesting a draft, pending, or other non-published product by ID or slug returns a `404` error. Non-published products are also excluded from the collection endpoint.

### Password-protected products

Password-protected products, including variations whose parent product is password-protected, are visible in the API, but their `description` and `short_description` fields are redacted (returned as empty strings) until the correct password has been submitted.

The `is_password_protected` field indicates whether the product or its parent has a configured password. It remains `true` after the current visitor has submitted the correct password and the descriptions become accessible.

Password verification uses WordPress's native `wp-postpass_*` cookie, set when a user submits the password form on the frontend. The Store API does not accept passwords directly.

Other product data (price, images, categories, etc.) remains accessible regardless of password status.

## List Products

```http
GET /products
GET /products?search=product%20name
GET /products?slug=slug-1,slug-2
GET /products?after=2017-03-22&date_column=date
GET /products?before=2017-03-22&date_column=date
GET /products?exclude=10,44,33
GET /products?include=10,44,33
GET /products?offset=10
GET /products?order=asc&orderby=price
GET /products?parent=10
GET /products?parent_exclude=10
GET /products?type=simple
GET /products?sku=sku-1,sku-2
GET /products?featured=true
GET /products?category=22
GET /products?brand=adidas
GET /products?_unstable_tax_my-taxonomy=my-taxonomy-term-id
GET /products?tag=special-items
GET /products?attributes[0][attribute]=pa_color&attributes[0][slug]=red
GET /products?on_sale=true
GET /products?min_price=5000
GET /products?max_price=10000
GET /products?stock_status=['outofstock']
GET /products?catalog_visibility=search
GET /products?rating=4,5
GET /products?related=34
GET /products?return_price_range=true
GET /products?return_attribute_counts=pa_size,pa_color
GET /products?return_rating_counts=true
```

| Attribute                                   | Type    | Required | Description                                                                                                                                                                                                                           |
| :------------------------------------------ | :------ | :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `search`                                    | string  |    no    | Limit results to those matching a string.                                                                                                                                                                                             |
| `slug`                                      | string  |    no    | Limit result set to products with specific slug(s). Use commas to separate.                                                                                                                                                           |
| `after`                                     | string  |    no    | Limit response to resources created after a given ISO8601 compliant date.                                                                                                                                                             |
| `before`                                    | string  |    no    | Limit response to resources created before a given ISO8601 compliant date.                                                                                                                                                            |
| `date_column`                               | string  |    no    | When limiting response using after/before, which date column to compare against. Allowed values: `date`, `date_gmt`, `modified`, `modified_gmt`                                                                                       |
| `exclude`                                   | array   |    no    | Ensure result set excludes specific IDs.                                                                                                                                                                                              |
| `include`                                   | array   |    no    | Limit result set to specific ids.                                                                                                                                                                                                     |
| `offset`                                    | integer |    no    | Offset the result set by a specific number of items.                                                                                                                                                                                  |
| `order`                                     | string  |    no    | Order sort attribute ascending or descending. Allowed values: `asc`, `desc`                                                                                                                                                           |
| `orderby`                                   | string  |    no    | Sort collection by object attribute. Allowed values : `date`, `modified`, `id`, `include`, `title`, `slug`, `price`, `popularity`, `rating`, `menu_order`, `comment_count`                                                            |
| `parent`                                    | array   |    no    | Limit result set to those of particular parent IDs.                                                                                                                                                                                   |
| `parent_exclude`                            | array   |    no    | Limit result set to all items except those of a particular parent ID.                                                                                                                                                                 |
| `type`                                      | string  |    no    | Limit result set to products assigned a specific type.                                                                                                                                                                                |
| `sku`                                       | string  |    no    | Limit result set to products with specific SKU(s). Use commas to separate.                                                                                                                                                            |
| `featured`                                  | boolean |    no    | Limit result set to featured products.                                                                                                                                                                                                |
| `category`                                  | string  |    no    | Limit result set to products assigned to categories IDs or slugs, separated by commas.                                                                                                                                                |
| `category_operator`                         | string  |    no    | Operator to compare product category terms. Allowed values: `in`, `not_in`, `and`                                                                                                                                                     |
| `brand`                                     | string  |    no    | Limit result set to products assigned to brands IDs or slugs, separated by commas.                                                                                                                                                    |
| `brand_operator`                            | string  |    no    | Operator to compare product brand terms. Allowed values: `in`, `not_in`, `and`                                                                                                                                                        |
| `_unstable_tax_[product-taxonomy]`          | string  |    no    | Limit result set to products assigned to the term ID of that custom product taxonomy. `[product-taxonomy]` should be the key of the custom product taxonomy registered.                                                               |
| `_unstable_tax_[product-taxonomy]_operator` | string  |    no    | Operator to compare custom product taxonomy terms. Allowed values: `in`, `not_in`, `and`                                                                                                                                              |
| `tag`                                       | string  |    no    | Limit result set to products assigned a specific tag ID.                                                                                                                                                                              |
| `tag_operator`                              | string  |    no    | Operator to compare product tags. Allowed values: `in`, `not_in`, `and`                                                                                                                                                               |
| `on_sale`                                   | boolean |    no    | Limit result set to products on sale.                                                                                                                                                                                                 |
| `min_price`                                 | string  |    no    | Limit result set to products based on a minimum price, provided using the smallest unit of the currency. E.g. provide 10025 for 100.25 USD, which is a two-decimal currency, and 1025 for 1025 JPY, which is a zero-decimal currency. |
| `max_price`                                 | string  |    no    | Limit result set to products based on a maximum price, provided using the smallest unit of the currency. E.g. provide 10025 for 100.25 USD, which is a two-decimal currency, and 1025 for 1025 JPY, which is a zero-decimal currency. |
| `stock_status`                              | array   |    no    | Limit result set to products with specified stock statuses. Expects an array of strings containing 'instock', 'outofstock' or 'onbackorder'.                                                                                          |
| `attributes`                                | array   |    no    | Limit result set to specific attribute terms. Expects an array of objects containing `attribute` (taxonomy), `term_id` or `slug`, and optional `operator` for comparison.                                                             |
| `attribute_relation`                        | string  |    no    | The logical relationship between attributes when filtering across multiple at once.                                                                                                                                                   |
| `catalog_visibility`                        | string  |    no    | Determines if hidden or visible catalog products are shown. Allowed values: `any`, `visible`, `catalog`, `search`, `hidden`                                                                                                           |
| `rating`                                    | array   |    no    | Limit result set to products with a certain average rating. Allowed values: `1`, `2`, `3`, `4`, `5`.                                                                                                                                  |
| `related`                                   | integer |    no    | Limit result set to products related to a specific product ID.                                                                                                                                                                        |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products"
```

**Example response:**

```json
[
	{
		"id": 34,
		"name": "WordPress Pennant",
		"slug": "wordpress-pennant",
		"variation": "",
		"permalink": "https://local.wordpress.test/product/wordpress-pennant/",
		"sku": "wp-pennant",
		"summary": "<p>This is an external product.</p>",
		"short_description": "<p>This is an external product.</p>",
		"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
		"on_sale": false,
		"prices": {
			"currency_code": "GBP",
			"currency_symbol": "£",
			"currency_minor_unit": 2,
			"currency_decimal_separator": ".",
			"currency_thousand_separator": ",",
			"currency_prefix": "£",
			"currency_suffix": "",
			"price": "1105",
			"regular_price": "1105",
			"sale_price": "1105",
			"price_range": null
		},
		"average_rating": "0",
		"review_count": 0,
		"images": [
			{
				"id": 57,
				"src": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg",
				"thumbnail": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg",
				"srcset": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg 800w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg 324w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-416x416.jpg 416w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-768x768.jpg 768w",
				"sizes": "(max-width: 800px) 100vw, 800px",
				"name": "pennant-1.jpg",
				"alt": ""
			}
		],
		"has_options": false,
		"is_purchasable": true,
		"is_in_stock": true,
		"is_password_protected": false,
		"low_stock_remaining": null,
		"add_to_cart": {
			"text": "Add to cart",
			"description": "Add &ldquo;WordPress Pennant&rdquo; to your cart"
		}
	}
]
```

## Single Product by ID

Get a single product by id.

```http
GET /products/:id
```

| Attribute | Type    | Required | Description                        |
| :-------- | :------ | :------: | :--------------------------------- |
| `id`      | integer |   Yes    | The ID of the product to retrieve. |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/34"
```

**Example response:**

```json
{
	"id": 34,
	"name": "WordPress Pennant",
	"slug": "wordpress-pennant",
	"variation": "",
	"permalink": "https://local.wordpress.test/product/wordpress-pennant/",
	"sku": "wp-pennant",
	"summary": "<p>This is an external product.</p>",
	"short_description": "<p>This is an external product.</p>",
	"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
	"on_sale": false,
	"prices": {
		"currency_code": "GBP",
		"currency_symbol": "£",
		"currency_minor_unit": 2,
		"currency_decimal_separator": ".",
		"currency_thousand_separator": ",",
		"currency_prefix": "£",
		"currency_suffix": "",
		"price": "1105",
		"regular_price": "1105",
		"sale_price": "1105",
		"price_range": null
	},
	"average_rating": "0",
	"review_count": 0,
	"images": [
		{
			"id": 57,
			"src": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg",
			"thumbnail": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg",
			"srcset": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg 800w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg 324w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-416x416.jpg 416w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-768x768.jpg 768w",
			"sizes": "(max-width: 800px) 100vw, 800px",
			"name": "pennant-1.jpg",
			"alt": ""
		}
	],
	"has_options": false,
	"is_purchasable": true,
	"is_in_stock": true,
	"is_password_protected": false,
	"low_stock_remaining": null,
	"add_to_cart": {
		"text": "Add to cart",
		"description": "Add &ldquo;WordPress Pennant&rdquo; to your cart"
	}
}
```

## Single Product by slug

Get a single product by slug.

```http
GET /products/:slug
```

| Attribute | Type   | Required | Description                          |
| :-------- | :----- | :------: | :----------------------------------- |
| `slug`    | string |   Yes    | The slug of the product to retrieve. |

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products/wordpress-pennant"
```

**Example response:**

```json
{
	"id": 34,
	"name": "WordPress Pennant",
	"slug": "wordpress-pennant",
	"variation": "",
	"permalink": "https://local.wordpress.test/product/wordpress-pennant/",
	"sku": "wp-pennant",
	"summary": "<p>This is an external product.</p>",
	"short_description": "<p>This is an external product.</p>",
	"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
	"on_sale": false,
	"prices": {
		"currency_code": "GBP",
		"currency_symbol": "£",
		"currency_minor_unit": 2,
		"currency_decimal_separator": ".",
		"currency_thousand_separator": ",",
		"currency_prefix": "£",
		"currency_suffix": "",
		"price": "1105",
		"regular_price": "1105",
		"sale_price": "1105",
		"price_range": null
	},
	"average_rating": "0",
	"review_count": 0,
	"images": [
		{
			"id": 57,
			"src": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg",
			"thumbnail": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg",
			"srcset": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg 800w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg 324w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-416x416.jpg 416w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-768x768.jpg 768w",
			"sizes": "(max-width: 800px) 100vw, 800px",
			"name": "pennant-1.jpg",
			"alt": ""
		}
	],
	"has_options": false,
	"is_purchasable": true,
	"is_in_stock": true,
	"is_password_protected": false,
	"low_stock_remaining": null,
	"add_to_cart": {
		"text": "Add to cart",
		"description": "Add &ldquo;WordPress Pennant&rdquo; to your cart"
	}
}
```

## Product Links and Embedding

Product responses include `_links` that provide URLs to related resources. When products have upsells, cross-sells, or related products configured, embeddable links are included that can be used with WordPress's `_embed` feature.

### Available Links

| Link         | Description                                         | Embeddable |
| :----------- | :-------------------------------------------------- | :--------: |
| `self`       | Link to the current product                         | No         |
| `collection` | Link to the products collection                     | No         |
| `up`         | Link to parent product (for variations)             | No         |
| `upsells`    | Link to fetch upsell products (if configured)       | Yes        |
| `cross_sells`| Link to fetch cross-sell products (if configured)   | Yes        |
| `related`    | Link to fetch related products                      | Yes        |

### Example Response with Links

```json
{
	"id": 34,
	"name": "WordPress Pennant",
	"_links": {
		"self": [{"href": "https://local.wordpress.test/wp-json/wc/store/v1/products/34"}],
		"collection": [{"href": "https://local.wordpress.test/wp-json/wc/store/v1/products"}],
		"upsells": [{"href": "https://local.wordpress.test/wp-json/wc/store/v1/products?include=10,20", "embeddable": true}],
		"cross_sells": [{"href": "https://local.wordpress.test/wp-json/wc/store/v1/products?include=30", "embeddable": true}],
		"related": [{"href": "https://local.wordpress.test/wp-json/wc/store/v1/products?related=34&per_page=10", "embeddable": true}]
	}
}
```

### Using the `_embed` Parameter

Add `?_embed` to any product request to automatically fetch and include the linked resources in an `_embedded` object:

```sh
curl "https://local.wordpress.test/wp-json/wc/store/v1/products/34?_embed"
```

**Example response with embedding:**

```json
{
	"id": 34,
	"name": "WordPress Pennant",
	"_links": {
		"self": [{"href": "https://local.wordpress.test/wp-json/wc/store/v1/products/34"}],
		"collection": [{"href": "https://local.wordpress.test/wp-json/wc/store/v1/products"}],
		"upsells": [{"href": "https://local.wordpress.test/wp-json/wc/store/v1/products?include=10,20", "embeddable": true}]
	},
	"_embedded": {
		"upsells": [
			{"id": 10, "name": "Upsell Product 1", "...": "..."},
			{"id": 20, "name": "Upsell Product 2", "...": "..."}
		]
	}
}
```

## Product Variations

By default, Store API excludes product variations. You can retrieve the variations for a product by using the `type=variation`.

```sh
curl "https://example-store.com/wp-json/wc/store/v1/products?type=variation"
```


---

## WooCommerce coding standards

*Source: best-practices/coding-standards/coding-standards.md*

# WooCommerce coding standards

Adhering to WooCommerce coding standards is essential for maintaining high code quality, ensuring compatibility, and facilitating easier maintenance and updates. This document outlines the recommended coding practices for developers working within the WooCommerce ecosystem, including the use of hooks, function prefixing, translatable texts, and code structure.


## Position of hooks

Position hooks below the function call to align with the common pattern in the WordPress and WooCommerce ecosystem.

Example:

```php
/**
 * Add custom message.
 */
function YOUR_PREFIX_custom_message() {
    echo 'This is a custom message';
}
add_action( 'wp_footer', 'YOUR_PREFIX_custom_message' );
```

## Prefixing function calls

Use a consistent prefix for all function calls to avoid conflicts. For the code snippets in this repo, use `YOUR_PREFIX`.

Example:

```php
/**
 * Add custom discount.
 */
function YOUR_PREFIX_custom_discount( $price, $product ) {
    return $price * 0.9;  // 10% discount
}
add_filter( 'woocommerce_product_get_price', 'YOUR_PREFIX_custom_discount', 10, 2 );
```

## Translatable texts and text domains

Ensure all plain texts are translatable and use a consistent text domain, adhering to internationalization best practices. For the code snippets in this repo, use the textdomain `YOUR-TEXTDOMAIN`.

Example:

```php
/**
 * Add welcome message.
 */
function YOUR_PREFIX_welcome_message() {
    echo __( 'Welcome to our website', 'YOUR-TEXTDOMAIN' );
}
add_action( 'wp_footer', 'YOUR_PREFIX_welcome_message' );
```

## Use of function_exists()

To prevent errors from potential function redeclaration, wrap all function calls with `function_exists()`.

Example:

```php
/**
 * Add thumbnail support.
 */
if ( ! function_exists( 'YOUR_PREFIX_theme_setup' ) ) {
    function YOUR_PREFIX_theme_setup() {
        add_theme_support( 'post-thumbnails' );
    }
}
add_action( 'after_setup_theme', 'YOUR_PREFIX_theme_setup' );
```

## Code quality standards

To ensure the highest standards of code quality, developers are encouraged to adhere to the following practices:

### WooCommerce sniffs and WordPress code standards

- **Ensure no code style issues** when code is passed through WooCommerce Sniffs and WordPress Code Standards for PHP_CodeSniffer.

### Automated testing

- **Unit tests**: Implement automated unit tests to validate code functionality in isolation.
- **E2E tests**: Utilize automated end-to-end tests to verify the integrated operation of components within the application.

### Tracking and managing bugs

- **Monitor and aim to minimize** the number of open bugs, ensuring a stable and reliable product.

### Code organization

- **Organize code in self-contained classes** to avoid creating "god/super classes" that contain all plugin code. This practice promotes modularity and simplifies maintenance.

By following these coding standards and practices, developers can create high-quality, maintainable, and secure WooCommerce extensions that contribute positively to the WordPress ecosystem.


---

## CSS/Sass naming conventions

*Source: best-practices/coding-standards/css-sass-naming-conventions.md*

# CSS/Sass naming conventions

## Introduction

Our guidelines are based on those used in [Calypso](https://github.com/Automattic/wp-calypso), which itself follows the [BEM methodology](https://getbem.com/).

Refer to the [Calypso CSS/Sass Coding Guidelines](https://wpcalypso.wordpress.com/devdocs/docs/coding-guidelines/css.md) for full details.

Read more about [BEM key concepts](https://en.bem.info/methodology/key-concepts/).

There are a few differences in WooCommerce which are outlined below.

## Prefixing

As a WordPress plugin WooCommerce has to play nicely with WordPress core and other plugins/themes. To minimize conflict potential, all classes should be prefixed with `.woocommerce-`.

## Class names

When naming classes, remember:

- **Block** - Standalone entity that is meaningful on its own. Such as the name of a component.
- **Element** - Parts of a block and have no standalone meaning. They are semantically tied to its block.
- **Modifier** - Flags on blocks or elements. Use them to change appearance or behavior.

### Example

```css
/* Block */
.woocommerce-loop {}

/* Nested block */
.woocommerce-loop-product {}

/* Modifier */
.woocommerce-loop-product--sale {}

/* Element */
.woocommerce-loop-product__link {}

/* Element */
.woocommerce-loop-product__button-add-to-cart {}

/* Modifier */
.woocommerce-loop-product__button-add-to-cart--added {}
```

**Note:** `.woocommerce-loop-product` is not named as such because the block is nested within `.woocommerce-loop`. It's to be specific so that we can have separate classes for single products, cart products, etc. **Nested blocks do not need to inherit their parents full name.**

## TL;DR

- Follow the [WordPress Coding standards for CSS](https://make.wordpress.org/core/handbook/best-practices/coding-standards/css/) unless it contradicts anything here.
- Follow [Calypso guidelines for CSS](https://wpcalypso.wordpress.com/devdocs/docs/coding-guidelines/css.md).
- Use BEM for [class names](https://en.bem.info/methodology/naming-convention/).
- Prefix all class names.


---

## WooCommerce grammar, punctuation and capitalization guide

*Source: best-practices/coding-standards/grammar-punctuation-capitalization.md*

# WooCommerce grammar, punctuation and capitalization guide

Following grammar, punctuation and style guidelines helps keep our presentation consistent. Users have a better experience if they know what to expect and where to find the information they need.

## Basics

**Be democratic**. Some people read every word. Some scan and search or prefer video. Help everyone.

**Be focused**. Lead with the most important information in sentences, paragraphs, and sections.

**Be concise**. Use plain language and brief sentences.

**Be consistent**. Follow our guidelines and style tips.

**Be specific**. Communicate crystal clear. Trim the fat.

## Guidelines

### Abbreviations and acronyms

Spell out the full version on first mention with abbreviation or acronym in parentheses. Use the short version on second and consecutive mentions.

- First use: Payment Card Industry Data Security Standard (PCI-DSS)
- Second use: PCI-DSS

If the abbreviation or acronym is widely known, use it as is. For example: API, FAQ, HTML, PHP, SQL, SSL.

### Active voice

With active voice, the subject in the sentence performs the action. With passive voice, the subject in the sentence has the action done unto it.

- Active: Jon downloaded his extension files.
- Passive: The extension files were downloaded by Jon.

### Capitalization

Cases when we capitalize:

- Blog post and documentation article titles: First word.
- Documentation headings (h2): Use sentence case (not title case) for docs titles and subheadings. 
- Product names: Every word except prepositions and conjunctions.
- Sentences: First word.
- Unordered/Bulleted lists - First word of each entry.

Cases when we use lower case:

- "ecommerce" (not "eCommerce")
- email address - `info@woocommerce.com`
- website URL - `developer.woocommerce.com`

### Contractions

Use with discretion. Contractions, such as I'm and there's, give writing an informal and conversational feel, but may be inappropriate if content is being translated. For example, sometimes the not in don't is ignored by online translators.

### Emoji

Emoji can add subtle emotion and humor or bring visual attention to your content. Use rarely and intentionally.

### Numbers

Spell out a number at the start of a sentence, and spell out numbers one through nine in all cases. Use numerals in all other cases.

- Ten products will launch in June. Not: 10 products will launch in June.
- Lance ran a marathon and won third place in his age group.
- I bought five hammers and 21 types of nails for the building project.
- There were 18 kinds of beer on tap at the pub.

Use a comma for numbers with more than three digits: 41,500, 170,000, 1,000,000 or 1 million.

#### Currency

Use currency codes and not only the symbol/sign when specifying dollars. Whole amounts need not have a decimal and two places.

- USD $20
- CAD $19.99
- AUD $39.50

When writing about other currencies, use the symbol/sign.

- €995
- ¥5,000
- £18.99

#### Dates

Spell out the day of the week and month, using the format:

- Monday, December 12, 2016

#### Decimals

Use decimal points when a number is difficult to convert to a fraction, such as 3.141 or 98.5 or 0.29.

#### Fractions

Spell out fractions: one-fourth

#### Percent

Spell out the word 'percent.' Don't use % symbol unless space is limited, e.g., for use on social media.

#### Phone numbers

Use hyphens without spaces between numbers, not parentheses or periods. Use a [country code](https://countrycode.org/) for all countries.

- +1-555-867-5309
- +34-902-1899-00

#### Range and span

Use a hyphen to indicate a range or span of numbers: 20-30 days.

#### Temperature

Use the degree symbol and the capital C abbreviation for Celsius and capital F abbreviation for Fahrenheit.

- 27°C
- 98°F

#### Times

Use numbers and am or pm with a space and without periods.

- 7:00 am
- 7:30 pm

Use a hyphen between times to indicate a time period in am or pm. Use 'to' if the time period spans am and pm.

- 7:00-9:00 am and 7:00 am to 10:30 pm

Specify a time zone when writing about an event with potential attendees worldwide. Automattic uses Coordinated Universal Time (UTC).

Abbreviate U.S. time zones:

- Eastern time: EDT or EST
- Central time: CDT or CST
- Mountain time: MDT or MST
- Pacific time: PDT or PST

#### Years

Abbreviate decades

- 80s and 90s
- 1900s and 1890s

### Punctuation

#### Ampersands

Ampersands need only be used when part of an official company/brand name. Should not be substituted for 'and.'

- Ben & Jerry's
- Andre, Timo, and Donny went to a football game at Camp Nou.

#### Apostrophes

An apostrophe makes a word possessive. If a word already ends in s and is singular, add an 's. If a word ends in s and is plural, add an apostrophe.

- A teammate borrowed Sam's bike.
- A teammate borrowed Chris's bike.
- Employees hid the office managers' pens.

These are possessives: FAQ's questions, HE's weekly rotation. These are plural: FAQs and HEs.

#### Colons

Use a colon to create a list.

- Aaron ordered three kinds of donuts: glazed, chocolate, and pumpkin.

#### Commas

Use a serial comma, also known as an Oxford comma, when compiling a list.

- Jinny likes sunflowers, daisies, and peonies.

Use common sense for other cases. Read the sentence out loud, and use a comma where clarity or pause may be needed.

#### Dashes and hyphens

Use a hyphen - without spaces on either side to link words, or indicate a span or range.

- first-time user
- Monday-Friday

Use an em dash - without spaces on either side to indicate an aside.

Use a true em dash, not hyphens.

- Multivariate testing-just one of our new Pro features-can help you grow your business.
- Austin thought Brad was the donut thief, but he was wrong-it was Lain.

#### Ellipses

Ellipses ... can be used to indicate an indefinite ending to a sentence or to show words are omitted when used in brackets [...] Use rarely.

#### Exclamation points

Use an exclamation point rarely and use only one.

Exclamation points follow the same placement convention explained in Periods.

#### Periods

Periods should be:

- Inside quotation marks
- Outside parentheses when the portion in parentheses is part of a larger sentence
- Inside parentheses when the part in parentheses can stand on its own

Examples

- Jake said, "I had the best day ever."
- She went to the supermarket (and to the nail salon).
- My mom loves pizza and beer. (Beer needs to be cold and dark.)

#### Question marks

Question marks follow the same placement convention explained in Periods.

#### Quotation marks

Periods and commas go within quotation marks. Question marks within quotes follow logic - if the question mark is part of the quotation, it goes within. If you're asking a question that ends with a quote, it goes outside the quote.

Use single quotation marks for quotes within quotes.

- Who sings, "All These Things That I've Done"?
- Brandon Flowers of The Killers said, "I was inspired and on a roll when I wrote, 'I got soul, but I'm not a soldier.'"

#### Semicolons

Semicolons can be used to join two related phrases.

- Their debut solo album hit the Top 10 in 20 countries; it was #1 in the UK.

### People, places, and things

#### Company names and products

Use brand identity names and products as written on official websites.

- Pull&Bear
- UE Boom

Refer to a company or product as 'it' (not 'they').

- WooCommerce is, and not WooCommerce are.

#### File extensions

A file extension type should be all uppercase without periods. Add a lowercase s to make plural.

- HTML
- JPEG
- PDF

A specific file should have a lowercase extension type:

- dancingcat.gif
- SalesReport2016.pdf
- firethatcannon.mp3

#### Names and titles

First mention of a person should include their first and last name. Second and consecutive mentions can use first name only.

Capitalize job titles, the names of teams, and departments.

- Happiness Engineers or HEs
- Team Apollo
- Legal

#### Pronouns

Use personal pronouns such as he/him/his, she/her/hers, and they/them/theirs as appropriate when referring to a specific person. When talking abstractly (rather than about a specific person), default to they/them/theirs, not he/him/his. For example: "when a developer needs to troubleshoot, they might choose to use Xdebug".

Don't use "one" as a pronoun. Instead, use "you" when talking directly to the reader. For example, use "if you encounter an error, you should try deactivating the plugin" rather than "if one encounters an error, they should try deactivating the plugin".

#### Quotations

Use present tense when quoting someone.

- "I love that WooCommerce is free and flexible," says Brent Jamison.

#### Schools

The first time you mention a school, college, or university in a piece of writing, refer to it by its full official name. On all other mentions, use its more common abbreviation.

- Georgia Institute of Technology, Georgia Tech
- Georgia State University, GSU

#### States, cities, and countries

Spell out all city and state names. Don't abbreviate city names.

On first mention, write out United States. For further mentions, use U.S. The same applies to other countries or federations with a common abbreviation, such as European Union (EU) and United Kingdom (UK).

#### URLs and websites

Capitalize the names of websites and web publications. Don't italicize.

Avoid writing out URLs; omit `http://www` when it's necessary.

### Slang and jargon

Write in plain English. Text should be universally understood, with potential for translation. Briefly define technical terms when needed.

### Text formatting

Use italics to indicate the title of a book, movie, or album.

- The Oren Klaff book Pitch Anything is on sale for USD $5.99.

Avoid:

- Underline formatting
- A mix of italic, bold, caps, and underline

Left-align text, never center or right-aligned.

Leave one space between sentences, never two.


---

## Naming conventions

*Source: best-practices/coding-standards/naming-conventions.md*

# Naming conventions

## PHP

WooCommerce core generally follows [WordPress PHP naming conventions](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#naming-conventions). 

There are some additional conventions that apply, depending on the location of the code.

### `/src`

Classes defined inside `/src` follow the [PSR-4](https://www.php-fig.org/psr/psr-4/) standard. See the [README for `/src`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/README.md) for more information.

The following conventions apply to this directory:

- No class name prefix is needed, as all classes in this location live within the `Automattic\WooCommerce` namespace.
- Classes are named using `CamelCase` convention.
- Functions are named using `snake_case` convention.
- Class file names should match the class name. They do not need a `class-` prefix.
- The namespace should match the directory structure.
- Hooks are prefixed with `woocommerce_`.
- Hooks are named using `snake_case` convention.

For example, the class defined in `src/Util/StringUtil.php` should be named `StringUtil` and should be in the `Automattic\WooCommerce\Util` namespace.  

### `/includes`

The `/includes` directory contains legacy code that does not follow the PSR-4 standard. See the [README for `/includes`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/README.md) for more information.

The following conventions apply to this directory:

- Class names are prefixed with `WC_`.
- Classes are named using `Upper_Snake_Case` convention.
- Functions are prefixed with `wc_`.
- Functions are named using `snake_case` convention.
- Hooks are prefixed with `woocommerce_`.
- Hooks are named using `snake_case` convention.

Class name examples:

- `WC_Cache_Helper`
- `WC_Cart`

Function name examples:

- `wc_get_product()`
- `wc_is_active_theme()`

Hook name examples (actions or filters):

- `woocommerce_after_checkout_validation`
- `woocommerce_get_formatted_order_total`

## JS

WooCommerce core follows [WordPress JS naming conventions](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/#naming-conventions).

As with PHP, function, class, and hook names should be prefixed, but the convention for JS is slightly different.

- Global class names are prefixed with `WC`. Class names exported from modules are not prefixed.
- Classes are named using `UpperCamelCase` convention.
- Global function names are prefixed with `wc`. Function names exported from modules are not prefixed.
- Functions are named using `camelCase` convention.
- Hooks names are prefixed with `woocommerce`.
- Hooks are named using `camelCase` convention.

Global class name example:

- `WCOrdersTable`

Global function name example:

- `wcSettings()`

Hook name example (actions or filters):

- `woocommerceTracksEventProperties`

## CSS and SASS

See [CSS/Sass Naming Conventions](./css-sass-naming-conventions.md).


---

## Developing using WooCommerce CRUD objects

*Source: best-practices/data-management/crud-objects.md*

# Developing using WooCommerce CRUD objects

CRUD is an abbreviation of the four basic operations you can do to a database or resource - Create, Read, Update, Delete.

[WooCommerce 3.0 introduced CRUD objects](https://woocommerce.wordpress.com/2016/10/27/the-new-crud-classes-in-woocommerce-2-7/) for working with WooCommerce data. **Whenever possible these objects should be used in your code instead of directly updating metadata or using WordPress post objects.**

Each of these objects contains a schema for the data it controls (properties), a getter and setter for each property, and a save/delete method which talks to a data store. The data store handles the actual saving/reading from the database. The object itself does not need to be aware of where the data is stored.

## The benefits of CRUD

* Structure - Each object has a pre-defined structure and keeps its own data valid.
* Control - We control the flow of data, and any validation needed, so we know when changes occur.
* Ease of development - As a developer, you don't need to know the internals of the data you're working with, just the names.
* Abstraction - The data can be moved elsewhere, e.g. custom tables, without affecting existing code.
* Unification - We can use the same code for updating things in admin as we do in the REST API and CLIs. Everything is unified.
* Simplified code - Less procedural code to update objects which reduces likelihood of malfunction and adds more unit test coverage.

## CRUD object structure

The [`WC_Data`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/abstracts/abstract-wc-data.php) class is the basic implementation for CRUD objects, and all CRUD objects extend it. The most important properties to note are `$data`, which is an array of props supported in each object, and `$id`, which is the object's ID.

The [coupon object class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/class-wc-coupon.php) is a good example of extending `WC_Data` and adding CRUD functions to all properties.

### Data

`$data` stores the property names, and default values:

```php
/**
 * Data array, with defaults.
 * @since 3.0.0
 * @var array
 */
protected $data = array(
	'code'                        => '',
	'amount'                      => 0,
	'date_created'                => '',
	'date_modified'               => '',
	'discount_type'               => 'fixed_cart',
	'description'                 => '',
	'date_expires'                => '',
	'usage_count'                 => 0,
	'individual_use'              => false,
	'product_ids'                 => array(),
	'excluded_product_ids'        => array(),
	'usage_limit'                 => 0,
	'usage_limit_per_user'        => 0,
	'limit_usage_to_x_items'      => 0,
	'free_shipping'               => false,
	'product_categories'          => array(),
	'excluded_product_categories' => array(),
	'exclude_sale_items'          => false,
	'minimum_amount'              => '',
	'maximum_amount'              => '',
	'email_restrictions'          => array(),
	'used_by'                     => array(),
);
```

### Getters and setters

Each one of the keys in this array (property) has a getter and setter, e.g. `set_used_by()` and `get_used_by()`. `$data` itself is private, so the getters and setters must be used to access the data.

Example getter:

```php
/**
 * Get records of all users who have used the current coupon.
 * @since  3.0.0
 * @param  string $context
 * @return array
 */
public function get_used_by( $context = 'view' ) {
	return $this->get_prop( 'used_by', $context );
}
```

Example setter:

```php
/**
 * Set which users have used this coupon.
 * @since 3.0.0
 * @param array $used_by
 * @throws WC_Data_Exception
 */
public function set_used_by( $used_by ) {
	$this->set_prop( 'used_by', array_filter( $used_by ) );
}
```

`set_prop` and `get_prop` are part of `WC_Data`. These apply various filters (based on context) and handle changes, so we can efficiently save only the props that have changed rather than all props.

A note on `$context`: when getting data for use on the front end or display, `view` context is used. This applies filters to the data so extensions can change the values dynamically. `edit` context should be used when showing values to edit in the backend, and for saving to the database. Using `edit` context does not apply any filters to the data.

### The constructor

The constructor of the CRUD objects facilitates the read from the database. The actual read is not done by the CRUD class, but by its data store.

Example:

```php
/**
 * Coupon constructor. Loads coupon data.
 * @param mixed $data Coupon data, object, ID or code.
 */
public function __construct( $data = '' ) {
	parent::__construct( $data );

	if ( $data instanceof WC_Coupon ) {
		$this->set_id( absint( $data->get_id() ) );
	} elseif ( is_numeric( $data ) && 'shop_coupon' === get_post_type( $data ) ) {
		$this->set_id( $data );
	} elseif ( ! empty( $data ) ) {
		$this->set_id( wc_get_coupon_id_by_code( $data ) );
		$this->set_code( $data );
	} else {
		$this->set_object_read( true );
	}

	$this->data_store = WC_Data_Store::load( 'coupon' );
	if ( $this->get_id() > 0 ) {
		$this->data_store->read( $this );
	}
}
```

Note how it sets the ID based on the data passed to the object, then calls the data store to retrieve the data from the database. Once the data is read via the data store, or if no ID is set, `$this->set_object_read( true );` is set so the data store and CRUD object knows it's read. Once this is set, changes are tracked.

### Saving and deleting

Save and delete methods are optional on CRUD child classes because the `WC_Data` parent class can handle it. When `save` is called, the data store is used to store data to the database. Delete removes the object from the database. `save` must be called for changes to persist, otherwise they will be discarded.

The save method in `WC_Data` looks like this:

```php
/**
 * Save should create or update based on object existence.
 *
 * @since  2.6.0
 * @return int
 */
public function save() {
	if ( $this->data_store ) {
		// Trigger action before saving to the DB. Allows you to adjust object props before save.
		do_action( 'woocommerce_before_' . $this->object_type . '_object_save', $this, $this->data_store );

		if ( $this->get_id() ) {
			$this->data_store->update( $this );
		} else {
			$this->data_store->create( $this );
		}
		return $this->get_id();
	}
}
```

Update/create is used depending on whether the object has an ID yet. The ID will be set after creation.

The delete method is like this:

```php
/**
 * Delete an object, set the ID to 0, and return result.
 *
 * @since  2.6.0
 * @param  bool $force_delete
 * @return bool result
 */
public function delete( $force_delete = false ) {
	if ( $this->data_store ) {
		$this->data_store->delete( $this, array( 'force_delete' => $force_delete ) );
		$this->set_id( 0 );
		return true;
	}
	return false;
}
```

## CRUD usage examples

### Creating a new simple product

```php
$product = new WC_Product_Simple();
$product->set_name( 'My Product' );
$product->set_slug( 'myproduct' );
$product->set_description( 'A new simple product' );
$product->set_regular_price( '9.50' );
$product->save();

$product_id = $product->get_id();
```

### Updating an existing coupon

```php
$coupon = new WC_Coupon( $coupon_id );
$coupon->set_discount_type( 'percent' );
$coupon->set_amount( 25.00 );
$coupon->save();
```

### Retrieving a customer

```php
$customer = new WC_Customer( $user_id );
$email    = $customer->get_email();
$address  = $customer->get_billing_address();
$name     = $customer->get_first_name() . ' ' . $customer->get_last_name();
```


---

## Data storage primer

*Source: best-practices/data-management/data-storage.md*

# Data storage primer

When developing for WordPress and WooCommerce, it's important to consider the nature and permanence of your data. This will help you decide the best way to store it. Here's a quick primer:

## Transients

If the data may not always be present (i.e., it expires), use a [transient](https://developer.wordpress.org/apis/handbook/transients/). Transients are a simple and standardized way of storing cached data in the database temporarily by giving it a custom name and a timeframe after which it will expire and be deleted.

## WP Cache

If the data is persistent but not always present, consider using the [WP Cache](https://developer.wordpress.org/reference/classes/wp_object_cache/). The WP Cache functions allow you to cache data that is computationally expensive to regenerate, such as complex query results.

## wp_options Table

If the data is persistent and always present, consider the [wp_options table](https://developer.wordpress.org/apis/handbook/options/). The Options API is a simple and standardized way of storing data in the wp_options table in the WordPress database.

## Post Types

If the data type is an entity with n units, consider a [post type](https://developer.wordpress.org/post_type/). Post types are "types" of content that are stored in the same way, but are easy to distinguish in the code and UI.

## Taxonomies

If the data is a means of sorting/categorizing an entity, consider a [taxonomy](https://developer.wordpress.org/taxonomy/). Taxonomies are a way of grouping things together.

## Logging

Logs should be written to a file using the [WC_Logger](https://woocommerce.com/wc-apidocs/class-WC_Logger.html) class. This is a simple and standardized way of recording events and errors for debugging purposes.

Remember, the best method of data storage depends on the nature of the data and how it will be used in your application.


---

## How to manage WooCommerce Data Stores

*Source: best-practices/data-management/data-stores.md*

# How to manage WooCommerce Data Stores

## Introduction

Data store classes act as a bridge between WooCommerce's data CRUD classes (`WC_Product`, `WC_Order`, `WC_Customer`, etc) and the database layer. With the database logic separate from data, WooCommerce becomes more flexible. The data stores shipped with WooCommerce core (powered by WordPress' custom posts system and some custom tables) can be swapped out for a different database structure, type, or even be powered by an external API.

This guide will walk through the structure of a data store class, how to create a new data store, how to replace a core data store, and how to call a data store from your own code.

The examples in this guide will look at the [`WC_Coupon`](https://github.com/woocommerce/woocommerce/blob/dcecf0f22890f3cd92fbea13a98c11b2537df2a8/includes/class-wc-coupon.php#L19) CRUD data class and [`WC_Coupon_Data_Store_CPT`](https://github.com/woocommerce/woocommerce/blob/dcecf0f22890f3cd92fbea13a98c11b2537df2a8/includes/data-stores/class-wc-coupon-data-store-cpt.php), an implementation of a coupon data store using WordPress custom post types. This is how coupons are currently stored in WooCommerce.

The important thing to know about `WC_Coupon` or any other CRUD data class when working with data stores is which props (properties) they contain. This is defined in the [`data`](https://github.com/woocommerce/woocommerce/blob/dcecf0f22890f3cd92fbea13a98c11b2537df2a8/includes/class-wc-coupon.php#L26) array of each class.

## Structure

Every data store for a CRUD object should implement the `WC_Object_Data_Store_Interface` interface.

`WC_Object_Data_Store_Interface` includes the following methods:

* `create`
* `read`
* `update`
* `delete`
* `read_meta`
* `delete_meta`
* `add_meta`
* `update_meta`

The `create`, `read`, `update`, and `delete` methods should handle the CRUD logic for your props:

* `create` should create a new entry in the database. Example: Create a coupon.
* `read` should query a single entry from the database and set properties based on the response. Example: Read a coupon.
* `update` should make changes to an existing entry. Example: Update or edit a coupon.
* `delete` should remove an entry from the database. Example: Delete a coupon.

All data stores must implement handling for these methods.

In addition to handling your props, other custom data can be passed. This is considered `meta`. For example, coupons can have custom data provided by plugins.

The `read_meta`, `delete_meta`, `add_meta`, and `update_meta` methods should be defined so meta can be read and managed from the correct source. In the case of our WooCommerce core classes, we define them in `WC_Data_Store_WP` and then use the same code for all of our data stores. They all use the WordPress meta system. You can redefine these if meta should come from a different source.

Your data store can also implement other methods to replace direct queries. For example, the coupons data store has a public `get_usage_by_user_id` method. Data stores should always define and implement an interface for the methods they expect, so other developers know what methods they need to write. Put another way, in addition to the `WC_Object_Data_Store_Interface` interface, `WC_Coupon_Data_Store_CPT` also implements `WC_Coupon_Data_Store_Interface`.

## Replacing a data store

Let's look at how we would replace the `WC_Coupon_Data_Store_CPT` class with a `WC_Coupon_Data_Store_Custom_Table` class. Our examples will just provide stub functions, instead of a full working solution. Imagine that we would like to store coupons in a table named `wc_coupons` with the following columns:

```text
id, code, amount, date_created, date_modified, discount_type, description, date_expires, usage_count,individual_use, product_ids, excluded_product_ids, usage_limit, usage_limit_per_user, limit_usage_to_x_items, free_shipping, product_categories, excluded_product_categories, exclude_sale_items, minimum_amount, maximum_amount, email_restrictions, used_by
```

These column names match 1 to 1 with prop names.

First we would need to create a new data store class to contain our logic:

```php
/**
 * WC Coupon Data Store: Custom Table.
 */
class WC_Coupon_Data_Store_Custom_Table extends WC_Data_Store_WP implements WC_Coupon_Data_Store_Interface, WC_Object_Data_Store_Interface {

}
```

Note that we implement the main `WC_Object_Data_Store_Interface` interface as well as the ` WC_Coupon_Data_Store_Interface` interface. Together, these represent all the methods we need to provide logic for.

We would then define the CRUD handling for these properties:

```php
/**
 * Method to create a new coupon in the database.
 *
 * @param WC_Coupon
 */
public function create( &$coupon ) {
	$coupon->set_date_created( current_time( 'timestamp' ) );
	
	/**
	 * This is where code for inserting a new coupon would go.
	 * A query would be built using getters: $coupon->get_code(), $coupon->get_description(), etc.
	 * After the INSERT operation, we want to pass the new ID to the coupon object.
	 */
	$coupon->set_id( $coupon_id );
	
	// After creating or updating an entry, we need to also cause our 'meta' to save.
	$coupon->save_meta_data();
	
	// Apply changes let's the object know that the current object reflects the database and no "changes" exist between the two.
	$coupon->apply_changes();
	
	// It is helpful to provide the same hooks when an action is completed, so that plugins can interact with your data store.
	do_action( 'woocommerce_new_coupon', $coupon_id );
}

/**
 * Method to read a coupon.
 *
 * @param WC_Coupon
 */
public function read( &$coupon ) {
	$coupon->set_defaults();

	// Read should do a check to see if this is a valid coupon
	// and otherwise	throw an 'Invalid coupon.' exception.
	// For valid coupons, set $data to contain our database result.
	// All props should be set using set_props with output from the database. This "hydrates" the CRUD data object.
	$coupon_id = $coupon->get_id();
	$coupon->set_props( array(
		'code'                        => $data->code,
		'description'                 => $data->description,
		// ..
	) );
	
	
	// We also need to read our meta data into the object.
	$coupon->read_meta_data();
	
	// This flag reports if an object has been hydrated or not. If this ends up false, the database hasn't correctly set the object.
	$coupon->set_object_read( true );
	do_action( 'woocommerce_coupon_loaded', $coupon );
}

/**
 * Updates a coupon in the database.
 *
 * @param WC_Coupon
 */
public function update( &$coupon ) {
	// Update coupon query, using the getters.
	
	$coupon->save_meta_data();
	$coupon->apply_changes();
	do_action( 'woocommerce_update_coupon', $coupon->get_id() );
}

/**
 * Deletes a coupon from the database.
 *
 * @param WC_Coupon
 * @param array $args Array of args to pass to the delete method.
 */
public function delete( &$coupon, $args = array() ) {
	// A lot of objects in WordPress and WooCommerce support
	// the concept of trashing. This usually is a flag to move the object
	// to a "recycling bin". Since coupons support trashing, your layer should too.
	// If an actual delete occurs, set the coupon ID to 0.
	
	$args = wp_parse_args( $args, array(
		'force_delete' => false,
	) );

	$id = $coupon->get_id();

	if ( $args['force_delete'] ) {
		// Delete Query
		$coupon->set_id( 0 );
		do_action( 'woocommerce_delete_coupon', $id );
	} else {
		// Trash Query
		do_action( 'woocommerce_trash_coupon', $id );
	}
}
```

We are extending `WC_Data_Store_WP` so our classes will continue to use WordPress' meta system.

As mentioned in the structure section, we are responsible for implementing the methods defined by `WC_Coupon_Data_Store_Interface`. Each interface describes the methods and parameters it accepts, and what your function should do.

A coupons replacement would look like the following:

```php
/**
 * Increase usage count for current coupon.
 * 
 * @param WC_Coupon
 * @param string $used_by Either user ID or billing email
 */
public function increase_usage_count( &$coupon, $used_by = '' ) {

}

/**
 * Decrease usage count for current coupon.
 * 
 * @param WC_Coupon
 * @param string $used_by Either user ID or billing email
 */
public function decrease_usage_count( &$coupon, $used_by = '' ) {

}

/**
 * Get the number of uses for a coupon by user ID.
 * 
 * @param WC_Coupon
 * @param id $user_id
 * @return int
 */
public function get_usage_by_user_id( &$coupon, $user_id ) {

}

/**
 * Return a coupon code for a specific ID.
 * @param int $id
 * @return string Coupon Code
 */
 public function get_code_by_id( $id ) {
 
 }

 /**
  * Return an array of IDs for for a specific coupon code.
  * Can return multiple to check for existence.
  * @param string $code
  * @return array Array of IDs.
  */
 public function get_ids_by_code( $code ) {
 
 }
```

Once all the data store methods are defined and logic written, we need to tell WooCommerce to load our new class instead of the built-in class. This is done using the `woocommerce_data_stores` filter. An array of data store slugs is mapped to default WooCommerce classes. Example:

```php
'coupon'              => 'WC_Coupon_Data_Store_CPT',
'customer'            => 'WC_Customer_Data_Store',
'customer-download'   => 'WC_Customer_Download_Data_Store',
'customer-session'    => 'WC_Customer_Data_Store_Session',
'order'               => 'WC_Order_Data_Store_CPT',
'order-refund'        => 'WC_Order_Refund_Data_Store_CPT',
'order-item'          => 'WC_Order_Item_Data_Store',
'order-item-coupon'   => 'WC_Order_Item_Coupon_Data_Store',
'order-item-fee'      => 'WC_Order_Item_Fee_Data_Store',
'order-item-product'  => 'WC_Order_Item_Product_Data_Store',
'order-item-shipping' => 'WC_Order_Item_Shipping_Data_Store',
'order-item-tax'      => 'WC_Order_Item_Tax_Data_Store',
'payment-token'       => 'WC_Payment_Token_Data_Store',
'product'             => 'WC_Product_Data_Store_CPT',
'product-grouped'     => 'WC_Product_Grouped_Data_Store_CPT',
'product-variable'    => 'WC_Product_Variable_Data_Store_CPT',
'product-variation'   => 'WC_Product_Variation_Data_Store_CPT',
'shipping-zone'       => 'WC_Shipping_Zone_Data_Store',
```

We specifically want to target the coupon data store, so we would do something like this:

```php
function myplugin_set_wc_coupon_data_store( $stores ) {
	$stores['coupon'] = 'WC_Coupon_Data_Store_Custom_Table';
	return $stores;
}

add_filter( 'woocommerce_data_stores', 'myplugin_set_wc_coupon_data_store' );
```

Our class would then be loaded by WooCommerce core, instead of `WC_Coupon_Data_Store_CPT`.

## Creating a new data store

### Defining a new product type

Does your extension create a new product type? Each product type has a data store in addition to a parent product data store. The parent store handles shared properties like name or description and the child handles more specific data.

For example, the external product data store handles "button text" and "external URL". The variable data store handles the relationship between parent products and their variations.

Check out [this walkthrough](https://developer.woocommerce.com/2017/02/06/wc-2-7-extension-compatibility-examples-3-bookings/) for more information on this process.

### Data store for custom data

If your extension introduces a new database table, new custom post type, or some new form of data not related to products, orders, etc, then you should implement your own data store.

Your data store should still implement `WC_Object_Data_Store_Interface` and provide the normal CRUD functions. Your data store should be the main point of entry for interacting with your data, so any other queries or operations should also have methods.

The [shipping zone data store](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/data-stores/class-wc-shipping-zone-data-store.php) serves as a good example for a "simple" data store using a custom table. The coupons code is a good example for a data store using a custom post type.

All you need to do to register your data store is add it to the `woocommerce_data_stores` filter:

```php
function myplugin_set_my_custom_data_store( $stores ) {
	$stores['mycustomdata'] = 'WC_My_Custom_Data_Store';
	return $stores;
}

add_filter( 'woocommerce_data_stores', 'myplugin_set_my_custom_data_store' );
```

You can then load your data store like any other WooCommerce data store.

## Calling a data store

Calling a data store is as simple as using the static `WC_Data_Store::load()` method:

```php
// Load the shipping zone data store.
$data_store = WC_Data_Store::load( 'shipping-zone' );
// Get the number of shipping methods for zone ID 4.
$num_of_methods = $data_store->get_method_count( 4 );
```

You can also chain methods:

```php
// Get the number of shipping methods for zone ID 4.
$num_of_methods = WC_Data_Store::load( 'shipping-zone' )->get_method_count( 4 );
```

The `::load()` method works for any data store registered to `woocommerce_data_stores`, so you could load your custom data store:

```php
$data_store = WC_Data_Store::load( 'mycustomdata' );
```

## Data store limitations and WP Admin

Currently, several WooCommerce screens still rely on WordPress to list objects. Examples of this include coupons and products.

If you replace data via a data store, some parts of the existing UI may fail. An example of this may be lists of coupons when using the `type` filter. This filter uses meta data, and is in turn passed to WordPress which runs a query using the `WP_Query` class. This cannot handle data outside of the regular meta tables (Ref #19937). To get around this, usage of `WP_Query` would need to be deprecated and replaced with custom query classes and functions.


---

## Logging in WooCommerce

*Source: best-practices/data-management/logging.md*

# Logging in WooCommerce

WooCommerce has its own robust system for logging, which can be used for debugging during development, catching errors on production, or even sending notifications when specific events occur. By default, WooCommerce uses this logger to record errors, warnings, and other notices that may be useful for troubleshooting problems with a store. Many extensions for WooCommerce also make use of the logger for similar purposes.

## Viewing logs

You can view the entries created by the logger by going to **WooCommerce > Status > Logs**. The log viewing interface depends on which log storage method is configured (see the "Configuring the logger" section below).

### File system

With the default file system storage method, the first thing you will see is the list of existing log files:

![The default log viewing interface, showing a list of log files](/img/doc_images/file-browse.png)

The name of a log file is based on the source of the entries it contains (meaning the extension or the part of the WooCommerce codebase), as well as the date the entries were generated. In this file browsing view, you can sort the files in different ways as well as filtering them to show only those from a specific source. Clicking on a file will take you to a single file view, where you can see the actual log entries:

![The contents of a log file](/img/doc_images/file-view-new.png)

Click on a line number in the file to highlight it. This can also be used to link to a specific line in a file from elsewhere.

From the file browser view, you can sort and filter a list of log files, and then search for a string within the contents of those files:

![A list of search results](/img/doc_images/search-results.png)

Clicking on a search result line number will take you to that line in the single file view.

### Database

With the database storage method, you will see a list of log entries, starting with the most recent:

![The log viewing interface when log entries are stored in the database](/img/doc_images/database-logs.png)

These entries can be sorted by timestamp, level, and source, as well as filtered to only show a particular source or a minimum level. You can also search for a string within the log entry message fields.

## Configuring the logger

From the Logs screen at **WooCommerce > Status > Logs**, click the "Settings" link to make configuration changes:

![The Logs settings screen](/img/doc_images/settings.png)

### Logger

Uncheck the box here to turn off all logging. This is not recommended in most circumstances, as logging can provide valuable information about what is happening on your site!

### Log storage

Out-of-the-box, WooCommerce has two different log storage methods available:

* **File system** - Log entries are recorded to files. Files are differentiated by the `source` value for the log entry (see the "Adding logs" section below), and by the current date. The files are stored in the `wc-logs` subdirectory of the site's `uploads` directory. A custom directory can be defined using the `woocommerce_log_directory` filter hook. Log files can be up to 5 MB in size, after which the log file will rotate.
* **Database** - Log entries are recorded to the database, in the `{$wpdb->prefix}woocommerce_log` table.

If you change this setting, and you already have some log entries, those entries will not be migrated to the other storage method, but neither will they be deleted.

### Retention period

The logger will periodically go through and delete logs that are older than this time period, as a space-saving measure. If log entries are stored in the file system, the entire log file that is beyond the retention period will be deleted, while with database storage, individual log entries will be deleted.

### Level threshold

Each log entry has a severity level (see the "Adding logs" section below). This sets a minimum severity level, and any log entries that are generated that are not at or above the minimum level will not be recorded. Use this setting with caution!

If this setting is set to "None", it means that all log entries will be recorded, regardless of severity level.

## Adding logs

Logs are added via methods in the `WC_Logger` class. The class instance is accessed by using the `wc_get_logger()` function. The basic method for adding a log entry is [`WC_Logger::log( $level, $message, $context )`](https://woocommerce.github.io/code-reference/classes/WC-Logger.html#method_log). There are also shortcut methods for each log severity level, for example `WC_Logger::warning( $message, $context )`. It is preferable to use the shortcut methods rather than the generic `log` method.

### Level

Logs have eight different severity levels:

* `emergency`
* `alert`
* `critical`
* `error`
* `warning`
* `notice`
* `info`
* `debug`

Aside from giving a site owner context as to how important a log entry is, these levels also allow logs to be filtered. If you only want log entries to be recorded for `error` severity and higher, you can set the threshold on the Logs Settings screen (see the "Configuring the logger" above).

Note that this threshold will apply to all logs, regardless of which log handler is in use. The `WC_Log_Handler_Email` class, for example, has its own threshold setting, but it is secondary to the global threshold.

### Message

The message is the main content of a log entry. Make sure it's understandable by anyone who might be viewing the logs!

### Context

The context parameter is intended to be used to store additional structured data related to the log entry. For example, in a log entry about an order, you may want to include contents of the related order object. When the logger is generating an entry, the data in the context parameter is converted to JSON before it is stored. So, if you want to add multiple pieces of context data, each should be added as a separate key within the context array.

There are two specific keys that can be added to the context array that will cause special behavior:

#### `source`

It is recommended that every log entry include a `source` value in the context parameter. `source` is intended to provide context about where in the application or codebase the log was generated, and can be used to filter log entries. 

If a source is not specified, the logger will generate a source value based on the plugin or file where the log entry was generated.

#### `backtrace`

Setting the `backtrace` key in your context parameter to `true` will cause the logger to generate a backtrace (i.e. stack trace) in array format, which will be included in the context in place of the `true` value. This is useful particularly for error-related logs, so you can see what code was executed that led to the log entry being generated.

![A backtrace displayed in the log file viewer](/img/doc_images/backtrace.png)

### Full example

```php
wc_get_logger()->info(
    'It is time for lunch.',
    array(
        'source'        => 'your_stomach',
        'backtrace'     => true,
        'previous_meal' => $elapsed_time_since_breakfast,
        'lunch_options' => array( 'fridge leftovers', 'bahn mi', 'tacos', 'pupusas' ),
    )
);
```

## Logging best practices

### When to use logging

* To help troubleshoot an unexpected problem:
    * An unexpected value or error is received from an API.
    * Data in the system is incorrect or corrupted.
    * The application is in an unexpected or broken state.
* To keep an audit log of a process:
    * Transaction details not stored elsewhere, like an order note (but maybe they should be?)
    * Results of data import or export.
    * An important setting is changed.
    * An automated process changes or deletes data.

### When _not_ to use logging

* To let a developer know that they're using a method or API incorrectly. This can lead to a large volume of useless log entries, especially if it will get triggered on every page request. Better to give them immediate feedback in the form of an error or exception (e.g. `wc_doing_it_wrong()`).

### Best practices

* Rather than using the `WC_Logger`'s `log()` method directly, it's better to use one of the wrapper methods that's specific to the log level. E.g. `info()` or `error()`.
* Write a message that is a complete, coherent sentence. This will make it more useful for people who aren't familiar with the codebase.
* Log messages should not be translatable. Keeping the message in English makes it easier to search for solutions based on the message contents, and also makes it easier for anyone troubleshooting to understand what's happening, since they may not speak the same language as the site owner.
* Ideally, each log entry message should be a single line (i.e. no line breaks within the message string). Additional lines or extra data should be put in the context array.
* Avoid outputting structured data in the message string. Put it in a key in the context array instead. The logger will handle converting it to JSON and making it legible in the log viewer.
* If you need to include a stack trace, let the logger generate it for you.
* Decide on a source for the component or system you are working on and use it for every log call you make. This will make it easier to find all the log entries that are related to the component, and filter them out from other, unrelated log entries.
* Consider adding one log entry after a looped process with the aggregated results of the loop, rather than adding a separate entry during each item within a loop.

## Customizing the logger

### The logger class

The `WC_Logger` class can be substituted for another class via the `woocommerce_logging_class` filter hook. The alternative class must implement [`WC_Logger_Interface`](https://woocommerce.github.io/code-reference/classes/WC-Logger-Interface.html), or it will not be used. Generally it is better to create a custom log handler (see below) rather than overriding the logger class itself.

### Log handlers

In WooCommerce, a log handler is a PHP class that takes the raw log data and transforms it into a log entry that can be stored or dispatched. WooCommerce ships with four different log handler classes:

* `Automattic\\WooCommerce\\Internal\\Admin\\Logging\\LogHandlerFileV2`: This is the default handler, representing the "file system" log storage method. It records log entries to files.
* `WC_Log_Handler_File`: This is the old default handler that also records log entries to files. It may be deprecated in the future, and it is not recommended to use this class or extend it.
* `WC_Log_Handler_DB`: This handler represents the "database" log storage method. It records log entries to the database.
* `WC_Log_Handler_Email`: This handler does not store log entries, but instead sends them as email messages. Emails are sent to the site admin email address. This handler has [some limitations](https://github.com/woocommerce/woocommerce/blob/fe81a4cf27601473ad5c394a4f0124c785aaa4e6/plugins/woocommerce/includes/log-handlers/class-wc-log-handler-email.php#L15-L27).

#### Changing or adding handlers

To switch from the file handler to the database handler, you can simply update the option on the Logs Settings screen. However, in some cases, you may want to have more than one log handler, and/or you might want to modify the settings of a handler. For example, you may want to have most logs saved to files, but log entries that are classified as emergency or critical errors also sent to an email address. For this, you can use the `woocommerce_register_log_handlers` filter hook to create an array of log handler class instances that you want to use. Some handler class constructors have optional parameters that you can use when instantiating the class to change their default behavior.

Here's an example of adding the email handler:

```php
function my_wc_log_handlers( $handlers ) {
	$recipients = array( 'wayne@example.com', 'garth@example.com' ); // Send logs to multiple recipients.
	$threshold  = 'critical'; // Only send emails for logs of this level and higher.
	$handlers[] = new WC_Log_Handler_Email( $recipients, $threshold );
	
	return $handlers;
}
add_filter( 'woocommerce_register_log_handlers', 'my_wc_log_handlers' );
```

#### Creating a custom handler

You may want to create your own log handler class in order to send logs somewhere else, such as a Slack channel or perhaps an InfluxDB instance. Your class must extend the [`WC_Log_Handler`](https://woocommerce.github.io/code-reference/classes/WC-Log-Handler.html) abstract class and implement the [`WC_Log_Handler_Interface`](https://woocommerce.github.io/code-reference/classes/WC-Log-Handler-Interface.html) interface. The [`WC_Log_Handler_Email`](https://github.com/woocommerce/woocommerce/blob/6688c60fe47ad42d49deedab8be971288e4786c1/plugins/woocommerce/includes/log-handlers/class-wc-log-handler-email.php) handler class provides a good example of how to set this up.

### Log file storage location

When using the "file system" log handler, by default the log files are stored in the `wc-logs` subdirectory of the WordPress `uploads` directory, which means they might be publicly accessible. WooCommerce adds an `.htaccess` file to prevent access to `wc-logs`, but not all web servers recognize that file. If you have the option, you may want to consider storing your log files in a directory outside of the web root. Make sure the directory has the same user/group permissions as the `uploads` directory so that WordPress can access it. Then use the `woocommerce_log_directory` filter hook to set the path to your custom directory.

### Turning off noisy logs

If there is a particular log that is recurring frequently and clogging up your log files, you should probably figure out why it keeps getting triggered and resolve the issue. However, if that's not possible, you can add a callback to the `woocommerce_logger_log_message` filter hook to ignore that particular log while still allowing other logs to get through:

```php
function my_ignored_logs( $message, $level, $context, $handler ) {
	if ( false !== strpos( $message, 'Look, a squirrel!' ) ) {
		return null;
	}
	
	return $message;
}
add_filter( 'woocommerce_logger_log_message', 'my_ignored_logs', 10, 4 );
```

### The Logs UI

If you create a custom log handler and you want to build a separate interface for it on the Logs screen, there are a couple of filter hooks that you can work with:

* `woocommerce_logger_handler_options`: This filter hook allows you to add your custom log handler to the list of "Log storage" options on the Settings screen. Your handler must be selected for this setting, making it the "default" log handler, before you can render an alternative interface for it.
* `wc_logs_render_page`: This is the action to hook into for rendering your own Logs interface. It only fires if the default log handler is set to something that is not one of the built-in handlers.
* `wc_logs_load_tab`: This action fires when the Logs tab first starts loading, before any content is output. It's useful for handling form submissions.


---

## How to configure caching plugins for WooCommerce

*Source: best-practices/performance/configuring-caching-plugins.md*

# How to configure caching plugins for WooCommerce

## Excluding pages from the cache

Oftentimes if using caching plugins they'll already exclude these pages. Otherwise make sure you exclude the following pages from the cache through your caching systems respective settings.

- Cart
- My Account
- Checkout

These pages need to stay dynamic since they display information specific to the current customer and their cart.

## Excluding WooCommerce session from the cache

If the caching system you're using offers database caching, it might be helpful to exclude `_wc_session_` from being cached. This will be dependent on the plugin or host caching so refer to the specific instructions or docs for that system.

## Excluding WooCommerce cookies from the cache

Cookies in WooCommerce help track the products in your customers cart, can keep their cart in the database if they leave the site, and powers the recently viewed widget. Below is a list of the cookies WooCommerce uses for this, which you can exclude from caching.

| COOKIE NAME | DURATION | PURPOSE |
| --- | --- | --- |
| woocommerce_cart_hash | session | Helps WooCommerce determine when cart contents/data changes. |
| woocommerce_items_in_cart | session | Helps WooCommerce determine when cart contents/data changes. |
| wp_woocommerce_session_ | 2 days | Contains a unique code for each customer so that it knows where to find the cart data in the database for each customer. |
| woocommerce_recently_viewed | session | Powers the Recent Viewed Products widget. |
| store_notice[notice id] | session | Allows customers to dismiss the Store Notice. |


We're unable to cover all options, but we have added some tips for the popular caching plugins. For more specific support, please reach out to the support team responsible for your caching integration.

### W3 total cache minify settings

Ensure you add 'mfunc' to the 'Ignored comment stems' option in the Minify settings.

### WP-Rocket

WooCommerce is fully compatible with WP-Rocket. Please ensure that the following pages (Cart, Checkout, My Account) are not to be cached in the plugin's settings.

We recommend avoiding JavaScript file minification.

### WP Super Cache

WooCommerce is natively compatible with WP Super Cache. WooCommerce sends information to WP Super Cache so that it doesn't cache the Cart, Checkout, or My Account pages by default.

### Varnish

```varnish
if (req.url ~ "^/(cart|my-account|checkout|addons)") {
  return (pass);
}
if ( req.url ~ "\\?add-to-cart=" ) {
  return (pass);
}
```

## Troubleshooting

### Why is my Varnish configuration not working in WooCommerce?

Check out the following WordPress.org Support forum post on[ how cookies may be affecting your varnish coding](https://wordpress.org/support/topic/varnish-configuration-not-working-in-woocommerce).

```text
Add this to vcl_recv above "if (req.http.cookie) {":

# Unset Cookies except for WordPress admin and WooCommerce pages 
if (!(req.url ~ "(wp-login|wp-admin|cart|my-account/*|wc-api*|checkout|addons|logout|lost-password|product/*)")) { 
unset req.http.cookie; 
} 
# Pass through the WooCommerce dynamic pages 
if (req.url ~ "^/(cart|my-account/*|checkout|wc-api/*|addons|logout|lost-password|product/*)") { 
return (pass); 
} 
# Pass through the WooCommerce add to cart 
if (req.url ~ "\?add-to-cart=" ) { 
return (pass); 
} 
# Pass through the WooCommerce API
if (req.url ~ "\?wc-api=" ) { 
return (pass); 
} 
# Block access to php admin pages via website 
if (req.url ~ "^/phpmyadmin/.*$" || req.url ~ "^/phppgadmin/.*$" || req.url ~ "^/server-status.*$") { 
error 403 "For security reasons, this URL is only accessible using localhost (127.0.0.1) as the hostname"; 
} 

Add this to vcl_fetch:

# Unset Cookies except for WordPress admin and WooCommerce pages 
if ( (!(req.url ~ "(wp-(login|admin)|login|cart|my-account/*|wc-api*|checkout|addons|logout|lost-password|product/*)")) || (req.request == "GET") ) { 
unset beresp.http.set-cookie; 
} 
```

### Why is my Password Reset stuck in a loop?

This is due to the My Account page being cached, Some hosts with server-side caching don't prevent my-account.php from being cached.

If you're unable to reset your password and keep being returned to the login screen, please speak to your host to make sure this page is being excluded from their caching.


---

## Performance best practices for WooCommerce extensions

*Source: best-practices/performance/performance-best-practices.md*

# Performance best practices for WooCommerce extensions

Optimizing the performance of WooCommerce extensions is vital for ensuring that online stores run smoothly, provide a superior user experience, and rank well in search engine results. This guide is tailored for developers looking to enhance the speed and efficiency of their WooCommerce extensions, with a focus on understanding performance impacts, benchmarking, testing, and implementing strategies for improvement.

## Performance optimization

For WooCommerce extensions, performance optimization means ensuring that your code contributes to a fast, responsive user experience without adding unnecessary load times or resource usage to the store.

### Why performance is critical

- **User Experience**: Fast-performing extensions contribute to a seamless shopping experience, encouraging customers to complete purchases.
- **Store Performance**: Extensions can significantly impact the overall speed of WooCommerce stores; optimized extensions help maintain optimal site performance.
- **SEO and Conversion Rates**: Speed is a critical factor for SEO rankings and conversion rates. Efficient extensions support better store rankings and higher conversions.

## Benchmarking performance

Setting clear performance benchmarks is essential for development and continuous improvement of WooCommerce extensions. A recommended performance standard is achieving a Chrome Core Web Vitals "Performance" score of 90 or above on a simple Woo site, using tools like the [Chrome Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/).

### Using accessible tools for benchmarking

Chrome Lighthouse provides a comprehensive framework for evaluating the performance of web pages, including those impacted by your WooCommerce extension. By integrating Lighthouse testing into your development workflow, you can identify and address performance issues early on.

We recommend leveraging tools like this to assess the impact of your extension on a WooCommerce store's performance and to identify areas for improvement.

## Performance improvement strategies

Optimizing the performance of WooCommerce extensions can involve several key strategies:

- **Optimize asset loading**: Ensure that scripts and styles are loaded conditionally, only on pages where they're needed.
- **Efficient database queries**: Optimize database interactions to minimize query times and resource usage. Use indexes appropriately and avoid unnecessary data retrieval.
- **Lazy Loading**: Implement lazy loading for images and content loaded by your extension to reduce initial page load times.
- **Minification and concatenation**: Minify CSS and JavaScript files and concatenate them where possible to reduce the number of HTTP requests.
- **Testing with and without your extension**: Regularly test WooCommerce stores with your extension activated and deactivated to clearly understand its impact on performance.
- **Caching support**: Ensure your extension is compatible with popular caching solutions, and avoid actions that might bypass or clear cache unnecessarily.

By following these best practices and regularly benchmarking and testing your extension, you can ensure it enhances, rather than detracts from, the performance of WooCommerce stores. Implementing these strategies will lead to more efficient, faster-loading extensions that store owners and their customers will appreciate.


---

## How to optimize performance for WooCommerce stores

*Source: best-practices/performance/performance-optimization.md*

# How to optimize performance for WooCommerce stores

## Introduction

This guide covers best practices and techniques for optimizing the performance of WooCommerce stores, including caching, image optimization, database maintenance, code minification, and the use of Content Delivery Networks (CDNs). By following these recommendations, developers can build high-performing WooCommerce stores that provide a better user experience and contribute to higher conversion rates.

## Audience

This guide is intended for developers who are familiar with WordPress and WooCommerce and want to improve the performance of their online stores.

## Prerequisites

To follow this guide, you should have:

1. A basic understanding of WordPress and WooCommerce.
2. Access to a WordPress website with WooCommerce installed and activated.

## Step 1 - Implement caching

Caching plays a crucial role in speeding up your WooCommerce store by serving static versions of your pages to visitors, reducing the load on your server. There are several ways to implement caching for your WooCommerce store:

### Server-Side caching

Enable server-side caching through your hosting provider or by using server-level caching solutions like Varnish, NGINX FastCGI Cache, or Redis.

### WordPress caching plugins

Install and configure a WordPress caching plugin, such as WP Rocket, W3 Total Cache, or WP Super Cache. These plugins can help you set up page caching, browser caching, and object caching for your WooCommerce store.

### WooCommerce-Specific caching

Ensure that your caching solution is configured correctly for WooCommerce, allowing dynamic content such as cart and checkout pages to remain uncached. Some caching plugins, like WP Rocket, include built-in support for WooCommerce caching.

## Step 2 - Optimize images

Optimizing images can significantly improve your store's performance by reducing the size of image files without compromising quality. To optimize images for your WooCommerce store:

1. Use the right image format: Choose an appropriate format for your images, such as JPEG for photographs and PNG for graphics with transparency.
2. Compress images: Use an image compression tool like TinyPNG or ShortPixel to reduce file sizes before uploading them to your store.
3. Enable lazy loading: Lazy loading delays the loading of images until they're needed, improving initial page load times. Many caching plugins and performance optimization plugins offer built-in lazy loading options.
4. Use responsive images: Ensure that your theme and plugins serve appropriately sized images for different devices and screen resolutions.

## Step 3 - Minify and optimize code

Minifying and optimizing your store's HTML, CSS, and JavaScript files can help reduce file sizes and improve page load times. To minify and optimize code for your WooCommerce store:

1. Use a plugin: Install a performance optimization plugin like Autoptimize, WP Rocket, or W3 Total Cache to minify and optimize your store's HTML, CSS, and JavaScript files.
2. Combine and inline critical CSS: Where possible, combine and inline critical CSS to reduce the number of requests and improve page load times.
3. Defer non-critical JavaScript: Defer loading of non-critical JavaScript files to improve perceived page load times.

## Step 4 - Use a content delivery network (CDN)

A Content Delivery Network (CDN) can help speed up your WooCommerce store by serving static assets like images, CSS, and JavaScript files from a network of servers distributed across the globe. To use a CDN for your WooCommerce store:

1. Choose a CDN provider: Select a CDN provider like Cloudflare, Fastly, or Amazon CloudFront that fits your needs and budget.
2. Set up your CDN: Follow your chosen CDN provider's instructions to set up and configure the CDN for your WooCommerce store.

## Step 5 - Optimize database

Regularly optimizing your WordPress database can help improve your WooCommerce store's performance by removing unnecessary data and optimizing database tables. To optimize your database:

1. Use a plugin: Install a database optimization plugin like WP-Optimize, WP-Sweep, or Advanced Database Cleaner to clean up and optimize your WordPress database.
2. Remove unnecessary data: Regularly delete spam comments, post revisions, and expired transients to reduce database clutter.
3. Optimize database tables: Use the database optimization plugin to optimize your database tables, improving their efficiency and reducing query times.

## Step 6 - Choose a high-performance theme and plugins

The theme and plugins you choose for your WooCommerce store can have a significant impact on performance. To ensure your store runs efficiently:

1. Select a lightweight, performance-optimized theme: Choose a theme specifically designed for WooCommerce that prioritizes performance and follows best coding practices.
2. Evaluate plugin performance: Use tools like Query Monitor or WP Hive to analyze the performance impact of the plugins you install, and remove or replace those that negatively affect your store's performance.

## Step 7 - Enable GZIP compression

GZIP compression can help reduce the size of your store's HTML, CSS, and JavaScript files, leading to faster page load times. To enable GZIP compression:

1. Use a plugin: Install a performance optimization plugin like WP Rocket, W3 Total Cache, or WP Super Cache that includes GZIP compression options.
2. Configure your server: Alternatively, enable GZIP compression directly on your server by modifying your .htaccess file (for Apache servers) or nginx.conf file (for NGINX servers).

## Step 8 - Monitor and analyze performance

Continuously monitor and analyze your WooCommerce store's performance to identify potential bottlenecks and areas for improvement. To monitor and analyze performance:

1. Use performance testing tools: Regularly test your store's performance using tools like Google PageSpeed Insights, GTmetrix, or WebPageTest.
2. Implement performance monitoring: Install a performance monitoring plugin like New Relic or use a monitoring service like Uptime Robot to keep track of your store's performance over time.

## Conclusion

By following these best practices and techniques for performance optimization, you can build a high-performing WooCommerce store that offers a better user experience and contributes to higher conversion rates. Continuously monitor and analyze your store's performance to ensure it remains optimized as your store grows and evolves.


---

## How to Prevent Data Leaks in WooCommerce

*Source: best-practices/security/prevent-data-leaks.md*

# How to Prevent Data Leaks in WooCommerce

Data leaks can expose sensitive information and compromise the security of a WooCommerce site. One common source of data leaks is direct access to PHP files. This tutorial will show you how to prevent these kinds of data leaks.

In each PHP file of your WooCommerce extension, you should check if a constant called 'ABSPATH' is defined. This constant is defined by WordPress itself, and it's not defined if a file is being accessed directly. Here's how you can do this:

```php
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly
}
```

With this code, if someone tries to access the PHP file directly, the 'ABSPATH' constant won't be defined, and the script will exit before any sensitive data can be leaked.

Remember, security is a crucial aspect of any WooCommerce site. Always take steps to prevent data leaks and protect your site's information.


---

## WooCommerce security best practices

*Source: best-practices/security/security-best-practices.md*

# WooCommerce security best practices

## Introduction to security practices

Security is extremely important for online stores. A breach can lead to significant financial loss, reputational damage, and erosion of customer trust. Implementing robust security practices is crucial. This guide covers the best practices for securing WooCommerce stores, including hardening WordPress, keeping plugins and themes up to date, implementing secure coding practices, and protecting user data. By following these recommendations, developers can build secure and resilient WooCommerce stores that protect both their business and their customers.

### Audience

This guide is intended for developers who are familiar with WordPress and WooCommerce and want to improve the security of their online stores.

### Prerequisites

To follow this guide, you should have:

1. A basic understanding of WordPress and WooCommerce.
2. Access to a WordPress website with WooCommerce installed and activated.

## Security standards

We recommend that you maintain the following standards: 

- **PHPCS**: The PHP Code Sniffer tool helps ensure your code adheres to specific coding standards, which can prevent common security issues. Extensions shouldn't have any failure results against PHPCS.

- **SemGrep**: Focuses on identifying patterns that may indicate security vulnerabilities, allowing developers to write more secure code. Extensions shouldn't have any failure results against SemGrep.

Understanding and implementing these standards can significantly reduce the risk of security vulnerabilities in your extensions and themes.

### Common security pitfalls and how to avoid them

Several common security pitfalls can easily be avoided with vigilance and best practices:

- **SQL injection**: Ensure all database queries are properly sanitized.
- **Cross-site scripting**: Sanitize all user input to prevent malicious code from being executed.
- **File inclusions**: Limit file inclusion to prevent unauthorized access to the file system.

Awareness and prevention of these common issues are crucial steps in securing your WooCommerce store. For more resources, we recommend reading the [WordPress security documentation](https://developer.wordpress.org/apis/security/).

## Manual testing guidelines

Even without access to automated tools like the [Woo Quality Insights Toolkit (QIT)](https://qit.woo.com), manual testing remains a vital component of securing your WooCommerce store. Here are some guidelines on how developers can manually test their extensions for security vulnerabilities: 

1. **Code review**: Regularly review your code for security vulnerabilities, focusing on the areas where breaches commonly occur, such as user input fields and database queries. Code reviews should check against the [WordPress security criteria](https://developer.wordpress.org/apis/security/) mentioned above. 
2. **Use security plugins**: Plugins like Wordfence, Sucuri, or iThemes Security provide an interface for manual security checks, including file integrity monitoring and malware scanning. Additionally, tooling like [OWASP Zap](https://www.zaproxy.org/) or [GitHub Security Scanning](https://github.com/features/security/) can be used.
3. **Testing environments**: Utilize staging environments to test the security of new features or updates before deploying them live.

## Other security best practices

### Keep WordPress, WooCommerce, and plugins up to date

Regularly updating WordPress, WooCommerce, and all installed plugins is crucial to maintaining a secure online store. Updates often include security patches that address vulnerabilities and help protect your store from attacks. To keep your WordPress and WooCommerce installations up to date:

1. Enable automatic updates for WordPress core.
2. Regularly check for and install updates for WooCommerce and all plugins.

### Choose secure plugins and themes

The plugins and themes you use can have a significant impact on the security of your WooCommerce store. To ensure your store is secure:

1. Install plugins and themes from reputable sources, such as the WordPress Plugin Directory and Theme Directory.
2. Regularly review and update the plugins and themes you use, removing any that are no longer maintained or have known security vulnerabilities.
3. Avoid using nulled or pirated plugins and themes, which may contain malicious code.

### Implement secure coding practices

Secure coding practices are essential for building a secure WooCommerce store. To implement secure coding practices:

1. Follow the WordPress Coding Standards when developing custom themes or plugins.
2. Use prepared statements and parameterized queries to protect against SQL injection attacks.
3. Validate and sanitize user input to prevent cross-site scripting (XSS) attacks and other vulnerabilities.
4. Regularly review and update your custom code to address potential security vulnerabilities.

### Harden WordPress security

Hardening your WordPress installation can help protect your WooCommerce store from attacks. To harden your WordPress security:

1. Use strong, unique passwords for all user accounts.
2. Limit login attempts and enable two-factor authentication (2FA) to protect against brute-force attacks.
3. Change the default `wp_` table prefix in your WordPress database.
4. Disable XML-RPC and REST API access when not needed.
5. Keep file permissions secure and restrict access to sensitive files and directories.

### Secure user data

Protecting your customers' data is a critical aspect of securing your WooCommerce store. To secure user data:

1. Use SSL certificates to encrypt data transmitted between your store and your customers.
2. Store customer data securely and limit access to sensitive information.
3. Comply with data protection regulations, such as the GDPR, to ensure you handle customer data responsibly.

### Implement a security plugin

Using a security plugin can help you monitor and protect your WooCommerce store from potential threats. To implement a security plugin:

1. Choose a reputable security plugin, such as Wordfence, Sucuri, or iThemes Security.
2. Configure the plugin's settings to enable features like malware scanning, firewall protection, and login security.

### Regularly monitor and audit your store's security

Continuously monitor and audit your WooCommerce store's security to identify potential vulnerabilities and address them before they can be exploited. To monitor and audit your store's security:

1. Use a security plugin to perform regular scans for malware and other security threats.
2. Monitor your site's activity logs to identify suspicious activity and potential security issues.
3. Perform regular security audits to evaluate your store's overall security and identify areas for improvement.

### Create regular backups

Backing up your WooCommerce store is essential for quickly recovering from security incidents, such as data loss or site compromise. To create regular backups:

1. Choose a reliable backup plugin, such as UpdraftPlus, BackupBuddy, or Duplicator.
2. Configure the plugin to automatically create regular backups of your entire site, including the database, files, and media.
3. Store your backups securely off-site to ensure they are accessible in case of an emergency.

## Conclusion

By following these security best practices, you can build a secure and resilient WooCommerce store that protects both your business and your customers. Regularly monitoring, auditing, and updating your store's security measures will help ensure it remains protected as new threats and vulnerabilities emerge.


---

## Shareable Checkout URLs

*Source: best-practices/urls-and-routing/checkout-urls.md*

# Shareable Checkout URLs

Custom checkout links automatically populate the cart with specific products and redirect customers straight to checkout with a unique session ID.

The custom checkout link path is `/checkout-link/` and is not customizable.

## Supported parameters

### Products

The `products` parameter accepts a comma-separated list of products. Each product uses the following positional format:

```plaintext
id-or-sku:quantity:variation-data:cart-item-data
```

The quantity, variation data, and cart item data are optional. The default quantity is `1`. Keep an empty field between colons when omitting a field that comes before one you want to provide.

The product identifier can be:

- A product or variation ID, such as `123`.
- A nonnumeric SKU, such as `BLUE-SHIRT`.
- A numeric SKU prefixed with `sku=`, such as `sku=999999`. Without the prefix, a numeric identifier is treated as a product ID.

Variation and cart item data use `key=value` pairs. Separate multiple pairs in the same field with semicolons. Variation data selects a variation, while cart item data passes additional values consumed by extensions or custom product types. The accepted cart item data depends on the extension handling the product.

For example:

```plaintext
products=123
products=123:2
products=BLUE-SHIRT:2
products=sku=999999:2
products=123:1:color=black;size=medium
products=123:1::nyp=120
products=123:2:color=black;size=medium:nyp=120
```

The last three examples add variation data, cart item data, or both. The empty variation field in `123:1::nyp=120` is required so that `nyp=120` is treated as cart item data.

Commas separate products, colons separate product fields, and semicolons separate data pairs. Prefix one of these delimiters with `~` when it is part of an SKU or data value rather than a separator. For example, the SKU `ABC,123:BLUE` is represented as follows:

```plaintext
products=ABC~,123~:BLUE:1
```

Existing links containing only product IDs and quantities continue to work.

### Coupon

```plaintext
coupon=SPRING10
```

A coupon code to apply to the cart. For example, `SPRING10`.

## Example

```plaintext
https://yourstore.com/checkout-link/?products=123:2,456:1&coupon=SPRING10
```

In this link:

- Product ID `123` will be added with quantity `2`.
- Product ID `456` will be added with quantity `1`.
- The coupon code `SPRING10` will be applied.
- The customer will be taken directly to the checkout page.

## Sessions

Once the user is redirected to the checkout page, the cart is populated with the products and coupon code. The final URL includes a `session` parameter storing the ID of the session. Future changes to the checkout will be persisted in the session, enabling persistent and shareable carts.


---

## Customizing WooCommerce endpoint URLs

*Source: best-practices/urls-and-routing/customizing-endpoint-urls.md*

# Customizing WooCommerce endpoint URLs

Before you start, check out [WooCommerce Endpoints](./woocommerce-endpoints.md). 

## Customizing endpoint URLs

The URL for each endpoint can be customized in **WooCommerce > Settings > Advanced** in the Page setup section.

![Endpoints](https://developer.woocommerce.com/wp-content/uploads/2023/12/endpoints.png)

Ensure that they are unique to avoid conflicts. If you encounter issues with 404s, go to **Settings > Permalinks** and save to flush the rewrite rules.

## Using endpoints in menus

If you want to include an endpoint in your menus, you need to use the Links section:

![The Links section of a menu item in WordPress](https://developer.woocommerce.com/wp-content/uploads/2023/12/2014-02-26-at-14.26.png)

Enter the full URL to the endpoint and then insert that into your menu.

Remember that some endpoints, such as view-order, require an order ID to work. In general, we don't recommend adding these endpoints to your menus. These pages can instead be accessed via the my-account page.

## Using endpoints in payment gateway plugins

WooCommerce provides helper functions in the order class for getting these URLs. They are:

`$order->get_checkout_payment_url( $on_checkout = false );`

and:

`$order->get_checkout_order_received_url();`

Gateways need to use these methods for full 2.1+ compatibility.

## Troubleshooting

### Endpoints showing 404

-   If you see a 404 error, go to **WordPress Admin** > **Settings > Permalinks** and Save. This ensures that rewrite rules for endpoints exist and are ready to be used.
-   If using an endpoint such as view-order, ensure that it specifies an order number. /view-order/ is invalid. /view-order/10/ is valid. These types of endpoints should not be in your navigation menus.

### Endpoints are not working

On Windows servers, the **web.config** file may not be set correctly to allow for the endpoints to work correctly. In this case, clicking on endpoint links (e.g. /edit-account/ or /customer-logout/) may appear to do nothing except refresh the page. In order to resolve this, try simplifying the **web.config** file on your Windows server. Here's a sample file configuration:

```xml
<<>?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers accessPolicy="Read, Execute, Script" />
    <rewrite>
    <rules>
      <rule name="wordpress" patternSyntax="Wildcard">
        <match url="*" />
        <conditions>
          <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
          <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
        </conditions>
        <action type="Rewrite" url="index.php" />
      </rule>
    </rules>
    </rewrite>
  </system.webServer>
</configuration>
```

### Pages direct to wrong place

Landing on the wrong page when clicking an endpoint URL is typically caused by incorrect settings. For example, clicking 'Edit address' on your account page takes you to the Shop page instead of the edit address form means you selected the wrong page in settings. Confirm that your pages are correctly configured and that a different page is used for each section.

### How to remove "Downloads" from My Account

Sometimes the "Downloads" endpoint on the "My account" page does not need to be displayed. This can be removed by going to **WooCommerce > Settings > Advanced > Account endpoints** and clearing the Downloads endpoint field.

![Account endpoints](https://developer.woocommerce.com/wp-content/uploads/2023/12/Screenshot-2023-04-09-at-11.45.58-PM.png)


---

## Understanding the risks of removing URL bases in WooCommerce

*Source: best-practices/urls-and-routing/removing-product-product-category-or-shop-from-the-url.md*

# Understanding the risks of removing URL bases in WooCommerce

## In sum

Removing  `/product/`,  `/product-category/`, or  `/shop/`  from the URLs is not advisable due to the way WordPress resolves its URLs. It uses the  `product-category`  (or any other text for that matter) base of a URL to detect that it is a URL leading to a product category. There are SEO plugins that allow you to remove this base, but that can lead to a number of problems with performance and duplicate URLs.

## Better to avoid

You will make it harder for WordPress to detect what page you are trying to reach when you type in a product category URL. Also, understand that the standard "Page" in WordPress always has no base text in the URL. For example:

- `http://yoursite.com/about-page/` (this is the URL of a standard page)
- `http://yoursite.com/product-category/category-x/` (this is the URL leading to a product category)

What would happen if we remove that 'product-category' part?

-   `http://yoursite.com/about-page/`
-   `http://yoursite.com/category-x/`

WordPress will have to do much more work to detect what page you are looking for when entering one of the above URLs. That is why we do not recommend using any SEO plugin to achieve this.


---

## Working with webhooks in WooCommerce

*Source: best-practices/urls-and-routing/webhooks.md*

# Working with webhooks in WooCommerce

## What are webhooks?

A  [Webhook](http://en.wikipedia.org/wiki/Webhook)  is an event notification sent to a URL of your choice. Users can configure them to trigger events on one site to invoke behavior on another.

Webhooks are useful for integrating with third-party services and other external API that support them.

## Webhooks in WooCommerce

Webhooks were introduced in WooCommerce 2.2 and can trigger events each time you add, edit or delete orders, products, coupons or customers.

It's also possible to use webhooks with WooCommerce actions, e.g., Create a webhook to be used every time a product is added to the shopping cart, using the action  `woocommerce_add_to_cart`.

Webhooks also make it easier for third-party apps to integrate with WooCommerce.

## Creating webhooks

![WebHooks screen](https://woocommerce.com/wp-content/uploads/2013/01/woo-webhooks.png)

To create a new webhook:

1/ **Go to**: **WooCommerce > Settings > Advanced > Webhooks**.
> **Note:** Webhooks were formerly found under WooCommerce > Settings > API prior to WooCommerce 3.4.

2/ Select  **Create a new webhook**  (first incident) or  **Add webhook**. The **Webhook Data**  box appears.

![WebHooks creation](https://woocommerce.com/wp-content/uploads/2013/01/woo-webhooks.png)

3/  **Enter**.

- **Name**: The  **name**  is auto-generated as "Webhook created on [date and time of creation]" as a standard to facilitate creation. Change the name to something else.
- **Status**: Set to **Active** (delivers payload),  **Paused** (does not deliver), or **Disabled** (does not deliver due delivery failures).
- **Topic**: Indicate when the webhook should be triggered -  **Order Created**,  **Product Deleted**, or **Customer Updated**. There are also  **Action** and  **Custom** options.
    - **Action Event**: This option is available when the Topic is a WooCommerce **Action**, such as  `woocommerce_add_to_cart`  for when customers add products to the shopping cart.
    - **Custom Topic**: This option is for  **advanced users only**. It's possible to introduce new, customized topics with the help of  `woocommerce_webhook_topic_hooks`  filter.
- **Delivery URL**: URL where the webhook payload is delivered.
- **Secret**: The Secret Key generates a hash of the delivered webhook and is provided in the request headers. This defaults to the current API user's consumer secret, if nothing is entered.

4/ **Save webhook**.

> **Note**: The first time your webhook is saved with the Activated status, it sends a ping to the Delivery URL.

Webhooks are disabled after 5 retries by default if the delivery URL returns an unsuccessful status such as  `404`  or  `5xx`. Successful responses are  `2xx`,  `301`  or  `302`.

To increase the number of retries, you can use the  `woocommerce_max_webhook_delivery_failures`  filter function.

## Editing and deleting webhooks

Webhooks are listed the same way as posts or products.

1.  Find the webhook you wish to alter.
2.  Hover over the name, and  **Edit**  and  **Delete permanently**  options appear.
3.  **Delete**, or make  **Edits**  and  **Save changes**. Bulk deletion is also possible with the dropdown.

![WebHooks deletion](https://woocommerce.com/wp-content/uploads/2013/01/editdelete-webhook.png)

## Webhook logs

WooCommerce saves logs of all events triggering a webhook. Webhook logs are found at:  **WooCommerce > Status > Logs**.

![WebHooks logs](https://woocommerce.com/wp-content/uploads/2022/11/Viewing-WooCommerce-Webhook-Logs.png?w=650)

Logs may be reviewed to see delivery and response from the server, making it simpler to integrate and debug.


---

## Understanding WooCommerce endpoints

*Source: best-practices/urls-and-routing/woocommerce-endpoints.md*

# Understanding WooCommerce endpoints

Endpoints are an extra part in the website URL that is detected to show different content when present.

For example: You may have a 'my account' page shown at URL **yoursite.com/my-account**. When the endpoint 'edit-account' is appended to this URL, making it '**yoursite.com/my-account/edit-account**' then the **Edit account page** is shown instead of the **My account page**.

This allows us to show different content without the need for multiple pages and shortcodes, and reduces the amount of content that needs to be installed.

Endpoints are located at **WooCommerce > Settings > Advanced**.

## Checkout endpoints

The following endpoints are used for checkout-related functionality and are appended to the URL of the /checkout page:

-   Pay page - `/order-pay/{ORDER_ID}`
-   Order received (thanks) - `/order-received/`
-   Add payment method - `/add-payment-method/`
-   Delete payment method - `/delete-payment-method/`
-   Set default payment method - `/set-default-payment-method/`

## Account endpoints

The following endpoints are used for account-related functionality and are appended to the URL of the /my-account page:

-   Orders - `/orders/`
-   View order - `/view-order/{ORDER_ID}`
-   Downloads - `/downloads/`
-   Edit account (and change password) - `/edit-account/`
-   Addresses - `/edit-address/`
-   Payment methods - `/payment-methods/`
-   Lost password - `/lost-password/`
-   Logout - `/customer-logout/`

## Learn more

- [Customizing endpoint URLs](./customizing-endpoint-urls.md)


---

## WooCommerce Block Development

*Source: block-development/README.md*

# WooCommerce Block Development

Welcome to the WooCommerce Block Development documentation!  
This section is your starting point for learning how to build, customize, and extend blocks for WooCommerce.

Whether you’re new to block development or looking to deepen your expertise, this guide will walk you through the process step by step, from the basics to advanced extensibility.

## Start Here

- **[Getting Started](/docs/block-development/getting-started/extensibility-overview/)**: Set up your environment and create your first block.
- **[Tutorials](/docs/category/tutorials/)**: Follow hands-on guides to build and enhance your blocks.
- **[Reference](/docs/category/reference/)**: Look up APIs, filters, and block details as you build.
- **[Extensibility](/docs/category/extensible-blocks/)**: Learn to extend and customize blocks for advanced use cases.
- **[Cart & Checkout](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/)** and **[Product Collection](/docs/block-development/extensible-blocks/product-collection-block/)**: Explore specialized block documentation.

Happy building!


---

## Getting started with Cart and Checkout extensibility

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/README.md*

# Getting started with Cart and Checkout extensibility

This document is a high-level overview of the moving parts required to extend the Cart and Checkout blocks.

To get started, it is recommended to first read the [Block Development Environment](https://developer.wordpress.org/block-editor/getting-started/devenv/) documentation from WordPress and follow [Tutorial: Build your first block
](https://developer.wordpress.org/block-editor/getting-started/tutorial/).

## Example block template package

There is an example block template in the WooCommerce repository. Having this template set up while reading this document may help to understand some of the concepts discussed. See the [`@woocommerce/extend-cart-checkout-block` package documentation](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/extend-cart-checkout-block/README.md) for how to install and run the example block.

(Note: the code in the repository linked above will not be very useful alone; the code there is templating code. It will be transformed into regular JS and PHP after following the README instructions.)

## Front-end extensibility

To extend the front-end of the blocks, extensions must use JavaScript. The JavaScript files must be enqueued and loaded on the page before they will have any effect.

### Build system

Some extensions may be very simple and include only a single JavaScript file, other extensions may be complex and the code may be split into multiple files. Either way, it is recommended that the files are bundled together and minified into a single output file. If your extension has several distinct parts that only load on specific pages, bundle splitting is recommended, though that is out of scope for this document.

To set up the build system, the recommended approach is to align with WordPress and use a JavaScript package called [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/). This package contains a script called `build`. By default, this will build your scripts into a single output file that can be enqueued using `wp_enqueue_script`.

The base configuration of the `build` script in  `@wordpress/scripts` can be overridden by creating a `webpack.config.js` file in the root of your plugin. The example block shows how the base config can be extended.

#### `WooCommerceDependencyExtractionWebpackPlugin`

See [`WordPress Dependency Extraction Webpack Plugin`](https://github.com/WordPress/gutenberg/tree/trunk/packages/dependency-extraction-webpack-plugin) and 
[`WooCommerce Dependency Extraction Webpack Plugin`](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/dependency-extraction-webpack-plugin#dependency-extraction-webpack-plugin).

This Webpack plugin is used to:

- Externalize dependencies that are available as shared scripts or modules on WordPress sites.
    - This means when you import something from `@woocommerce/blocks-checkout` it resolves that path to `window.wc.wcBlocksCheckout` without you needing to change your code. It makes your code easier to read and allows these packages to be loaded onto the page once.
- Add an asset file for each entry point that declares an object with the list of WordPress script or module dependencies for the entry point. The asset file also contains the current version calculated for the current source code.

The PHP "asset file" that this plugin outputs contains information your script needs to register itself, such as dependencies and paths.

If you have written code that is built by Webpack and using the WooCommerce Dependency Extraction Webpack Plugin, there will be an asset file output for each entry point. This asset file is a PHP file that contains information about your script, specifically dependencies and version, here's an example:

```php
<?php
return array(
  'dependencies' => array(
    'react',
    'wc-settings',
    'wp-block-editor',
    'wp-blocks',
    'wp-components',
    'wp-element',
    'wp-i18n',
    'wp-primitives'
  ),
  'version' => '455da4f55e1ac73b6d34'
);
```

When enqueueing your script, using this asset file will ensure the dependencies are loaded correctly and that the client gets the most up-to-date version of your script (the version is used to ensure your script is fetched fresh, rather than from the cache).

```php
<?php
$script_path = '/build/index.js';
$script_url  = plugins_url( $script_path, __FILE__ );

$script_asset_path = dirname( __FILE__ ) . '/build/index.asset.php';
$script_asset      = file_exists( $script_asset_path )
  ? require $script_asset_path
  : [
    'dependencies' => [],
    'version'      => $this->get_file_version( $script_path ),
  ];

wp_register_script(
  'example-blocks-integration-handle',
  $script_url,
  $script_asset['dependencies'],
  $script_asset['version'],
  true
);
```

Please see the [Cart and Checkout – Handling scripts, styles, and data](/docs/block-development/reference/integration-interface/) document for more information about how to correctly register scripts using the `IntegrationInterface`.

### Creating a block

In the example block, there is a "checkout-newsletter-subscription-block" directory which contains the files needed to register an inner block in the Checkout. The example block template is only set up to import and build a single block, but the Webpack config can be modified to build multiple blocks. Doing this is not supported as part of this document, refer to the [Webpack documentation](https://webpack.js.org/concepts/) instead.

The principles covered in [Tutorial: Build your first block
](https://developer.wordpress.org/block-editor/getting-started/tutorial/) apply here too.

### Modifying existing values on the front-end

You may not need to create a block to get your extension working the way you want, for example, if your extension only modifies existing content through filters.

In this case, you could remove the block folder from the example block, modify the Webpack config file so it no longer reads from that directory, and include the code you need in the entry JavaScript file.

More information about how to use filters can be found in the [Filter Registry](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/filter-registry/README.md) and [Available Filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) documents.

### Importing WooCommerce components into your extension

Components can be imported from `@woocommerce/blocks-components` (externalized to `window.wc.blocksComponents` by `@woocommerce/dependency-extraction-webpack-plugin`). The list of available components can be seen in [the WooCommerce Storybook](https://woocommerce.github.io/woocommerce/?path=/docs/woocommerce-blocks_external-components-button--docs), listed under "WooCommerce Blocks -> External components".

An example of importing the `Button` component is:

```js
import { Button } from '@woocommerce/blocks-components';

const MyComponent = () => {
  return <div class="my-wrapper">
    <Button type="button" />
  </div>;
}
```

### Importing WooCommerce utilities and React hooks

Some checkout utilities and React hooks are available for external use from `@woocommerce/blocks-checkout`. See the [Checkout Utilities](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/checkout-utilities/) documentation for available utilities.

For accessing store data, using the [`wc/store/...`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/data-store/) data stores is preferred over importing internal hooks like `useStoreCart`.

## Back-end extensibility

### Declaring compatibility with the Cart and Checkout blocks

Declaring compatibility helps merchants understand whether an extension supports the Cart and Checkout blocks if compatibility conflicts arise. Extensions usually fall into one of these categories:

- An extension that is incompatible with the Cart and Checkout blocks should declare its incompatibility.
- An extension that is compatible with the Cart and Checkout blocks should declare its compatibility.
- An extension that does not affect the Cart or Checkout flow does not need to declare compatibility.

WooCommerce only checks block compatibility for extensions that declare the `WC tested up to` header in the main plugin file. Add the header with the WooCommerce version your extension has tested against:

```php
<?php
/**
 * Plugin Name: WooCommerce Example Extension
 * Plugin URI: https://wordpress.org/plugins/example-extension/
 * Description: Sample description.
 * Author: WooCommerce
 * Author URI: https://woocommerce.com/
 * Version: 1.0.0
 * Text Domain: woocommerce-example-extension
 * Domain Path: /languages
 * WC requires at least: 6.0
 * WC tested up to: 8.0
 */
```

To declare that an extension is compatible with the Cart and Checkout blocks, add the following snippet to the main plugin file:

```php
add_action( 'before_woocommerce_init', function() {
	if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
	}
} );
```

To declare that an extension is incompatible with the Cart and Checkout blocks, add the following snippet to the main plugin file:

```php
add_action( 'before_woocommerce_init', function() {
	if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, false );
	}
} );
```

If you prefer to include the compatibility declaration outside the main plugin file, pass the plugin file path, such as `my-plugin-slug/my-plugin.php`, instead of `__FILE__`.

### Modifying information during the Checkout process

Modifying the server-side part of the Cart and Checkout blocks is possible using PHP. Some actions and filters from the shortcode cart/checkout experience will work too, but not all of them. We have a working document ([Hook alternatives document](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/hook-alternatives.md)) that outlines which hooks are supported as well as alternatives.

### Extending Store API

If you need to change how the Store API works, or extend the data in the responses, see [Extending the Store API](/docs/apis/store-api/extending-store-api/).


---

## Additional checkout fields

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/additional-checkout-fields.md*

# Additional checkout fields

A common use-case for developers and merchants is to add a new field to the Checkout form to collect additional data about a customer or their order.

This document will outline the steps an extension should take to register some additional checkout fields.

## Available field locations

Additional checkout fields can be registered in three different places:

| Title                                | Identifier    |
| ------------------------------------ | ------------- |
| Contact information                  | **`contact`** |
| Addresses (Shipping **and** Billing) | **`address`** |
| Order information                    | **`order`**   |

A field can only be shown in one location, it is not possible to render the same field in multiple locations in the same registration.

### Contact information

The contact information section currently renders at the top of the form. It contains the `email` field and any other additional fields.

![Showing the contact information section with two fields rendered, email and an additional checkout field (optional)](https://github.com/woocommerce/woocommerce/assets/5656702/097c2596-c629-4eab-9604-577ee7a14cfe)

Fields rendered here will be saved to the shopper's account. They will be visible and editable render in the shopper's "Account details" section.

### Address

The "Address" section currently contains a form for the shipping address and the billing address. Additional checkout fields can be registered to appear within these forms.

![The shipping address form showing the additional checkout field at the bottom](https://github.com/woocommerce/woocommerce/assets/5656702/746d280f-3354-4d37-a78a-a2518eb0e5de)

Fields registered here will be saved to both the customer _and_ the order, so returning customers won't need to refill those values again.

If a field is registered in the `address` location it will appear in both the shipping **and** the billing address. It is not possible to have the field in only one of the addresses.

You will also end up collecting two values for this field, one for shipping and one for billing.

### Order information

As part of the additional checkout fields feature, the checkout block has a new inner block called the "Order information block".

This block is used to render fields that aren't part of the contact information or address information, for example it may be a "How did you hear about us" field or a "Gift message" field.

Fields rendered here will be saved to the order. They will not be part of the customer's saved address or account information. New orders will not have any previously used values pre-filled.

![The order information section containing an additional checkout field](https://github.com/woocommerce/woocommerce/assets/5656702/295b3048-a22a-4225-96b0-6b0371a7cd5f)

By default, this block will render as the last step in the Checkout form, however it can be moved using the Gutenberg block controls in the editor.

![The order information block in the post editor"](https://github.com/woocommerce/woocommerce/assets/5656702/05a3d7d9-b3af-4445-9318-443ae2c4d7d8)

## Accessing values

Additional fields are saved to individual meta keys in both the customer meta and order meta, you can access them using helper methods, or using the meta keys directly, we recommend using the helper methods, as they're less likely to change, can handle future migrations, and will support future enhancements (e.g. reading from different locations).

For address fields, two values are saved: one for shipping, and one for billing. If the customer has selected 'Use same address for billing` then the values will be the same, but still saved independently of each other.

For contact and order fields, only one value is saved per field.

### Helper methods

`CheckoutFields` provides a function to access values from both customers and orders, it's are `get_field_from_object`.

To access a customer billing and/or shipping value:

```php
use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\Domain\Services\CheckoutFields;

$field_id = 'my-plugin-namespace/my-field';
$customer = wc()->customer; // Or new WC_Customer( $id )
$checkout_fields = Package::container()->get( CheckoutFields::class );
$my_customer_billing_field = $checkout_fields->get_field_from_object( $field_id, $customer, 'billing' );
$my_customer_shipping_field = $checkout_fields->get_field_from_object( $field_id, $customer, 'shipping' );
```

To access an order field:

```php
use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\Domain\Services\CheckoutFields;

$field_id = 'my-plugin-namespace/my-field';
$order = wc_get_order( 1234 );
$checkout_fields = Package::container()->get( CheckoutFields::class );
$my_order_billing_field = $checkout_fields->get_field_from_object( $field_id, $order, 'billing' );
$my_order_shipping_field = $checkout_fields->get_field_from_object( $field_id, $order, 'shipping' );
```

After an order is placed, the data saved to the customer and the data saved to the order will be the same. Customers can change the values for _future_ orders, or from within their My Account page. If you're looking at a customer value at a specific point in time (i.e. when the order was placed), access it from the order object, if you're looking for the most up to date value regardless, access it from the customer object.

#### Guest customers

When a guest customer places an order with additional fields, those fields will be saved to its session, so as long as the customer still has a valid session going, the values will always be there.

#### Logged-in customers

For logged-in customers, the value is only persisted once they place an order. Accessing a logged-in customer object during the place order lifecycle will return null or stale data.

If you're at a place order hook, doing this will return previous data (not the currently inserted one):

```php
$customer = new WC_Customer( $order->customer_id ); // Or new WC_Customer( 1234 )
$my_customer_billing_field = $checkout_fields->get_field_from_object( $field_id, $customer, 'billing' );
```

Instead, always access the latest data if you want to run some extra validation/data-moving:

```php
$customer = wc()->customer // This will return the current customer with its session.
$my_customer_billing_field = $checkout_fields->get_field_from_object( $field_id, $customer, 'billing' );
```

#### Accessing all fields

You can use `get_all_fields_from_object` to access all additional fields saved to an order or a customer.

```php
use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\Domain\Services\CheckoutFields;

$order = wc_get_order( 1234 );
$checkout_fields = Package::container()->get( CheckoutFields::class );
$order_additional_billing_fields = $checkout_fields->get_all_fields_from_object( $order, 'billing' );
$order_additional_shipping_fields = $checkout_fields->get_all_fields_from_object( $order, 'shipping' );
$order_other_additional_fields = $checkout_fields->get_all_fields_from_object( $order, 'other' ); // Contact and Order are saved in the same place under the additional group.
```

This will return an array of all values, it will only include fields currently registered, if you want to include fields no longer registered, you can pass a third `true` parameter.

```php

$order = wc_get_order( 1234 );
$checkout_fields = Package::container()->get( CheckoutFields::class );
$order_additional_billing_fields = $checkout_fields->get_all_fields_from_object( $order, 'billing' ); // array( 'my-plugin-namespace/my-field' => 'my-value' );

$order_additional_billing_fields = $checkout_fields->get_all_fields_from_object( $order, 'billing', true  ); // array( 'my-plugin-namespace/my-field' => 'my-value', 'old-namespace/old-key' => 'old-value' );
```

### Accessing values directly

While not recommended, you can use the direct meta key to access certain values, this is useful for external engines or page/email builders who only provide access to meta values.

Values are saved under a predefined prefix, this is needed to able to query fields without knowing which ID the field was registered under, for a field with key `'my-plugin-namespace/my-field'`, it's meta key will be the following if it's an address field:

- `_wc_billing/my-plugin-namespace/my-field`
- `_wc_shipping/my-plugin-namespace/my-field`

Or the following if it's a contact/order field:

- `_wc_other/my-plugin-namespace/my-field`.

Those prefixes are part of `CheckoutFields` class, and can be accessed using the following constants:

```php
echo ( CheckoutFields::BILLING_FIELDS_PREFIX ); // _wc_billing/
echo ( CheckoutFields::SHIPPING_FIELDS_PREFIX ); // _wc_shipping/
echo ( CheckoutFields::OTHER_FIELDS_PREFIX ); // _wc_other/
```

`CheckoutFields` provides a couple of helpers to get the group name or key based on one or the other:

```php
CheckoutFields::get_group_name( "_wc_billing" ); // "billing"
CheckoutFields::get_group_name( "_wc_billing/" ); // "billing"

CheckoutFields::get_group_key( "shipping" ); // "_wc_shipping/"
```

Use cases here would be to build the key name to access the meta directly:

```php
$key      = CheckoutFields::get_group_key( "other" ) . 'my-plugin/is-opt-in';
$opted_in = get_user_meta( 123, $key, true ) === "1" ? true : false;
```

#### Checkboxes values

When accessing a checkbox values directly, it will either return `"1"` for true, `"0"` for false, or `""` if the value doesn't exist, only the provided functions will sanitize that to a boolean.

## Supported field types

The following field types are supported:

- `select`
- `text`
- `checkbox`
- `date`

There are plans to expand this list, but for now these are the types available.

## Using the API

To register additional checkout fields you must use the `woocommerce_register_additional_checkout_field` function.

:::note

Register fields on the `woocommerce_init` action (or later). Registering earlier can cause initialization and translation issues.

:::

The registration function takes an array of options describing your field. Some field types take additional options.

### Options

#### General options

These options apply to all field types (except in a few circumstances which are noted inline).

| Option name | Description | Required? | Example | Default value |
| --- | --- | --- | --- | --- |
| `id` | The field's ID. This should be a unique identifier for your field. It is composed of a namespace and field name separated by a `/`. | Yes | `plugin-namespace/how-did-you-hear` | No default - this must be provided. |
| `label` | The label shown on your field. This will be the placeholder too. | Yes | `How did you hear about us?` | No default - this must be provided. |
| `optionalLabel` | The label shown on your field if it is optional. This will be the placeholder too. | No | `How did you hear about us? (Optional)` | The default value will be the value of `label` with `(optional)` appended. |
| `location` | The location to render your field. | Yes | `contact`, `address`, or `order` | No default - this must be provided. |
| `type` | The type of field you're rendering. It defaults to `text` and must match one of the supported field types. | No | `text`, `select`, `checkbox`, or `date` | `text` |
| `attributes` | An array of additional attributes to render on the field's input element. This is _not_ supported for `select` fields. | No | `[	'data-custom-data' => 'my-custom-data' ]` | `[]` |
| `required` | Can be a boolean or a JSON Schema array. If boolean and `true`, the shopper _must_ provide a value for this field during the checkout process. For checkbox fields, the shopper must check the box to place the order. If a JSON Schema array, the field will be required based on the schema conditions. See [Conditional visibility and validation via JSON Schema](#conditional-visibility-and-validation-via-json-schema). | No | `true` or `["type" => "object", "properties" => [...]]` | `false` |
| `hidden` | Can be a boolean or a JSON Schema array. Must be `false` when used as a boolean. If a JSON Schema array, the field will be hidden based on the schema conditions. See [Conditional visibility and validation via JSON Schema](#conditional-visibility-and-validation-via-json-schema). | No | `false` or `["type" => "object", "properties" => [...]]` | `false` |
| `validation` | An array of JSON Schema objects that define validation rules for the field. See [Conditional visibility and validation via JSON Schema](#conditional-visibility-and-validation-via-json-schema). | No | `[{"type": "object", "properties": {...}}]` | `[]` |
| `sanitize_callback` | A function called to sanitize the customer-provided value when posted. | No | See example below | By default the field's value is returned unchanged. |
| `validate_callback` | A function called to validate the customer-provided value when posted. This runs _after_ sanitization. | No | See example below | The default validation function will add an error to the response if the field is required and does not have a value. [See the default validation function.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/Domain/Services/CheckoutFields.php#L270-L281) |

##### Example of `sanitize_callback`. This function will remove spaces from the value {/* omit in toc */}

```php
'sanitize_callback' => function( $field_value ) {
	return str_replace( ' ', '', $field_value );
},
```

##### Example of `validate_callback`. This function will check if the value is an email {/* omit in toc */}

```php
'validate_callback' => function( $field_value ) {
	if ( ! is_email( $field_value ) ) {
		return new WP_Error( 'invalid_alt_email', 'Please ensure your alternative email matches the correct format.' );
	}
},
```

#### Options for `text` fields

Text fields don't have any additional options beyond the general options listed above.

#### Options for `date` fields

Date field values are strings in `YYYY-MM-DD` format. In JSON Schema, use `type: string` and `format: date`. You can use the field's `validation` option to [validate dates and compare them with other date fields](#date-field-validation).

As well as the options above, date fields support `min` and `max` options to limit the range of dates a shopper can pick.

| Option name | Description | Required? | Example | Default value |
| --- | --- | --- | --- | --- |
| `min` | The earliest date the shopper can select. | No | `2026-01-01`, `P0D`, `P1D` | No minimum. |
| `max` | The latest date the shopper can select. | No | `2026-12-31`, `P30D`, `-P18Y` | No maximum. |

Each one takes either:

- An **absolute** date in `YYYY-MM-DD` format, such as `2026-01-01`. This is the same format the HTML `min` and `max` attributes use.
- A **duration relative to today**, written in the [ISO 8601-2 duration format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#iso_8601_duration_format), optionally signed: `P1D` (tomorrow), `-P5D` (five days ago), `P2W`, `P3M`, `-P18Y`. `P0D` means today.

```php
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/delivery-date',
		'label'    => 'Preferred delivery date',
		'location' => 'order',
		'type'     => 'date',
		'required' => true,
		'min'      => 'P1D',   // From tomorrow,
		'max'      => 'P30D',  // up to 30 days out.
	)
);
```

##### Dates only, not times

A date field holds a calendar date with no time component, so only the `Y`, `M`, `W` and `D` parts of a duration are meaningful. A duration carrying a time component, such as `PT1H` or `P1DT12H`, is rejected at registration.

##### Pass the duration, don't resolve it yourself

```php
// Don't do this.
'min' => date( 'Y-m-d', strtotime( '+1 day' ) ),
```

This ends up resolving to a date that may not always be up to date between registration, field rendering, and value submission. Instead, pass P1D, which will be evaluated at input time and submission time.

Registration fails with a `_doing_it_wrong` notice if a constraint can't be parsed. Express both bounds in the same unit, i.e. avoid `'min' => 'P30D'`, `'max' => 'P1M'` as it would form an invalid range in February for example. Avoid mixing absolute and durations unless you're sure they won't overlap at some point in the future.

If mixed dates (absolute and durations) resolve to an invalid range, where min is later than max, WooCommerce will ignore them and the field will be boundless and will emit a log warning.

The input value will follow the browser's locale settings, the DB value will be in YYYY-MM-DD, and the final rendered value (in pages and emails) will follow the site's date format, set in **Settings -> General**.

#### Options for `select` fields

As well as the options above, select fields must also be registered with an  `options` option. This is used to specify what options the shopper can select.

Select fields will mount with no value selected by default, if the field is required, the user will be required to select a value.

You can set a placeholder to be shown on the select by passing a `placeholder` value when registering the field. This will be the first option in the select and will not be selectable if the field is required.

| Option name | Description | Required? | Example | Default value |
| --- | --- | --- | --- | --- |
| `options` | An array of options to show in the select input. Each options must be an array containing a `label` and `value` property. Each entry must have a unique `value`. Any duplicate options will be removed. The `value` is what gets submitted to the server during checkout and the `label` is simply a user-friendly representation of this value. It is not transmitted to the server in any way. | Yes | see below | No default - this must be provided. |
| `placeholder` | If this value is set, the shopper will see this option in the select. If the select is required, the shopper cannot select this option. | No | `Select a role` | Select a $label |

##### Example of `options` value

```php
[

	[
		'value' => 'store_1',
		'label' => 'Our London Store'
	],
	[
		'value' => 'store_2',
		'label' => 'Our Paris Store'
	],
	[
		'value' => 'store_3',
		'label' => 'Our New York Store'
	]
]
```

#### Options for `checkbox` fields

As well as the options above, checkbox field support showing an error message if it's required and not checked.

| Option name | Description | Required? | Example | Default value |
| --- | --- | --- | --- | --- |
| `error_message` | A custom message to show if the box is unchecked. | No | `You must confirm you are over 18 before placing the order.` | `Please check this box if you want to proceed.` |

### Attributes

Adding additional attributes to checkbox, text, and date fields is supported. Adding them to select fields is **not possible for now**.

These attributes have a 1:1 mapping to the HTML attributes on `input` elements (except `pattern` on checkbox).

The supported attributes are:

- `data-*` attributes
- `aria-*` attributes
- `autocomplete`
- `autocapitalize`
- `pattern` (not supported on checkbox fields)
- `title`
- `maxLength` (equivalent to `maxlength` HTML attribute)
- `readOnly` (equivalent to `readonly` HTML attribute)

`maxLength` and `readOnly` are in camelCase because the attributes are rendered on a React element which must receive them in this format.

Certain attributes are not passed through to the field intentionally, these are `autofocus` and `disabled`. We are welcome to hear feedback and adjust this behaviour if valid use cases are provided.

## Usage examples

### Rendering a text field

This example demonstrates rendering a text field in the address section:

```php
add_action(
	'woocommerce_init',
	function() {
		woocommerce_register_additional_checkout_field(
			array(
				'id'            => 'namespace/gov-id',
				'label'         => 'Government ID',
				'optionalLabel' => 'Government ID (optional)',
				'location'      => 'address',
				'required'      => true,
				'attributes'    => array(
					'autocomplete'     => 'government-id',
					'aria-describedby' => 'some-element',
					'aria-label'       => 'custom aria label',
					'pattern'          => '[A-Z0-9]{5}', // A 5-character string of capital letters and numbers.
					'title'            => 'Title to show on hover',
					'data-custom'      => 'custom data',
				),
			),
		);
	}
);
```

This results in the following address form (the billing form will be the same):

![The shipping address form with the Government ID field rendered at the bottom](https://github.com/woocommerce/woocommerce/assets/5656702/f6eb3c6f-9178-4978-8e74-e6b2ea353192)

The rendered markup looks like this:

```html
	<input type="text" id="shipping-namespace-gov-id" autocapitalize="off"
       autocomplete="government-id" aria-label="custom aria label"
       aria-describedby="some-element" required="" aria-invalid="true"
       title="Title to show on hover" pattern="[A-Z0-9]{5}"
       data-custom="custom data" value="">
```

### Rendering a checkbox field

This example demonstrates rendering a checkbox field in the contact information section:

```php
add_action(
	'woocommerce_init',
	function() {
		woocommerce_register_additional_checkout_field(
			array(
				'id'       => 'namespace/marketing-opt-in',
				'label'    => 'Do you want to subscribe to our newsletter?',
				'location' => 'contact',
				'type'     => 'checkbox',
			)
		);
	}
);
```

This results in the following contact information section:

![The contact information section with a newsletter subscription checkbox rendered inside it](https://github.com/woocommerce/woocommerce/assets/5656702/7444e41a-97cc-451d-b2c9-4eedfbe05724)

Note that because an `optionalLabel` was not supplied, the string `(optional)` is appended to the label. To remove that an `optionalLabel` property should be supplied to override this.

### Rendering a select field

This example demonstrates rendering a select field in the order information section:

```php
add_action(
	'woocommerce_init',
	function() {
		woocommerce_register_additional_checkout_field(
			array(
				'id'          => 'namespace/how-did-you-hear-about-us',
				'label'       => 'How did you hear about us?',
				'placeholder' => 'Select a source',
				'location'    => 'order',
				'type'        => 'select',
				'options'     => [
					[
						'value' => 'google',
						'label' => 'Google'
					],
					[
						'value' => 'facebook',
						'label' => 'Facebook'
					],
					[
						'value' => 'friend',
						'label' => 'From a friend'
					],
					[
						'value' => 'other',
						'label' => 'Other'
					],
				]
			)
		);
	}
);
```

This results in the order information section being rendered like so:

### The select input before being focused

![The select input before being focused](https://github.com/woocommerce/woocommerce/assets/5656702/bbe17ad0-7c7d-419a-951d-315f56f8898a)

### The select input when focused

![The select input when focused](https://github.com/woocommerce/woocommerce/assets/5656702/bd943906-621b-404f-aa84-b951323e25d3)

If it is undesirable to force the shopper to select a value, mark the select as optional by setting the `required` option to `false`.

## Validation and sanitization

It is possible to add custom validation and sanitization for additional checkout fields using WordPress action hooks.

These actions happen in two places:

1. Updating and submitting the form during the checkout process and,
2. Updating address/contact information in the "My account" area.

### Sanitization

Sanitization is used to ensure the value of a field is in a specific format. An example is when taking a government ID, you may want to format it so that all letters are capitalized and there are no spaces. At this point, the value should **not** be checked for _validity_. That will come later. This step is only intended to set the field up for validation.

#### Using the `woocommerce_sanitize_additional_field` filter

To run a custom sanitization function for a field you can use the `sanitize_callback` function on registration, or the `woocommerce_sanitize_additional_field` filter.

| Argument       | Type              | Description                                                             |
|----------------|-------------------|-------------------------------------------------------------------------|
| `$field_value` | `boolean\|string` | The value of the field.                                                 |
| `$field_key`   | `string`          | The ID of the field. This is the same ID the field was registered with. |

##### Example of sanitization

This example shows how to remove whitespace and capitalize all letters in the example Government ID field we added above.

```php
add_action(
	'woocommerce_sanitize_additional_field',
	function ( $field_value, $field_key ) {
		if ( 'namespace/gov-id' === $field_key ) {
			$field_value = str_replace( ' ', '', $field_value );
			$field_value = strtoupper( $field_value );
		}
		return $field_value;
	},
	10,
	2
);
```

### Validation

There are two phases of validation in the additional checkout fields system. The first is validating a single field based on its key and value.

#### Single field validation

##### Using the `woocommerce_validate_additional_field` action

When the `woocommerce_validate_additional_field` action is fired  the callback receives the field's key, the field's value, and a `WP_Error` object.

To add validation errors to the response, use the [`WP_Error::add`](https://developer.wordpress.org/reference/classes/wp_error/add/) method.

| Argument | Type | Description |
| --- | --- | --- |
| `$errors` | `WP_Error` | An error object containing errors that were already encountered while processing the request. If no errors were added yet, it will still be a `WP_Error` object but it will be empty. |
| `$field_key` | `string` | The id of the field. This is the ID the field was registered with. |
| `$field_value` | `boolean\|string` | The value of the field |

###### The `WP_Error` object

When adding your error to the `WP_Error` object, it should have a unique error code. You may want to prefix the error code with the plugin namespace to reduce the chance of collision. Using codes that are already in use across other plugins may result in the error message being overwritten or showing in a different location.

###### Example of single-field validation

The below example shows how to apply custom validation to the `namespace/gov-id` text field from above. The code here ensures the field is made up of 5 characters, either upper-case letters or numbers. The sanitization function from the example above ensures that all whitespace is removed and all letters are capitalized, so this check is an extra safety net to ensure the input matches the pattern.

```php
add_action(
	'woocommerce_validate_additional_field',
	function ( WP_Error $errors, $field_key, $field_value ) {
		if ( 'namespace/gov-id' === $field_key ) {
			$match = preg_match( '/[A-Z0-9]{5}/', $field_value );
			if ( 0 === $match || false === $match ) {
				$errors->add( 'invalid_gov_id', 'Please ensure your government ID matches the correct format.' );
			}
		}
	},
	10,
	3
);
```

It is important to note that this action must _add_ errors to the `WP_Error` object it receives. Returning a new `WP_Error` object or any other value will result in the errors not showing.

If no validation errors are encountered the function can just return void.

#### Multiple field validation

There are cases where the validity of a field depends on the value of another field, for example validating the format of a government ID based on what country the shopper is in. In this case, validating only single fields (as above) is not sufficient as the country may be unknown during the `woocommerce_validate_additional_field` action.

To solve this, it is possible to validate a field in the context of the location it renders in. The other fields in that location will be passed to this action.

##### Using the `woocommerce_blocks_validate_location_{location}_fields` action

This action will be fired for each location that additional fields can render in (`address`, `contact`, and `order`). For `address` it fires twice, once for the billing address and once for the shipping address.

The callback receives the keys and values of the other additional fields in the same location.

It is important to note that any fields rendered in other locations will not be passed to this action, however it might be possible to get those values by accessing the customer or order object, however this is not supported and there are no guarantees regarding backward compatibility in future versions.

| Argument | Type | Description |
| --- | --- | --- |
| `$errors` | `WP_Error` | An error object containing errors that were already encountered while processing the request. If no errors were added yet, it will still be a `WP_Error` object but it will be empty. |
| `$fields` | `array` | The fields rendered in this locations. |
| `$group` | `'billing'\|'shipping'\|'other'` | If the action is for the address location, the type of address will be set here. If it is for contact or order, this will be 'other'. |

There are several places where these hooks are fired.

- When checking out using the Checkout block or Store API.
    - `woocommerce_blocks_validate_location_address_fields` (x2)
    - `woocommerce_blocks_validate_location_contact_fields`
    - `woocommerce_blocks_validate_location_other_fields`
- When updating addresses in the "My account" area
    - `woocommerce_blocks_validate_location_address_fields` (**x1** - only the address being edited)
- When updating the "Account details" section in the "My account" area
    - `woocommerce_blocks_validate_location_contact_fields`

##### Example of location validation

In this example, assume there is another field registered alongside the `namespace/gov-id` called `namespace/confirm-gov-id`. This field will be a confirmation for the Government ID field.

The example below illustrates how to verify that the value of the confirmation field matches the value of the main field.

```php
add_action(
	'woocommerce_blocks_validate_location_address_fields',
	function ( \WP_Error $errors, $fields, $group ) {
		if ( $fields['namespace/gov-id'] !== $fields['namespace/confirm-gov-id'] ) {
			$errors->add( 'gov_id_mismatch', 'Please ensure your government ID matches the confirmation.' );
		}
	},
	10,
	3
);
```

If these fields were rendered in the "contact" location instead, the code would be the same except the hook used would be: `woocommerce_blocks_validate_location_contact_fields`.

## Conditional visibility and validation via JSON Schema

The `required`, `hidden`, and `validation` properties accept an `array` of [JSON Schema](https://json-schema.org/understanding-json-schema/about) to create conditional logic for fields. This allows you to dynamically control field visibility, requirement status, and validation rules based on the values of other fields.

Schema is evaluated in the frontend in real-time, and on the backend at any update. This ensures fast and responsive UI, and consistent results between the client and server.

### JSON Schema Structure

Each schema in the array should be a valid JSON Schema object that defines conditions for when the property should be applied. The schema is evaluated against the current cart and checkout state, which includes all field values and various options (payment, shipping, customer).

Basic structure of a JSON Schema object:

```json
{
  "type": "object",
  "properties": {
    "fieldId": {
      "enum": ["value1", "value2"]
    }
  },
  "required": ["fieldId"]
}
```

If you're not familiar with JSON Schema, you can get a quick introduction to it [from the official website](https://json-schema.org/understanding-json-schema/basics), or from one of the libraries used [like AJV](https://ajv.js.org/json-schema.html) or [OPIS.](https://opis.io/json-schema/2.x/examples.html) Checkout builds an abstraction on top of both of them.

### Document object

When you're writing your rules, you're writing a partial schema for the document object, essentially describing the ideal state you want for your field to be required or hidden. 

**Important:** All properties in the document object use snake_case naming convention (e.g., `total_price`, `shipping_rates`, `customer_note`), not camelCase.

An example of the document object looks like this:

<details>
	<summary>Document object</summary>

```json
{
	"cart": {
		"coupons": [
			"my_coupon"
		],
		"shipping_rates": [
			"free_shipping:1"
		],
		"items": [
			27,
			27,
			68
		],
		"items_type": [
			"simple",
			"variation"
		],
		"items_count": 3,
		"items_weight": 0,
		"needs_shipping": true,
		"prefers_collection": false,
		"totals": {
			"total_price": 6600,
			"total_tax": 600
		},
		"extensions": {}
	},
	"checkout": {
		"create_account": false,
		"customer_note": "",
		"additional_fields": {
			"namespace/myorder-field": "myvalue"
		},
		"payment_method": "bacs"
	},
	"customer": {
		"id": 1,
		"billing_address": {
			"first_name": "First Name",
			"last_name": "Last Name",
			"company": "Company",
			"address_1": "Address 1",
			"address_2": "Address 2",
			"city": "City",
			"state": "State",
			"postcode": "08000",
			"country": "US",
			"email": "email@example.com",
			"phone": "1234567890",
			"namespace/myfield": "myvalue"
		},
		"shipping_address": {
			"first_name": "First Name",
			"last_name": "Last Name",
			"company": "Company",
			"address_1": "Address 1",
			"address_2": "Address 2",
			"city": "City",
			"state": "State",
			"postcode": "08000",
			"country": "US",
			"phone": "1234567890",
			"namespace/myfield": "myvalue"
		},
		"additional_fields": {
			"namespace/mycontact-field": "myvalue"
		},
		"address": {
			"first_name": "First Name",
			"last_name": "Last Name",
			"company": "Company",
			"address_1": "Address 1",
			"address_2": "Address 2",
			"city": "City",
			"state": "State",
			"postcode": "08000",
			"country": "US",
			"phone": "1234567890",
			"namespace/myfield": "myvalue"
		}
	}
}
```

</details>

It's full schema is this one:

<details>
	<summary>Document schema</summary>
	
```json
{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"title": "Cart and Checkout Document Object Schema",
	"description": "Document object schema for cart, checkout, and customer information, to be used for conditional visibility, requirement, and validation of fields.",
	"type": "object",
	"properties": {
		"cart": {
			"type": "object",
			"description": "Information about the shopping cart",
			"properties": {
				"coupons": {
					"type": "array",
					"description": "List of coupon codes applied to the cart",
					"items": {
						"type": "string"
					}
				},
				"shipping_rates": {
					"type": "array",
					"description": "List of currently selected shipping rates",
					"items": {
						"type": "string",
						"description": "Shipping rate identifier using the full shipping rate ID so method_id:instance_id, for example: flat_rate:1"
					}
				},
				"items": {
					"type": "array",
					"description": "List of product IDs in the cart, IDs will be duplicated depending on the quantity of the product in the cart, so if you have 2 of product ID 1, the array will have 2 entries of product ID 1. This only supports integer quantities, not floats (which round up to the nearest integer).",
					"items": {
						"type": "integer"
					}
				},
				"items_type": {
					"type": "array",
					"description": "Types of items in the cart, for example: simple, variation, subscription, etc.",
					"items": {
						"type": "string"
					}
				},
				"items_count": {
					"type": "integer",
					"description": "Total number of items in the cart",
					"minimum": 0
				},
				"items_weight": {
					"type": "number",
					"description": "Total weight of items in the cart",
					"minimum": 0
				},
				"needs_shipping": {
					"type": "boolean",
					"description": "Whether the items in the cart require shipping"
				},
				"prefers_collection": {
					"type": "boolean",
					"description": "Whether the customer prefers using Local Pickup"
				},
				"totals": {
					"type": "object",
					"description": "Cart totals information",
					"properties": {
						"total_price": {
							"type": "integer",
							"description": "Total price of the cart in smallest currency unit (e.g., cents), after applying all discounts, shipping, and taxes"
						},
						"total_tax": {
							"type": "integer",
							"description": "Total tax amount in smallest currency unit (e.g., cents), after applying all discounts, shipping, and taxes"
						}
					},
					"additionalProperties": false
				},
				"extensions": {
					"type": "object",
					"description": "Additional cart extension data, this is similar to what's passed in Store API's extensions parameter"
				}
			},
			"additionalProperties": false
		},
		"checkout": {
			"type": "object",
			"description": "Checkout preferences and settings",
			"properties": {
				"create_account": {
					"type": "boolean",
					"description": "Whether the customer checked the create account checkbox, this will be false if the customer is logged in, cannot create an account, or forced to create an account."
				},
				"customer_note": {
					"type": "string",
					"description": "Customer's note or special instructions for the order, this will be empty if the customer didn't add a note."
				},
				"additional_fields": {
					"type": "object",
					"description": "Additional checkout fields with 'order' location. These fields are rendered in the order information section.",
					"additionalProperties": {
						"type": "string"
					},
					"patternProperties": {
						"^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$": {
							"type": "string",
							"description": "Custom fields with namespace identifiers"
						}
					}
				},
				"payment_method": {
					"type": "string",
					"description": "Selected payment method identifier, this will be the payment method ID regardless if the customer selected a saved payment method or new payment method"
				}
			},
			"additionalProperties": false
		},
		"customer": {
			"type": "object",
			"description": "Customer information",
			"properties": {
				"id": {
					"type": "integer",
					"description": "Customer ID, this will be 0 if the customer is not logged in"
				},
				"billing_address": {
					"$ref": "#/definitions/address",
					"description": "Customer's billing address"
				},
				"shipping_address": {
					"$ref": "#/definitions/address",
					"description": "Customer's shipping address"
				},
				"additional_fields": {
					"type": "object",
					"description": "Additional checkout fields with 'contact' location. These fields are rendered in the contact information section.",
					"additionalProperties": {
						"type": "string"
					},
					"patternProperties": {
						"^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$": {
							"type": "string",
							"description": "Custom fields with namespace identifiers"
						}
					}
				},
				"address": {
					"$ref": "#/definitions/address",
					"description": "This is a dynamic field that will be the billing or shipping address depending on the context of the field being evaluated."
				}
			},
			"additionalProperties": false
		}
	},
	"additionalProperties": false,
	"definitions": {
		"address": {
			"type": "object",
			"description": "Customer address information",
			"properties": {
				"first_name": {
					"type": "string",
					"description": "First name of the recipient"
				},
				"last_name": {
					"type": "string",
					"description": "Last name of the recipient"
				},
				"company": {
					"type": "string",
					"description": "Company name"
				},
				"address_1": {
					"type": "string",
					"description": "Primary address line"
				},
				"address_2": {
					"type": "string",
					"description": "Secondary address line"
				},
				"city": {
					"type": "string",
					"description": "City name"
				},
				"state": {
					"type": "string",
					"description": "State or province, this will be the state code if it's a predefined list, for example: CA, TX, NY, etc, or the field value if it's a freeform state, for example: London."
				},
				"postcode": {
					"type": "string",
					"description": "Postal or ZIP code"
				},
				"country": {
					"type": "string",
					"description": "Country code (e.g., US, UK)"
				},
				"email": {
					"type": "string",
					"format": "email",
					"description": "Email address"
				},
				"phone": {
					"type": "string",
					"description": "Phone number"
				}
			},
			"additionalProperties": {
				"type": "string",
				"description": "Additional fields with 'address' location appear here as properties within the address objects"
			},
			"patternProperties": {
				"^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$": {
					"type": "string",
					"description": "Additional fields with 'address' location using namespace identifiers (e.g., 'namespace/field-name')"
				}
			}
		}
	}
}
```

</details>

### Examples

#### Required and visible field

In this example we make the field required and visible only if local pickup is being used.

```php
'required' => [
    "type" => "object",
	"properties" => [
		"cart" => [
			"properties" => [
				"prefers_collection" => [
					"const" => true
				]
			]
		]
	]
],
'hidden' => [
	"type" => "object",
	"properties" => [
		"cart" => [
			"properties" => [
				"prefers_collection" => [
					"const" => false
				]
			]
		]
	]
]
```

Notice that for hidden, we inverse the field, meaning, this field should only be hidden if `prefers_collection` is false, which is almost all cases except when it's selected. In the examples above, we used [the keyword `const`](https://ajv.js.org/json-schema.html#const).


#### Validation schema example

Validation is slightly different from conditional visibility and requirement. In validation, you will pass in a subset of schema (only applicable to your field), and its role is to validate the field and show any errors if there.

In this example, we ensure that VAT is made up of a country code and 8-12 numbers.

```php
'validation' => [
	"type" => "string",
	"pattern" => "^[A-Z]{2}[0-9]{8,12}$",
	"errorMessage" => "Please enter a valid VAT code with 2 letters for country code and 8-12 numbers."
]
```

Validation can also be against other fields, for example, an alternative email field that shouldn't match the current email:

```php
'validation' => [
	"type" => "string",
	"format" => "email",
	"not" => [
		"const" => [ '$data' => "/customer/billing_address/email" ]
	],
	"errorMessage" => "Please enter a valid alternative email."
]
```

In the example above, we used [format keyword](https://github.com/ajv-validator/ajv-formats) and `$data` to refer to the current field value via [JSON pointers](https://ajv.js.org/guide/combining-schemas.html#data-reference). We also used the `errorMessage` property to provide a custom error message.

##### Date field validation

A field registered with `'type' => 'date'` holds a string. Its validation schema uses `'type' => 'string'` and `'format' => 'date'` to check for a real calendar date in `YYYY-MM-DD` format.

WooCommerce supports the [AJV date comparison keywords](https://ajv.js.org/packages/ajv-formats.html#keywords-to-compare-values-formatmaximum-formatminimum-and-formatexclusivemaximum-formatexclusiveminimum):

- `formatMinimum`: on or after the given date.
- `formatMaximum`: on or before the given date.
- `formatExclusiveMinimum`: after the given date.
- `formatExclusiveMaximum`: before the given date.

Each bound accepts a date string or a `$data` reference to another field. For example, register these fields on `woocommerce_init` to require check-out to be after check-in:

```php
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'hotel/check-in',
		'label'    => 'Check-in',
		'location' => 'order',
		'type'     => 'date',
		'required' => true,
	)
);

woocommerce_register_additional_checkout_field(
	array(
		'id'         => 'hotel/check-out',
		'label'      => 'Check-out',
		'location'   => 'order',
		'type'       => 'date',
		'required'   => true,
		'validation' => array(
			'type'                   => 'string',
			'format'                 => 'date',
			'formatExclusiveMinimum' => array( '$data' => '1/hotel~1check-in' ),
			'errorMessage'           => 'Check-out must be after check-in.',
		),
	)
);
```

Schema validation is useful when referencing another field (via $data) or when combining conditions (AnyOf, AllOf, OneOf). If you’re validating against a static date or a relative duration, use [min/max](#options-for-date-fields), which also constrain the calendar to the specified range.

#### `$data` keyword and JSON pointers

`$data` keyword is a way in JSON schema to reference another field's value. In the above example, we use it to refer to the billing email via [JSON pointers](https://ajv.js.org/guide/combining-schemas.html#data-reference).

When dealing with JSON pointers, there are some things to keep in mind:

- The forward slash `/` is used to navigate through the JSON object, so for additional fields, a field named `my-plugin-namespace/my-field` will need to be referenced as `my-plugin-namespace~1my-field`.
- Navigation in JSON pointers can be from the current field backward, or from the root. If you have an address field and want to validate say the phone field, this means you will validate 2 values, one for shipping, and one for billing, so you can reference the phone field in 2 ways:
    - `0/customer/address/phone` which uses root navigation (via the `0/`) prefix, and uses the dynamic `address` group, which will change depending if the billing or shipping value is being validated.
    - `1/phone` which uses relative pointers to step back, in this case, it will access its sibling field, the `phone` field. Increase the number to step back even further, for example, `2/id` will access the customer ID.

### Keywords and values that are not in spec

We support [JSON Schema Draft-07](https://json-schema.org/draft-07), which is simple and doesn't support all the keywords and values that are in the latest spec, but we feel like it covers most of the use cases. On top of that, we introduced some non-standard keywords and values that are not in the spec, their implementation might be different between Opis and AJV (or any future implementation), this is the list of such keywords and values:

- `errorMessage`: Custom error message for validation, in AJV, this is `errorMessage` and in Opis, this is `$error`, we only support `errorMessage` and maps that internally for Opis. We also don't support templates in `errorMessage` for now.
- `$data`: Refers to the current field value via [JSON pointers](https://ajv.js.org/guide/combining-schemas.html#data-reference), both Opis and AJV use the same implementation.
- `formatMinimum`, `formatMaximum`, `formatExclusiveMinimum`, and `formatExclusiveMaximum`: Compare date strings using the [date field validation rules](#date-field-validation).


### Evaluation Logic

- For `required`: If any schema in the array matches the current checkout state, the field will be required.
- For `hidden`: If any schema in the array matches the current checkout state, the field will be hidden.
- For `validation`: The value of the field will be evaluated against the partial schema provided and an error will be shown if it didn't match.

### Performance Considerations

Complex JSON Schema conditions can impact checkout performance. Keep your schemas as simple as possible and limit the number of conditions to what's necessary for your use case.

## Backward compatibility

Due to technical reasons, it's not yet possible to specify the meta key for fields, as we want them to be prefixed and managed. Plugins with existing fields in shortcode Checkout can be compatible and react to reading and saving fields using hooks.

Assuming 2 fields, named `my-plugin-namespace/address-field` in the address step and `my-plugin-namespace/my-other-field` in the order step, you can:

### React to saving fields

You can react to those fields being saved by hooking into `woocommerce_set_additional_field_value` action.

```php
add_action(
	'woocommerce_set_additional_field_value',
	function ( $key, $value, $group, $wc_object ) {
		if ( 'my-plugin-namespace/address-field' !== $key ) {
			return;
		}

		if ( 'billing' === $group ) {
			$my_plugin_address_key = 'existing_billing_address_field_key';
		} else {
			$my_plugin_address_key = 'existing_shipping_address_field_key';
		}

		$wc_object->update_meta_data( $my_plugin_address_key, $value, true );
	},
	10,
	4
);

add_action(
	'woocommerce_set_additional_field_value',
	function ( $key, $value, $group, $wc_object ) {
		if ( 'my-plugin-namespace/my-other-field' !== $key ) {
			return;
		}

		$my_plugin_key = 'existing_order_field_key';

		$wc_object->update_meta_data( $my_plugin_key, $value, true );
	},
	10,
	4
);
```

This way, you can ensure existing systems will continue working and your integration will continue to work. However, ideally, you should migrate your existing data and systems to use the new meta fields.


### React to reading fields

You can use the `woocommerce_get_default_value_for_{$key}` filters to provide a different default value (a value coming from another meta field for example):

```php
add_filter(
	"woocommerce_get_default_value_for_my-plugin-namespace/address-field",
	function ( $value, $group, $wc_object ) {

		if ( 'billing' === $group ) {
			$my_plugin_key = 'existing_billing_address_field_key';
		} else {
			$my_plugin_key = 'existing_shipping_address_field_key';
		}

		return $wc_object->get_meta( $my_plugin_key );
	},
	10,
	3
);

add_filter(
	"woocommerce_get_default_value_for_my-plugin-namespace/my-other-field",
	function ( $value, $group, $wc_object ) {

		$my_plugin_key = 'existing_order_field_key';

		return $wc_object->get_meta( $my_plugin_key );
	},
	10,
	3
);
```

## A full example

In this full example we will register the Government ID text field and verify that it conforms to a specific pattern.

This example is just a combined version of the examples shared above.

```php
add_action(
	'woocommerce_init',
	function() {
		woocommerce_register_additional_checkout_field(
			array(
				'id'            => 'namespace/gov-id',
				'label'         => 'Government ID',
				'location'      => 'address',
				'required'      => true,
				'attributes'    => array(
					'autocomplete' => 'government-id',
					'pattern'      => '[A-Z0-9]{5}', // A 5-character string of capital letters and numbers.
					'title'        => 'Your 5-digit Government ID',
				),
			),
		);
		woocommerce_register_additional_checkout_field(
			array(
				'id'            => 'namespace/confirm-gov-id',
				'label'         => 'Confirm government ID',
				'location'      => 'address',
				'required'      => true,
				'attributes'    => array(
					'autocomplete' => 'government-id',
					'pattern'      => '[A-Z0-9]{5}', // A 5-character string of capital letters and numbers.
					'title'        => 'Confirm your 5-digit Government ID',
				),
			),
		);

		add_action(
			'woocommerce_sanitize_additional_field',
			function ( $field_value, $field_key ) {
				if ( 'namespace/gov-id' === $field_key || 'namespace/confirm-gov-id' === $field_key ) {
					$field_value = str_replace( ' ', '', $field_value );
					$field_value = strtoupper( $field_value );
				}
				return $field_value;
			},
			10,
			2
		);

		add_action(
		'woocommerce_validate_additional_field',
			function ( WP_Error $errors, $field_key, $field_value ) {
				if ( 'namespace/gov-id' === $field_key ) {
					$match = preg_match( '/[A-Z0-9]{5}/', $field_value );
					if ( 0 === $match || false === $match ) {
						$errors->add( 'invalid_gov_id', 'Please ensure your government ID matches the correct format.' );
					}
				}
				return $errors;
			},
			10,
			3
		);
	}
);

add_action(
	'woocommerce_blocks_validate_location_address_fields',
	function ( \WP_Error $errors, $fields, $group ) {
		if ( $fields['namespace/gov-id'] !== $fields['namespace/confirm-gov-id'] ) {
			$errors->add( 'gov_id_mismatch', 'Please ensure your government ID matches the confirmation.' );
		}
	},
	10,
	3
);
```


---

## Available slots

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/available-slot-fills.md*

# Available slots

This document presents the list of available Slots that you can use for adding your custom content (Fill).

If you want to add a new SlotFill component, check the [Checkout - Slot Fill document](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/slot/README.md). To read more about Slot and Fill, check the [Slot and Fill document](/docs/block-development/reference/slot-fills/).

**Note About Naming:** Slots that are prefixed with `Experimental` are experimental and subject to change or remove. Once they graduate from the experimental stage, the naming would change and the `Experimental` prefix would be dropped. Check the [Feature Gating document](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md) from more information.

## ExperimentalOrderMeta

This Slot renders below the Checkout summary section and above the "Proceed to Checkout" button in the Cart.

```ts
const { __ } = window.wp.i18n;
const { registerPlugin } = window.wp.plugins;
const { ExperimentalOrderMeta } = window.wc.blocksCheckout;

const render = () => {
	return (
		<ExperimentalOrderMeta>
			<div class="wc-block-components-totals-wrapper">
				{ __( 'Yearly recurring total ...', 'YOUR-TEXTDOMAIN' ) }
			</div>
		</ExperimentalOrderMeta>
	);
};

registerPlugin( 'slot-and-fill-examples', {
	render,
	scope: 'woocommerce-checkout',
} );
```

Cart:

![Example of ExperimentalOrderMeta in the Cart block](https://user-images.githubusercontent.com/1628454/154517779-117bb4e4-568e-413c-904c-855fc3450dfa.png)

Checkout:

![Example of ExperimentalOrderMeta in the Checkout block](https://user-images.githubusercontent.com/1628454/154697224-de245182-6783-4914-81ba-1dbcf77292eb.png)

### Passed parameters

-   `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/types/type-defs/cart.ts)
-   `extensions`: external data registered by third-party developers using `ExtendSchema`. If you used `ExtendSchema` on `wc/store/cart` you would find your data under your namespace here.
-   `context`, equal to the name of the Block in which the fill is rendered: `woocommerce/cart` or `woocommerce/checkout`

## ExperimentalOrderShippingPackages

This slot renders inside the shipping step of Checkout and inside the shipping options in Cart.

```ts
const { __ } = window.wp.i18n;
const { registerPlugin } = window.wp.plugins;
const { ExperimentalOrderShippingPackages } = window.wc.blocksCheckout;

const render = () => {
	return (
		<ExperimentalOrderShippingPackages>
			<div>{ __( 'Express Shipping', 'YOUR-TEXTDOMAIN' ) }</div>
		</ExperimentalOrderShippingPackages>
	);
};

registerPlugin( 'slot-and-fill-examples', {
	render,
	scope: 'woocommerce-checkout',
} );
```

Cart:

![Example of ExperimentalOrderShippingPackages in the Cart block](https://user-images.githubusercontent.com/6165348/118399054-2b4dec80-b653-11eb-94a0-989e2e6e362a.png)

Checkout:

![Example of ExperimentalOrderShippingPackages in the Checkout block](https://user-images.githubusercontent.com/6165348/118399133-90094700-b653-11eb-8ff0-c917947c199f.png)

### Passed parameters

-   `collapsible`: `Boolean|undefined` If a shipping package panel should be collapsible or not, this is false in Checkout and undefined in Cart.
-   `collapse`: `Boolean` If a panel should be collapsed by default, this is true if panels are collapsible.
-   `showItems`: `Boolean|undefined` If we should show the content of each package, this is undefined in Cart and Checkout and is left to the actual package logic to decide.
-   `noResultsMessage`: A React element that you can render if there are no shipping options.
-   `renderOption`: a render function that takes a rate object and returns a render option.
-   `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/types/type-defs/cart.ts)
-   `extensions`: external data registered by third-party developers using `ExtendSchema`, if you used `ExtendSchema` on `wc/store/cart` you would find your data under your namespace here.
-   `components`: an object containing components you can use to render your own shipping rates, it contains `ShippingRatesControlPackage`.
-   `context`, equal to the name of the Block in which the fill is rendered: `woocommerce/cart` or `woocommerce/checkout`

## ExperimentalOrderLocalPickupPackages

This slot renders inside the Checkout Pickup Options block in the Checkout block. It does not render in the Cart block.

```ts
const { __ } = window.wp.i18n;
const { registerPlugin } = window.wp.plugins;
const { ExperimentalOrderLocalPickupPackages } = window.wc.blocksCheckout;

const render = () => {
	return (
		<ExperimentalOrderLocalPickupPackages>
			<div>
				{ __(
					'By using our convenient local pickup option, you can come to our store and pick up your order. We will send you an email when your order is ready for pickup.',
					'YOUR-TEXTDOMAIN'
				) }
			</div>
		</ExperimentalOrderLocalPickupPackages>
	);
};

registerPlugin( 'slot-and-fill-examples', {
	render,
	scope: 'woocommerce-checkout',
} );
```

Checkout:

![Example of ExperimentalOrderLocalPickupPackages in the Checkout block](https://user-images.githubusercontent.com/5656702/222814945-a449d016-0621-4a70-b0f4-2ae1ce6487f1.png)

### Passed parameters

-   `renderPickupLocation`: a render function that renders the address details of a local pickup option.
-   `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/types/type-defs/cart.ts)
-   `extensions`: external data registered by third-party developers using `ExtendSchema`, if you used `ExtendSchema` on `wc/store/cart` you would find your data under your namespace here.
-   `components`: an object containing components you can use to render your own pickup rates, it contains `ShippingRatesControlPackage` and `RadioControl`.

## ExperimentalDiscountsMeta

This slot renders below the `CouponCode` input.

```ts
const { __ } = window.wp.i18n;
const { registerPlugin } = window.wp.plugins;
const { ExperimentalDiscountsMeta } = window.wc.blocksCheckout;

const render = () => {
	return (
		<ExperimentalDiscountsMeta>
			<div class="wc-block-components-totals-wrapper">
				{ __( 'You have 98683 coins to spend ...', 'YOUR-TEXTDOMAIN' ) }
			</div>
		</ExperimentalDiscountsMeta>
	);
};

registerPlugin( 'slot-and-fill-examples', {
	render,
	scope: 'woocommerce-checkout',
} );
```

Cart:

![Cart showing ExperimentalDiscountsMeta location](https://user-images.githubusercontent.com/5656702/122774218-ea27a880-d2a0-11eb-9450-11f119567f26.png)

Checkout:

![Checkout showing ExperimentalDiscountsMeta location](https://user-images.githubusercontent.com/5656702/122779606-efd3bd00-d2a5-11eb-8c84-6525eca5d704.png)

### Passed parameters

-   `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/types/type-defs/cart.ts)
-   `extensions`: external data registered by third-party developers using `ExtendSchema`, if you used `ExtendSchema` on `wc/store/cart` you would find your data under your namespace here.
-   `context`, equal to the name of the Block in which the fill is rendered: `woocommerce/cart` or `woocommerce/checkout`


---

## Checkout flow and events

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/checkout-payment-methods/checkout-flow-and-events.md*

# Checkout flow and events

This document gives an overview of the flow for the checkout in the WooCommerce checkout block, and some general architectural overviews.

The architecture of the Checkout Block is derived from the following principles:

-   A single source of truth for data within the checkout flow.
-   Provide a consistent interface for extension integrations (eg Payment methods). This interface protects the integrity of the checkout process and isolates extension logic from checkout logic. The checkout block handles _all_ communication with the server for processing the order. Extensions are able to react to and communicate with the checkout block via the provided interface.
-   Checkout flow state is tracked by checkout status.
-   Extensions are able to interact with the checkout flow via subscribing to emitted events.

Here's a high level overview of the flow:

![checkout flow diagram](https://user-images.githubusercontent.com/1628454/113739726-f8c9df00-96f7-11eb-80f1-78e25ccc88cb.png)

## General Concepts

### Tracking flow through status

At any point in the checkout lifecycle, components should be able to accurately detect the state of the checkout flow. This includes things like:

-   Is something loading? What is loading?
-   Is there an error? What is the error?
-   is the checkout calculating totals?

Using simple booleans can be fine in some cases, but in others it can lead to complicated conditionals and bug prone code (especially for logic behaviour that reacts to various flow state).

To surface the flow state, the block uses statuses that are tracked in the various contexts. _As much as possible_ these statuses are set internally in reaction to various actions so there's no implementation needed in children components (components just have to _consume_ the status not set status).

The following statuses exist in the Checkout.

#### Checkout Data Store Status

There are various statuses that are exposed on the Checkout data store via selectors. All the selectors are detailed below and in the [Checkout API docs](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/internal-developers/block-client-apis/checkout/checkout-api.md).

You can use them in your component like so

```jsx
const { useSelect } = window.wp.data;
const { checkoutStore } = window.wc.wcBlocksData;

const MyComponent = ( props ) => {
	const isComplete = useSelect( ( select ) =>
		select( checkoutStore ).isComplete()
	);
	// do something with isComplete
};
```

The following boolean flags available related to status are:

**isIdle**: When the checkout status is `IDLE` this flag is true. Checkout will be this status after any change to checkout state after the block is loaded. It will also be this status when retrying a purchase is possible after processing happens with an error.

**isBeforeProcessing**: When the checkout status is `BEFORE_PROCESSING` this flag is true. Checkout will be this status when the user submits checkout for processing.

**isProcessing**: When the checkout status is `PROCESSING` this flag is true. Checkout will be this status when all the observers on the event emitted with the `BEFORE_PROCESSING` status are completed without error. It is during this status that the block will be sending a request to the server on the checkout endpoint for processing the order. **Note:** there are some checkout payment status changes that happen during this state as well (outlined in the `PaymentProvider` exposed statuses section).

**isAfterProcessing**: When the checkout status is `AFTER_PROCESSING` this flag is true. Checkout will have this status after the block receives the response from the server side processing request.

**isComplete**: When the checkout status is `COMPLETE` this flag is true. Checkout will have this status after all observers on the events emitted during the `AFTER_PROCESSING` status are completed successfully. When checkout is at this status, the shopper's browser will be redirected to the value of `redirectUrl` at that point (usually the `order-received` route).

#### Special States

The following booleans are exposed via the checkout provider. They are independent from each other and checkout statuses, but can be used in combination to react to various states in the checkout.

##### **isCalculating**

`isCalculating` is true when the total is being re-calculated for the order, or when a plugin is intentionally disabling the checkout using the `disableCheckoutFor` action (covered in the next section).

There are numerous things that might trigger a recalculation of the total—coupons being added or removed, shipping rates updating, shipping rates being selected, etc. Instead of having to check each of those individual states, you can reliably check if this boolean is true (calculating) or false (not calculating).

What `isCalculating` affects:

- Disables the "Place Order" button in the checkout block
- Disables the "Proceed to Checkout" button in the cart block
- Shows a loading state for Express Payment methods while calculations are pending

###### Controlling `isCalculating` with `disableCheckoutFor`

You can programmatically control `isCalculating` using the `disableCheckoutFor` thunk:

```jsx
const { dispatch } = window.wp.data;
const { checkoutStore } = window.wc.wcBlocksData;

// Example: Disable checkout while performing an async operation
dispatch( checkoutStore ).disableCheckoutFor( async () => {
	// Your async operation here, e.g. validating data with an API
	await myAsyncOperation();
	// No need to return anything - we only care about the promise resolving
} );
```

The thunk controls internal state, ensuring that the client won't be able to attempt completing the flow until the provided promise resolves, regardless of whether it succeeds or fails.

##### **hasError**

`hasError` is true when anything in the checkout has created an error condition state. This might be validation errors, request errors, coupon application errors, payment processing errors etc.

### `ShippingProvider` Exposed Statuses

The shipping context provider exposes everything related to shipping in the checkout. Included in this are a set of error statuses that inform what error state the shipping context is in and the error state is affected by requests to the server on address changes, rate retrieval and selection.

Currently the error status may be one of `NONE`, `INVALID_ADDRESS` or `UNKNOWN` (note, this may change in the future).

The status is exposed on the `currentErrorStatus` object provided by the `useShippingDataContext` hook. This object has the following properties on it:

-   `isPristine` and `isValid`: Both of these booleans are connected to the same error status. When the status is `NONE` the values for these booleans will be `true`. It basically means there is no shipping error.
-   `hasInvalidAddress`: When the address provided for shipping is invalid, this will be true.
-   `hasError`: This is `true` when the error status for shipping is either `UNKNOWN` or `hasInvalidAddress`.

### Payment Method Data Store Status

The status of the payment lives in the payment data store. You can query the status with the following selectors:

```jsx
const { select } = window.wp.data;
const { paymentStore } = window.wc.wcBlocksData;

const MyComponent = ( props ) => {
	const isPaymentIdle = select( paymentStore ).isPaymentIdle();
	const isExpressPaymentStarted =
		select( paymentStore ).isExpressPaymentStarted();
	const isPaymentProcessing = select( paymentStore ).isPaymentProcessing();
	const isPaymentReady = select( paymentStore ).isPaymentReady();
	const hasPaymentError = select( paymentStore ).hasPaymentError();

	// do something with the boolean values
};
```

The status here will help inform the current state of _client side_ processing for the payment and are updated via the store actions at different points throughout the checkout processing cycle. _Client side_ means the state of processing any payments by registered and active payment methods when the checkout form is submitted via those payment methods registered client side components. It's still possible that payment methods might have additional server side processing when the order is being processed but that is not reflected by these statuses (more in the [payment method integration doc](./payment-method-integration.md)).

The possible _internal_ statuses that may be set are:

-   `IDLE`: This is the status when checkout is initialized and there are payment methods that are not doing anything. This status is also set whenever the checkout status is changed to `IDLE`.
-   `EXPRESS_STARTED`: **Express Payment Methods Only** - This status is used when an express payment method has been triggered by the user clicking it's button. This flow happens before processing, usually in a modal window.
-   `PROCESSING`: This status is set when the checkout status is `PROCESSING`, checkout `hasError` is false, checkout is not calculating, and the current payment status is not `FINISHED`. When this status is set, it will trigger the payment processing event emitter.
-   `READY`: This status is set after all the observers hooked into the payment processing event have completed successfully. The `CheckoutProcessor` component uses this along with the checkout `PROCESSING` status to signal things are ready to send the order to the server with data for processing and to take payment
-   `ERROR`: This status is set after an observer hooked into the payment processing event returns an error response. This in turn will end up causing the checkout `hasError` flag to be set to true.

### Emitting Events

Another tricky thing for extensibility, is providing opinionated, yet flexible interfaces for extensions to act and react to specific events in the flow. For stability, it's important that the core checkout flow _controls_ all communication to and from the server specific to checkout/order processing and leave extension specific requirements for the extension to handle. This allows for extensions to predictably interact with the checkout data and flow as needed without impacting other extensions hooking into it.

One of the most reliable ways to implement this type of extensibility is via the usage of an events system. Thus the various context providers:

-   expose subscriber APIs for extensions to subscribe _observers_ to the events they want to react to.
-   emit events at specific points of the checkout flow that in turn will feed data to the registered observers and, in some cases, react accordingly to the responses from observers.

One _**very important rule**_ when it comes to observers registered to any event emitter in this system is that they _cannot_ update context state. Updating state local to a specific component is okay but not any context or global state. The reason for this is that the observer callbacks are run sequentially at a specific point and thus subsequent observers registered to the same event will not react to any change in global/context state in earlier executed observers.

```jsx
const unsubscribe = emitter( myCallback );
```

You could substitute in whatever emitter you are registering for the `emitter` function. So for example if you are registering for the `onCheckoutValidation` event emitter, you'd have something like:

```jsx
const unsubscribe = onCheckoutValidation( myCallback );
```

You can also indicate what priority you want your observer to execute at. Lower priority is run before higher priority, so you can affect when your observer will run in the stack of observers registered to an emitter. You indicate priority via an number on the second argument:

```jsx
const unsubscribe = onCheckoutValidation( myCallback, 10 );
```

In the examples, `myCallback`, is your subscriber function. The subscriber function could receive data from the event emitter (described in the emitter details below) and may be expected to return a response in a specific shape (also described in the specific emitter details). The subscriber function can be a `Promise` and when the event emitter cycles through the registered observers it will await for any registered Promise to resolve.

Finally, the return value of the call to the emitter function is an unsubscribe function that can be used to unregister your observer. This is especially useful in a React component context where you need to make sure you unsubscribe the observer on component unmount. An example is usage in a `useEffect` hook:

```jsx
const MyComponent = ( { onCheckoutValidation } ) => {
	useEffect( () => {
		const unsubscribe = onCheckoutValidation( () => true );
		return unsubscribe;
	}, [ onCheckoutValidation ] );
	return null;
};
```

**`Event Emitter Utilities`**

There are a bunch of utility methods that can be used related to events. These are available in `assets/js/base/context/event-emit/utils.ts` and can be imported as follows:

```jsx
import {
	noticeContexts,
	responseTypes,
	shouldRetry,
} from '@woocommerce/base-context';
import {
	isSuccessResponse,
	isErrorResponse,
	isFailResponse,
} from '@woocommerce/types';
```

The helper functions are described below:

-   `isSuccessResponse`, `isErrorResponse` and `isFailResponse`: These are helper functions that receive a value and report via boolean whether the object is a type of response expected. For event emitters that receive responses from registered observers, a `type` property on the returned object from the observer indicates what type of response it is and event emitters will react according to that type. So for instance if an observer returned `{ type: 'success' }` the emitter could feed that to `isSuccessResponse` and it would return `true`. You can see an example of this being implemented for the [payment processing emitted event here](https://github.com/woocommerce/woocommerce/blob/df02d62e2d41e9007da44cb87fea2b7a9551f55c/plugins/woocommerce/client/blocks/packages/public-api/types/type-guards/observers.ts#L41-L65).
-   `noticeContexts`: This is an object containing properties referencing areas where notices can be targeted in the checkout. The object has the following properties:
    -   `PAYMENTS`: This is a reference to the notice area in the payment methods step.
    -   `EXPRESS_PAYMENTS`: This is a reference to the notice area in the express payment methods step.
-   `responseTypes`: This is an object containing properties referencing the various response types that can be returned by observers for some event emitters. It makes it easier for autocompleting the types and avoiding typos due to human error. The types are `SUCCESS`, `FAIL`, `ERROR`. The values for these types also correspond to the [payment status types](https://github.com/woocommerce/woocommerce/blob/2db0cfdaecc7cc60a45790e760e71c26edc4f295/plugins/woocommerce/src/StoreApi/Payments/PaymentResult.php#L13) from the [checkout endpoint response from the server](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Schemas/V1/CheckoutSchema.php).
-   `shouldRetry`: This is a function containing the logic whether the checkout flow should allow the user to retry the payment after a previous payment failed. It receives the `response` object and by default checks whether the `retry` property is true/undefined or false. Refer to the [`onCheckoutSuccess`](#oncheckoutsuccess) documentation for more details.

Note: `noticeContexts` and `responseTypes` are exposed to payment methods via the `emitResponse` prop given to their component:

```jsx
const MyPaymentMethodComponent = ( { emitResponse } ) => {
	const { noticeContexts, responseTypes } = emitResponse;
	// other logic for payment method...
};
```

The following event emitters are available to extensions to register observers to:

### `onCheckoutValidation`

Observers registered to this event emitter will receive nothing as an argument. Also, all observers will be executed before the checkout handles the responses from the emitters. Observers registered to this emitter can return `true` if they have nothing to communicate back to checkout, `false` if they want checkout to go back to `IDLE` status state, or an object with any of the following properties:

-   `errorMessage`: This will be added as an error notice on the checkout context.
-   `validationErrors`: This will be set as inline validation errors on checkout fields. If your observer wants to trigger validation errors it can use the following shape for the errors:
    -   This is an object where keys are the property names the validation error is for (that correspond to a checkout field, eg `country` or `coupon`) and values are the error message describing the validation problem.

This event is emitted when the checkout status is `BEFORE_PROCESSING` (which happens at validation time, after the checkout form submission is triggered by the user - or Express Payment methods).

If all observers return `true` for this event, then the checkout status will be changed to `PROCESSING`.

This event emitter subscriber can be obtained via the checkout context using the `useCheckoutContext` hook or to payment method extensions as a prop on their registered component:

_For internal development:_

```jsx
import { useCheckoutContext } from '@woocommerce/base-contexts';
import { useEffect } from '@wordpress/element';

const Component = () => {
	const { onCheckoutValidation } = useCheckoutContext();
	useEffect( () => {
		const unsubscribe = onCheckoutValidation( () => true );
		return unsubscribe;
	}, [ onCheckoutValidation ] );
	return null;
};
```

_For registered payment method components:_

```jsx
const { useEffect } = window.wp.element;

const PaymentMethodComponent = ( { eventRegistration } ) => {
	const { onCheckoutValidation } = eventRegistration;
	useEffect( () => {
		const unsubscribe = onCheckoutValidation( () => true );
		return unsubscribe;
	}, [ onCheckoutValidation ] );
};
```

_For anything else:_

```jsx
const { onCheckoutValidation } = wc.blocksCheckoutEvents;

useEffect( () => {
	const unsubscribe = onCheckoutValidation( () => true );
	return unsubscribe;
}, [ onCheckoutValidation ] );
```

### ~~`onPaymentProcessing`~~

This is now deprecated and replaced by the `onPaymentSetup` event emitter.

### `onPaymentSetup`

This event emitter was fired when the payment method context status is `PROCESSING` and that status is set when the checkout status is `PROCESSING`, checkout `hasError` is false, checkout is not calculating, and the current payment status is not `FINISHED`.

This event emitter will execute through each registered observer (passing in nothing as an argument) _until_ an observer returns a non-truthy value at which point it will _abort_ further execution of registered observers.

When a payment method returns a non-truthy value, if it returns a valid response type the event emitter will update various internal statuses according to the response. Here's the possible response types that will get handled by the emitter:

#### Success

A successful response should be given when the user's entered data is correct and the payment checks are successful. A response is considered successful if, at a minimum, it is an object with this shape:

```js
const successResponse = { type: 'success' };
```

When a success response is returned, the payment method context status will be changed to `SUCCESS`. In addition, including any of the additional properties will result in extra actions:

-   `paymentMethodData`: The contents of this object will be included as the value for `payment_data` when checkout sends a request to the checkout endpoint for processing the order. This is useful if a payment method does additional server side processing.
-   `billingAddress`: This allows payment methods to update any billing data information in the checkout (typically used by Express payment methods) so it's included in the checkout processing request to the server. This data should be in the [shape outlined here](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/settings/default-fields.ts).
-   `shippingAddress`: This allows payment methods to update any shipping data information for the order (typically used by Express payment methods) so it's included in the checkout processing request to the server. This data should be in the [shape outlined here](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/settings/default-fields.ts).

If `billingAddress` or `shippingAddress` properties aren't in the response object, then the state for the data is left alone.

#### Fail

A fail response should be given when there is an error with the payment processing. A response is considered a fail response when it is an object with this shape:

```js
const failResponse = { type: 'failure' };
```

When a fail response is returned by an observer, the payment method context status will be changed to `FAIL`. In addition, including any of the following properties will result in extra actions:

-   `message`: The string provided here will be set as an error notice in the checkout.
-   `messageContext`: If provided, this will target the given area for the error notice (this is where `noticeContexts` mentioned earlier come in to play). Otherwise the notice will be added to the `noticeContexts.PAYMENTS` area.
-   `paymentMethodData`: (same as for success responses).
-   `billingAddress`: (same as for success responses).

#### Error

An error response should be given when there is an error with the user input on the checkout form. A response is considered an error response when it is an object with this shape:

```js
const errorResponse = { type: 'error' };
```

When an error response is returned by an observer, the payment method context status will be changed to `ERROR`. In addition, including any of the following properties will result in extra actions:

-   `message`: The string provided here will be set as an error notice.
-   `messageContext`: If provided, this will target the given area for the error notice (this is where `noticeContexts` mentioned earlier come in to play). Otherwise, the notice will be added to the `noticeContexts.PAYMENTS` area.
-   `validationErrors`: This will be set as inline validation errors on checkout fields. If your observer wants to trigger validation errors it can use the following shape for the errors:
    -   This is an object where keys are the property names the validation error is for (that correspond to a checkout field, eg `country` or `coupon`) and values are the error message describing the validation problem.

If the response object doesn't match any of the above conditions, then the fallback is to set the payment status as `SUCCESS`.

When the payment status is set to `SUCCESS` and the checkout status is `PROCESSING`, the `CheckoutProcessor` component will trigger the request to the server for processing the order.

This event emitter subscriber can be obtained via the checkout context using the `usePaymentEventsContext` hook or to payment method extensions as a prop on their registered component:

_For internal development:_

```jsx
import { usePaymentEventsContext } from '@woocommerce/base-contexts';
import { useEffect } from '@wordpress/element';

const Component = () => {
	const { onPaymentSetup } = usePaymentEventsContext();
	useEffect( () => {
		const unsubscribe = onPaymentSetup( () => true );
		return unsubscribe;
	}, [ onPaymentSetup ] );
	return null;
};
```

_For registered payment method components:_

```jsx
const { useEffect } = window.wp.element;

const PaymentMethodComponent = ( { eventRegistration } ) => {
	const { onPaymentSetup } = eventRegistration;
	useEffect( () => {
		const unsubscribe = onPaymentSetup( () => true );
		return unsubscribe;
	}, [ onPaymentSetup ] );
};
```

### `onCheckoutSuccess`

This event emitter is fired when the checkout status is `AFTER_PROCESSING` and the checkout `hasError` state is false. The `AFTER_PROCESSING` status is set by the `CheckoutProcessor` component after receiving a response from the server for the checkout processing request.

Observers registered to this event emitter will receive the following object as an argument:

```js
const onCheckoutProcessingData = {
	redirectUrl,
	orderId,
	customerId,
	orderNotes,
	paymentResult,
};
```

The properties are:

-   `redirectUrl`: This is a string that is the url the checkout will redirect to as returned by the processing on the server.
-   `orderId`: Is the id of the current order being processed.
-   `customerId`: Is the id for the customer making the purchase (that is attached to the order).
-   `orderNotes`: This will be any custom note the customer left on the order.
-   `paymentResult`: This is the value of [`payment_result` from the /checkout StoreApi response](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Schemas/V1/CheckoutSchema.php). The data exposed on this object is (via the object properties):
    -   `paymentStatus`: Whatever the status is for the payment after it was processed server side. Will be one of `success`, `failure`, `pending`, `error`.
    -   `paymentDetails`: This will be an arbitrary object that contains any data the payment method processing server side sends back to the client in the checkout processing response. Payment methods are able to hook in on the processing server side and set this data for returning.

This event emitter will invoke each registered observer until a response from any of the registered observers does not equal `true`. At that point any remaining non-invoked observers will be skipped and the response from the observer triggering the abort will be processed.

This emitter will handle a `success` response type (`{ type: success }`) by setting the checkout status to `COMPLETE`. Along with that, if the response includes `redirectUrl` then the checkout will redirect to the given address.

This emitter will also handle a `failure` response type or an `error` response type and if no valid type is detected it will treat it as an `error` response type.

In all cases, if there are the following properties in the response, additional actions will happen:

-   `message`: This string will be added as an error notice.
-   `messageContext`: If present, the notice will be configured to show in the designated notice area (otherwise it will just be a general notice for the checkout block).
-   `retry`: If this is `true` or not defined, then the checkout status will be set to `IDLE`. This basically means that the error is recoverable (for example try a different payment method) and so checkout will be reset to `IDLE` for another attempt by the shopper. If this is `false`, then the checkout status is set to `COMPLETE` and the checkout will redirect to whatever is currently set as the `redirectUrl`.
-   `redirectUrl`: If this is present, then the checkout will redirect to this url when the status is `COMPLETE`.

If all observers return `true`, then the checkout status will just be set to `COMPLETE`.

This event emitter subscriber can be obtained via the checkout context using the `useCheckoutContext` hook or to payment method extensions as a prop on their registered component:

_For internal development:_

```jsx
import { useCheckoutContext } from '@woocommerce/base-contexts';
import { useEffect } from '@wordpress/element';

const Component = () => {
	const { onCheckoutSuccess } = useCheckoutContext();
	useEffect( () => {
		const unsubscribe = onCheckoutSuccess( () => true );
		return unsubscribe;
	}, [ onCheckoutSuccess ] );
	return null;
};
```

_For registered payment method components:_

```jsx
const { useEffect } = window.wp.element;

const PaymentMethodComponent = ( { eventRegistration } ) => {
	const { onCheckoutSuccess } = eventRegistration;
	useEffect( () => {
		const unsubscribe = onCheckoutSuccess( () => true );
		return unsubscribe;
	}, [ onCheckoutSuccess ] );
};
```

_For anything else:_

```jsx
const { onCheckoutSuccess } = wc.blocksCheckoutEvents;

useEffect( () => {
	const unsubscribe = onCheckoutSuccess( () => true );
	return unsubscribe;
}, [ onCheckoutSuccess ] );
```

### `onCheckoutFail`

This event emitter is fired when the checkout status is `AFTER_PROCESSING` and the checkout `hasError` state is `true`. The `AFTER_PROCESSING` status is set by the `CheckoutProcessor` component after receiving a response from the server for the checkout processing request.

Observers registered to this emitter will receive the same data package as those registered to `onCheckoutSuccess`.

The response from the first observer returning a value that does not `===` true will be handled similarly as the `onCheckoutSuccess` except it only handles when the type is `error` or `failure`.

If all observers return `true`, then the checkout status will just be set to `IDLE` and a default error notice will be shown in the checkout context.

This event emitter subscriber can be obtained via the checkout context using the `useCheckoutContext` hook or to payment method extensions as a prop on their registered component:

_For internal development:_

```jsx
import { useCheckoutContext } from '@woocommerce/base-contexts';
import { useEffect } from '@wordpress/element';

const Component = () => {
	const { onCheckoutFail } = useCheckoutContext();
	useEffect( () => {
		const unsubscribe = onCheckoutFail( () => true );
		return unsubscribe;
	}, [ onCheckoutFail ] );
	return null;
};
```

_For registered payment method components:_

```jsx
const { useEffect } = window.wp.element;

const PaymentMethodComponent = ( { eventRegistration } ) => {
	const { onCheckoutFail } = eventRegistration;
	useEffect( () => {
		const unsubscribe = onCheckoutFail( () => true );
		return unsubscribe;
	}, [ onCheckoutFail ] );
};
```

_For anything else:_

```jsx
const { onCheckoutFail } = wc.blocksCheckoutEvents;

useEffect( () => {
	const unsubscribe = onCheckoutFail( () => true );
	return unsubscribe;
}, [ onCheckoutFail ] );
```

### `onShippingRateSuccess`

This event emitter is fired when shipping rates are not loading and the shipping data context error state is `NONE` and there are shipping rates available.

This event emitter doesn't care about any registered observer response and will simply execute all registered observers passing them the current shipping rates retrieved from the server.

### `onShippingRateFail`

This event emitter is fired when shipping rates are not loading and the shipping data context error state is `UNKNOWN` or `INVALID_ADDRESS`.

This event emitter doesn't care about any registered observer response and will simply execute all registered observers passing them the current error status in the context.

### `onShippingRateSelectSuccess`

This event emitter is fired when a shipping rate selection is not being persisted to the server and there are selected rates available and the current error status in the context is `NONE`.

This event emitter doesn't care about any registered observer response and will simply execute all registered observers passing them the current selected rates.

### `onShippingRateSelectFail`

This event emitter is fired when a shipping rate selection is not being persisted to the server and the shipping data context error state is `UNKNOWN` or `INVALID_ADDRESS`.

This event emitter doesn't care about any registered observer response and will simply execute all registered observers passing them the current error status in the context.


---

## Filtering payment methods in the Checkout block

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/checkout-payment-methods/filtering-payment-methods.md*

# Filtering payment methods in the Checkout block

## The problem

You're an extension developer, and your extension is conditionally hiding payment gateways on the checkout step. You need to be able to hide payment gateways on the Checkout block using a front-end extensibility point.

### The solution

WooCommerce Blocks provides a function called `registerPaymentMethodExtensionCallbacks` which allows extensions to register callbacks for specific payment methods to determine if they can make payments.

### Importing

#### Aliased import

```js
import { registerPaymentMethodExtensionCallbacks } from '@woocommerce/blocks-registry';
```

#### `wc global`

```js
const { registerPaymentMethodExtensionCallbacks } = window.wc.wcBlocksRegistry;
```

### Signature

| Parameter   | Description                                                                                                         | Type                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `namespace` | Unique string to identify your extension. Choose something that eliminates a name collision with another extension. | `string`                                          |
| `callbacks` | An object containing callbacks registered for different payment methods                                             | Record< string, CanMakePaymentExtensionCallback > |

Read more below about [callbacks](#callbacks-registered-for-payment-methods).

#### Extension namespace collision

When trying to register callbacks under an extension namespace already used with `registerPaymentMethodExtensionCallbacks`, the registration will be aborted and you will be notified that you are not using a unique namespace. This will be shown in the JavaScript console.

### Usage example

```js
registerPaymentMethodExtensionCallbacks( 'my-hypothetical-extension', {
	cod: ( arg ) => {
		return arg.shippingAddress.city === 'Berlin';
	},
	cheque: ( arg ) => {
		return false;
	},
} );
```

### Callbacks registered for payment methods

Extensions can register only one callback per payment method:

```text
payment_method_name: ( arg ) => {...}
```

`payment_method_name` is the value of the [name property](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/checkout-payment-methods/payment-method-integration) used when the payment method was registered with WooCommerce Blocks.

The registered callbacks are used to determine whether the corresponding payment method should be available as an option for the shopper. The function will be passed an object containing data about the current order.

```ts
type CanMakePaymentExtensionCallback = (
	cartData: CanMakePaymentArgument
) => boolean;
```

Each callback will have access to the information bellow

```ts
interface CanMakePaymentArgument {
	cart: Cart;
	cartTotals: CartTotals;
	cartNeedsShipping: boolean;
	billingAddress: CartResponseBillingAddress;
	shippingAddress: CartResponseShippingAddress;
	selectedShippingMethods: Record< string, unknown >;
	paymentRequirements: Array< string >;
}
```

If you need data that is not available in the parameter received by the callback you can consider [exposing your data in the Store API](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-add-data.md).


## Filtering payment methods using requirements

### The problem

Your extension has added functionality to your store in such a way that only specific payment gateways can process orders that contain certain products.

Using the example of `Bookings` if the shopper adds a `Bookable` product to their cart, for example a stay in a hotel, and you, the merchant, want to confirm all bookings before taking payment. You would still need to capture the customer's checkout details but not their payment method at that point.

### The solution

To allow the shopper to check out without entering payment details, but still require them to fill in the other checkout details it is possible to create a new payment method which will handle carts containing a `Bookable` item.

Using the `supports` configuration of payment methods it is possible to prevent other payment methods (such as credit card, PayPal etc.) from being used to check out, and only allow the one your extension has added to appear in the Checkout block.

For more information on how to register a payment method with WooCommerce Blocks, please refer to the [Payment method integration](./payment-method-integration.md) documentation.

### Basic usage

Following the documentation for registering payment methods linked above, you should register your payment method with a unique `supports` feature, for example `booking_availability`. This will be used to isolate it and prevent other methods from displaying.

First you will need to create a function that will perform the checks on the cart to determine what the specific payment requirements of the cart are. Below is an example of doing this for our `Bookable` products.

Then you will need to use the `register_payment_requirements` on the `ExtendSchema` class to tell the Checkout block to execute a callback to check for requirements.

### Putting it all together

This code example assumes there is some class called `Pseudo_Booking_Class` that has the `cart_contains_bookable_product` method available. The implementation of this method is not relevant here.

```php
/**
 * Check the content of the cart and add required payment methods.
 *
 *
 * @return array list of features required by cart items.
 */
function inject_payment_feature_requirements_for_cart_api() {
  // Cart contains a bookable product, so return an array containing our requirement of booking_availability.
  if ( Pseudo_Booking_Class::cart_contains_bookable_product() ) {
    return array( 'booking_availability' );
  }

  // No bookable products in the cart, no need to add anything.
  return array();
}
```

To summarise the above: if there's a bookable product in the cart then this function will return an array containing `booking_availability`, otherwise it will return an empty array.

The next step will tell the `ExtendSchema` class to execute this callback when checking which payment methods to display.

To do this you could use the following code:

```php
add_action('woocommerce_blocks_loaded', function() {
  woocommerce_store_api_register_payment_requirements(
    array(
      'data_callback' => 'inject_payment_feature_requirements_for_cart_api',
    )
  );
});
```

It is important to note the comment in this code block, you must not instantiate your own version of `ExtendSchema`.

If you've added your payment method correctly with the correct `supports` values then when you reach the checkout page with a `Bookable` item in your cart, any method that does not `supports` the `booking_availability` requirement should not display, while yours, the one that _does_ support this requirement _will_ display.


---

## Payment method integration

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/checkout-payment-methods/payment-method-integration.md*

# Payment method integration

## Client Side integration

The client side integration consists of an API for registering both _regular_ and _express_ payment methods.

In both cases, the client side integration is done using registration methods exposed on the `blocks-registry` API. You can access this via the `wc` global in a WooCommerce environment (`wc.wcBlocksRegistry`).

> Note: The `@woocommerce/blocks-registry` import examples in this document require a build process that maps WooCommerce packages to their registered script handles. Do not install `@woocommerce/blocks-registry` from npm. Use the [`@woocommerce/dependency-extraction-webpack-plugin`](https://www.npmjs.com/package/@woocommerce/dependency-extraction-webpack-plugin) in your webpack configuration to externalize bundled WooCommerce packages such as `@woocommerce/blocks-registry` to the `wc-blocks-registry` script.

## Express Payment Methods

Express payment methods are payment methods that consist of a one-button payment process initiated by the shopper such as Stripe, ApplePay, or GooglePay.

![Express Payment Area](https://user-images.githubusercontent.com/1429108/79565636-17fed500-807f-11ea-8e5d-9af32e43b71d.png)

### Registration

To register an express payment method, you use the `registerExpressPaymentMethod` function from the blocks registry. 

```js
const { registerExpressPaymentMethod } = window.wc.wcBlocksRegistry;
```

If you're using an aliased import for `@woocommerce/blocks-registry`, you can import the function like this:

```js
import { registerExpressPaymentMethod } from '@woocommerce/blocks-registry';
```

The registry function expects a JavaScript object with options specific to the payment method:

```js
registerExpressPaymentMethod( options );
```

The options you feed the configuration instance should be an object in this shape (see `ExpressPaymentMethodConfiguration` typedef):

```js
const options = {
	name: 'my_payment_method',
	title: 'My Mayment Method',
	description: 'A sentence or two about your payment method',
	gatewayId: 'gateway-id',
	label: <ReactNode />,
	content: <ReactNode />,
	edit: <ReactNode />,
	canMakePayment: () => true,
	paymentMethodId: 'my_payment_method',
	supports: {
		features: [],
		style: [],
	},
};
```

#### `ExpressPaymentMethodConfiguration`

| Option | Type | Description | Required |
| --- | --- | --- | --- |
| `name` | String | Unique identifier for the gateway client side. | Yes |
| `title` | String | Human readable name of your payment method. Displayed to the merchant in the editor. | No |
| `description` | String | One or two sentences describing your payment gateway. Displayed to the merchant in the editor. | No |
| `gatewayId` | String | ID of the Payment Gateway registered server side. Used to direct the merchant to the right settings page within the editor. If this is not provided, the merchant will be redirected to the general Woo payment settings page. | No |
| `content` | ReactNode | React node output in the express payment method area when the block is rendered in the frontend. Receives props from the checkout payment method interface. | Yes |
| `edit` | ReactNode | React node output in the express payment method area when the block is rendered in the editor. Receives props from the payment method interface to checkout (with preview data). | Yes |
| `canMakePayment` | Function | Callback to determine whether the payment method should be available for the shopper. | Yes |
| `paymentMethodId` | String | Identifier accompanying the checkout processing request to the server. Used to identify the payment method gateway class for processing the payment. Should match the gateway's server-side ID, as it is also used to detect whether the gateway is compatible with the Checkout block in the editor. Defaults to the value of `name` when omitted. | No |
| `supports:features` | Array | Array of payment features supported by the gateway. Used to crosscheck if the payment method can be used for the cart content. Defaults to `['products']` if no value is provided. | No |
| `supports:style` | Array | This is an array of style variations supported by the express payment method. These are styles that are applied across all the active express payment buttons and can be controlled from the express payment block in the editor. Supported values for these are one of `['height', 'borderRadius']`. | No |

#### The `canMakePayment` option

`canMakePayment` is a callback to determine whether the payment method should be available as an option for the shopper. The function will be passed an object containing data about the current order.

```ts
canMakePayment( {
	cart: Cart,
	cartTotals: CartTotals,
	cartNeedsShipping: boolean,
	shippingAddress: CartShippingAddress,
	billingAddress: CartBillingAddress,
	selectedShippingMethods: Record<string,unknown>,
	paymentRequirements: string[],
} )
```

`canMakePayment` returns a boolean value. If your gateway needs to perform async initialization to determine availability, you can return a promise (resolving to boolean). This allows a payment method to be hidden based on the cart, e.g. if the cart has physical/shippable products (example: [`Cash on delivery`](https://github.com/woocommerce/woocommerce/blob/df02d62e2d41e9007da44cb87fea2b7a9551f55c/plugins/woocommerce/client/blocks/assets/js/extensions/payment-methods/cod/index.js#L46-L73)); or for payment methods to control whether they are available depending on other conditions.

`canMakePayment` only runs on the frontend of the Store. In editor context, rather than use `canMakePayment`, the editor will assume the payment method is available (true) so that the defined `edit` component is shown to the merchant.

**Keep in mind this function could be invoked multiple times in the lifecycle of the checkout and thus any expensive logic in the callback provided on this property should be memoized.**

### Button Attributes for Express Payment Methods

This API provides a way to synchronise the look and feel of the express payment buttons for a coherent shopper experience. Express Payment Methods must prefer the values provided in the `buttonAttributes`, and use it's own configuration settings as backup when the buttons are rendered somewhere other than the Cart or Checkout block.

For example, in your button component, you would do something like this:

```js
// Get your extension specific settings and set defaults if not available
let {
	borderRadius = '4',
	height = '48',
} = getButtonSettingsFromConfig();

// In a cart & checkout block context, we receive `buttonAttributes` as a prop which overwrite the extension specific settings
if ( typeof buttonAttributes !== 'undefined' ) {
	height = buttonAttributes.height;
	borderRadius = buttonAttributes.borderRadius;
}
...

return <button style={height: `${height}px`, borderRadius: `${borderRadius}px`} />
```

## Payment Methods

Payment methods are the payment method options that are displayed in the checkout block. Examples include _cheque_, PayPal Standard, and Stripe Credit Card.

![Image 2021-02-24 at 4 24 05 PM](https://user-images.githubusercontent.com/1429108/109067640-c7073680-76bc-11eb-98e5-f04d35ddef99.jpg)

### Registration

To register a payment method, you use the `registerPaymentMethod` function from the blocks registry. 

```js
const { registerPaymentMethod } = window.wc.wcBlocksRegistry;
```

If you're using an aliased import for `@woocommerce/blocks-registry`, you can import the function like this:

```js
import { registerPaymentMethod } from '@woocommerce/blocks-registry';
```

The registry function expects a JavaScript object with options specific to the payment method:

```js
registerPaymentMethod( options );
```

The options you feed the configuration instance should be an object in this shape (see `PaymentMethodRegistrationOptions` typedef). The options you feed the configuration instance are the same as those for express payment methods with the following additions:

| Property | Type | Description |
| --- | --- | --- |
| `savedTokenComponent` | ReactNode | A React node that contains logic for handling saved payment methods. Rendered when a customer's saved token for this payment method is selected. |
| `label` | ReactNode | A React node used to output the label for the payment method option. This can be text or images. |
| `ariaLabel` | string | The label read by screen-readers when the payment method is selected. |
| `placeOrderButtonLabel` | string | Optional label to change the default "Place Order" button text when this payment method is selected. Mutually exclusive with `placeOrderButton`. |
| `placeOrderButton` | React Component | Optional React component to replace the default "Place Order" button when this payment method is selected. Mutually exclusive with `placeOrderButtonLabel`. The component receives `PaymentMethodInterface` props. |
| `supports` | object | Contains information about supported features: |
| `supports.showSavedCards` | boolean | Determines if saved cards for this payment method are shown to the customer. |
| `supports.showSaveOption` | boolean | Controls whether to show the checkbox for saving the payment method for future use. |

### Using Custom Place Order Button

The `placeOrderButton` property allows you to replace the default "Place Order" button with a custom component. This is useful for payment methods that require custom button styling (e.g., Google Pay, Apple Pay) or need to show a payment UI before submitting the order. If this doesn't apply to your payment method, omitting this property and using the default button is recommended.

Your custom button component receives all the same props as the payment method `content` component via the `PaymentMethodInterface`, plus additional button-specific props:

- `waitingForProcessing` - Whether the checkout is processing
- `waitingForRedirect` - Whether the checkout is waiting to redirect after success
- `disabled` - Whether the button should be disabled
- `isEditor` - Whether the button is being rendered in the block editor
- `isPreview` - Whether the button is being rendered in preview mode

Here's a simple example:

```js
const CustomButton = ( props ) => {
	const { validate, onSubmit, disabled, isEditor, isPreview, eventRegistration: { onPaymentSetup }, emitResponse } = props;

	const [
		isShowingInternalPaymentSheet,
		setIsShowingInternalPaymentSheet,
	] = React.useState( false );
  
  const paymentResultRef = React.useRef( false );

	const handleClick = async () => {
		// 1. Validate the checkout form
		const validationResult = await validate();

		if ( validationResult.hasError ) {
			return; // WooCommerce automatically displays validation errors
		}

		// 2. Show your payment UI (e.g., Google Pay sheet, Apple Pay sheet)
		// setIsShowingInternalPaymentSheet( true );
		// const paymentResult = await showPaymentSheet( billing.cartTotal.value );
    // paymentResultRef.current = paymentResult.success;
		// if ( ! paymentResult.success ) {
		//     setIsShowingInternalPaymentSheet( false );
		//     return;
		// }

		// 3. Submit the checkout to the server once all payment information has been collected.
		onSubmit();
	};

  React.useEffect(
    () =>
      onPaymentSetup( () => {
        return ({
          type: paymentResultRef.current ? emitResponse.responseTypes.SUCCESS : emitResponse.responseTypes.ERROR,
          meta: {
            paymentMethodData: {
              payment_method: 'your-payment-method',
            },
          },
        });
      } ),
    [ onPaymentSetup, emitResponse.responseTypes.SUCCESS, emitResponse.responseTypes.ERROR ]
  );

	// In editor/preview mode, show a placeholder or preview version
	if ( isEditor || isPreview ) {
		return (
			<button type="button" disabled>
				Pay with Custom Method (Preview)
			</button>
		);
	}

	return (
		<button
		  type="button"
			onClick={ handleClick }
			disabled={ disabled || isShowingInternalPaymentSheet }
		>
			{ disabled || isShowingInternalPaymentSheet
				? 'Processing...'
				: 'Pay with Custom Method' }
		</button>
	);
};

registerPaymentMethod( {
	name: 'my-custom-payment',
	label: <div>My Custom Payment</div>,
	content: <div>Payment method description</div>,
	edit: <div>Payment method description</div>,
	placeOrderButton: CustomButton,
	canMakePayment: () => true,
	supports: {
		features: [ 'products' ],
	},
} );
```

**Note:** The custom button is only shown when the payment method is selected from the list. When a saved payment token is selected, the default "Place Order" button is used instead.

## Props Fed to Payment Method Nodes

A big part of the payment method integration is the interface that is exposed for payment methods to use via props when the node provided is cloned and rendered on block mount. While all the props are listed below, you can find more details about what the props reference, their types etc via the [typedefs described in this file](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/types/type-defs/payment-method-interface.ts).

| Property | Type | Description |
| --- | --- | --- |
| `activePaymentMethod` | String | The slug of the current active payment method in the checkout. |
| `billing` | Object with billingAddress, cartTotal, currency, cartTotalItems, displayPricesIncludingTax, appliedCoupons, customerId properties | Contains everything related to billing. |
| `cartData` | Object with cartItems, cartFees, extensions properties | Data exposed from the cart including items, fees, and any registered extension data. Note that this data should be treated as immutable (should not be modified/mutated) or it will result in errors in your application. |
| `checkoutStatus` | Object with isCalculating, isComplete, isIdle, isProcessing properties | The current checkout status exposed as various boolean state. |
| `components` | Object with ValidationInputError, PaymentMethodLabel, PaymentMethodIcons, LoadingMask properties | It exposes React components that can be implemented by your payment method for various common interface elements used by payment methods. |
| `emitResponse` | Object with noticeContexts and responseTypes properties | Contains some constants that can be helpful when using the event emitter. Read the _[Emitting Events](./checkout-flow-and-events.md#emitting-events)_ section for more details. |
| `eventRegistration` | Object with onCheckoutValidation, onCheckoutSuccess, onCheckoutFail, onPaymentSetup, onShippingRateSuccess, onShippingRateFail, onShippingRateSelectSuccess, onShippingRateSelectFail properties | Contains all the checkout event emitter registration functions. These are functions the payment method can register observers on to interact with various points in the checkout flow (see [this doc](./checkout-flow-and-events.md) for more info). |
| `onClick` | Function | **Provided to express payment methods** that should be triggered when the payment method button is clicked (which will signal to checkout the payment method has taken over payment processing) |
| `onClose` | Function | **Provided to express payment methods** that should be triggered when the express payment method modal closes and control is returned to checkout. |
| `onSubmit` | Function | Submits the checkout and begins processing |
| `validate` | Function | Async function that validates the checkout form without submitting. Returns a promise resolving to `{ hasError: boolean }`. Useful when you need to validate before showing a payment sheet. |
| `buttonAttributes` | Object with height, borderRadius properties | Styles set by the merchant that should be respected by all express payment buttons |
| `paymentStatus` | Object | Various payment status helpers. Note, your payment method does not have to handle setting this status client side. Checkout will handle this via the responses your payment method gives from observers registered to [checkout event emitters](./checkout-flow-and-events.md). |
| `paymentStatus.isPristine` | Boolean | This is true when the current payment status is `PRISTINE`. |
| `paymentStatus.isStarted` | Boolean | This is true when the current payment status is `EXPRESS_STARTED`. |
| `paymentStatus.isProcessing` | Boolean | This is true when the current payment status is `PROCESSING`. |
| `paymentStatus.isFinished` | Boolean | This is true when the current payment status is one of `ERROR`, `FAILED`, or `SUCCESS`. |
| `paymentStatus.hasError` | Boolean | This is true when the current payment status is `ERROR`. |
| `paymentStatus.hasFailed` | Boolean | This is true when the current payment status is `FAILED`. |
| `paymentStatus.isSuccessful` | Boolean | This is true when the current payment status is `SUCCESS`. |
| `setExpressPaymentError` | Function | Receives a string and allows express payment methods to set an error notice for the express payment area on demand. This can be necessary because some express payment method processing might happen outside of checkout events. |
| `shippingData` | Object with shippingRates, shippingRatesLoading, selectedRates, setSelectedRates, isSelectingRate, shippingAddress, setShippingAddress, needsShipping properties | Contains all shipping related data (outside of the shipping status). |
| `shippingStatus` | Object with shippingErrorStatus, shippingErrorTypes properties | Various shipping status helpers. |
| `shouldSavePayment` | Boolean | Indicates whether or not the shopper has selected to save their payment method details (for payment methods that support saved payments). True if selected, false otherwise. Defaults to false. |

Any registered `savedTokenComponent` node will also receive a `token` prop which includes the id for the selected saved token in case your payment method needs to use it for some internal logic. However, keep in mind, this is just the id representing this token in the database (and the value of the radio input the shopper checked), not the actual customer payment token (since processing using that usually happens on the server for security).

## Server Side Integration

For the server side integration, you need to create a class that extends the `Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType` class. 

This class is the server side representation of your payment method. It is used to handle the registration of your payment methods assets with the Store API and Checkout block at the correct time. It is not the same as the [Payment Gateway API](/features/payments/payment-gateway-api.md) that you need to implement separately for payment processing.

### Example Payment Method Integration Class

```php
<?php
namespace MyPlugin\MyPaymentMethod;

use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;

final class MyPaymentMethodType extends AbstractPaymentMethodType {
	/**
	 * This property is a string used to reference your payment method. It is important to use the same name as in your
	 * client-side JavaScript payment method registration.
	 *
	 * @var string
	 */
	protected $name = 'my_payment_method';

	/**
	 * Initializes the payment method.
	 * 
	 * This function will get called during the server side initialization process and is a good place to put any settings
	 * population etc. Basically anything you need to do to initialize your gateway. 
	 * 
	 * Note, this will be called on every request so don't put anything expensive here.
	 */
	public function initialize() {
		$this->settings = get_option( 'woocommerce_my_payment_method_settings', [] );
	}

	/**
	 * This should return whether the payment method is active or not. 
	 * 
	 * If false, the scripts will not be enqueued.
	 *
	 * @return boolean
	 */
	public function is_active() {
		return filter_var( $this->get_setting( 'enabled', false ), FILTER_VALIDATE_BOOLEAN );
	}

	/**
	 * Returns an array of scripts/handles to be registered for this payment method.
	 * 
	 * In this function you should register your payment method scripts (using `wp_register_script`) and then return the 
	 * script handles you registered with. This will be used to add your payment method as a dependency of the checkout script 
	 * and thus take sure of loading it correctly. 
	 * 
	 * Note that you should still make sure any other asset dependencies your script has are registered properly here, if 
	 * you're using Webpack to build your assets, you may want to use the WooCommerce Webpack Dependency Extraction Plugin
	 * (https://www.npmjs.com/package/@woocommerce/dependency-extraction-webpack-plugin) to make this easier for you.
	 *
	 * @return array
	 */
	public function get_payment_method_script_handles() {
		wp_register_script(
			'my-payment-method',
			'path/to/your/script/my-payment-method.js',
			[],
			'1.0.0',
			true
		);
		return [ 'my-payment-method' ];
	}

	/**
	 * Returns an array of script handles to be enqueued for the admin.
	 * 
	 * Include this if your payment method has a script you _only_ want to load in the editor context for the checkout block. 
	 * Include here any script from `get_payment_method_script_handles` that is also needed in the admin.
	 */
	public function get_payment_method_script_handles_for_admin() {
		return $this->get_payment_method_script_handles();
	}

	/**
	 * Returns an array of key=>value pairs of data made available to the payment methods script client side.
	 * 
	 * This data will be available client side via `wc.wcSettings.getSetting`. So for instance if you assigned `stripe` as the 
	 * value of the `name` property for this class, client side you can access any data via: 
	 * `wc.wcSettings.getSetting( 'stripe_data' )`. That would return an object matching the shape of the associative array 
	 * you returned from this function.
	 *
	 * @return array
	 */
	public function get_payment_method_data() {
		return [
			'title'       => $this->get_setting( 'title' ),
			'description' => $this->get_setting( 'description' ),
			'supports'    => $this->get_supported_features(),
		];
	}
}
```

### Registering the Payment Method Integration

After creating a class that extends `Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType`, you need to register it with the server side handling of payment methods. 

You can do this by using the `register` method on the `PaymentMethodRegistry` class. 

```php
use MyPlugin\MyPaymentMethod\MyPaymentMethodType;
use Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry;

add_action(
	'woocommerce_blocks_payment_method_type_registration',
	function( PaymentMethodRegistry $payment_method_registry ) {
		$payment_method_registry->register( new MyPaymentMethodType() );
	}
);
```

## Processing Payments (legacy support)

Payments are still handled via the [Payment Gateway API](/features/payments/payment-gateway-api.md). This is a separate API from the one used for the payment methods integration above.

The checkout block converts incoming `payment_data` provided by the client-side script to `$_POST` and calls the Payment Gateway `process_payment` method. 

_If you already have a WooCommerce Payment method extension integrated with the shortcode checkout flow, the legacy handling will take care of processing your payment for you on the server side._

## Processing Payments via the Store API

There may be more advanced cases where the legacy payment processing mentioned earlier doesn't work for your existing payment method integration. For these cases, there is also an action hook you can use to handle the server side processing of the order which provides more context and is specific to the Store API.

This hook is the _preferred_ place to hook in your payment processing:

```php
do_action_ref_array( 'woocommerce_rest_checkout_process_payment_with_context', [ $context, &$result ] );
```

> Note: A good place to register your callback on this hook is in the `initialize` method of the payment method type class you created earlier

A callback on this hook will receive:

- A `PaymentContext` object which contains the chosen `payment_method` (this is the same as the `paymentMethodId` value defined when registering your payment method), the `order` being placed, and any additional `payment_data` provided by the payment method client.
- A `PaymentResult` object which you can use to set the status, redirect url, and any additional payment details back to the client via the Store API.

If you set a status on the provided `PaymentResult` object, legacy payment processing will be ignored for your payment method. If there is an error, your callback can throw an exception which will be handled by the Store API. 

Here is an example callback:

```php
add_action(
	'woocommerce_rest_checkout_process_payment_with_context',
	function( $context, $result ) {
		if ( $context->payment_method === 'my_payment_method' ) {
			// Order processing would happen here!
			// $context->order contains the order object if needed
			// ...

			// If the logic above was successful, we can set the status to success.
			$result->set_status( 'success' );
			$result->set_payment_details(
				array_merge(
					$result->payment_details,
					[
						'custom-data' => '12345',
					]
				)
			);
			$result->set_redirect_url( 'some/url/to/redirect/to' );
		}
	},
  10,
  2
);
```

## Passing values from the client to the server side payment processing

In this example, lets pass some data from the BACS payment method to the server. Registration of BACS looks something like this:

```js
// Get our settings that were provided when the payment method was registered
const settings = window.wc.wcSettings.getSetting( 'bacs_data' );

// This is a component that would be rendered in the checkout block when the BACS payment method is selected
const Content = () => {
	return decodeEntities( settings?.description || '' );
};

// This is the label for the payment method
const Label = ( props ) => {
	const { PaymentMethodLabel } = props.components;
	return <PaymentMethodLabel text={ decodeEntities( settings?.title || 'BACS' ) } />;
};

// Register the payment method
const bankTransferPaymentMethod = {
	name: 'BACS',
	label: <Label />,
	content: <Content />,
	edit: <Content />,
	canMakePayment: () => true,
	supports: {
		features: settings?.supports ?? [],
	},
};
```

Payment method nodes are passed everything from the [usePaymentMethodInterface hook](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/internal-developers/block-client-apis/checkout/checkout-api.md#usepaymentmethodinterface). So we can consume this in our `<Content />` component like this:

```js
const Content = ( props ) => {
	const { eventRegistration, emitResponse } = props;
	const { onPaymentProcessing } = eventRegistration;
	useEffect( () => {
		const unsubscribe = onPaymentProcessing( async () => {
			// Here we can do any processing we need, and then emit a response.
			// For example, we might validate a custom field, or perform an AJAX request, and then emit a response indicating it is valid or not.
			const myGatewayCustomData = '12345';
			const customDataIsValid = !! myGatewayCustomData.length;

			if ( customDataIsValid ) {
				return {
					type: emitResponse.responseTypes.SUCCESS,
					meta: {
						paymentMethodData: {
							myGatewayCustomData,
						},
					},
				};
			}

			return {
				type: emitResponse.responseTypes.ERROR,
				message: 'There was an error',
			};
		} );
		// Unsubscribes when this component is unmounted.
		return () => {
			unsubscribe();
		};
	}, [
		emitResponse.responseTypes.ERROR,
		emitResponse.responseTypes.SUCCESS,
		onPaymentProcessing,
	] );
	return decodeEntities( settings.description || '' );
};
```

Now when an order is placed, if we look at the API request payload, we can see the following JSON:

```json
{
	"shipping_address": {},
	"billing_address": {},
	"customer_note": "",
	"create_account": false,
	"payment_method": "bacs",
	"payment_data": [
		{
			"key": "myGatewayCustomData",
			"value": "12345"
		}
	],
	"extensions": {}
}
```

A callback on `woocommerce_rest_checkout_process_payment_with_context` can then access this data and use it to process the payment.

```php
add_action( 'woocommerce_rest_checkout_process_payment_with_context', function( $context, $result ) {
  if ( $context->payment_method === 'bacs' ) {
    $myGatewayCustomData = $context->payment_data['myGatewayCustomData'];
    // Here we would use the $myGatewayCustomData to process the payment


---

## Checkout Utilities

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/checkout-utilities.md*

# Checkout Utilities

Utility functions and React hooks for checkout functionality, available from `@woocommerce/blocks-checkout`.

## `useValidateCheckout`

A hook that validates the checkout form and automatically scrolls to the first validation error if any are found.

This hook is primarily used internally by the `PlaceOrderButton` component to provide the `validate` prop to custom place order button components. However, it can also be used directly if needed.

### Usage

```jsx
// Aliased import
import { useValidateCheckout } from '@woocommerce/blocks-checkout';

// Global import
// const { useValidateCheckout } = wc.blocksCheckout;

const MyComponent = () => {
    const validateCheckout = useValidateCheckout();

    const handleClick = async () => {
        const { hasError } = await validateCheckout();

        if ( hasError ) {
            // Validation failed - errors are automatically shown and
            // the page scrolls to the first error
            return;
        }

        // Validation passed - proceed with your logic
    };

    return <button onClick={ handleClick }>Validate</button>;
};
```

### Return Value

The hook returns a function that, when called:

1. Emits the `CHECKOUT_VALIDATION` event to run all registered validation callbacks
2. Checks the validation store for any field-level validation errors
3. If errors are found:
    - Shows all validation errors
    - Scrolls to and focuses the first error element
4. Returns a promise that resolves to `{ hasError: boolean }`

| Property   | Type      | Description                                      |
|:-----------|:----------|:-------------------------------------------------|
| `hasError` | `boolean` | `true` if validation failed, `false` if passed.  |


---

## DOM events

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/dom-events.md*

# DOM events

Some blocks need to react to certain events in order to display the most up to date data or behave in a certain way. That's the case of the Cart block, for example, that must listen to 'add to cart' events in order to update the cart contents; or the Mini-Cart block, that gets opened every time a product is added to the cart.

## WooCommerce core events in WooCommerce Blocks

WooCommerce core uses jQuery events to trigger and listen to certain events, like when a product is added or removed from the cart. In WooCommerce Blocks, we moved away from using jQuery, but we still need to listen to those events. To achieve that, we have a utility named [`translatejQueryEventToNative()`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/assets/js/base/utils/legacy-events.ts) that listens to those jQuery events, and every time one is triggered, it triggers an associated DOM native event (with the `wc-blocks_` prefix).

## WooCommerce Blocks events

### `wc-blocks_adding_to_cart`

This event is the equivalent to the jQuery event `adding_to_cart` triggered by WooCommerce core. It indicates that the process of adding a product to the cart was sent to the server, but there is still no indication on whether the product was successfully added or not.

_Example usage in WC Blocks:_ Mini-Cart block listens to this event to append its dependencies.

### `wc-blocks_added_to_cart`

This event is the equivalent to the jQuery event `added_to_cart` triggered by WooCommerce core. It indicates that the process of adding a product to the cart has finished with success.

_Example usage in WC Blocks:_ Cart and Mini-Cart blocks (via the `useStoreCart()` hook) listen to this event to know if they need to update their contents.

#### `detail` parameters

| Parameter          | Type    | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preserveCartData` | boolean | `false`       | Whether Cart data in the store should be preserved. By default, it's `false` so any `wc-blocks_added_to_cart` event will invalidate cart data and blocks listening to it will refetch cart data again. However, if the code triggering the event already updates the store (ie: All Products block), it can set `preserveCartData: true` to avoid the other blocks refetching the data again. |

### `wc-blocks_removed_from_cart`

This event is the equivalent to the jQuery event `removed_from_cart` triggered by WooCommerce core. It indicates that a product has been removed from the cart.

_Example usage in WC Blocks:_ Cart and Mini-Cart blocks (via the `useStoreCart()` hook) listen to this event to know if they need to update their contents.


---

## Available Filters

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/README.md*

# Available Filters

This document lists the filters that are currently available to extensions and offers usage information for each one of them. Information on registering filters can be found on the [Checkout - Filter Registry](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/filter-registry/README.md) page.

## Cart Line Items filters

The following [Cart Line Items filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/cart-line-items/) are available:

-   `cartItemClass`
-   `cartItemPrice`
-   `itemName`
-   `saleBadgePriceFormat`
-   `showRemoveItemLink`
-   `subtotalPriceFormat`

The following screenshot shows which parts the individual filters affect:

![Cart Line Items](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-26-at-13.12.33.png)

## Order Summary Items filters

The following [Order Summary Items filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/order-summary-items/) are available:

-   `cartItemClass`
-   `cartItemPrice`
-   `cartItemScreenReaderPrice`
-   `itemName`
-   `subtotalPriceFormat`

The following screenshot shows which parts the individual filters affect:

![Order Summary Items](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-26-at-16.29.45.png)

## Totals Footer Item filter

The following [Totals Footer Item filter](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/totals-footer-item/) is available:

-   `totalLabel`
-   `totalValue`

## Checkout and place order button filters

The following [Checkout and place order button filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/checkout-and-place-order-button/) are available:

-   `proceedToCheckoutButtonLabel`
-   `proceedToCheckoutButtonLink`
-   `placeOrderButtonLabel`

## Coupon filters

The following [Coupon filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/coupons/) are available:

-   `coupons`
-   `showApplyCouponNotice`
-   `showRemoveCouponNotice`

## Additional Cart and Checkout inner block types filter

The following [Additional Cart and Checkout inner block types filter](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/additional-cart-checkout-inner-block-types/) is available:

-   `additionalCartCheckoutInnerBlockTypes`

## Combined filters

Filters can also be combined. The following example shows how to combine some of the available filters.

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const isOrderSummaryContext = ( args ) => args?.context === 'summary';

const modifyCartItemClass = ( defaultValue, extensions, args ) => {
	if ( isOrderSummaryContext( args ) ) {
		return 'my-custom-class';
	}
	return defaultValue;
};

const modifyCartItemPrice = ( defaultValue, extensions, args ) => {
	if ( isOrderSummaryContext( args ) ) {
		return '<price/> for all items';
	}
	return defaultValue;
};

const modifyItemName = ( defaultValue, extensions, args ) => {
	if ( isOrderSummaryContext( args ) ) {
		return `${ defaultValue }`;
	}
	return defaultValue;
};

const modifySubtotalPriceFormat = ( defaultValue, extensions, args ) => {
	if ( isOrderSummaryContext( args ) ) {
		return '<price/> per item';
	}
	return defaultValue;
};

registerCheckoutFilters( 'example-extension', {
	cartItemClass: modifyCartItemClass,
	cartItemPrice: modifyCartItemPrice,
	itemName: modifyItemName,
	subtotalPriceFormat: modifySubtotalPriceFormat,
} );
```

## Troubleshooting

If you are logged in to the store as an administrator, you should be shown an error like this if your filter is not
working correctly. The error will also be shown in your console.

![Troubleshooting](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-30-at-10.52.53.png)


---

## Inner block types

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/additional-cart-checkout-inner-block-types.md*

# Inner block types

The following Additional Cart and Checkout inner block types filter is available:

-   `additionalCartCheckoutInnerBlockTypes`

## `additionalCartCheckoutInnerBlockTypes`

### Description

The Cart and Checkout blocks are made up of inner blocks. These inner blocks areas allow certain block types to be added as children. By default, only `core/paragraph`, `core/image`, and `core/separator` are available to add.

By using the `additionalCartCheckoutInnerBlockTypes` filter it is possible to add items to this array to control what the editor can into an inner block.

This filter is called once for each inner block area, so it is possible to be very granular when determining what blocks can be added where.

### Parameters

-   _defaultValue_ `array` (default: `[]`) - The default value of the filter.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following key:
    -   _block_ `string` - The block name of the inner block area, e.g. `woocommerce/checkout-shipping-address-block`.
-   _validation_ `boolean` or `Error` - Checks if the returned value is an array of strings. If an error occurs, it will be thrown.

### Returns

-   `array` - The modified array with allowed block types for the corresponding inner block area.

### Code example

Let's suppose we want to allow the editor to add some blocks in specific places in the Cart and Checkout blocks.

1. Allow `core/quote` to be inserted in every block area in the Cart and Checkout blocks.
2. Allow `core/table` to be inserted in the Shipping Address block in the Checkout.

In our extension we could register a filter satisfy both of these conditions like so:

```tsx
document.addEventListener( 'DOMContentLoaded', function () {
	const { registerCheckoutFilters } = window.wc.blocksCheckout;

	const modifyAdditionalInnerBlockTypes = (
		defaultValue,
		extensions,
		args,
		validation
	) => {
		defaultValue.push( 'core/quote' );

		if ( args?.block === 'woocommerce/checkout-shipping-address-block' ) {
			defaultValue.push( 'core/table' );
		}

		return defaultValue;
	};

	registerCheckoutFilters( 'example-extension', {
		additionalCartCheckoutInnerBlockTypes: modifyAdditionalInnerBlockTypes,
	} );
} );
```

To call this filter within the editor, wrap the filter registration in a `DOMContentLoaded` event listener and ensure the code runs in the admin panel.

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots

| Before                                                                 | After                                                                 |
|:---------------------------------------------------------------------:|:---------------------------------------------------------------------:|
|![Before applying the Additional Cart and Checkout inner block types filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/0d4560c8-c2b1-4ed8-8aee-469b248ccb08) |![After applying the Additional Cart and Checkout inner block types filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/d38cd568-6c8c-4158-9269-d8dffdf66988) |


---

## Cart line items

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/cart-line-items.md*

# Cart line items

The following Cart Line Items filters are available:

-   `cartItemClass`
-   `cartItemPrice`
-   `itemName`
-   `saleBadgePriceFormat`
-   `showRemoveItemLink`
-   `subtotalPriceFormat`

The following objects are shared between the filters:

-   Cart object
-   Cart Item object

The following screenshot shows which parts the individual filters affect:

![Cart Line Items](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-26-at-13.12.33.png)

## `cartItemClass`

### Description {/* omit in toc */}

The `cartItemClass` filter allows to change the cart item class.

### Parameters {/* omit in toc */}

-   _defaultValue_ `object` (default: `''`) - The default cart item class.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see Cart object.
    -   _cartItem_ `object` - The cart item object from `wc/store/cart`, see Cart Item object.
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.

### Returns {/* omit in toc */}

-   `string` - The modified cart item class, or an empty string.

### Code examples {/* omit in toc */}

#### Basic example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCartItemClass = ( defaultValue, extensions, args ) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	return 'my-custom-class';
};

registerCheckoutFilters( 'example-extension', {
	cartItemClass: modifyCartItemClass,
} );
```

#### Advanced example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCartItemClass = ( defaultValue, extensions, args ) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return 'cool-class';
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return 'hot-class';
	}

	return 'my-custom-class';
};

registerCheckoutFilters( 'example-extension', {
	cartItemClass: modifyCartItemClass,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots {/* omit in toc */}

| Before | After |
| --- | --- |
| ![Before applying the Cart Item Class filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/a587a6ce-d051-4ed0-bba5-815b5d72179d) | ![After applying the Cart Item Class filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/9b25eeae-6d81-4e28-b177-32f942e1d0c2) |


## `cartItemPrice`

### Description {/* omit in toc */}

The `cartItemPrice` filter allows to format the cart item price.

### Parameters {/* omit in toc */}

-   _defaultValue_ `string` (default: `<price/>`) - The default cart item price.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see Cart object.
    -   _cartItem_ `object` - The cart item object from `wc/store/cart`, see Cart Item object.
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.
-   _validation_ `boolean` - Checks if the return value contains the substring `<price/>`.

### Returns {/* omit in toc */}

-   `string` - The modified format of the cart item price, which must contain the substring `<price/>`, or the original price format.

### Code examples {/* omit in toc */}

#### Basic example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCartItemPrice = ( defaultValue, extensions, args, validation ) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	return '<price/> for all items';
};

registerCheckoutFilters( 'example-extension', {
	cartItemPrice: modifyCartItemPrice,
} );
```

#### Advanced example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCartItemPrice = ( defaultValue, extensions, args, validation ) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return '<price/> to keep you warm';
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return '<price/> to keep you cool';
	}

	return '<price/> for all items';
};

registerCheckoutFilters( 'example-extension', {
	cartItemPrice: modifyCartItemPrice,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots {/* omit in toc */}

| Before | After |
| --- | --- |
| ![Before applying the Cart Item Price filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/bbaeb68a-492e-41e7-87b7-4b8b05ca3709) | ![After applying the Cart Item Price filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/bbaeb68a-492e-41e7-87b7-4b8b05ca3709) |

## `itemName`

### Description {/* omit in toc */}

The `itemName` filter allows to change the cart item name.

### Parameters {/* omit in toc */}

-   _defaultValue_ `string` - The default cart item name.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see Cart object.
    -   _cartItem_ `object` - The cart item object from `wc/store/cart`, see Cart Item object.
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.

### Returns {/* omit in toc */}

-   `string` - The original or modified cart item name.

### Code examples {/* omit in toc */}

#### Basic example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyItemName = ( defaultValue, extensions, args ) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	return `🪴 ${ defaultValue } 🪴`;
};

registerCheckoutFilters( 'example-extension', {
	itemName: modifyItemName,
} );
```

#### Advanced example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyItemName = ( defaultValue, extensions, args ) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return `⛷️ ${ defaultValue } ⛷️`;
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return `🏄‍♂️ ${ defaultValue } 🏄‍♂️`;
	}

	return `🪴 ${ defaultValue } 🪴`;
};

registerCheckoutFilters( 'example-extension', {
	itemName: modifyItemName,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots {/* omit in toc */}

| Before | After |
| --- | --- |
| ![Before applying the Item Name filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/97d0f501-138e-4448-93df-a4d865b524e6) | ![After applying the Item Name filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/69381932-d064-4e8f-b378-c2477fef56ae) |

## `saleBadgePriceFormat`

### Description {/* omit in toc */}

The `saleBadgePriceFormat` filter allows to format the cart item sale badge price.

### Parameters {/* omit in toc */}

-   _defaultValue_ `string` (default: `<price/>`) - The default cart item sale badge price.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see Cart object.
    -   _cartItem_ `object` - The cart item object from `wc/store/cart`, see Cart Item object.
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.
-   _validation_ `boolean` - Checks if the return value contains the substring `<price/>`.

### Returns {/* omit in toc */}

-   `string` - The modified format of the cart item sale badge price, which must contain the substring `<price/>`, or the original price format.

### Code examples {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifySaleBadgePriceFormat = (
	defaultValue,
	extensions,
	args,
	validation
) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	return '<price/> per item';
};

registerCheckoutFilters( 'example-extension', {
	saleBadgePriceFormat: modifySaleBadgePriceFormat,
} );
```

#### Advanced example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifySaleBadgePriceFormat = (
	defaultValue,
	extensions,
	args,
	validation
) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return '<price/> per item while keeping warm';
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return '<price/> per item while looking cool';
	}

	return '<price/> per item';
};

registerCheckoutFilters( 'example-extension', {
	saleBadgePriceFormat: modifySaleBadgePriceFormat,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots {/* omit in toc */}

| Before | After |
| --- | --- |
| ![Before applying the Sale Badge Price Format filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/d2aeb206-e620-44e0-93c1-31484cfcdca6) | ![After applying the Sale Badge Price Format filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/6b929695-5d89-433b-8694-b9201a7c0519) |


## `showRemoveItemLink`

### Description {/* omit in toc */}

The `showRemoveItemLink` is used to show or hide the cart item remove link.

### Parameters {/* omit in toc */}

-   _defaultValue_ (type: `boolean`, default: `true`) - The default value of the remove link.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see Cart object.
    -   _cartItem_ `object` - The cart item object from `wc/store/cart`, see Cart Item object.
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.

### Returns {/* omit in toc */}

-   `boolean` - `true` if the cart item remove link should be shown, `false` otherwise.

### Code examples {/* omit in toc */}

#### Basic example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyShowRemoveItemLink = ( defaultValue, extensions, args ) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	return false;
};

registerCheckoutFilters( 'example-extension', {
	showRemoveItemLink: modifyShowRemoveItemLink,
} );
```

#### Advanced example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyShowRemoveItemLink = ( defaultValue, extensions, args ) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return false;
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return false;
	}

	return true;
};

registerCheckoutFilters( 'example-extension', {
	showRemoveItemLink: modifyShowRemoveItemLink,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots {/* omit in toc */}

| Before | After |
| --- | --- |
| ![Before applying the Show Remove Item Link filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/a4254f3b-f056-47ad-b34a-d5f6d5500e56) | ![After applying the Show Remove Item Link filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/32c55dc7-ef65-4f35-ab90-9533bc79d362) |



## `subtotalPriceFormat`

### Description {/* omit in toc */}

The `subtotalPriceFormat` filter allows to format the cart item subtotal price.

### Parameters {/* omit in toc */}

-   _defaultValue_ `string` (default: `<price/>`) - The default cart item subtotal price.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see Cart object.
    -   _cartItem_ `object` - The cart item object from `wc/store/cart`, see Cart Item object.
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.
-   _validation_ `boolean` - Checks if the return value contains the substring `<price/>`.

### Returns {/* omit in toc */}

-   `string` - The modified format of the cart item subtotal price, which must contain the substring `<price/>`, or the original price format.

### Code examples {/* omit in toc */}

#### Basic example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifySubtotalPriceFormat = (
	defaultValue,
	extensions,
	args,
	validation
) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	return '<price/> per item';
};

registerCheckoutFilters( 'example-extension', {
	subtotalPriceFormat: modifySubtotalPriceFormat,
} );
```

#### Advanced example {/* omit in toc */}

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifySubtotalPriceFormat = (
	defaultValue,
	extensions,
	args,
	validation
) => {
	const isCartContext = args?.context === 'cart';

	if ( ! isCartContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return '<price/> per warm beanie';
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return '<price/> per cool sunglasses';
	}

	return '<price/> per item';
};

registerCheckoutFilters( 'example-extension', {
	subtotalPriceFormat: modifySubtotalPriceFormat,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots {/* omit in toc */}

| Before | After |
| --- | --- |
| ![Before applying the Subtotal Price Format filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/a392cb24-4c40-4e25-8396-bf4971830e22) | ![After applying the Subtotal Price Format filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/af69b26f-662a-4ef9-a288-3713b6e46373) |

## Cart object

The Cart object of the filters above has the following keys:

-   _billingAddress_ `object` - The billing address object with the following keys:
    -   _address_1_ `string` - The first line of the address.
    -   _address_2_ `string` - The second line of the address.
    -   _city_ `string` - The city of the address.
    -   _company_ `string` - The company of the address.
    -   _country_ `string` - The country of the address.
    -   _email_ `string` - The email of the address.
    -   _first_name_ `string` - The first name of the address.
    -   _last_name_ `string` - The last name of the address.
    -   _phone_ `string` - The phone of the address.
    -   _postcode_ `string` - The postcode of the address.
    -   _state_ `string` - The state of the address.
-   ~~_billingData_~~ `object` - The billing data object with the same keys as the `billingAddress` object.
-   _cartCoupons_ `array` - The cart coupons array.
-   _cartErrors_ `array` - The cart errors array.
-   _cartFees_ `array` - The cart fees array.
-   _cartHasCalculatedShipping_ `boolean` - Whether the cart has calculated shipping.
-   _cartIsLoading_ `boolean` - Whether the cart is loading.
-   _cartItemErrors_ `array` - The cart item errors array.
-   _cartItems_ `array` - The cart items array with cart item objects, see Cart Item object.
-   _cartItemsCount_ `number` - The cart items count.
-   _cartItemsWeight_ `number` - The cart items weight.
-   _cartNeedsPayment_ `boolean` - Whether the cart needs payment.
-   _cartNeedsShipping_ `boolean` - Whether the cart needs shipping.
-   _cartTotals_ `object` - The cart totals object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _tax_lines_ `array` - The tax lines array with tax line objects with the following keys:
        -   _name_ `string` - The name of the tax line.
        -   _price_ `number` - The price of the tax line.
        -   _rate_ `string` - The rate ID of the tax line.
    -   _total_discount_ `string` - The total discount.
    -   _total_discount_tax_ `string` - The total discount tax.
    -   _total_fees_ `string` - The total fees.
    -   _total_fees_tax_ `string` - The total fees tax.
    -   _total_items_ `string` - The total items.
    -   _total_items_tax_ `string` - The total items tax.
    -   _total_price_ `string` - The total price.
    -   _total_shipping_ `string` - The total shipping.
    -   _total_shipping_tax_ `string` - The total shipping tax.
    -   _total_tax_ `string` - The total tax.
-   _crossSellsProducts_ `array` - The cross sells products array with cross sells product objects.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _isLoadingRates_ `boolean` - Whether the cart is loading shipping rates.
-   _paymentRequirements_ `array` - The payment requirements array.
-   _shippingAddress_ `object` - The shipping address object with the same keys as the `billingAddress` object.
-   _shippingRates_ `array` - The shipping rates array.

## Cart Item object

The Cart Item object of the filters above has the following keys:

-   _backorders_allowed_ `boolean` - Whether backorders are allowed.
-   _catalog_visibility_ `string` - The catalog visibility.
-   _description_ `string` - The cart item description.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _id_ `number` - The item ID.
-   _images_ `array` - The item images array.
-   _item_data_ `array` - The item data array.
-   _key_ `string` - The item key.
-   _low_stock_remaining_ `number` - The low stock remaining.
-   _name_ `string` - The item name.
-   _permalink_ `string` - The item permalink.
-   _prices_ `object` - The item prices object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _price_ `string` - The price.
    -   _price_range_ `string` - The price range.
    -   _raw_prices_ `object` - The raw prices object with the following keys:
        -   _precision_ `number` - The precision.
        -   _price_ `number` - The price.
        -   _regular_price_ `number` - The regular price.
        -   _sale_price_ `number` - The sale price.
    -   _regular_price_ `string` - The regular price.
    -   _sale_price_ `string` - The sale price.
-   _quantity_ `number` - The item quantity.
-   _quantity_limits_ `object` - The item quantity limits object with the following keys:
    -   _editable_ `boolean` - Whether the quantity is editable.
    -   _maximum_ `number` - The maximum quantity.
    -   _minimum_ `number` - The minimum quantity.
    -   _multiple_of_ `number` - The multiple of quantity.
-   _short_description_ `string` - The item short description.
-   _show_backorder_badge_ `boolean` - Whether to show the backorder badge.
-   _sku_ `string` - The item SKU.
-   _sold_individually_ `boolean` - Whether the item is sold individually.
-   _totals_ `object` - The item totals object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _line_subtotal_ `string` - The line subtotal.
    -   _line_subtotal_tax_ `string` - The line subtotal tax.
    -   _line_total_ `string` - The line total.
    -   _line_total_tax_ `string` - The line total tax.
-   _type_ `string` - The item type.
-   _variation_ `array` - The item variation array.


---

## Checkout and place order button

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/checkout-and-place-order-button.md*

# Checkout and place order button

The following Checkout and place order button filters are available:

-   `proceedToCheckoutButtonLabel`
-   `proceedToCheckoutButtonLink`
-   `placeOrderButtonLabel`

The following objects are shared between the filters:

-   Cart object
-   Cart Item object

## `proceedToCheckoutButtonLabel`

### Description 

The `proceedToCheckoutButtonLabel` filter allows change the label of the "Proceed to checkout" button.

### Parameters 

-   _defaultValue_ `string` (default: `Proceed to Checkout`) - The label of the "Proceed to checkout" button.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](#cart-object).

### Returns 

-   `string` - The label of the "Proceed to checkout" button.

### Code examples 

#### Basic example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyProceedToCheckoutButtonLabel = (
	defaultValue,
	extensions,
	args
) => {
	if ( ! args?.cart.items ) {
		return defaultValue;
	}

	return 'Go to checkout';
};

registerCheckoutFilters( 'example-extension', {
	proceedToCheckoutButtonLabel: modifyProceedToCheckoutButtonLabel,
} );
```

#### Advanced example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyProceedToCheckoutButtonLabel = (
	defaultValue,
	extensions,
	args
) => {
	if ( ! args?.cart.items ) {
		return defaultValue;
	}

	const isSunglassesInCart = args?.cart.items.some(
		( item ) => item.name === 'Sunglasses'
	);

	if ( isSunglassesInCart ) {
		return '😎 Proceed to checkout 😎';
	}

	return defaultValue;
};

registerCheckoutFilters( 'example-extension', {
	proceedToCheckoutButtonLabel: modifyProceedToCheckoutButtonLabel,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots 

| Before | After |
| --- | --- |
| ![Before applying the Proceed To Checkout Button Label filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/fb0216c1-a091-4d58-b443-f49ccff98ed8) | ![After applying the Item Name filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/ef15b6df-fbd7-43e7-a359-b4adfbba961a) |

## `proceedToCheckoutButtonLink`

### Description 

The `proceedToCheckoutButtonLink` filter allows change the link of the "Proceed to checkout" button.

### Parameters 

-   _defaultValue_ `string` (default: `/checkout`) - The link of the "Proceed to checkout" button.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/).

### Returns 

-   `string` - The link of the "Proceed to checkout" button.

### Code examples 

#### Basic example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyProceedToCheckoutButtonLink = (
	defaultValue,
	extensions,
	args
) => {
	if ( ! args?.cart.items ) {
		return defaultValue;
	}

	return '/custom-checkout';
};

registerCheckoutFilters( 'example-extension', {
	proceedToCheckoutButtonLink: modifyProceedToCheckoutButtonLink,
} );
```

#### Advanced example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyProceedToCheckoutButtonLink = (
	defaultValue,
	extensions,
	args
) => {
	if ( ! args?.cart.items ) {
		return defaultValue;
	}

	const isSunglassesInCart = args?.cart.items.some(
		( item ) => item.name === 'Sunglasses'
	);

	if ( isSunglassesInCart ) {
		return '/custom-checkout';
	}

	return defaultValue;
};

registerCheckoutFilters( 'example-extension', {
	proceedToCheckoutButtonLink: modifyProceedToCheckoutButtonLink,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots 

| Before | After |
| --- | --- |
| ![Before applying the Proceed To Checkout Button Link filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/3f657e0f-4fcc-4746-a554-64221e071b2e) | ![After applying the Proceed To Checkout Button Link filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/064df213-439e-4d8f-b29c-55962604cb97) |

## `placeOrderButtonLabel`

### Description 

The `placeOrderButtonLabel` filter allows change the label of the "Place order" button.

### Parameters 

-   _defaultValue_ (type: `string`, default: `Place order`) - The label of the "Place order" button.
-   _extensions_ `object` (default: `{}`) - The extensions object.

### Returns 

-   `string` - The label of the "Place order" button.

### Code example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyPlaceOrderButtonLabel = ( defaultValue, extensions ) => {
	return '😎 Pay now 😎';
};

registerCheckoutFilters( 'example-extension', {
	placeOrderButtonLabel: modifyPlaceOrderButtonLabel,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots 

| Before | After |
| --- | --- |
| ![Before applying the Place Order Button Label filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/aa6d9b65-4d56-45f7-8162-a6bbfe171250) | ![After applying the Place Order Button Label filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/a5cc2572-16e7-4781-a5ab-5d6cdced2ff6) |

{/* FEEDBACK */}

## Cart object

The Cart object of the filters above has the following keys:

-   _billingAddress_ `object` - The billing address object with the following keys:
    -   _address_1_ `string` - The first line of the address.
    -   _address_2_ `string` - The second line of the address.
    -   _city_ `string` - The city of the address.
    -   _company_ `string` - The company of the address.
    -   _country_ `string` - The country of the address.
    -   _email_ `string` - The email of the address.
    -   _first_name_ `string` - The first name of the address.
    -   _last_name_ `string` - The last name of the address.
    -   _phone_ `string` - The phone of the address.
    -   _postcode_ `string` - The postcode of the address.
    -   _state_ `string` - The state of the address.
-   _coupons_ `array` - The coupons array.
-   _crossSells_ `array` - The cross sell items array.
-   _errors_ `array` - The errors array.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _fees_ `array` - The fees array.
-   _hasCalculatedShipping_ `boolean` - Whether the cart has calculated shipping.
-   _items_ `array` - The cart items array with cart item objects, see [Cart Item object](#cart-item-object).
-   _itemsCount_ `number` - The number of items in the cart.
-   _itemsWeight_ `number` - The total weight of the cart items.
-   _needsPayment_ `boolean` - Whether the cart needs payment.
-   _needsShipping_ `boolean` - Whether the cart needs shipping.
-   _paymentMethods_ `array` - The payment methods array.
-   _paymentRequirements_ `array` - The payment requirements array.
-   _shippingAddress_ `object` - The shipping address object with the same keys as the billing address object.
-   _shippingRates_ `array` - The shipping rates array.
-   _totals_ `object` - The totals object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _tax_lines_ `array` - The tax lines array of objects with the following keys:
        -   _name_ `string` - The tax name.
        -   _price_ `string` - The tax price.
        -   _rate_ `string` - The tax rate.
    -   _total_discount_ `string` - The total discount.
    -   _total_discount_tax_ `string` - The total discount tax.
    -   _total_fee_ `string` - The total fee.
    -   _total_fee_tax_ `string` - The total fee tax.
    -   _total_items_ `string` - The total items.
    -   _total_items_tax_ `string` - The total items tax.
    -   _total_price_ `string` - The total price.
    -   _total_shipping_ `string` - The total shipping.
    -   _total_shipping_tax_ `string` - The total shipping tax.
    -   _total_tax_ `string` - The total tax.

## Cart Item object

The Cart Item object of the filters above has the following keys:

-   _backorders_allowed_ `boolean` - Whether backorders are allowed.
-   _catalog_visibility_ `string` - The catalog visibility.
-   _description_ `string` - The cart item description.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _id_ `number` - The item ID.
-   _images_ `array` - The item images array.
-   _item_data_ `array` - The item data array.
-   _key_ `string` - The item key.
-   _low_stock_remaining_ `number` - The low stock remaining.
-   _name_ `string` - The item name.
-   _permalink_ `string` - The item permalink.
-   _prices_ `object` - The item prices object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _price_ `string` - The price.
    -   _price_range_ `string` - The price range.
    -   _raw_prices_ `object` - The raw prices object with the following keys:
        -   _precision_ `number` - The precision.
        -   _price_ `number` - The price.
        -   _regular_price_ `number` - The regular price.
        -   _sale_price_ `number` - The sale price.
    -   _regular_price_ `string` - The regular price.
    -   _sale_price_ `string` - The sale price.
-   _quantity_ `number` - The item quantity.
-   _quantity_limits_ `object` - The item quantity limits object with the following keys:
    -   _editable_ `boolean` - Whether the quantity is editable.
    -   _maximum_ `number` - The maximum quantity.
    -   _minimum_ `number` - The minimum quantity.
    -   _multiple_of_ `number` - The multiple of quantity.
-   _short_description_ `string` - The item short description.
-   _show_backorder_badge_ `boolean` - Whether to show the backorder badge.
-   _sku_ `string` - The item SKU.
-   _sold_individually_ `boolean` - Whether the item is sold individually.
-   _totals_ `object` - The item totals object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _line_subtotal_ `string` - The line subtotal.
    -   _line_subtotal_tax_ `string` - The line subtotal tax.
    -   _line_total_ `string` - The line total.
    -   _line_total_tax_ `string` - The line total tax.
-   _type_ `string` - The item type.
-   _variation_ `array` - The item variation array.


---

## Coupons

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/coupons.md*

# Coupons

The following Coupon filters are available:

-   `coupons`
-   `showApplyCouponNotice`
-   `showRemoveCouponNotice`

## `coupons`

### Description 

The current functionality is to display the coupon codes in the Cart and Checkout sidebars. This could be undesirable if you dynamically generate a coupon code that is not user-friendly. It may, therefore, be desirable to change the way this code is displayed. To achieve this, the filter `coupons` exists. This filter could also be used to show or hide coupons. This filter must _not_ be used to alter the value/totals of a coupon. This will not carry through to the Cart totals.

### Parameters 

-   _coupons_ `object` - The coupons object with the following keys:
    -   _code_ `string` - The coupon code.
    -   _discount_type_ `string` - The type of discount. Can be `percent` or `fixed_cart`.
    -   _totals_ `object` - The totals object with the following keys:
        -   _currency_code_ `string` - The currency code.
        -   _currency_decimal_separator_ `string` - The currency decimal separator.
        -   _currency_minor_unit_ `number` - The currency minor unit.
        -   _currency_prefix_ `string` - The currency prefix.
        -   _currency_suffix_ `string` - The currency suffix.
        -   _currency_symbol_ `string` - The currency symbol.
        -   _currency_thousand_separator_ `string` - The currency thousand separator.
        -   _total_discount_ `string` - The total discount.
        -   _total_discount_tax_ `string` - The total discount tax.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following key:
    -   _context_ `string` (default: `summary`) - The context of the item.

### Returns 

-   `array` - The coupons array of objects with the same keys as above.

### Code example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCoupons = ( coupons, extensions, args ) => {
	return coupons.map( ( coupon ) => {
		if ( ! coupon.label.match( /autocoupon(?:_\d+)+/ ) ) {
			return coupon;
		}

		return {
			...coupon,
			label: 'Automatic coupon',
		};
	} );
};

registerCheckoutFilters( 'example-extension', {
	coupons: modifyCoupons,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots 

| Before                                                                 | After                                                                 |
|:---------------------------------------------------------------------:|:---------------------------------------------------------------------:|
|![Before applying the Coupons filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/6cab1aff-e4b9-4909-b81c-5726c6a20c40) |![After applying the Coupons filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/a5cc2572-16e7-4781-a5ab-5d6cdced2ff6) |

## `showApplyCouponNotice`

### Description 

### Parameters 

-   _value_ `boolean` (default: `true`) - Whether to show the apply coupon notice.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _context_ `string` (allowed values: `wc/cart` and `wc/checkout`) - The context of the coupon notice.
    -   _couponCode_ `string` - The coupon code.

### Returns 

-   `boolean` - Whether to show the apply coupon notice.

### Code examples 

#### Basic example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyShowApplyCouponNotice = ( defaultValue, extensions, args ) => {
	return false;
};

registerCheckoutFilters( 'example-extension', {
	showApplyCouponNotice: modifyShowApplyCouponNotice,
} );
```

#### Advanced example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyShowApplyCouponNotice = ( defaultValue, extensions, args ) => {
	if ( args?.couponCode === '10off' ) {
		return false;
	}

	return defaultValue;
};

registerCheckoutFilters( 'example-extension', {
	showApplyCouponNotice: modifyShowApplyCouponNotice,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots 

| Before                                                                 | After                                                                 |
|:---------------------------------------------------------------------:|:---------------------------------------------------------------------:|
|![Before applying the Show Apply Coupon Notice filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/374d4899-61f3-49b2-ae04-5541d4c130c2) |![After applying the Show Apply Coupon Notice filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/c35dbd9b-eee4-4afe-9a29-9c554d467729) |

## `showRemoveCouponNotice`

### Description 

### Parameters 

-   _value_ `boolean` (default: `true`) - Whether to show the remove coupon notice.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _context_ `string` (allowed values: `wc/cart` and `wc/checkout`) - The context of the coupon notice.
    -   _couponCode_ `string` - The coupon code.

### Returns 

-   `boolean` - Whether to show the remove coupon notice.

### Code examples 

#### Basic example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyShowRemoveCouponNotice = ( defaultValue, extensions, args ) => {
	return false;
};

registerCheckoutFilters( 'example-extension', {
	showRemoveCouponNotice: modifyShowRemoveCouponNotice,
} );
```

#### Advanced example 

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyShowRemoveCouponNotice = ( defaultValue, extensions, args ) => {
	if ( args?.couponCode === '10off' ) {
		return false;
	}

	return defaultValue;
};

registerCheckoutFilters( 'example-extension', {
	showRemoveCouponNotice: modifyShowRemoveCouponNotice,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots 

| Before                                                                 | After                                                                 |
|:---------------------------------------------------------------------:|:---------------------------------------------------------------------:|
|![Before applying the Show Remove Coupon Notice filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/9d8607fa-ab20-4181-b70b-7954e7aa49cb) |![After applying the Show Remove Coupon Notice filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/83d5f65f-c4f3-4707-a250-077952514931) |


---

## Order summary items

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/order-summary-items.md*

# Order summary items

The following Order Summary Items filters are available:

-   `cartItemClass`
-   `cartItemPrice`
-   `cartItemScreenReaderPrice`
-   `itemName`
-   `subtotalPriceFormat`

The following objects are shared between the filters:

-   Cart object
-   Cart Item object

The following screenshot shows which parts the individual filters affect:

![Order Summary Items](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-26-at-16.29.45.png)

## `cartItemClass`

### Description

The `cartItemClass` filter allows to change the order summary item class.

### Parameters

-   _defaultValue_ `string` (default: `''`) - The default order summary item class.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](#cart-object).
    -   _cartItem_ `object` - The order summary item object from `wc/store/cart`, see [order summary item object](#cart-item-object).
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.

### Returns

-   `string` - The modified order summary item class, or an empty string.

### Code examples

#### Basic example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCartItemClass = ( defaultValue, extensions, args ) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	return 'my-custom-class';
};

registerCheckoutFilters( 'example-extension', {
	cartItemClass: modifyCartItemClass,
} );
```

#### Advanced example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCartItemClass = ( defaultValue, extensions, args ) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return 'cool-class';
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return 'hot-class';
	}

	return 'my-custom-class';
};

registerCheckoutFilters( 'example-extension', {
	cartItemClass: modifyCartItemClass,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots

| Before                                                                                                                                               | After                                                                                                                                               |
|:----------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
| ![Before applying the Cart Item Class filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/ff555a84-8d07-4889-97e1-8f7d50d47350) | ![After applying the Cart Item Class filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/183809d8-03dc-466d-a415-d8d2062d880f) |

## `cartItemPrice`

### Description

The `cartItemPrice` filter allows to format the order summary item price.

### Parameters

-   _defaultValue_ `string` (default: `<price/>`) - The default order summary item price.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](#cart-object).
    -   _cartItem_ `object` - The order summary item object from `wc/store/cart`, see [order summary item object](#cart-item-object).
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.
-   _validation_ `boolean` - Checks if the return value contains the substring `<price/>`.

### Returns

-   `string` - The modified format of the order summary item price, which must contain the substring `<price/>`, or the original price format.

### Code examples

#### Basic example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCartItemPrice = ( defaultValue, extensions, args, validation ) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	return '<price/> for all items';
};

registerCheckoutFilters( 'example-extension', {
	cartItemPrice: modifyCartItemPrice,
} );
```

#### Advanced example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCartItemPrice = ( defaultValue, extensions, args, validation ) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return '<price/> to keep you ☀️';
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return '<price/> to keep you ❄️';
	}

	return '<price/> for all items';
};

registerCheckoutFilters( 'example-extension', {
	cartItemPrice: modifyCartItemPrice,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots

| Before                                                                                                                                               | After                                                                                                                                               |
|:----------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
| ![Before applying the Cart Item Price filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/58137fc4-884d-4783-9275-5f78abec1473) | ![After applying the Cart Item Price filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/fb502b74-6447-49a8-8d35-241e738f089d) |

## `cartItemScreenReaderPrice`

### Description

The `cartItemScreenReaderPrice` filter allows for formatting the order summary item price announced to screen reader and assistive technology users. There are no visual changes on the screen. The code changes can be seen in the `<span class="screen-reader-text">` included for each item in the cart.

### Parameters

-   _defaultValue_ `string` (default: `Total price for <quantity/> <productName/> item: <price/>` for purchases of a single item; `Total price for <quantity/> <productName/> items: <price/>` for purchases of multiple items) - The default order summary screen reader text.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](#cart-object).
    -   _cartItem_ `object` - The order summary item object from `wc/store/cart`, see [order summary item object](#cart-item-object).
    -   _context_ `string` (`summary`) - The context of the item, fixed to match the context of other filters in the mini-cart summary.
-   _validation_ `boolean` - Checks if the return value contains the substrings `<quantity/>`, `<productName/>` and `<price/>`.

### Returns

-   `string` - The modified format of the order summary item price, which must contain the substrings `<quantity/>`, `<productName/>` and `<price/>`.

### Code examples

#### Basic example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;
const { _n } = window.wp.i18n;

const modifyCartItemScreenReaderPrice = ( defaultValue, extensions, args, validation ) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	return _n(
		'<quantity/> <productName/> item will cost <price/>',
		'<quantity/> <productName/> items will cost <price/>',
		args?.cartItem?.quantity ?? 1,
		'example-extension'
	);
};

registerCheckoutFilters( 'example-extension', {
	cartItemScreenReaderPrice: modifyCartItemScreenReaderPrice,
} );
```

#### Advanced example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;
const { _n } = window.wp.i18n;

const modifyCartItemScreenReaderPrice = ( defaultValue, extensions, args, validation ) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return _n(
			'Total price for <quantity/> <productName/> item: <price/> to keep you warm',
			'Total price for <quantity/> <productName/> items: <price/> to keep you warm',
			args?.cartItem?.quantity ?? 1,
			'example-extension'
		);
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return _n(
			'Total price for <quantity/> <productName/> item: <price/> to keep you cool',
			'Total price for <quantity/> <productName/> items: <price/> to keep you cool',
			args?.cartItem?.quantity ?? 1,
			'example-extension'
		);
	}

	return defaultValue;
};

registerCheckoutFilters( 'example-extension', {
	cartItemScreenReaderPrice: modifyCartItemScreenReaderPrice,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

## `itemName`

### Description

The `itemName` filter allows to change the order summary item name.

### Parameters

-   _defaultValue_ `string` - The default order summary item name.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](#cart-object).
    -   _cartItem_ `object` - The order summary item object from `wc/store/cart`, see [order summary item object](#cart-item-object).
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.

### Returns

-   `string` - The original or modified order summary item name.

### Code examples

#### Basic example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyItemName = ( defaultValue, extensions, args ) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	return `🪴 ${ defaultValue } 🪴`;
};

registerCheckoutFilters( 'example-extension', {
	itemName: modifyItemName,
} );
```

#### Advanced example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyItemName = ( defaultValue, extensions, args ) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return `⛷️ ${ defaultValue } ⛷️`;
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return `🏄‍♂️ ${ defaultValue } 🏄‍♂️`;
	}

	return `🪴 ${ defaultValue } 🪴`;
};

registerCheckoutFilters( 'example-extension', {
	itemName: modifyItemName,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots

| Before                                                                                                                                         | After                                                                                                                                         |
|:----------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------:|
| ![Before applying the Item Name filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/3dc0bda7-fccf-4f35-a2e2-aa04e616563a) | ![After applying the Item Name filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/c96b8394-03a7-45f6-813b-5335f4bf83b5) |

## `subtotalPriceFormat`

### Description

The `subtotalPriceFormat` filter allows to format the order summary item subtotal price.

### Parameters

-   _defaultValue_ `string` (default: `<price/>`) - The default order summary item subtotal price.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](#cart-object).
    -   _cartItem_ `object` - The order summary item object from `wc/store/cart`, see [order summary item object](#cart-item-object).
    -   _context_ `string` (allowed values: `cart` or `summary`) - The context of the item.
-   _validation_ `boolean` - Checks if the return value contains the substring `<price/>`.

### Returns

-   `string` - The modified format of the order summary item subtotal price, which must contain the substring `<price/>`, or the original price format.

### Code examples

#### Basic example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifySubtotalPriceFormat = (
	defaultValue,
	extensions,
	args,
	validation
) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	return '<price/> per item';
};

registerCheckoutFilters( 'example-extension', {
	subtotalPriceFormat: modifySubtotalPriceFormat,
} );
```

#### Advanced example

```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifySubtotalPriceFormat = (
	defaultValue,
	extensions,
	args,
	validation
) => {
	const isOrderSummaryContext = args?.context === 'summary';

	if ( ! isOrderSummaryContext ) {
		return defaultValue;
	}

	if ( args?.cartItem?.name === 'Beanie with Logo' ) {
		return '<price/> per warm beanie';
	}

	if ( args?.cartItem?.name === 'Sunglasses' ) {
		return '<price/> per cool sunglasses';
	}

	return '<price/> per item';
};

registerCheckoutFilters( 'example-extension', {
	subtotalPriceFormat: modifySubtotalPriceFormat,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots

| Before                                                                                                                                                     | After                                                                                                                                                     |
|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|
| ![Before applying the Subtotal Price Format filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/3574e7ae-9857-4651-ac9e-e6b597e3a589) | ![After applying the Subtotal Price Format filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/94e18439-6d6b-44a4-ade1-8302c5984641) |

## Cart object

The Cart object of the filters above has the following keys:

-   _billingAddress_ `object` - The billing address object with the following keys:
    -   _address_1_ `string` - The first line of the address.
    -   _address_2_ `string` - The second line of the address.
    -   _city_ `string` - The city of the address.
    -   _company_ `string` - The company of the address.
    -   _country_ `string` - The country of the address.
    -   _email_ `string` - The email of the address.
    -   _first_name_ `string` - The first name of the address.
    -   _last_name_ `string` - The last name of the address.
    -   _phone_ `string` - The phone of the address.
    -   _postcode_ `string` - The postcode of the address.
    -   _state_ `string` - The state of the address.
-   ~~_billingData_~~ `object` - The billing data object with the same keys as the `billingAddress` object.
-   _cartCoupons_ `array` - The cart coupons array.
-   _cartErrors_ `array` - The cart errors array.
-   _cartFees_ `array` - The cart fees array.
-   _cartHasCalculatedShipping_ `boolean` - Whether the cart has calculated shipping.
-   _cartIsLoading_ `boolean` - Whether the cart is loading.
-   _cartItemErrors_ `array` - The cart item errors array.
-   _cartItems_ `array` - The cart items array with cart item objects, see [Cart Item object](#cart-item-object).
-   _cartItemsCount_ `number` - The cart items count.
-   _cartItemsWeight_ `number` - The cart items weight.
-   _cartNeedsPayment_ `boolean` - Whether the cart needs payment.
-   _cartNeedsShipping_ `boolean` - Whether the cart needs shipping.
-   _cartTotals_ `object` - The cart totals object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _tax_lines_ `array` - The tax lines array with tax line objects with the following keys:
        -   _name_ `string` - The name of the tax line.
        -   _price_ `number` - The price of the tax line.
        -   _rate_ `string` - The rate ID of the tax line.
    -   _total_discount_ `string` - The total discount.
    -   _total_discount_tax_ `string` - The total discount tax.
    -   _total_fees_ `string` - The total fees.
    -   _total_fees_tax_ `string` - The total fees tax.
    -   _total_items_ `string` - The total items.
    -   _total_items_tax_ `string` - The total items tax.
    -   _total_price_ `string` - The total price.
    -   _total_shipping_ `string` - The total shipping.
    -   _total_shipping_tax_ `string` - The total shipping tax.
    -   _total_tax_ `string` - The total tax.
-   _crossSellsProducts_ `array` - The cross sells products array with cross sells product objects.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _isLoadingRates_ `boolean` - Whether the cart is loading shipping rates.
-   _paymentRequirements_ `array` - The payment requirements array.
-   _shippingAddress_ `object` - The shipping address object with the same keys as the `billingAddress` object.
-   _shippingRates_ `array` - The shipping rates array.

## Cart Item object

The Cart Item object of the filters above has the following keys:

-   _backorders_allowed_ `boolean` - Whether backorders are allowed.
-   _catalog_visibility_ `string` - The catalog visibility.
-   _description_ `string` - The cart item description.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _id_ `number` - The item ID.
-   _images_ `array` - The item images array.
-   _item_data_ `array` - The item data array.
-   _key_ `string` - The item key.
-   _low_stock_remaining_ `number` - The low stock remaining.
-   _name_ `string` - The item name.
-   _permalink_ `string` - The item permalink.
-   _prices_ `object` - The item prices object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _price_ `string` - The price.
    -   _price_range_ `string` - The price range.
    -   _raw_prices_ `object` - The raw prices object with the following keys:
        -   _precision_ `number` - The precision.
        -   _price_ `number` - The price.
        -   _regular_price_ `number` - The regular price.
        -   _sale_price_ `number` - The sale price.
    -   _regular_price_ `string` - The regular price.
    -   _sale_price_ `string` - The sale price.
-   _quantity_ `number` - The item quantity.
-   _quantity_limits_ `object` - The item quantity limits object with the following keys:
    -   _editable_ `boolean` - Whether the quantity is editable.
    -   _maximum_ `number` - The maximum quantity.
    -   _minimum_ `number` - The minimum quantity.
    -   _multiple_of_ `number` - The multiple of quantity.
-   _short_description_ `string` - The item short description.
-   _show_backorder_badge_ `boolean` - Whether to show the backorder badge.
-   _sku_ `string` - The item SKU.
-   _sold_individually_ `boolean` - Whether the item is sold individually.
-   _totals_ `object` - The item totals object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _line_subtotal_ `string` - The line subtotal.
    -   _line_subtotal_tax_ `string` - The line subtotal tax.
    -   _line_total_ `string` - The line total.
    -   _line_total_tax_ `string` - The line total tax.
-   _type_ `string` - The item type.
-   _variation_ `array` - The item variation array.


---

## Totals footer item

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/totals-footer-item.md*

# Totals footer item

The following Totals Footer Item filter are available:

-   `totalLabel`
-   `totalValue`

## `totalLabel`

The following object is used in the filter:

-   [Cart object](#cart-object)

### Description

The `totalLabel` filter allows to change the label of the total item in the footer of the Cart and Checkout blocks.

### Parameters

-   _defaultValue_ `string` (default: `Total`) - The total label.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](#cart-object).

### Returns

-   `string` - The updated total label.

### Code example

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyTotalLabel = ( defaultValue, extensions, args ) => {
	return 'Deposit due today';
};

registerCheckoutFilters( 'example-extension', {
	totalLabel: modifyTotalLabel,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots

| Before | After |
| :---: | :---: |
| ![Before applying the Total Label filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/5b2fb8ab-db84-4ed0-a676-d5203edc84d2) | ![After applying the Total Label filter](https://github.com/woocommerce/woocommerce-blocks/assets/3323310/07955eea-cb17-48e9-9cb5-6548dd6a3b24) |


## `totalValue`

The following object is used in the filter:

-   [Cart object](#cart-object)

### Description

The `totalValue` filter allows to format the total price in the footer of the Cart and Checkout blocks.

### Parameters

-   _defaultValue_ `string` (default: `Total`) - The total label.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _args_ `object` - The arguments object with the following keys:
    -   _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](#cart-object).
-   _validation_ `boolean` - Checks if the return value contains the substring `<price/>`.

### Returns

-   `string` - The modified format of the total price, which must contain the substring `<price/>`, or the original price format.

### Code example

```ts
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyTotalsPrice = ( defaultValue, extensions, args, validation ) => {
	return 'Pay <price/> now';
};

registerCheckoutFilters( 'my-extension', {
	totalValue: modifyTotalsPrice,
} );
```

> Filters can be also combined. See [Combined filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) for an example.

### Screenshots

| Before | After |
| :---: | :---: |
| ![Before applying the Total Value filter](https://github.com/woocommerce/woocommerce/assets/3323310/4b788bdd-6fbd-406c-a9ad-4fb13f901c23) | ![After applying the Total Value filter](https://github.com/woocommerce/woocommerce/assets/3323310/1b1b5f72-7f2f-4ee5-b2a4-1d8eb2208deb) |


## Cart object

The Cart object of the filters above has the following keys:

-   _billingAddress_ `object` - The billing address object with the following keys:
    -   _address_1_ `string` - The first line of the address.
    -   _address_2_ `string` - The second line of the address.
    -   _city_ `string` - The city of the address.
    -   _company_ `string` - The company of the address.
    -   _country_ `string` - The country of the address.
    -   _email_ `string` - The email of the address.
    -   _first_name_ `string` - The first name of the address.
    -   _last_name_ `string` - The last name of the address.
    -   _phone_ `string` - The phone of the address.
    -   _postcode_ `string` - The postcode of the address.
    -   _state_ `string` - The state of the address.
-   ~~_billingData_~~ `object` - The billing data object with the same keys as the `billingAddress` object.
-   _cartCoupons_ `array` - The cart coupons array.
-   _cartErrors_ `array` - The cart errors array.
-   _cartFees_ `array` - The cart fees array.
-   _cartHasCalculatedShipping_ `boolean` - Whether the cart has calculated shipping.
-   _cartIsLoading_ `boolean` - Whether the cart is loading.
-   _cartItemErrors_ `array` - The cart item errors array.
-   _cartItems_ `array` - The cart items array with cart item objects, see [Cart Item object](#cart-item-object).
-   _cartItemsCount_ `number` - The cart items count.
-   _cartItemsWeight_ `number` - The cart items weight.
-   _cartNeedsPayment_ `boolean` - Whether the cart needs payment.
-   _cartNeedsShipping_ `boolean` - Whether the cart needs shipping.
-   _cartTotals_ `object` - The cart totals object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _tax_lines_ `array` - The tax lines array with tax line objects with the following keys:
        -   _name_ `string` - The name of the tax line.
        -   _price_ `number` - The price of the tax line.
        -   _rate_ `string` - The rate ID of the tax line.
    -   _total_discount_ `string` - The total discount.
    -   _total_discount_tax_ `string` - The total discount tax.
    -   _total_fees_ `string` - The total fees.
    -   _total_fees_tax_ `string` - The total fees tax.
    -   _total_items_ `string` - The total items.
    -   _total_items_tax_ `string` - The total items tax.
    -   _total_price_ `string` - The total price.
    -   _total_shipping_ `string` - The total shipping.
    -   _total_shipping_tax_ `string` - The total shipping tax.
    -   _total_tax_ `string` - The total tax.
-   _crossSellsProducts_ `array` - The cross sells products array with cross sells product objects.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _isLoadingRates_ `boolean` - Whether the cart is loading shipping rates.
-   _paymentRequirements_ `array` - The payment requirements array.
-   _shippingAddress_ `object` - The shipping address object with the same keys as the `billingAddress` object.
-   _shippingRates_ `array` - The shipping rates array.

## Cart Item object

The Cart Item object of the filters above has the following keys:

-   _backorders_allowed_ `boolean` - Whether backorders are allowed.
-   _catalog_visibility_ `string` - The catalog visibility.
-   _description_ `string` - The cart item description.
-   _extensions_ `object` (default: `{}`) - The extensions object.
-   _id_ `number` - The item ID.
-   _images_ `array` - The item images array.
-   _item_data_ `array` - The item data array.
-   _key_ `string` - The item key.
-   _low_stock_remaining_ `number` - The low stock remaining.
-   _name_ `string` - The item name.
-   _permalink_ `string` - The item permalink.
-   _prices_ `object` - The item prices object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _price_ `string` - The price.
    -   _price_range_ `string` - The price range.
    -   _raw_prices_ `object` - The raw prices object with the following keys:
        -   _precision_ `number` - The precision.
        -   _price_ `number` - The price.
        -   _regular_price_ `number` - The regular price.
        -   _sale_price_ `number` - The sale price.
    -   _regular_price_ `string` - The regular price.
    -   _sale_price_ `string` - The sale price.
-   _quantity_ `number` - The item quantity.
-   _quantity_limits_ `object` - The item quantity limits object with the following keys:
    -   _editable_ `boolean` - Whether the quantity is editable.
    -   _maximum_ `number` - The maximum quantity.
    -   _minimum_ `number` - The minimum quantity.
    -   _multiple_of_ `number` - The multiple of quantity.
-   _short_description_ `string` - The item short description.
-   _show_backorder_badge_ `boolean` - Whether to show the backorder badge.
-   _sku_ `string` - The item SKU.
-   _sold_individually_ `boolean` - Whether the item is sold individually.
-   _totals_ `object` - The item totals object with the following keys:
    -   _currency_code_ `string` - The currency code.
    -   _currency_decimal_separator_ `string` - The currency decimal separator.
    -   _currency_minor_unit_ `number` - The currency minor unit.
    -   _currency_prefix_ `string` - The currency prefix.
    -   _currency_suffix_ `string` - The currency suffix.
    -   _currency_symbol_ `string` - The currency symbol.
    -   _currency_thousand_separator_ `string` - The currency thousand separator.
    -   _line_subtotal_ `string` - The line subtotal.
    -   _line_subtotal_tax_ `string` - The line subtotal tax.
    -   _line_total_ `string` - The line total.
    -   _line_total_tax_ `string` - The line total tax.
-   _type_ `string` - The item type.
-   _variation_ `array` - The item variation array.


---

## How the checkout block processes an order

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/how-checkout-processes-an-order.md*

# How the checkout block processes an order

This document will shed some light on the inner workings of the Checkout flow. More specifically, what happens after a user hits the "Place Order" button.

## Structure

The following areas are associated with processing the checkout for a user.

### The Payment Registry [(file)](https://href.li/?https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/blocks-registry/payment-methods/registry.ts#L1)

The payment registry stores all the configuration information for each payment method. We can register a new payment method here with the `registerPaymentMethod` and `registerExpressPaymentMethod `functions, also available to other plugins.

### Data Stores

Data stores are used to keep track of data that is likely to change during a user's session, such as the active payment method, whether the checkout has an error, etc. We split these data stores by areas of concern, so we have 2 data stores related to the checkout: `wc/store/checkout` [(file)](https://href.li/?https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/checkout/index.ts#L1) and `wc/store/payment` [(file)](https://href.li/?https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/payment-methods/index.ts#L1) . Data stores live in the `assets/js/data` folder.

### Contexts

Contexts are used to make data available to the Checkout block. Each of these provide data and functions related to a specific area of concern, via the use of a hook. For example, if we wanted to use the `onPaymentSetup` handler from the `PaymentEventsContext` context, we can do it like this:

```js
const { onPaymentSetup } = usePaymentEventsContext();
```

The other job of contexts is to run side effects for our Checkout block. What typically happens is that the `CheckoutEvents` and `PaymentEvents` will listen for changes in the checkout and payment data stores, and dispatch actions on those stores based on some logic.

For example, in the `CheckoutEvents` context, we dispatch the `emitValidateEvent` action when the checkout status is `before_processing`. There is a lot of similar logic that reacts to changes in status and other state data from these two stores.

The Checkout contexts are:

| Context                                                                                                                                                                                                                | Description                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [CheckoutEvents](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/checkout-events/index.tsx#L4)                          | Provides some checkout related event handlers        |
| [ PaymentEvents ](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/payment-methods/payment-method-events-context.tsx#L3) | Provides event handlers related to payments          |
| [ CustomerData ](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/customer/index.tsx#L1)                                 | Provides data related to the current customer        |
| [ ShippingData ](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/shipping/index.js#L1)                                  | Provides data and actions related to shipping errors |

### The Checkout Processor (checkout-processor.js)

The checkout processor component subscribes to changes in the checkout or payment data stores, packages up some of this data and calls the StoreApi `/checkout` endpoint when the conditions are right.

## The Checkout Provider

The [checkout provider](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/assets/js/base/context/providers/cart-checkout/checkout-provider.js), wraps all the contexts mentioned above around the `CheckoutProcessor` component.

---

## Checkout User Flow

Below is the complete checkout flow

### 1\. Click the "Place Order" button

The checkout process starts when a user clicks the button

### 2\. Checkout status is set to `before_processing` [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/checkout-events/index.tsx#L167)

As soon as the user clicks the "Place Order" button, we change the checkout status to _"before_processing"_. This is where we handle the validation of the checkout information.

### 3\. Emit the `checkout_validation_before_processing` event [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/checkout-events/index.tsx#L113)

This is where the WooCommerce Blocks plugin and other plugins can register event listeners for dealing with validation. The event listeners for this event will run and if there are errors, we set checkout status to `idle` and display the errors to the user.

If there are no errors, we move to step 4 below.

### 4\. Checkout status is set to `processing` [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/checkout/thunks.ts#L76)

The processing status is used by step 5 below to change the payment status

### 5\. Payment status is set to `processing` [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/payment-methods/payment-method-events-context.tsx#L94)

Once all the checkout processing is done and if there are no errors, the payment processing begins

### 6\. Emit the `payment_processing` event [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/payment-methods/thunks.ts#L42)

The `payment_processing` event is emitted. Otherplugins can register event listeners for this event and run their own code.

For example, the Stripe plugin checks the address and payment details here, and uses the stripe APIs to create a customer and payment reference within Stripe.

**Important note: The actual payment is not taken here**. **It acts like a pre-payment hook to run any payment plugin code before the actual payment is attempted.**

### 7\. Execute the `payment_processing` event listeners and set the payment and checkout states accordingly [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/payment-methods/thunks.ts#L54-L132)

If the registered event listeners return errors, we will display this to the user.

If the event listeners are considered successful, we sync up the address of the checkout with the payment address, store the `paymentMethodData` in the payment store, and set the payment status property `{ isProcessing: true }`.

### 8\. POST to `/wc/store/v1/checkout` [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/checkout-processor.js#L234)

The `/checkout` StoreApi endpoint is called if there are no payment errors. This will take the final customer addresses and chosen payment method, and any additional payment data, then attempts payment and returns the result.

**Important: payment is attempted through the StoreApi, NOT through the `payment_processing` event that is sent from the client**

### 9\. The `processCheckoutResponse` action is triggered on the checkout store [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/checkout/thunks.ts#L33)

Once the fetch to the StoreApi `/checkout` endpoint returns a response, we pass this to the `processCheckoutResponse` action on the `checkout` data store.

It will perform the following actions:

-   It sets the redirect url to redirect to once the order is complete
-   It stores the payment result in the `checkout` data store.
-   It changes the checkout status to `after_processing` (step 10)

### 10\. Checkout status is set to `after_processing` [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/checkout/thunks.ts#L42)

The `after_processing` status indicates that we've finished the main checkout processing step. In this step, we run cleanup actions and display any errors that have been triggered during the last step.

### 11\. Emit the `checkout_after_processing_with_success` event [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/checkout/thunks.ts#L118-L128)

If there are no errors, the `checkout_after_processing_with_success` event is triggered. This is where other plugins can run some code after the checkout process has been successful.

Any event listeners registered on the `checkout_after_processing_with_success` event will be executed. If there are no errors from the event listeners, `setComplete` action is called on the `checkout` data store to set the status to `complete` (step 13). An event listener can also return an error here, which will be displayed to the user.

### 12\. Emit the `checkout_after_processing_with_error` event [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/checkout/thunks.ts#L104-L116)

If there has been an error from step 5, the `checkout_after_processing_with_error` event will be emitted. Other plugins can register event listeners to run here to display an error to the user. The event listeners are processed and display any errors to the user.

### 13\. Set checkout status to `complete` [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/checkout/utils.ts#L146)

If there are no errors, the `status` property changes to `complete` in the checkout data store. This indicates that the checkout process is complete.

### 14\. Redirect [(file)](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/base/context/providers/cart-checkout/checkout-processor.js#L193-L197)

Once the checkout status is set to `complete`, if there is a `redirectUrl` in the checkout data store, then we redirect the user to the URL.

## Other notable things

### Checking payment methods

A payment method is registered with a [configuration object](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/types/type-defs/payments.ts#L60-L83). It must include a function named `canMakePayment`. This function should return true if the payment method can be used to pay for the current cart. The current cart (items, addresses, shipping methods etc.) is passed to this function, and each payment method is responsible for reporting whether it can be used.

The `checkPaymentMethodsCanPay()` [function](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/payment-methods/check-payment-methods.ts#L26) goes through all the registered payment methods, checks if they can pay, and if so, adds them to the `availablePaymentMethods` property on the payment data store.

The `checkPaymentMethodsCanPay()` [function](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/payment-methods/check-payment-methods.ts#L26) must be called in a few places in order to validate the payment methods before they can be displayed to the user as viable options.

-   [Once the cart loads](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/cart/index.ts#L46-L57), we want to be able to display express payment methods, so we need to validate them first.
-   [Once the cart changes](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/cart/index.ts#L42-L43), we may want to enable/disable certain payment methods
-   [once the checkout loads](https://github.com/woocommerce/woocommerce-blocks/blob/4af2c0916a936369be8a4f0044683b90b3af4f0d/assets/js/data/checkout/index.ts#L44-L49), we want to verify all registered payment methods


---

## Removing checkout fields

*Source: block-development/extensible-blocks/cart-and-checkout-blocks/removing-checkout-fields.md*

# Removing checkout fields

If you're trying to extend the new Checkout block, you might notice the previous `checkout_fields` isn't working. This is intentional as we want to offer more curated extensibility paths. With that said, one of the most common requests we get is how to disable Checkout fields for certain order types. This is not something we encourage, but we are sharing the details due to how commonly requested it is.

## Why we don't encourage removing fields

The simple reason is that Checkout is complex, and many plugins need different data, payment methods will need your address info to run fraud detection, or validate your card, tax (including core) will need your full address to calculate taxes correctly, this is something we still think about in Checkout and are looking for a universal solution. While we work on this solution, the document below will help you remove checkout fields.

## Disabling fields for a single country

Checkout fields still respect country locale, which means you can modify fields for a country via PHP and this would work fine. The following billing form has 10 fields, 7 of them are required:

![Image](https://github.com/user-attachments/assets/63d83769-c20c-4c85-aebf-da8510d1d9ae)

Let's say that in Algeria, we know for sure that postal code and city are redundant, so we can remove them:

```php
add_filter('woocommerce_get_country_locale', function( $locale ) {

	$locale['DZ']['postcode']['required'] = false;
	$locale['DZ']['postcode']['hidden'] = true;

	$locale['DZ']['city']['required'] = false;
	$locale['DZ']['city']['hidden'] = true;

	 return $locale;
});
```

With the code above, both of those fields are removed for Algeria, but not for other countries, which is a good and safe update.

![Image](https://github.com/user-attachments/assets/96d45e1a-99f0-4b91-92d1-85ee742a9705)

Keep in mind that this will remove fields for both shipping and billing. We think strongly that billing shape should match shipping shape.

## Removing every field except Country and names

We can follow up with removing all other fields except Country, removing the country would fail your order, as we need country to know which fields to remove:

```php
add_filter('woocommerce_get_country_locale', function( $locale ) {

	$locale['DZ']['address_1'] = [
		'required' => false,
		'hidden'   => true,
	];

	$locale['DZ']['postcode'] = [
		'required' => false,
		'hidden'   => true,
	];

	$locale['DZ']['city'] = [
		'required' => false,
		'hidden'   => true,
	];

	$locale['DZ']['company'] = [
		'required' => false,
		'hidden'   => true,
	];
	
	$locale['DZ']['state'] = [
		'required' => false,
		'hidden'   => true,
	];
	
	$locale['DZ']['phone'] = [
		'required' => false,
		'hidden'   => true,
	];

	return $locale;
});
```

This is the result:

![Image](https://github.com/user-attachments/assets/19c82877-3405-4762-82ce-e952746abe66)

You notice that Address Line 2 is not visible, this is because it will always be skipped if Address Line 1 is skipped.

## Removing Company and Phone

One easy way (if you have access to the website), is to just toggle off the fields from the editor:

![Image](https://github.com/user-attachments/assets/53740d32-4ccd-4d5e-b08f-91a8b8b7d055)

This would be the result:

![Image](https://github.com/user-attachments/assets/3bb8dc23-22cc-4787-8577-648081e57644)

## Removing Company and Phone via code

Unlike other fields, Phone, Company, and Address 2 state is persisted to the database via an option:

- `woocommerce_checkout_phone_field`
- `woocommerce_checkout_company_field`
- `woocommerce_checkout_address_2_field`

The value of those options can be: `required`, `optional`, or `hidden`. They manage the default state of the field. So you can edit that, but still leave agency to the merchant to set it as they see fit. You can also edit them based on locale/country.

To edit the default value:

```php
add_filter(
	'default_option_woocommerce_checkout_phone_field',
	function ( $default_value ) {
		return "required";
	},
	10,
	1
);
```

If you want to change the value depending on locale (overriding the merchant value for that country), you can use the examples above.

Till now, all changes are applied to Algeria only, customers switching would see the correct fields for each country:

![Image](https://github.com/user-attachments/assets/3b8cb49a-1c95-4fab-8aaa-26b14ce22aad)

## Applying changes to all countries you sell to

As with the above, this is not something we recommend unless you sell to a very controlled set of countries and tested this with each country. Some payment gateways would only enable fraud detection on production mode and not test mode, and your fields that passed test mode fails in production mode, but here it is regardless:

```php
add_filter('woocommerce_get_country_locale', function( $locale ) {
	foreach ( $locale as $key => $value ) {
		$locale[ $key ]['address_1'] = [
			'required' => false,
			'hidden'   => true,
		];

		$locale[ $key ]['postcode'] = [
			'required' => false,
			'hidden'   => true,
		];

		$locale[ $key ]['city'] = [
			'required' => false,
			'hidden'   => true,
		];

		$locale[ $key ]['state'] = [
			'required' => false,
			'hidden'   => true,
		];
	}

	return $locale;
});
```

The above code would loop over all counties you sell and disable the fields there.

## Limiting changes to virtual carts only

We can choose to remove fields for virtual cart (ones that only require billing and no shipping), this can be done with some extra checks:

```php
add_filter('woocommerce_get_country_locale', function( $locale ) {
	$cart = wc()->cart;

	// Only remove fields if we're operating on a cart.
	if ( ! $cart ) {
		return $locale;
	}

	// Only remove fields if we're dealing with a virtual cart.
	if ( $cart->needs_shipping() ) {
		return $locale;
	}
  // Perform the rest of the logic below...
```

## Editing the address card text

For future visits, Checkout will show an address card for saved addresses, this isn't working constantly right now for billing, but once it works, it will show up like this:

![Image](https://github.com/user-attachments/assets/ab56c4ca-39ba-47ab-83d1-1ce6dfefc0c3)

We can edit that using PHP, because the value is coming from `get_address_formats` function, which passes through the `woocommerce_localisation_address_formats` filter.

We can use the following code:

```php
add_filter( 'woocommerce_localisation_address_formats', function( $formats ) {
	foreach ( $formats as $key => $format ) {
		$formats[ $key ] = "{first_name} {last_name}\n{country}";
		// You can also use `{name}` instead of first name and last name.
	}

	return $formats;
} );
```

![Image](https://github.com/user-attachments/assets/2f87e168-896f-44b3-8c4f-63cc2e159d03)

A note that you need to pass the string in double quotes for it to work; otherwise the line breaks won't be recognized.


---

## Product collection block

*Source: block-development/extensible-blocks/product-collection-block/README.md*

# Product collection block

Display a collection of products from your store.

## Start here

1. [DOM events sent from product collection block](/docs/block-development/extensible-blocks/product-collection-block/dom-events)
2. [Registering custom collections in product collection block](/docs/block-development/extensible-blocks/product-collection-block/register-product-collection)


---

## DOM events sent from product collection block

*Source: block-development/extensible-blocks/product-collection-block/dom-events.md*

# DOM events sent from product collection block

## `wc-blocks_product_list_rendered`

This event is triggered when Product Collection block was rendered or re-rendered (e.g. due to page change).

### `detail` parameters

| Parameter          | Type    | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collection` | string | `undefined`       | Collection type. It's `undefined` for "create your own" collections as the type is not specified. For other Core collections it can be one of type: `woocommerce/product-collection/best-sellers`, `woocommerce/product-collection/featured`, `woocommerce/product-collection/new-arrivals`, `woocommerce/product-collection/on-sale`, `woocommerce/product-collection/top-rated`. For custom collections it will hold their name. |

### Example usage

```javascript
window.document.addEventListener(
  'wc-blocks_product_list_rendered',
  ( e ) => {
    const { collection } = e.detail;
    console.log( collection ) // -> collection name, e.g. woocommerce/product-collection/on-sale
  }
);
```

## Event: `wc-blocks_viewed_product`

This event is triggered when some blocks are clicked in order to view product (redirect to product page).

### `detail` parameters

| Parameter          | Type    | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collection` | string | `undefined`       | Collection type. It's `undefined` for "create your own" collections as the type is not specified. For other Core collections it can be one of type: `woocommerce/product-collection/best-sellers`, `woocommerce/product-collection/featured`, `woocommerce/product-collection/new-arrivals`, `woocommerce/product-collection/on-sale`, `woocommerce/product-collection/top-rated`. For custom collections it will hold their name. |
| `productId` | number |        | Product ID |

### Example usage

```javascript
window.document.addEventListener(
  'wc-blocks_viewed_product',
  ( e ) => {
    const { collection, productId } = e.detail;
    console.log( collection ) // -> collection name, e.g. "woocommerce/product-collection/featured" or undefined for default one
    console.log( productId ) // -> product ID, e.g. 34
  }
);
```


---

## Registering custom collections in product collection block

*Source: block-development/extensible-blocks/product-collection-block/register-product-collection.md*

# Registering custom collections in product collection block

The `__experimentalRegisterProductCollection` function is part of the `@woocommerce/blocks-registry` package. This function allows third party developers to register a new collection. This function accepts most of the arguments that are accepted by [Block Variation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/#defining-a-block-variation).

**CAUTION:** It's experimental and may change in the future. Please use it with caution.

**There are two ways to use this function:**

1. Using `@woocommerce/dependency-extraction-webpack-plugin` in a Webpack configuration: This will allow you to import the function from the package & use it in your code. For example:

	```tsx
	import { __experimentalRegisterProductCollection } from "@woocommerce/blocks-registry";
	```

2. Using the global `wc` object: This will allow you to use the function using the global JS object without importing it. For example:

	```tsx
	wc.wcBlocksRegistry.__experimentalRegisterProductCollection({
	...
	});
	```

Be sure to add `wc-blocks-registry` as a dependency to your script if you opt to use the `wc` global.

  ```php
  function enqueue_my_custom_product_collection_script() {
      wp_enqueue_script(
          'my-custom-product-collection',
          plugins_url( '/dist/my-custom-product-collection.js', __FILE__ ),
          array( 'wc-blocks-registry' ),
          10
      );
  }
  add_action( 'enqueue_block_editor_assets', 'enqueue_my_custom_product_collection_script' );
  ```

**Tip:** The first method is recommended if you are using Webpack.

## Defining a Collection

We will explain important arguments that can be passed to `__experimentalRegisterProductCollection`. For other arguments, you can refer to the [Block Variation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/#defining-a-block-variation) documentation.

A Collection is defined by an object that can contain the following fields:

- `name` (type `string`): A unique and machine-readable collection name. We recommend using the format `<plugin-name>/product-collection/<collection-name>`. Both `<plugin-name>` and `<collection-name>` should consist only of alphanumeric characters and hyphens (e.g., `my-plugin/product-collection/my-collection`).
- `title` (type `string`): The title of the collection, which will be displayed in various places including the block inserter and collection chooser.
- `description` (optional, type `string`): A human-readable description of the collection.
- `innerBlocks` (optional, type `Array[]`): An array of inner blocks that will be added to the collection. If not provided, the default inner blocks will be used.
- `isDefault`: It's set to `false` for all collections. Third party developers don't need to pass this argument.
- `isActive`: It will be managed by us. Third party developers don't need to pass this argument.
- `usesReference` (optional, type `Array[]`): An array of strings specifying the required reference for the collection. Acceptable values are `product`, `archive`, `cart`, and `order`. When the required reference isn't available on Editor side but will be available in Frontend, we will show a preview label.
- `scope` (optional, type `Array[]`): The list of scopes where the collection is applicable. Acceptable values are `block`, `inserter`, and `transform`. Defaults to `["block", "inserter"]`.
   	- **Note:** For Product Collection block, `block` scope means that the collection will be shown in Collection Chooser and "Choose Collection" toolbar button will be visible. For other scopes, you can refer to the [Block Variation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/#defining-a-block-variation) documentation.

### Attributes

Attributes are the properties that define the behavior of the collection. All the attributes are *optional*. Here are some of the important attributes that can be passed to `__experimentalRegisterProductCollection`:

- `query` (type `object`): The query object that defines the query for the collection. It can contain the following fields:
    - `offset` (type `number`): The number of items to offset the query by.
    - `order` (type `string`): The order of the query. Accepted values are `asc` and `desc`.
    - `orderBy` (type `string`): The field to order the query by.
    - `pages` (type `number`): The number of pages to query.
    - `perPage` (type `number`): The number of products per page.
    - `search` (type `string`): The search term to query by.
    - `taxQuery` (type `object`): The tax query to filter the query by. For example, if you wanna fetch products with category `Clothing` & `Accessories` and tag `Summer` then you can pass `taxQuery` as `{"product_cat":[20,17],"product_tag":[36]}`. Where array values are the term IDs.
    - `featured` (type `boolean`): Whether to query for featured items.
    - `timeFrame` (type `object`): The time frame to query by.
        - `operator` (type `string`): The operator to use for the time frame query. Accepted values are `in` and `not-in`.
        - `value` (type `string`): The value to query by. It should be a valid date string that PHP's `strtotime` function can parse.
    - `woocommerceOnSale` (type `boolean`): Whether to query for items on sale.
    - `woocommerceStockStatus` (type `array`): The stock status to query by. Some of the accepted values are `instock`, `outofstock`, `onbackorder`.
    - `woocommerceAttributes` (type `array`): The attributes to query by.
        - For example, if you wanna fetch products with color `blue` & `gray` and size `Large` then you can pass `woocommerceAttributes` as `[{"termId":23,"taxonomy":"pa_color"},{"termId":26,"taxonomy":"pa_size"},{"termId":29,"taxonomy":"pa_color"}]`.
    - `woocommerceHandPickedProducts` (type `array`): The hand-picked products to query by. It should contain the product IDs.
    - `priceRange` (type `object`): The price range to query by.
        - `min` (type `number`): The minimum price.
        - `max` (type `number`): The maximum price.

- `displayLayout` (type `object`): The display layout object that defines the layout of the collection. It can contain the following fields:
    - `type` (type `string`): The type of layout. Accepted values are `grid`, `stack` and `carousel`.
    - `columns` (type `number`): The number of columns to display.
    - `shrinkColumns` (type `boolean`): Whether the layout should be responsive.

- `hideControls` (type `array`): The controls to hide. Possible values:
    - `order` - "Order by" setting
    - `attributes` - "Product Attributes" filter
    - `created` - "Created" filter
    - `featured` - "Featured" filter
    - `hand-picked` - "Hand-picked Products" filter
    - `keyword` - "Keyword" filter
    - `on-sale` - "On Sale" filter
    - `stock-status` - "Stock Status" filter
    - `taxonomy` - "Product Categories", "Product Tags" and custom taxonomies filters
    - `price-range` - "Price Range" filter

#### Preview Attribute

The `preview` attribute is optional, and it is used to set the preview state of the collection. It can contain the following fields:

- `initialPreviewState` (type `object`): The initial preview state of the collection. It can contain the following fields:
    - `isPreview` (type `boolean`): Whether the collection is in preview mode.
    - `previewMessage` (type `string`): The message to be displayed in the Tooltip when the user hovers over the preview label.
- `setPreviewState` (optional, type `function`): The function to set the preview state of the collection. It receives the following arguments:
    - `setState` (type `function`): The function to set the preview state. You can pass a new preview state to this function containing `isPreview` and `previewMessage`.
    - `attributes` (type `object`): The current attributes of the collection.
    - `location` (type `object`): The location of the collection. Accepted values are `product`, `archive`, `cart`, `order`, `site`.

For more info, you may check [PR #46369](https://github.com/woocommerce/woocommerce/pull/46369), in which the Preview feature was added

## Examples

### Example 1: Registering a new collection

```tsx
__experimentalRegisterProductCollection({
  name: "your-plugin-name/product-collection/my-custom-collection",
  title: "My Custom Collection",
  icon: "games",
  description: "This is a custom collection.",
  keywords: ["custom collection", "product collection"],
});
```

As you can see in the example above, we are registering a new collection with the name `woocommerce/product-collection/my-custom-collection` & title `My Custom Collection`. Here is screenshot of how it will look like:
![image](https://github.com/woocommerce/woocommerce/assets/16707866/7fddbc02-a6cd-494e-b2f4-13dd5ef9cf96)

### Example 2: Register a new collection with a preview

As you can see below, setting the initial preview state is possible. In the example below, we are setting `isPreview` and `previewMessage`.

```tsx
__experimentalRegisterProductCollection({
  name: "your-plugin-name/product-collection/my-custom-collection-with-preview",
  title: "My Custom Collection with Preview",
  icon: "games",
  description: "This is a custom collection with preview.",
  keywords: ["My Custom Collection with Preview", "product collection"],
  preview: {
    initialPreviewState: {
      isPreview: true,
      previewMessage:
        "This is a preview message for my custom collection with preview.",
    },
  },
  attributes: {
    query: {
      perPage: 5,
      featured: true,
    },
    displayLayout: {
      type: "grid",
      columns: 3,
      shrinkColumns: true,
    },
	hideControls: [ "created", "stock-status" ]
  },
});
```

Here is how it will look like:
![image](https://github.com/woocommerce/woocommerce/assets/16707866/5fc1aa20-552a-4e09-b811-08babab46665)

### Example 3: Advanced usage of preview

As you can see below, it's also possible to use `setPreviewState` to set the preview state. In the example below, we are setting `initialPreviewState` and using `setPreviewState` to change the preview state after 5 seconds.

**This example shows:**

- How to access current attributes and location in the preview state
- How to use async operations
   	- We are using `setTimeout` to change the preview state after 5 seconds. You can use any async operation, like fetching data from an API, to decide the preview state.
- How to use the cleanup function as a return value
   	- We are returning a cleanup function that will clear the timeout after the component is unmounted. You can use this to clean up any resources you have used in `setPreviewState`.

```tsx
__experimentalRegisterProductCollection({
  name: "your-plugin-name/product-collection/my-custom-collection-with-advanced-preview",
  title: "My Custom Collection with Advanced Preview",
  icon: "games",
  description: "This is a custom collection with advanced preview.",
  keywords: [
    "My Custom Collection with Advanced Preview",
    "product collection",
  ],
  preview: {
    setPreviewState: ({
      setState,
      attributes: currentAttributes,
      location,
    }) => {
      // setPreviewState has access to the current attributes and location.
      // console.log( currentAttributes, location );

      const timeoutID = setTimeout(() => {
        setState({
          isPreview: false,
          previewMessage: "",
        });
      }, 5000);

      return () => clearTimeout(timeoutID);
    },
    initialPreviewState: {
      isPreview: true,
      previewMessage:
        "This is a preview message for my custom collection with advanced preview.",
    },
  },
});
```

### Example 4: Collection with inner blocks

As you can see below, it's also possible to define inner blocks for the collection. In the example below, we are defining inner blocks for the collection.

```tsx
__experimentalRegisterProductCollection({
  name: "your-plugin-name/product-collection/my-custom-collection-with-inner-blocks",
  title: "My Custom Collection with Inner Blocks",
  icon: "games",
  description: "This is a custom collection with inner blocks.",
  keywords: ["My Custom Collection with Inner Blocks", "product collection"],
  innerBlocks: [
    [
      "core/heading",
      {
        textAlign: "center",
        level: 2,
        content: "Title of the collection",
      },
    ],
    [
      "woocommerce/product-template",
      {},
      [
        ["woocommerce/product-image"],
        [
          "woocommerce/product-price",
          {
            textAlign: "center",
            fontSize: "small",
          },
        ],
      ],
    ],
  ],
});
```

This will create a collection with a heading, product image, and product price. Here is how it will look like:

![image](https://github.com/woocommerce/woocommerce/assets/16707866/3d92c084-91e9-4872-a898-080b4b93afca)

**Tip:** You can learn more about inner blocks template in the [Inner Blocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/#template) documentation.

### Example 5: Collection with `usesReference` argument

When a collection requires a reference to work properly, you can specify it using the `usesReference` argument. In the example below, we are defining a collection that requires a `product` reference.

```tsx
__experimentalRegisterProductCollection({
  name: "your-plugin-name/product-collection/my-custom-collection",
  title: "My Custom Collection",
  icon: "games",
  description: "This is a custom collection.",
  keywords: ["custom collection", "product collection"],
  usesReference: ["product"],
});
```

This will create a collection that requires a `product` reference. If the required reference isn't available on the Editor side but will be available in the Frontend, we will show a preview label.

When a collection need one of the multiple references, you can specify it using the `usesReference` argument. In the example below, we are defining a collection that requires either a `product` or `order` reference.

```tsx
__experimentalRegisterProductCollection({
  name: "your-plugin-name/product-collection/my-custom-collection",
  title: "My Custom Collection",
  icon: "games",
  description: "This is a custom collection.",
  keywords: ["custom collection", "product collection"],
  usesReference: ["product", "order"],
});
```

### Example 6: Scope argument

When you don't specify the `scope` argument, its default value is `["block", "inserter"]`. This default behavior is inherited from the [Block Variation API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/#defining-a-block-variation).

The Product Collection block uses the `block` scope to control:

1. Visibility in the Collection Chooser
2. Display of the "Choose Collection" toolbar button

#### Don't show collection in Collection Chooser

If you don't want to show your collection in the Collection Chooser, you can set the `scope` argument to an empty array or any other value that doesn't include the `block` value. 

For example:

```tsx
__experimentalRegisterProductCollection({
  name: "your-plugin-name/product-collection/my-custom-collection",
  title: "My Custom Collection",
  icon: "games",
  description: "This is a custom collection.",
  keywords: ["custom collection", "product collection"],
  scope: [],
});
```

#### Show collection in the block inserter only

If you want to show your collection exclusively in the block inserter and not in the Collection Chooser, you can set the `scope` argument to `["inserter"]`. This allows users to add your custom collection directly from the block inserter while keeping it hidden from the Collection Chooser interface.

For example:

```tsx
__experimentalRegisterProductCollection({
  name: "your-plugin-name/product-collection/my-custom-collection",
  title: "My Custom Collection",
  description: "This is a custom collection.",
  keywords: ["custom collection", "product collection"],
  scope: ["inserter"],
});
```


---

**Tip:** You can also take a look at how we are defining our core collections at [plugins/woocommerce/client/blocks/assets/js/blocks/product-collection/collections](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/assets/js/blocks/product-collection/collections/) directory. Our core collections will also evolve over time.


---

## On-Sale Badge block

*Source: block-development/extensible-blocks/product-sale-badge-block/README.md*

# On-Sale Badge block

The On-Sale Badge block displays a "Sale" badge on products that are on sale.

> **Note:** This block uses the slug `woocommerce/product-sale-badge`.

## `woocommerce_sale_badge_text`

### Description {/* omit in toc */}

The `woocommerce_sale_badge_text` filter allows customization of the sale badge text based on product context.

### Parameters {/* omit in toc */}

-   _$sale_text_ `string` (default: `'Sale'`) - The sale badge text.
-   _$product_ `WC_Product` - The product object.

### Returns {/* omit in toc */}

-   `string` - The filtered sale badge text.

### Code examples {/* omit in toc */}

#### Basic example {/* omit in toc */}

```php
add_filter( 'woocommerce_sale_badge_text', 'custom_sale_badge_text', 10, 2 );

function custom_sale_badge_text( $sale_text, $product ) {
	return __( 'On Sale', 'your-textdomain' );
}
```

#### Product-specific customization {/* omit in toc */}

```php
add_filter( 'woocommerce_sale_badge_text', 'custom_sale_badge_by_product_type', 10, 2 );

function custom_sale_badge_by_product_type( $sale_text, $product ) {
	if ( $product->is_type( 'variable' ) ) {
		return __( 'Save Now', 'your-textdomain' );
	}

	if ( $product->is_type( 'simple' ) ) {
		return __( 'Limited Offer', 'your-textdomain' );
	}

	return $sale_text;
}
```

#### Discount percentage {/* omit in toc */}

```php
add_filter( 'woocommerce_sale_badge_text', 'show_discount_percentage_badge', 10, 2 );

function show_discount_percentage_badge( $sale_text, $product ) {
	if ( $product->is_type( 'simple' ) || $product->is_type( 'external' ) ) {
		$regular_price = (float) $product->get_regular_price();
		$sale_price    = (float) $product->get_sale_price();

		if ( $regular_price > 0 ) {
			$percentage = round( ( ( $regular_price - $sale_price ) / $regular_price ) * 100 );
			return sprintf( __( '-%s%%', 'your-textdomain' ), $percentage );
		}
	}

	return $sale_text;
}
```

## Difference from `woocommerce_sale_flash`

| Aspect | `woocommerce_sale_badge_text` | `woocommerce_sale_flash` |
| --- | --- | --- |
| **Context** | On-Sale Badge block | Classic templates (`loop/sale-flash.php`, `single-product/sale-flash.php`) |
| **Output** | Plain text | HTML markup |
| **Parameters** | `$sale_text`, `$product` | `$html`, `$post`, `$product` |
| **Default** | `'Sale'` | `'<span class="onsale">Sale!</span>'` |
| **Since** | WooCommerce 10.0.0 | WooCommerce 2.x |

### Output handling

The block filter expects plain text only. HTML tags will be escaped and displayed as text.

```php
// Correct - plain text
add_filter( 'woocommerce_sale_badge_text', function( $text, $product ) {
	return 'Hot Deal';
}, 10, 2 );

// Incorrect - HTML will be escaped
add_filter( 'woocommerce_sale_badge_text', function( $text, $product ) {
	return '<strong>Hot Deal</strong>'; // Displays as "&lt;strong&gt;Hot Deal&lt;/strong&gt;"
}, 10, 2 );
```

The classic filter expects HTML markup:

```php
add_filter( 'woocommerce_sale_flash', function( $html, $post, $product ) {
	return '<span class="onsale">Hot Deal</span>';
}, 10, 3 );
```

### Supporting both

To support both block and classic themes, implement both filters:

```php
// Block filter
add_filter( 'woocommerce_sale_badge_text', 'my_custom_sale_badge', 10, 2 );

function my_custom_sale_badge( $sale_text, $product ) {
	return __( 'Special Offer', 'your-textdomain' );
}

// Classic filter
add_filter( 'woocommerce_sale_flash', 'my_classic_sale_flash', 10, 3 );

function my_classic_sale_flash( $html, $post, $product ) {
	return '<span class="onsale">' . __( 'Special Offer', 'your-textdomain' ) . '</span>';
}
```

## Notes

-   The sale badge only renders when `$product->is_on_sale()` returns `true`.
-   Filter output is escaped with `esc_html()` by the block.
-   For Cart and Checkout blocks, use the [`saleBadgePriceFormat` filter](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/cart-line-items/#salebadgepriceformat) instead.


---

## Extensibility in blocks

*Source: block-development/getting-started/extensibility-overview.md*

# Extensibility in blocks

These documents are all dealing with extensibility in the various WooCommerce Blocks.

## Imports and dependency extraction

The documentation in this section will use window globals in code examples, for example:

```js
const { registerCheckoutFilters } = window.wc.blocksCheckout;
```

However, if you're using `@woocommerce/dependency-extraction-webpack-plugin` for enhanced dependency management you can instead use ES module syntax:

```js
import { registerCheckoutFilters } from '@woocommerce/blocks-checkout';
```

See [@woocommerce/dependency-extraction-webpack-plugin](https://www.npmjs.com/package/@woocommerce/dependency-extraction-webpack-plugin) for more information.

## Hooks (actions and filters)

| Document | Description |
| --- | --- |
| [Actions](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md) | Documentation covering action hooks on the server side. |
| [Filters](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md) | Documentation covering filter hooks on the server side. |
| [Migrated Hooks](/docs/block-development/reference/hooks/migrated-hooks/) | Documentation covering the migrated WooCommerce core hooks. |

## REST API

| Document | Description |
| --- | --- |
| [Exposing your data in the Store API.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-add-data.md) | Explains how you can add additional data to Store API endpoints. |
| [Available endpoints to extend with ExtendSchema](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md) | A list of all available endpoints to extend. |
| [Available Formatters](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-formatters.md) | Available `Formatters` to format data for use in the Store API. |
| [Updating the cart with the Store API](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-update-cart.md) | Update the server-side cart following an action from the front-end. |

## Checkout Payment Methods

| Document | Description |
| --- | --- |
| [Checkout Flow and Events](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/checkout-payment-methods/checkout-flow-and-events/) | All about the checkout flow in the checkout block and the various emitted events that can be subscribed to. |
| [Payment Method Integration](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/checkout-payment-methods/payment-method-integration/) | Information about implementing payment methods. |
| [Filtering Payment Methods](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/checkout-payment-methods/filtering-payment-methods/) | Information about filtering the payment methods available in the Checkout Block. |

## Checkout Block

In addition to the reference material below, [please see the `block-checkout` package documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/README.md) which is used to extend checkout with Filters, Slot Fills, and Inner Blocks.

| Document | Description |
| --- | --- |
| [How the Checkout Block processes an order](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/how-checkout-processes-an-order/) | The detailed inner workings of the Checkout Flow. |
| [IntegrationInterface](/docs/block-development/reference/integration-interface/) | The `IntegrationInterface` class and how to use it to register scripts, styles, and data with WooCommerce Blocks. |
| [Available Filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/) | All about the filters that you may use to change values of certain elements of WooCommerce Blocks. |
| [Slots and Fills](/docs/block-development/reference/slot-fills/) | Explains Slot Fills and how to use them to render your own components in Cart and Checkout. |
| [Available Slot Fills](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/available-slot-fills/) | Available Slots that you can use and their positions in Cart and Checkout. |
| [DOM Events](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/dom-events/) | A list of DOM Events used by some blocks to communicate between them and with other parts of WooCommerce. |
| [Filter Registry](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/filter-registry/README.md) | The filter registry allows callbacks to be registered to manipulate certain values. |
| [Additional Checkout Fields](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/additional-checkout-fields/) | The filter registry allows callbacks to be registered to manipulate certain values. |


---

## Frequently Asked Questions

*Source: block-development/getting-started/faq.md*

# Frequently Asked Questions

This document aims to answer some of the frequently asked questions we see from developers extending WooCommerce Blocks.

We will add to the FAQ document as we receive questions, this isn't the document's final form.

If you have questions that aren't addressed here, we invite you to ask them on [GitHub Discussions](https://github.com/woocommerce/woocommerce/discussions) or in the [WooCommerce Community Slack](https://woocommerce.com/community-slack/)

## General questions

### How do I react to changes to the Cart or Checkout e.g. shipping method selection, or address changes?

The Cart and Checkout blocks read all their data from [`@wordpress/data` data stores](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/). We also have [documentation for the data stores WooCommerce Blocks uses](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/data-store).

It is common for developers to want to react to changes in the cart or checkout. For example, if a user changes their shipping method, or changes a line of their address.

There are two ways to do this, depending on how your code is running.

#### If your code is running in a React component

If your component is an inner block of the Cart/Checkout, or rendered in a [Slot/Fill](/docs/block-development/reference/slot-fills/), you can directly select the data you need from the relevant data store and perform any necessary actions when the data changes. For more information on available selectors, refer to the [documentation for the relevant data store](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/data-store).

```js
/**
 * External dependencies
 */
import { useSelect } from '@wordpress/data';
import { cartStore } from '@woocommerce/block-data';
import { useEffect } from '@wordpress/element';

export const MyComponent = () => {
	const { shippingAddress } = useSelect(
		( select ) => select( cartStore ).getCartData(),
		[]
	);
	useEffect( () => {
		// Do something when shippingAddress changes
	}, [ shippingAddress ] );
};
```

#### If your code is running in a non-React context

This would be true if you're not rendering a block, or running any React code. This means you won't have access to React hooks or custom hooks like `useSelect`. In this case you'd need to use the non-hook alternative to `useSelect` which is `select`. Given the requirement to react to changes, simply calling `select` will not be enough as this will only run once. You'll need to use the `subscribe` method to subscribe to changes to the data you're interested in.

```ts
/**
 * External dependencies
 */
import { select, subscribe } from '@wordpress/data';
import { cartStore } from '@woocommerce/block-data';

let previousCountry = '';
const unsubscribe = subscribe( () => {
  const { shippingAddress } = select( cartStore ).getCartData();
  if ( shippingAddress.country !== previousCountry ) {
    previousCountry = shippingAddress.country;
    // Do something when shipping country changes.
  }
  if ( /* some other condition that makes this subscription no longer needed */ ) {
    unsubscribe();
  }
}, cartStore );
```

Since the `subscribe` callback would run every time the data store receives an action, you'll need to use caching to avoid doing work when it isn't required. For example, if you only want to do work when the country changes, you would need to cache the previous value and compare it to the current value before running the task.

If you no longer need to react to changes, you can unsubscribe from the data store using the `unsubscribe` method which is returned by the `subscribe` method, like in the example above.

## Cart modifications

### How do I dynamically make changes to the cart from the client?

To perform actions on the server based on a client-side action, you'll need to use [`extensionCartUpdate`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-update-cart.md)

As an example, to add a "Get 10% off if you sign up to the mailing list" checkbox on your site you can use `extensionCartUpdate` to automatically apply a 10% coupon to the cart.

![Image](https://github.com/user-attachments/assets/e0d114b1-4e4c-4b34-9675-5571136b36d0)

Assuming you've already added the checkbox, either through the Additional Checkout Fields API, or by creating an inner block, the next step will be to register the server-side code to apply the coupon if the box is checked, and remove it if it's not.

```php
add_action('woocommerce_blocks_loaded', function() {
  woocommerce_store_api_register_update_callback(
    [
      'namespace' => 'extension-unique-namespace',
      'callback'  => function( $data ) {
        if ( isset( $data['checked'] ) && filter_var( $data['checked'], FILTER_VALIDATE_BOOLEAN ) === true ) {
          WC()->cart->apply_coupon( 'mailing-list-10-percent-coupon' );
        } else {
          WC()->cart->remove_coupon( 'mailing-list-10-percent-coupon' );
        }
      }
    ]
  );
} );
```

The code in the checkbox's event listener on the front end would look like this:

```js
const { extensionCartUpdate } = window.wc.blocksCheckout;

const onChange = ( checked ) => {
    extensionCartUpdate(
        {
            namespace: 'extension-unique-namespace',
            data: {
                checked
            }  
        } 
    )
}
```

To change how this coupon is displayed in the list of coupons in the order summary, you can use the `coupons` checkout filter, like so:

```js
const { registerCheckoutFilters } = window.wc.blocksCheckout;

const modifyCoupons = ( coupons, extensions, args ) => {
	return coupons.map( ( coupon ) => {
		if ( ! coupon.label === 'mailing-list-10-percent-coupon' ) {
			return coupon;
		}

		return {
			...coupon,
			label: 'Mailing list discount',
		};
	} );
};

registerCheckoutFilters( 'extension-unique-namespace', {
	coupons: modifyCoupons,
} );
```

### How do I add fees to the cart when a specific payment method is chosen?

You need to add the fees on the server based on the selected payment method, this can be achieved using the `woocommerce_cart_calculate_fees` action.

This is the server-side code required to add the fee:

```php
add_action(
	'woocommerce_cart_calculate_fees',
	function () {
		if ( is_admin() && ! defined( 'DOING_AJAX' ) ) {
			return;
		}

		$chosen_payment_method_id = WC()->session->get( 'chosen_payment_method' );
		$cart                     = WC()->cart;

		if ( 'your-payment-method-slug' === $chosen_payment_method_id ) {
			$percentage = 0.05;
			$surcharge  = ( $cart->cart_contents_total + $cart->shipping_total ) * $percentage;
			$cart->add_fee( 'Payment method fee', $surcharge );
		}
	}
);
```

### How to force-refresh the cart from the server

This can be achieved using [`extensionCartUpdate`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-update-cart.md) which is the preferred way, but it is also possible by executing the `receiveCart` action on the `wc/store/cart` data store with a valid cart object, like so:

```js
const { dispatch } = window.wp.data;

dispatch( 'wc/store/cart' ).receiveCart( cartObject )
```

All the cart routes on Store API return a cart object which can be used here. Passing an invalid cart object here will cause errors in the block.

You can also use:

```js
const { dispatch } = window.wp.data;

dispatch('wc/store/cart').invalidateResolutionForStore()
```

However, this will cause a brief flash of an empty cart while the new cart is fetched.

### How do I render something in each cart item?

This is currently **not** officially supported, however we have heard of developers doing this using DOM manipulation and React portals. If you choose to take this route, please note that your integrations may stop working if we make changes to the Cart block in the future. 

## Checkout modifications

### How do I remove checkout fields?

We don't encourage this due to the wide array of plugins WordPress and Woo support. Some of these may rely on certain checkout fields to function, but if you're certain the fields are safe to remove, please see [Removing Checkout Fields](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/removing-checkout-fields/).

### How do I modify the order or customer data during checkout?

If you want to modify order or customer data submitted during checkout you can use the `woocommerce_store_api_checkout_order_processed` action.

This action fires just before payment is processed. At this point you can modify the order as you would at any other point in the WooCommerce lifecycle, you still have to call `$order->save()` to persist the changes.

As an example, let's make sure the user's first and last names are capitalized:

```php
add_action(
  'woocommerce_store_api_checkout_order_processed',
  function( WC_Order $order ) {
    $order->set_shipping_first_name( ucfirst( $order->get_shipping_first_name() ) );
    $order->set_shipping_last_name( ucfirst( $order->get_shipping_last_name() ) );

    $order->set_billing_first_name( ucfirst( $order->get_billing_first_name() ) );
    $order->set_billing_last_name( ucfirst( $order->get_billing_last_name() ) );

    $order->save();
  }
);
```

### How do I render something in the Checkout block?

This depends on what you want to render.

#### Rendering a field

The recommended approach to rendering fields in the Checkout block is to use the [Additional Checkout Fields API](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/additional-checkout-fields/).

#### Rendering a custom block

To render a custom block in the Checkout block, the recommended approach is to create a child block of one of the existing Checkout inner blocks. Register the block on both the server and the client. WooCommerce uses the server-registered `parent` metadata to make the block's saved attributes available to its frontend component; a block registered only in JavaScript may work in the editor but lose its attributes on the frontend.

The [`@woocommerce/extend-cart-checkout-block`](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/extend-cart-checkout-block/README.md) template demonstrates the complete registration path. Please note that this example contains multiple other examples of extensibility, not just inner blocks. See the [Checkout Blocks Registry documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/public-api/blocks-checkout/blocks-registry/README.md#registering-a-block) for registration details and frontend attribute handling.


---

## Blocks reference

*Source: block-development/reference/block-references.md*

# Blocks reference

This page lists the Woo blocks included in the package. (Incomplete as there are still blocks that are not using block.json definition).

{/* START Autogenerated - DO NOT EDIT */}

## Accordion Group - woocommerce/accordion-group

A group of headers and associated expandable content.

- **Name:** woocommerce/accordion-group
- **Category:** woocommerce
- **Supports:** align (full, wide), background (backgroundImage, backgroundSize), color (background, gradient, text), interactivity, layout, shadow, spacing (blockGap, margin, padding), ~~html~~
- **Attributes:** allowedBlocks, autoclose, iconPosition

## Accordion Header - woocommerce/accordion-header

Accordion header.

- **Name:** woocommerce/accordion-header
- **Category:** woocommerce
- **Parent:** woocommerce/accordion-item
- **Supports:** anchor, border, color (background, gradient, text), interactivity, layout, shadow, spacing (margin, padding), typography (fontSize, textAlign), ~~align~~
- **Attributes:** icon, iconPosition, level, levelOptions, openByDefault, textAlignment, title

## Accordion - woocommerce/accordion-item

A single accordion that displays a header and expandable content.

- **Name:** woocommerce/accordion-item
- **Category:** woocommerce
- **Parent:** woocommerce/accordion-group
- **Supports:** align (full, wide), color (background, gradient, text), interactivity, layout, shadow, spacing (blockGap, margin)
- **Attributes:** openByDefault

## Accordion Panel - woocommerce/accordion-panel

Accordion Panel

- **Name:** woocommerce/accordion-panel
- **Category:** woocommerce
- **Parent:** woocommerce/accordion-item
- **Supports:** border, color (background, gradient, text), interactivity, layout, shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight)
- **Attributes:** allowedBlocks, isSelected, openByDefault, templateLock

## Active Filters Controls - woocommerce/active-filters

Display the currently active filters.

- **Name:** woocommerce/active-filters
- **Category:** woocommerce
- **Supports:** color (text, ~~background~~), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~
- **Attributes:** displayStyle, headingLevel

## Add to Cart with Options - woocommerce/add-to-cart-form

Display a button that lets customers add a product to their cart. Use the added options to optimize for different product types.

- **Name:** woocommerce/add-to-cart-form
- **Category:** woocommerce-product-elements
- **Supports:** interactivity
- **Attributes:** quantitySelectorStyle

## Add to Cart + Options (Beta) - woocommerce/add-to-cart-with-options

Use blocks to create an "Add to cart" area that's customized for different product types, such as variable and grouped. 

- **Name:** woocommerce/add-to-cart-with-options
- **Category:** woocommerce-product-elements
- **Supports:** interactivity
- **Attributes:** isDescendantOfAddToCartWithOptions

## Grouped Product Selector (Beta) - woocommerce/add-to-cart-with-options-grouped-product-selector

Display a group of products that can be added to the cart.

- **Name:** woocommerce/add-to-cart-with-options-grouped-product-selector
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/add-to-cart-with-options
- **Supports:** interactivity

## Grouped Product: Template (Beta) - woocommerce/add-to-cart-with-options-grouped-product-item

A list item template that represents a child product within the Grouped Product Selector block.

- **Name:** woocommerce/add-to-cart-with-options-grouped-product-item
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/add-to-cart-with-options-grouped-product-selector
- **Supports:** interactivity, ~~inserter~~

## Grouped Product: Item Label (Beta) - woocommerce/add-to-cart-with-options-grouped-product-item-label

Display the product title as a label or paragraph.

- **Name:** woocommerce/add-to-cart-with-options-grouped-product-item-label
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/add-to-cart-with-options-grouped-product-item
- **Supports:** color (background, gradients, text), layout (selfStretch), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~

## Grouped Product: Item Selector (Beta) - woocommerce/add-to-cart-with-options-grouped-product-item-selector

Add a way of selecting a child product within the Grouped Product block. Depending on the type of product and its properties, this might be a button, a checkbox, or a link.

- **Name:** woocommerce/add-to-cart-with-options-grouped-product-item-selector
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/add-to-cart-with-options-grouped-product-item
- **Supports:** interactivity, ~~inserter~~

## Product Quantity (Beta) - woocommerce/add-to-cart-with-options-quantity-selector

Display an input field customers can use to select the number of products to add to their cart. 

- **Name:** woocommerce/add-to-cart-with-options-quantity-selector
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/add-to-cart-with-options
- **Supports:** color (background, text), interactivity, shadow

## Variation Description (Beta) - woocommerce/add-to-cart-with-options-variation-description

Displays the description of the selected variation.

- **Name:** woocommerce/add-to-cart-with-options-variation-description
- **Category:** woocommerce
- **Ancestor:** woocommerce/add-to-cart-with-options
- **Supports:** color (background, gradients, link, text), dimensions (minHeight), interactivity, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~

## Variation Selector: Template (Beta) - woocommerce/add-to-cart-with-options-variation-selector-attribute

A template for attribute name and options that will be applied to all variable products with attributes.

- **Name:** woocommerce/add-to-cart-with-options-variation-selector-attribute
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/add-to-cart-with-options-variation-selector
- **Supports:** interactivity, ~~inserter~~
- **Attributes:** autoselect, disabledAttributesAction, displayStyle

## Variation Selector: Attribute Name (Beta) - woocommerce/add-to-cart-with-options-variation-selector-attribute-name

Format the name of an attribute associated with a variable product.

- **Name:** woocommerce/add-to-cart-with-options-variation-selector-attribute-name
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/add-to-cart-with-options-variation-selector-attribute
- **Supports:** color (background, gradients, text), interactivity, spacing (padding), typography (fontSize, lineHeight), ~~alignWide~~, ~~align~~, ~~inserter~~

## Variation Selector (Beta) - woocommerce/add-to-cart-with-options-variation-selector

Display any product variations available to select from and add to cart.

- **Name:** woocommerce/add-to-cart-with-options-variation-selector
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/add-to-cart-with-options
- **Supports:** interactivity

## Add to Wishlist Button - woocommerce/add-to-wishlist-button

Lets shoppers add the current product to their wishlist from the single-product page.

- **Name:** woocommerce/add-to-wishlist-button
- **Category:** woocommerce
- **Ancestor:** woocommerce/add-to-cart-with-options
- **Supports:** color (background, text), interactivity, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~multiple~~, ~~reusable~~

## Filter by Attribute Controls - woocommerce/attribute-filter

Enable customers to filter the product grid by selecting one or more attributes, such as color.

- **Name:** woocommerce/attribute-filter
- **Category:** woocommerce
- **Supports:** color (text, ~~background~~), ~~html~~, ~~inserter~~, ~~interactivity~~, ~~lock~~
- **Attributes:** attributeId, className, displayStyle, headingLevel, isPreview, queryType, selectType, showCounts, showFilterButton

## Store Breadcrumbs - woocommerce/breadcrumbs

Enable customers to keep track of their location within the store and navigate back to parent pages.

- **Name:** woocommerce/breadcrumbs
- **Category:** woocommerce
- **Supports:** align (full, wide), color (link, text, ~~background~~), interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** align, contentJustification, fontSize

## Accepted Payment Methods - woocommerce/cart-accepted-payment-methods-block

Display accepted payment methods.

- **Name:** woocommerce/cart-accepted-payment-methods-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-totals-block
- **Supports:** inserter, ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~

## Cart Cross-Sells - woocommerce/cart-cross-sells-block

Shows the Cross-Sells block.

- **Name:** woocommerce/cart-cross-sells-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-items-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~multiple~~, ~~reusable~~

## Cart Cross-Sells Products - woocommerce/cart-cross-sells-products-block

Shows the Cross-Sells products.

- **Name:** woocommerce/cart-cross-sells-products-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-cross-sells-block
- **Supports:** email, ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** columns, lock

## Express Checkout - woocommerce/cart-express-payment-block

Allow customers to breeze through with quick payment options.

- **Name:** woocommerce/cart-express-payment-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** buttonBorderRadius, buttonHeight, lock, showButtonStyles

## Cart Items - woocommerce/cart-items-block

Column containing cart items.

- **Name:** woocommerce/cart-items-block
- **Category:** woocommerce
- **Parent:** woocommerce/filled-cart-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Cart Line Items - woocommerce/cart-line-items-block

Block containing current line items in Cart.

- **Name:** woocommerce/cart-line-items-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-items-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Order Summary - woocommerce/cart-order-summary-block

Show customers a summary of their order.

- **Name:** woocommerce/cart-order-summary-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Coupon Form - woocommerce/cart-order-summary-coupon-form-block

Shows the apply coupon form.

- **Name:** woocommerce/cart-order-summary-coupon-form-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-order-summary-block
- **Supports:** ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Discount - woocommerce/cart-order-summary-discount-block

Shows the cart discount row.

- **Name:** woocommerce/cart-order-summary-discount-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Fees - woocommerce/cart-order-summary-fee-block

Shows the cart fee row.

- **Name:** woocommerce/cart-order-summary-fee-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Heading - woocommerce/cart-order-summary-heading-block

Shows the heading row.

- **Name:** woocommerce/cart-order-summary-heading-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-order-summary-block
- **Supports:** ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, content, lock

## Shipping - woocommerce/cart-order-summary-shipping-block

Shows the cart shipping row.

- **Name:** woocommerce/cart-order-summary-shipping-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Subtotal - woocommerce/cart-order-summary-subtotal-block

Shows the cart subtotal row.

- **Name:** woocommerce/cart-order-summary-subtotal-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Taxes - woocommerce/cart-order-summary-taxes-block

Shows the cart taxes row.

- **Name:** woocommerce/cart-order-summary-taxes-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Totals - woocommerce/cart-order-summary-totals-block

Shows the subtotal, fees, discounts, shipping and taxes.

- **Name:** woocommerce/cart-order-summary-totals-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-order-summary-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Cart Totals - woocommerce/cart-totals-block

Column containing the cart totals.

- **Name:** woocommerce/cart-totals-block
- **Category:** woocommerce
- **Parent:** woocommerce/filled-cart-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** checkbox, lock, text

## Empty Cart - woocommerce/empty-cart-block

Contains blocks that are displayed when the cart is empty.

- **Name:** woocommerce/empty-cart-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart
- **Supports:** align (wide), ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Filled Cart - woocommerce/filled-cart-block

Contains blocks that are displayed when the cart contains products.

- **Name:** woocommerce/filled-cart-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart
- **Supports:** align (wide), ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Proceed to Checkout - woocommerce/proceed-to-checkout-block

Allow customers proceed to Checkout.

- **Name:** woocommerce/proceed-to-checkout-block
- **Category:** woocommerce
- **Parent:** woocommerce/cart-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Cart Link - woocommerce/cart-link

Display a link to the cart.

- **Name:** woocommerce/cart-link
- **Category:** woocommerce
- **Supports:** color (background, link, ~~text~~), interactivity (clientNavigation), spacing (padding), typography (fontSize), ~~html~~, ~~multiple~~
- **Attributes:** cartIcon, content

## Catalog Sorting - woocommerce/catalog-sorting

Enable customers to change the sorting order of the products.

- **Name:** woocommerce/catalog-sorting
- **Category:** woocommerce
- **Supports:** color (text, ~~background~~), interactivity, typography (fontSize)
- **Attributes:** fontSize, useLabel

## Product Category Description - woocommerce/category-description

Displays the current category description.

- **Name:** woocommerce/category-description
- **Category:** woocommerce
- **Supports:** color (background, text), spacing (margin, padding), typography, ~~align~~, ~~html~~
- **Attributes:** textAlign

## Product Category Title - woocommerce/category-title

Displays the current category title and lets permitted users edit it.

- **Name:** woocommerce/category-title
- **Category:** woocommerce
- **Supports:** color (background, text), spacing (margin, padding), typography, ~~align~~, ~~html~~
- **Attributes:** isLink, level, linkTarget, rel, textAlign

## Checkout - woocommerce/checkout

Display a checkout form so your customers can submit orders.

- **Name:** woocommerce/checkout
- **Category:** woocommerce
- **Supports:** align (wide), ~~html~~, ~~multiple~~
- **Attributes:** align, showFormStepNumbers

## Actions - woocommerce/checkout-actions-block

Allow customers to place their order.

- **Name:** woocommerce/checkout-actions-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** cartPageId, className, lock, priceSeparator, showReturnToCart

## Additional information - woocommerce/checkout-additional-information-block

Render additional fields in the 'Additional information' location.

- **Name:** woocommerce/checkout-additional-information-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Billing Address - woocommerce/checkout-billing-address-block

Collect your customer's billing address.

- **Name:** woocommerce/checkout-billing-address-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Contact Information - woocommerce/checkout-contact-information-block

Collect your customer's contact information.

- **Name:** woocommerce/checkout-contact-information-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Express Checkout - woocommerce/checkout-express-payment-block

Allow customers to breeze through with quick payment options.

- **Name:** woocommerce/checkout-express-payment-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** buttonBorderRadius, buttonHeight, className, lock, showButtonStyles

## Checkout Fields - woocommerce/checkout-fields-block

Column containing checkout address fields.

- **Name:** woocommerce/checkout-fields-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Order Note - woocommerce/checkout-order-note-block

Allow customers to add a note to their order.

- **Name:** woocommerce/checkout-order-note-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Order Summary - woocommerce/checkout-order-summary-block

Show customers a summary of their order.

- **Name:** woocommerce/checkout-order-summary-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Cart Items - woocommerce/checkout-order-summary-cart-items-block

Shows cart items.

- **Name:** woocommerce/checkout-order-summary-cart-items-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-order-summary-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, disableProductDescriptions, lock

## Coupon Form - woocommerce/checkout-order-summary-coupon-form-block

Shows the apply coupon form.

- **Name:** woocommerce/checkout-order-summary-coupon-form-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-order-summary-block
- **Supports:** ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Discount - woocommerce/checkout-order-summary-discount-block

Shows the cart discount row.

- **Name:** woocommerce/checkout-order-summary-discount-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Fees - woocommerce/checkout-order-summary-fee-block

Shows the cart fee row.

- **Name:** woocommerce/checkout-order-summary-fee-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Shipping - woocommerce/checkout-order-summary-shipping-block

Shows the cart shipping row.

- **Name:** woocommerce/checkout-order-summary-shipping-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Subtotal - woocommerce/checkout-order-summary-subtotal-block

Shows the cart subtotal row.

- **Name:** woocommerce/checkout-order-summary-subtotal-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Taxes - woocommerce/checkout-order-summary-taxes-block

Shows the cart taxes row.

- **Name:** woocommerce/checkout-order-summary-taxes-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-order-summary-totals-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Totals - woocommerce/checkout-order-summary-totals-block

Shows the subtotal, fees, discounts, shipping and taxes.

- **Name:** woocommerce/checkout-order-summary-totals-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-order-summary-block
- **Supports:** ~~align~~, ~~html~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** className, lock

## Payment Options - woocommerce/checkout-payment-block

Payment options for your store.

- **Name:** woocommerce/checkout-payment-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Pickup Method - woocommerce/checkout-pickup-options-block

Shows local pickup locations.

- **Name:** woocommerce/checkout-pickup-options-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Shipping Address - woocommerce/checkout-shipping-address-block

Collect your customer's shipping address.

- **Name:** woocommerce/checkout-shipping-address-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Delivery - woocommerce/checkout-shipping-method-block

Select between shipping or local pickup.

- **Name:** woocommerce/checkout-shipping-method-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Shipping Options - woocommerce/checkout-shipping-methods-block

Display shipping options and rates for your store.

- **Name:** woocommerce/checkout-shipping-methods-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Terms and Conditions - woocommerce/checkout-terms-block

Ensure that customers agree to your Terms & Conditions and Privacy Policy.

- **Name:** woocommerce/checkout-terms-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout-fields-block
- **Supports:** ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** checkbox, className, showSeparator, text

## Checkout Totals - woocommerce/checkout-totals-block

Column containing the checkout totals.

- **Name:** woocommerce/checkout-totals-block
- **Category:** woocommerce
- **Parent:** woocommerce/checkout
- **Supports:** ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** checkbox, className, text

## Classic Shortcode - woocommerce/classic-shortcode

Renders classic WooCommerce shortcodes.

- **Name:** woocommerce/classic-shortcode
- **Category:** woocommerce
- **Supports:** align, inserter, interactivity (~~clientNavigation~~), ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** align, shortcode

## Coming Soon - woocommerce/coming-soon



- **Name:** woocommerce/coming-soon
- **Category:** woocommerce
- **Supports:** color (background, text), ~~inserter~~
- **Attributes:** color, comingSoonPatternId, storeOnly

## Coupon Code - woocommerce/coupon-code

Include a coupon code to entice customers to make a purchase.

- **Name:** woocommerce/coupon-code
- **Category:** woocommerce
- **Supports:** align, color (background, text), email, spacing (margin, padding), typography (fontSize), ~~html~~
- **Attributes:** amount, couponCode, discountType, emailRestrictions, excludeSaleItems, excludedProductCategoryIds, excludedProductIds, expiryDay, freeShipping, individualUse, maximumAmount, minimumAmount, productCategoryIds, productIds, source, usageLimit, usageLimitPerUser

## Customer account - woocommerce/customer-account

A block that allows your customers to log in and out of their accounts in your store.

- **Name:** woocommerce/customer-account
- **Category:** woocommerce
- **Supports:** align, color (background, text), interactivity, spacing (margin, padding), typography (fontSize)
- **Attributes:** displayStyle, hasDropdownNavigation, iconClass, iconStyle

## Dropdown - woocommerce/dropdown

Display options in a dropdown.

- **Name:** woocommerce/dropdown
- **Category:** woocommerce
- **Ancestor:** woocommerce/add-to-cart-with-options-variation-selector-attribute
- **Supports:** interactivity, woocommerce (innerBlockDisplayStyle)

## Email Content - woocommerce/email-content

A placeholder block for email content.

- **Name:** woocommerce/email-content
- **Category:** woocommerce
- **Supports:** email, ~~inserter~~
- **Attributes:** emailType, postId

## Featured Category - woocommerce/featured-category

Visually highlight a product category and encourage prompt action.

- **Name:** woocommerce/featured-category
- **Category:** woocommerce
- **Supports:** align (full, wide), ariaLabel, color (background, text), filter (duotone), interactivity (clientNavigation), spacing (padding), ~~html~~
- **Attributes:** alt, categoryId, contentAlign, dimRatio, focalPoint, hasParallax, imageFit, isRepeated, linkText, mediaId, mediaSrc, minHeight, overlayColor, overlayGradient, previewCategory

## Featured Product - woocommerce/featured-product

Highlight a product or variation.

- **Name:** woocommerce/featured-product
- **Category:** woocommerce
- **Supports:** align (full, wide), ariaLabel, color (background, text), filter (duotone), interactivity (clientNavigation), multiple, spacing (padding), ~~html~~
- **Attributes:** alt, contentAlign, dimRatio, focalPoint, hasParallax, imageFit, isRepeated, linkText, mediaId, mediaSrc, minHeight, overlayColor, overlayGradient, previewProduct, productId

## Filter Block - woocommerce/filter-wrapper



- **Name:** woocommerce/filter-wrapper
- **Category:** woocommerce
- **Supports:** interactivity (~~clientNavigation~~), ~~inserter~~
- **Attributes:** filterType, heading

## Hand-picked Products - woocommerce/handpicked-products

Display a selection of hand-picked products in a grid.

- **Name:** woocommerce/handpicked-products
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~
- **Attributes:** align, alignButtons, columns, contentVisibility, isPreview, orderby, products

## Mini-Cart - woocommerce/mini-cart

Display a button for shoppers to quickly view their cart.

- **Name:** woocommerce/mini-cart
- **Category:** woocommerce
- **Supports:** interactivity, spacing (margin, padding), typography (fontSize), ~~html~~, ~~multiple~~
- **Attributes:** addToCartBehaviour, cartAndCheckoutRenderStyle, hasHiddenPrice, iconColor, iconColorValue, miniCartIcon, onCartClickBehaviour, priceColor, priceColorValue, productCountColor, productCountColorValue, productCountVisibility

## Mini-Cart Contents - woocommerce/mini-cart-contents

Display a Mini-Cart widget.

- **Name:** woocommerce/mini-cart-contents
- **Category:** woocommerce
- **Supports:** color (background, link, text), ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock, width

## Empty Mini-Cart view - woocommerce/empty-mini-cart-contents-block

Blocks that are displayed when the Mini-Cart is empty.

- **Name:** woocommerce/empty-mini-cart-contents-block
- **Category:** woocommerce
- **Parent:** woocommerce/mini-cart-contents
- **Supports:** interactivity, ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Filled Mini-Cart view - woocommerce/filled-mini-cart-contents-block

Contains blocks that display the content of the Mini-Cart.

- **Name:** woocommerce/filled-mini-cart-contents-block
- **Category:** woocommerce
- **Parent:** woocommerce/mini-cart-contents
- **Supports:** interactivity, ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Mini-Cart View Cart Button - woocommerce/mini-cart-cart-button-block

Block that displays the cart button when the Mini-Cart has products.

- **Name:** woocommerce/mini-cart-cart-button-block
- **Category:** woocommerce
- **Parent:** woocommerce/mini-cart-footer-block
- **Supports:** color (background, text), inserter, interactivity (clientNavigation), ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** cartButtonLabel, lock

## Mini-Cart Proceed to Checkout Button - woocommerce/mini-cart-checkout-button-block

Block that displays the checkout button when the Mini-Cart has products.

- **Name:** woocommerce/mini-cart-checkout-button-block
- **Category:** woocommerce
- **Parent:** woocommerce/mini-cart-footer-block
- **Supports:** color (background, text), inserter, interactivity (clientNavigation), ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** checkoutButtonLabel, lock

## Mini-Cart Footer - woocommerce/mini-cart-footer-block

Block that displays the footer of the Mini-Cart block.

- **Name:** woocommerce/mini-cart-footer-block
- **Category:** woocommerce
- **Parent:** woocommerce/filled-mini-cart-contents-block
- **Supports:** interactivity, ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Mini-Cart Items - woocommerce/mini-cart-items-block

Contains the products table and other custom blocks of filled mini-cart.

- **Name:** woocommerce/mini-cart-items-block
- **Category:** woocommerce
- **Parent:** woocommerce/filled-mini-cart-contents-block
- **Supports:** interactivity (clientNavigation), ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Mini-Cart Products Table - woocommerce/mini-cart-products-table-block

Block that displays the products table of the Mini-Cart block.

- **Name:** woocommerce/mini-cart-products-table-block
- **Category:** woocommerce
- **Parent:** woocommerce/mini-cart-items-block
- **Supports:** interactivity, ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Mini-Cart Shopping Button - woocommerce/mini-cart-shopping-button-block

Block that displays the shopping button when the Mini-Cart is empty.

- **Name:** woocommerce/mini-cart-shopping-button-block
- **Category:** woocommerce
- **Parent:** woocommerce/empty-mini-cart-contents-block
- **Supports:** color (background, text), inserter, interactivity (clientNavigation), ~~align~~, ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock, startShoppingButtonLabel

## Mini-Cart Title - woocommerce/mini-cart-title-block

Block that displays the title of the Mini-Cart block.

- **Name:** woocommerce/mini-cart-title-block
- **Category:** woocommerce
- **Parent:** woocommerce/filled-mini-cart-contents-block
- **Supports:** color (text, ~~background~~), interactivity (clientNavigation), typography (fontSize), ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** lock

## Mini-Cart Title Items Counter - woocommerce/mini-cart-title-items-counter-block

Block that displays the items counter part of the Mini-Cart Title block.

- **Name:** woocommerce/mini-cart-title-items-counter-block
- **Category:** woocommerce
- **Parent:** woocommerce/mini-cart-title-block
- **Supports:** color (background, text), interactivity, spacing (padding), typography (fontSize), ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~

## Mini-Cart Title Label - woocommerce/mini-cart-title-label-block

Block that displays the 'Your cart' part of the Mini-Cart Title block.

- **Name:** woocommerce/mini-cart-title-label-block
- **Category:** woocommerce
- **Parent:** woocommerce/mini-cart-title-block
- **Supports:** color (background, text), interactivity (clientNavigation), spacing (padding), typography (fontSize), ~~align~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~, ~~reusable~~
- **Attributes:** label

## Next/Previous Buttons - woocommerce/product-gallery-large-image-next-previous

Display next and previous buttons.

- **Name:** woocommerce/product-gallery-large-image-next-previous
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-gallery-large-image, woocommerce/product-collection
- **Supports:** align, color (background, text), interactivity, layout (allowVerticalAlignment, default, ~~allowJustification~~, ~~allowOrientation~~), shadow, spacing (margin)

## Additional Field List - woocommerce/order-confirmation-additional-fields

Display the list of additional field values from the current order.

- **Name:** woocommerce/order-confirmation-additional-fields
- **Category:** woocommerce
- **Supports:** align (full, wide), spacing (margin, padding), ~~html~~, ~~multiple~~
- **Attributes:** align, className

## Additional Fields - woocommerce/order-confirmation-additional-fields-wrapper

Display additional checkout fields from the 'contact' and 'order' locations.

- **Name:** woocommerce/order-confirmation-additional-fields-wrapper
- **Category:** woocommerce
- **Supports:** align (full, wide), spacing (margin, padding), ~~html~~, ~~multiple~~
- **Attributes:** heading

## Additional Information - woocommerce/order-confirmation-additional-information

Displays additional information provided by third-party extensions for the current order.

- **Name:** woocommerce/order-confirmation-additional-information
- **Category:** woocommerce
- **Supports:** align (full, wide), spacing (margin, padding), ~~html~~, ~~multiple~~
- **Attributes:** align, className

## Billing Address - woocommerce/order-confirmation-billing-address

Display the order confirmation billing address.

- **Name:** woocommerce/order-confirmation-billing-address
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~inserter~~, ~~multiple~~
- **Attributes:** align

## Billing Address Section - woocommerce/order-confirmation-billing-wrapper

Display the order confirmation billing section.

- **Name:** woocommerce/order-confirmation-billing-wrapper
- **Category:** woocommerce
- **Supports:** align (full, wide), spacing (margin, padding), ~~html~~, ~~multiple~~
- **Attributes:** heading

## Account Creation - woocommerce/order-confirmation-create-account

Allow customers to create an account after their purchase.

- **Name:** woocommerce/order-confirmation-create-account
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, button, text), spacing (margin, padding), ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~
- **Attributes:** align, className, customerEmail, hasDarkControls, lock, nonceToken

## Order Downloads - woocommerce/order-confirmation-downloads

Display links to purchased downloads.

- **Name:** woocommerce/order-confirmation-downloads
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, gradients, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~multiple~~
- **Attributes:** align, className

## Downloads Section - woocommerce/order-confirmation-downloads-wrapper

Display the downloadable products section.

- **Name:** woocommerce/order-confirmation-downloads-wrapper
- **Category:** woocommerce
- **Supports:** align (full, wide), spacing (margin, padding), ~~html~~, ~~multiple~~
- **Attributes:** heading

## Shipping Address - woocommerce/order-confirmation-shipping-address

Display the order confirmation shipping address.

- **Name:** woocommerce/order-confirmation-shipping-address
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~inserter~~, ~~multiple~~
- **Attributes:** align

## Shipping Address Section - woocommerce/order-confirmation-shipping-wrapper

Display the order confirmation shipping section.

- **Name:** woocommerce/order-confirmation-shipping-wrapper
- **Category:** woocommerce
- **Supports:** align (full, wide), spacing (margin, padding), ~~html~~, ~~multiple~~
- **Attributes:** heading

## Order Status - woocommerce/order-confirmation-status

Display a "thank you" message, or a sentence regarding the current order status.

- **Name:** woocommerce/order-confirmation-status
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, gradients, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~multiple~~
- **Attributes:** align, className

## Order Summary - woocommerce/order-confirmation-summary

Display the order summary on the order confirmation page.

- **Name:** woocommerce/order-confirmation-summary
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, gradients, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~multiple~~
- **Attributes:** align, className

## Order Totals - woocommerce/order-confirmation-totals

Display the items purchased and order totals.

- **Name:** woocommerce/order-confirmation-totals
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, gradients, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~multiple~~
- **Attributes:** align, className

## Order Totals Section - woocommerce/order-confirmation-totals-wrapper

Display the order details section.

- **Name:** woocommerce/order-confirmation-totals-wrapper
- **Category:** woocommerce
- **Supports:** align (full, wide), spacing (margin, padding), ~~html~~, ~~multiple~~
- **Attributes:** heading

## WooCommerce Page - woocommerce/page-content-wrapper

Displays WooCommerce page content.

- **Name:** woocommerce/page-content-wrapper
- **Category:** woocommerce
- **Supports:** ~~html~~, ~~inserter~~, ~~multiple~~
- **Attributes:** page

## Payment Method Icons - woocommerce/payment-method-icons

Display icons for available payment methods.

- **Name:** woocommerce/payment-method-icons
- **Category:** woocommerce
- **Supports:** spacing (margin, padding)
- **Attributes:** numberOfIcons

## Filter by Price Controls - woocommerce/price-filter

Enable customers to filter the product grid by choosing a price range.

- **Name:** woocommerce/price-filter
- **Category:** woocommerce
- **Supports:** color (text, ~~background~~), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~
- **Attributes:** className, headingLevel, inlineInput, showFilterButton, showInputFields

## Best Selling Products - woocommerce/product-best-sellers

Display a grid of your all-time best selling products.

- **Name:** woocommerce/product-best-sellers
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~
- **Attributes:** alignButtons, catOperator, categories, columns, contentVisibility, editMode, isPreview, orderby, rows, stockStatus

## Product Categories List - woocommerce/product-categories

Show all product categories as a list or dropdown.

- **Name:** woocommerce/product-categories
- **Category:** woocommerce
- **Supports:** align (full, wide), color (link, text, ~~background~~), interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** align, hasCount, hasEmpty, hasImage, isDropdown, isHierarchical, showChildrenOnly

## Products by Category - woocommerce/product-category

Display a grid of products from your selected categories.

- **Name:** woocommerce/product-category
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~
- **Attributes:** alignButtons, catOperator, categories, columns, contentVisibility, editMode, isPreview, orderby, rows, stockStatus

## Product Collection - woocommerce/product-collection

Display a collection of products from your store.

- **Name:** woocommerce/product-collection
- **Category:** woocommerce
- **Supports:** align (full, wide), anchor, email, interactivity, ~~html~~
- **Attributes:** __privatePreviewState, collection, convertedFromProducts, dimensions, displayLayout, forcePageReload, hideControls, query, queryContextIncludes, queryId, tagName

## No results - woocommerce/product-collection-no-results

The contents of this block will display when there are no products found.

- **Name:** woocommerce/product-collection-no-results
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-collection
- **Supports:** align, color (background, gradients, link, text), email, interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~

## Product Description - woocommerce/product-description

Displays the description of the product.

- **Name:** woocommerce/product-description
- **Category:** woocommerce
- **Ancestor:** woocommerce/single-product, woocommerce/product-template, core/post-template
- **Supports:** align (full, wide), background (backgroundImage, backgroundSize), color (background, gradients, heading, link, text), dimensions (minHeight), interactivity (clientNavigation), layout, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~

## Product Details - woocommerce/product-details

Display a product's description, attributes, and reviews

- **Name:** woocommerce/product-details
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, ~~text~~), interactivity (clientNavigation), spacing (margin, padding)
- **Attributes:** align, hideTabTitle

## Product Average Rating (Beta) - woocommerce/product-average-rating

Display the average rating of a product

- **Name:** woocommerce/product-average-rating
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/single-product
- **Supports:** color (background, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize)
- **Attributes:** textAlign

## Add to Cart Button - woocommerce/product-button

Display a call to action button which either adds the product to the cart, or links to the product page.

- **Name:** woocommerce/product-button
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/all-products, woocommerce/single-product, core/post-template, woocommerce/product-template
- **Supports:** align (full, wide), color (background, text, ~~link~~), email, interactivity, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** productId, textAlign, width

## Product Image - woocommerce/product-image

Display the main product image.

- **Name:** woocommerce/product-image
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/all-products, woocommerce/single-product, woocommerce/product-template, core/post-template
- **Supports:** dimensions (aspectRatio), email, interactivity (clientNavigation), spacing (margin, padding), typography (fontSize), ~~html~~
- **Attributes:** aspectRatio, height, imageSizing, productId, saleBadgeAlign, scale, showProductLink, showSaleBadge, width

## Product Price - woocommerce/product-price

Display the price of a product.

- **Name:** woocommerce/product-price
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/all-products, woocommerce/featured-product, woocommerce/single-product, woocommerce/product-template, core/post-template
- **Supports:** color (background, text, ~~link~~), email, interactivity, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** productId, textAlign

## Product Image Gallery - woocommerce/product-image-gallery

Display a product's images.

- **Name:** woocommerce/product-image-gallery
- **Category:** woocommerce-product-elements
- **Supports:** align, interactivity (clientNavigation), ~~multiple~~

## Product Meta - woocommerce/product-meta

Display a product’s SKU, categories, tags, and more.

- **Name:** woocommerce/product-meta
- **Category:** woocommerce-product-elements
- **Supports:** align, interactivity (clientNavigation), ~~reusable~~

## Product Rating - woocommerce/product-rating

Display the average rating of a product.

- **Name:** woocommerce/product-rating
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/all-products, woocommerce/single-product, woocommerce/product-template, core/post-template
- **Supports:** color (text, ~~background~~, ~~link~~), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize)
- **Attributes:** productId, textAlign

## Product Rating Counter - woocommerce/product-rating-counter

Display the review count of a product

- **Name:** woocommerce/product-rating-counter
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/single-product
- **Supports:** color (link, ~~background~~, ~~text~~), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize), ~~inserter~~
- **Attributes:** productId, textAlign

## Product Rating Stars - woocommerce/product-rating-stars

Display the average rating of a product with stars

- **Name:** woocommerce/product-rating-stars
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/single-product
- **Supports:** color (text, ~~background~~, ~~link~~), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize), ~~inserter~~
- **Attributes:** productId, textAlign

## Related Products - woocommerce/related-products

Display related products.

- **Name:** woocommerce/related-products
- **Category:** woocommerce
- **Supports:** align, interactivity (clientNavigation), ~~inserter~~, ~~reusable~~

## On-Sale Badge - woocommerce/product-sale-badge

Displays an on-sale badge if the product is on-sale.

- **Name:** woocommerce/product-sale-badge
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/single-product, woocommerce/product-template, core/post-template, woocommerce/product-gallery
- **Supports:** align, color (background, gradients, text, ~~link~~), email, interactivity (clientNavigation), spacing (margin), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** productId

## Product SKU - woocommerce/product-sku

Displays the SKU of a product.

- **Name:** woocommerce/product-sku
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/product-meta, woocommerce/all-products, woocommerce/single-product, woocommerce/product-template, core/post-template
- **Supports:** color (background, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** isDescendantOfAllProducts, prefix, productId, showProductSelector, suffix

## Product Stock Indicator - woocommerce/product-stock-indicator

Let shoppers know when products are out of stock or on backorder. This block is hidden when products are in stock.

- **Name:** woocommerce/product-stock-indicator
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/all-products, woocommerce/single-product, woocommerce/product-template, core/post-template
- **Supports:** color (background, text), interactivity, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** isDescendantOfAllProducts

## Product Summary - woocommerce/product-summary

Display a short description about a product.

- **Name:** woocommerce/product-summary
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/all-products, woocommerce/featured-product, woocommerce/single-product, woocommerce/product-template, core/post-template
- **Supports:** color (background, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign)
- **Attributes:** isDescendantOfAllProducts, linkText, productId, showDescriptionIfEmpty, showLink, summaryLength

## Product Title - woocommerce/product-title

Display the title of a product.

- **Name:** woocommerce/product-title
- **Category:** woocommerce-product-elements
- **Ancestor:** woocommerce/all-products
- **Supports:** color (background, gradients, text, ~~link~~), interactivity (~~clientNavigation~~), spacing (margin), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** align, headingLevel, linkTarget, productId, showProductLink

## Product Filters - woocommerce/product-filters

Add a set of filters shoppers can use.

- **Name:** woocommerce/product-filters
- **Category:** woocommerce
- **Supports:** align, color (background, button, heading, text, ~~enableContrastChecker~~), inserter, interactivity, layout (default, ~~allowEditing~~), position (sticky), spacing (blockGap), typography (fontSize)
- **Attributes:** isPreview, overlayMode, overlayPosition

## Active Filters - woocommerce/product-filter-active

Display all active filters.

- **Name:** woocommerce/product-filter-active
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filters
- **Supports:** interactivity, spacing (margin, padding, ~~blockGap~~)

## Attribute Filter - woocommerce/product-filter-attribute

Let shoppers filter products by attribute.

- **Name:** woocommerce/product-filter-attribute
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filters
- **Supports:** color (text, ~~background~~), interactivity, spacing (blockGap, margin, padding), typography (fontSize, lineHeight)
- **Attributes:** attributeId, displayStyle, hideEmpty, isPreview, queryType, selectType, showCounts, sortOrder

## List - woocommerce/product-filter-checkbox-list

Display filter options as a list.

- **Name:** woocommerce/product-filter-checkbox-list
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filter-attribute, woocommerce/product-filter-status, woocommerce/product-filter-taxonomy, woocommerce/product-filter-rating
- **Supports:** interactivity, woocommerce (innerBlockDisplayStyle)
- **Attributes:** customLabelElement, customOptionElement, customOptionElementBorder, customOptionElementSelected, labelElement, optionElement, optionElementBorder, optionElementSelected

## Chips - woocommerce/product-filter-chips

Display filter options as chips.

- **Name:** woocommerce/product-filter-chips
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filter-attribute, woocommerce/product-filter-taxonomy, woocommerce/product-filter-status, woocommerce/add-to-cart-with-options-variation-selector-attribute
- **Supports:** interactivity, layout (default, ~~allowEditing~~, ~~allowInheriting~~, ~~allowJustification~~, ~~allowOrientation~~, ~~allowSizingOnChildren~~, ~~allowSwitching~~, ~~allowVerticalAlignment~~), spacing (blockGap, padding), typography (fontSize), woocommerce (innerBlockDisplayStyle)
- **Attributes:** chipBackground, chipBorder, chipText, customChipBackground, customChipBorder, customChipText, customSelectedChipBackground, customSelectedChipBorder, customSelectedChipText, selectedChipBackground, selectedChipBorder, selectedChipText

## Clear filters - woocommerce/product-filter-clear-button

Let shoppers clear any active filters.

- **Name:** woocommerce/product-filter-clear-button
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filter-active
- **Supports:** inserter, interactivity

## Price Filter - woocommerce/product-filter-price

Let shoppers filter products by price.

- **Name:** woocommerce/product-filter-price
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filters
- **Supports:** interactivity, ~~html~~

## Price Slider - woocommerce/product-filter-price-slider

Let shoppers choose a price range with a slider.

- **Name:** woocommerce/product-filter-price-slider
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filter-price
- **Supports:** color (~~background~~, ~~enableContrastChecker~~, ~~text~~), interactivity, ~~html~~
- **Attributes:** customSlider, customSliderHandle, customSliderHandleBorder, inlineInput, showInputFields, slider, sliderHandle, sliderHandleBorder

## Rating Filter - woocommerce/product-filter-rating

Let shoppers filter products by rating.

- **Name:** woocommerce/product-filter-rating
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filters
- **Supports:** color (text, ~~background~~), interactivity
- **Attributes:** className, isPreview, minRating, showCounts

## Chips - woocommerce/product-filter-removable-chips

Display active filters as removable chips.

- **Name:** woocommerce/product-filter-removable-chips
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filter-active
- **Supports:** interactivity, layout (default, ~~allowInheriting~~, ~~allowSwitching~~, ~~allowVerticalAlignment~~)
- **Attributes:** chipBackground, chipBorder, chipText, customChipBackground, customChipBorder, customChipText

## Availability Filter - woocommerce/product-filter-status

Let shoppers filter products by availability.

- **Name:** woocommerce/product-filter-status
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filters
- **Supports:** color (text, ~~background~~), interactivity, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** displayStyle, hideEmpty, isPreview, showCounts

## Taxonomy Filter - woocommerce/product-filter-taxonomy

Let shoppers filter products by category, brand, or tag.

- **Name:** woocommerce/product-filter-taxonomy
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-filters
- **Supports:** color (text, ~~background~~), interactivity, spacing (blockGap, margin, padding), typography (fontSize, lineHeight)
- **Attributes:** displayStyle, hideEmpty, isPreview, showCounts, sortOrder, taxonomy

## Product Gallery - woocommerce/product-gallery

Showcase your products relevant images and media.

- **Name:** woocommerce/product-gallery
- **Category:** woocommerce
- **Ancestor:** woocommerce/single-product
- **Supports:** align, email, interactivity, layout (allowEditing, allowOrientation, default, ~~allowJustification~~)
- **Attributes:** fullScreenOnClick, hoverZoom

## Viewer - woocommerce/product-gallery-large-image

Container for the current gallery image, navigation buttons, zoom functionality and more.

- **Name:** woocommerce/product-gallery-large-image
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-gallery
- **Supports:** interactivity

## Thumbnails - woocommerce/product-gallery-thumbnails

Display the Thumbnails of a product.

- **Name:** woocommerce/product-gallery-thumbnails
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-gallery
- **Supports:** interactivity, spacing (margin)
- **Attributes:** activeThumbnailStyle, aspectRatio, thumbnailSize

## Newest Products - woocommerce/product-new

Display a grid of your newest products.

- **Name:** woocommerce/product-new
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~
- **Attributes:** alignButtons, catOperator, categories, columns, contentVisibility, editMode, isPreview, orderby, rows, stockStatus

## On Sale Products - woocommerce/product-on-sale

Display a grid of products currently on sale.

- **Name:** woocommerce/product-on-sale
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~
- **Attributes:** alignButtons, catOperator, categories, columns, contentVisibility, isPreview, orderby, rows, stockStatus

## Product Results Count - woocommerce/product-results-count

Display the number of products on the archive page or search result page.

- **Name:** woocommerce/product-results-count
- **Category:** woocommerce
- **Supports:** color (text, ~~background~~), interactivity (clientNavigation), typography (fontSize)

## Product Reviews - woocommerce/product-reviews

Display a product's reviews

- **Name:** woocommerce/product-reviews
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, gradients, heading, link, text), interactivity, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** tagName

## Review Author Name - woocommerce/product-review-author-name

Displays the name of the author of the review.

- **Name:** woocommerce/product-review-author-name
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews
- **Supports:** color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** isLink, linkTarget, textAlign

## Review Content - woocommerce/product-review-content

Displays the contents of a product review.

- **Name:** woocommerce/product-review-content
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews
- **Supports:** color (background, gradients, link, text), spacing (padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** textAlign

## Review Date - woocommerce/product-review-date

Displays the date on which the review was posted.

- **Name:** woocommerce/product-review-date
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews
- **Supports:** color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** format, isLink

## Reviews Form - woocommerce/product-review-form

Display a product's reviews form.

- **Name:** woocommerce/product-review-form
- **Category:** woocommerce
- **Supports:** color (background, gradients, heading, link, text), interactivity, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** textAlign

## Review Rating - woocommerce/product-review-rating

Displays the rating of a product review.

- **Name:** woocommerce/product-review-rating
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews
- **Supports:** color (background, gradients, text), interactivity (clientNavigation)
- **Attributes:** textAlign

## Reviews Template - woocommerce/product-review-template

Contains the block elements used to display product reviews, like the title, author, date, rating and more.

- **Name:** woocommerce/product-review-template
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews
- **Supports:** align, interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~

## Reviews Pagination - woocommerce/product-reviews-pagination

Displays a paginated navigation to next/previous set of product reviews, when applicable.

- **Name:** woocommerce/product-reviews-pagination
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews
- **Supports:** align, color (background, gradients, link, text), interactivity (clientNavigation), layout (default, ~~allowInheriting~~, ~~allowSwitching~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
- **Attributes:** paginationArrow

## Reviews Next Page - woocommerce/product-reviews-pagination-next

Displays the next product review's page link.

- **Name:** woocommerce/product-reviews-pagination-next
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews-pagination
- **Supports:** color (background, gradients, ~~text~~), interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
- **Attributes:** label

## Reviews Page Numbers - woocommerce/product-reviews-pagination-numbers

Displays a list of page numbers for product reviews pagination.

- **Name:** woocommerce/product-reviews-pagination-numbers
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews-pagination
- **Supports:** color (background, gradients, ~~text~~), interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~

## Reviews Previous Page - woocommerce/product-reviews-pagination-previous

Displays the previous product review's page link.

- **Name:** woocommerce/product-reviews-pagination-previous
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews-pagination
- **Supports:** color (background, gradients, ~~text~~), interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
- **Attributes:** label

## Reviews Title - woocommerce/product-reviews-title

Displays a title with the number of reviews.

- **Name:** woocommerce/product-reviews-title
- **Category:** woocommerce
- **Ancestor:** woocommerce/product-reviews
- **Supports:** align, color (background, gradients, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~anchor~~, ~~html~~
- **Attributes:** level, levelOptions, showProductTitle, showReviewsCount, textAlign

## Product Specifications - woocommerce/product-specifications

Display product weight, dimensions, and attributes.

- **Name:** woocommerce/product-specifications
- **Category:** woocommerce
- **Ancestor:** woocommerce/single-product, woocommerce/product-template, core/post-template
- **Supports:** align (full, wide), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
- **Attributes:** showAttributes, showDimensions, showWeight

## Products by Tag - woocommerce/product-tag

Display a grid of products with selected tags.

- **Name:** woocommerce/product-tag
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~
- **Attributes:** alignButtons, columns, contentVisibility, isPreview, orderby, rows, stockStatus, tagOperator, tags

## Product Template - woocommerce/product-template

Contains the block elements used to render a product.

- **Name:** woocommerce/product-template
- **Category:** woocommerce
- **Supports:** align (full, wide), anchor, color (background, gradients, link, text), email, interactivity, layout (~~allowEditing~~, ~~allowInheriting~~, ~~allowSizingOnChildren~~, ~~allowSwitching~~, ~~allowVerticalAlignment~~), typography (fontSize, lineHeight), ~~html~~, ~~inserter~~, ~~reusable~~

## Top Rated Products - woocommerce/product-top-rated

Display a grid of your top rated products.

- **Name:** woocommerce/product-top-rated
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~
- **Attributes:** alignButtons, catOperator, categories, columns, contentVisibility, editMode, isPreview, orderby, rows, stockStatus

## All Products - woocommerce/all-products

Display products from your store in a grid layout.

- **Name:** woocommerce/all-products
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~, ~~multiple~~
- **Attributes:** alignButtons, columns, contentVisibility, isPreview, layoutConfig, orderby, rows

## Products by Attribute - woocommerce/products-by-attribute

Display a grid of products with selected attributes.

- **Name:** woocommerce/products-by-attribute
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~
- **Attributes:** alignButtons, attrOperator, attributes, columns, contentVisibility, isPreview, orderby, rows, stockStatus

## Filter by Rating Controls - woocommerce/rating-filter

Enable customers to filter the product grid by rating.

- **Name:** woocommerce/rating-filter
- **Category:** woocommerce
- **Supports:** color (background, button, text), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~
- **Attributes:** className, displayStyle, isPreview, selectType, showCounts, showFilterButton

## All Reviews - woocommerce/all-reviews

Show a list of all product reviews.

- **Name:** woocommerce/all-reviews
- **Category:** woocommerce
- **Supports:** color (text, ~~background~~), interactivity (clientNavigation), typography (fontSize), ~~html~~

## Reviews by Category - woocommerce/reviews-by-category

Show product reviews from specific categories.

- **Name:** woocommerce/reviews-by-category
- **Category:** woocommerce
- **Supports:** color (text, ~~background~~), interactivity (clientNavigation), typography (fontSize), ~~html~~

## Reviews by Product - woocommerce/reviews-by-product

Display reviews for your products.

- **Name:** woocommerce/reviews-by-product
- **Category:** woocommerce
- **Supports:** color (text, ~~background~~), interactivity (clientNavigation), typography (fontSize), ~~html~~

## Saved for Later - woocommerce/saved-for-later

Display items the shopper has saved from their cart for later.

- **Name:** woocommerce/saved-for-later
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, text), interactivity, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~multiple~~, ~~reusable~~
- **Attributes:** columnCount

## Product - woocommerce/single-product

Display a single product of your choice with full control over its presentation.

- **Name:** woocommerce/single-product
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity
- **Attributes:** productId

## Filter by Stock Controls - woocommerce/stock-filter

Enable customers to filter the product grid by stock status.

- **Name:** woocommerce/stock-filter
- **Category:** woocommerce
- **Supports:** color (background, button, text), interactivity (~~clientNavigation~~), ~~html~~, ~~inserter~~, ~~lock~~, ~~multiple~~
- **Attributes:** className, displayStyle, headingLevel, isPreview, selectType, showCounts, showFilterButton

## Store Notices - woocommerce/store-notices

Display shopper-facing notifications generated by WooCommerce or extensions.

- **Name:** woocommerce/store-notices
- **Category:** woocommerce
- **Supports:** align (full, wide), interactivity (clientNavigation), ~~multiple~~
- **Attributes:** align

## Wishlist - woocommerce/wishlist

Display the shopper's wishlist.

- **Name:** woocommerce/wishlist
- **Category:** woocommerce
- **Supports:** align (full, wide), color (background, text), interactivity, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
- **Attributes:** columnCount

{/* END Autogenerated - DO NOT EDIT */}


---

## Data Store

*Source: block-development/reference/data-store/README.md*

# Data Store

This document provides an overview of the data stores registered with `wp.data` for use by various blocks. Store descriptions are exported as constants on the `wc.wcBlocksData` export (externally registered as `@woocommerce/block-data` and enqueued via handle `wc-blocks-data-store`). For any block using the store, it's recommended to import the store description rather than using the reference directly to ensure dependencies are extracted correctly. It is assumed readers have some familiarity with the `wp.data` API. You can read more about that [in the @wordpress/data reference guide](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/).

## [Cart Store (wc/store/cart)](cart.md)

The **[Cart Store (wc/store/cart)](cart.md)** is responsible for handling cart-related data and operations. To access this store using a constant, you can use:

```ts
const { cartStore } = window.wc.wcBlocksData;
```

## [Checkout Store (wc/store/checkout)](checkout.md)

The **[Checkout Store (wc/store/checkout)](checkout.md)** manages the checkout process, ensuring a seamless experience for users. To access this store using a constant, you can use:

```ts
const { checkoutStore } = window.wc.wcBlocksData;
```

## [Collections Store (wc/store/collections)](collections.md)

The **[Collections Store (wc/store/collections)](collections.md)** holds data indexed by namespace, model name, and query string. To access this store using a constant, you can use:

```ts
const { COLLECTIONS_STORE_KEY } = window.wc.wcBlocksData;
```

## [Payment Store (wc/store/payment)](payment.md)

The **[Payment Store (wc/store/payment)](payment.md)** deals with all payment-related data and transactions. To access this store using a constant, you can use:

```ts
const { paymentStore } = window.wc.wcBlocksData;
```

## [Query-State Store (wc/store/query-state)](query-state.md)

The **[Query-State Store (wc/store/query-state)](query-state.md)** holds arbitrary values indexed by context and key. It's often used for tracking the state of query objects for a given context. To access this store using a constant, you can use:

```ts
const { QUERY_STATE_STORE_KEY } = window.wc.wcBlocksData;
```

## [Schema Store (wc/store/schema)](schema.md)

The **[Schema Store (wc/store/schema)](schema.md)** is primarily used for accessing routes and has more of an internal usage. To access this store using a constant, you can use:

```ts
const { SCHEMA_STORE_KEY } = window.wc.wcBlocksData;
```

## [Store Notices Store (wc/store/store-notices)](store-notices.md)

The **[Store Notices Store (wc/store/store-notices)](store-notices.md)** is dedicated to handling various store notices and alerts. To access this store using a constant, you can use:

```ts
const { storeNoticesStore } = window.wc.wcBlocksData;
```

This `StoreDescriptor` can be passed in the `mapSelect` function of `useSelect` and in `useDispatch`.

## [Validation Store (wc/store/validation)](validation.md)

The **[Validation Store (wc/store/validation)](validation.md)** holds data relating to validation errors, it is primarily used in the Cart and Checkout flows to ensure the Checkout doesn't continue while invalid data is present. To access this store using a constant, you can use:

```ts
const { validationStore } = window.wc.wcBlocksData;
```


---

## Cart Store (`wc/store/cart`)

*Source: block-development/reference/data-store/cart.md*

# Cart Store (`wc/store/cart`) 

> 💡 What's the difference between the Cart Store and the Checkout Store?
>
> The **Cart Store (`wc/store/cart`)** manages and retrieves data about the shopping cart, including items, customer data, and interactions like coupons.
>
> The **Checkout Store (`wc/store/checkout`)** manages and retrieves data related to the checkout process, customer IDs, order IDs, and checkout status.


## Overview

The Cart Store provides a collection of selectors and methods to manage and retrieve cart-related data for WooCommerce Blocks. It offers functionality ranging from fetching cart details to managing customer interactions, such as applying coupons or updating shipping information.

## Usage

To utilize this store you will import the `cartStore` `StoreDescriptor` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the `StoreDescriptor` via:

```js
const { cartStore } = window.wc.wcBlocksData;
```

## Actions

### setCartData

This action is used to set the cart data in the store.

#### _Parameters_ 

-   _cartData_ `object`: The current cart data with the following keys:
    -   _coupons_ `array`: The coupon items in the cart.
    -   _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
    -   _shippingAddress_ `object`: The shipping address (see `getCustomerData` selector).
    -   _billingAddress_ `object`: The billing address (see `getCustomerData` selector).
    -   _items_ `array`: The cart items.
    -   _itemsCount_ `number`: The total number of items in the cart
    -   _itemsWeight_ `number`: The total weight of items in the cart.
    -   _crossSells_ `array`: The cross sells items.
    -   _needsPayment_ `boolean`: If the cart needs payment.
    -   _needsShipping_ `boolean`: If the cart needs shipping.
    -   _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
    -   _fees_ `array`: The cart fees.
    -   _totals_ `object`: The cart totals (see `getCartTotals` selector).
    -   _errors_ `array`: The cart errors (see `getCartErrors` selector).
    -   _paymentRequirements_ `object`: The payment requirements for the cart.
    -   _extensions_ `object`: The extensions data.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( setCartData( newCartData ) );
```

### setErrorData

This action is used to set the error data in the store.

#### _Parameters_ 

-   _errorData_ `object`: The error data that needs to be set in the store.
    -   _code_ `string`: The error code.
    -   _message_ `string`: The error message.
    -   _data_ `object`: Additional error data. This is an optional object with the following keys:
        -   _status_ `number`: The error status.
        -   _params_ `string`: The error params.
        -   _message_ `string`: The error message.
        -   _cart_ `object`: The cart data. This is an optional object with the following keys:
            -   _coupons_ `array`: The coupon items in the cart.
            -   _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
            -   _shippingAddress_ `object`: The shipping address (see `getCustomerData` selector).
            -   _billingAddress_ `object`: The billing address (see `getCustomerData` selector).
            -   _items_ `array`: The cart items.
            -   _itemsCount_ `number`: The total number of items in the cart
            -   _itemsWeight_ `number`: The total weight of items in the cart.
            -   _crossSells_ `array`: The cross sells items.
            -   _needsPayment_ `boolean`: If the cart needs payment.
            -   _needsShipping_ `boolean`: If the cart needs shipping.
            -   _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
            -   _fees_ `array`: The cart fees.
            -   _totals_ `object`: The cart totals (see `getCartTotals` selector).
            -   _errors_ `array`: The cart errors (see `getCartErrors` selector).
            -   _paymentRequirements_ `object`: The payment requirements for the cart.
            -   _extensions_ `object`: The extensions data.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( setErrorData( newErrorData ) );
```

### receiveCartContents

This action returns an action object used in updating the store with the provided cart. It omits the customer addresses so that only updates to cart items and totals are received.

#### _Parameters_ 

-   _cartContents_ `object`: A cart contents API response.
    -   _coupons_ `array`: The coupon items in the cart.
    -   _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
    -   _shippingAddress_ `object`: The shipping address (see `getCustomerData` selector).
    -   _billingAddress_ `object`: The billing address (see `getCustomerData` selector).
    -   _items_ `array`: The cart items.
    -   _itemsCount_ `number`: The total number of items in the cart
    -   _itemsWeight_ `number`: The total weight of items in the cart.
    -   _crossSells_ `array`: The cross sells items.
    -   _needsPayment_ `boolean`: If the cart needs payment.
    -   _needsShipping_ `boolean`: If the cart needs shipping.
    -   _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
    -   _fees_ `array`: The cart fees.
    -   _totals_ `object`: The cart totals (see `getCartTotals` selector).
    -   _errors_ `array`: The cart errors (see `getCartErrors` selector).
    -   _paymentRequirements_ `object`: The payment requirements for the cart.
    -   _extensions_ `object`: The extensions data.

#### _Returns_ 

-   `object`: The action object with the following keys:
    -   _type_ `string`: The action type.
    -   _cartContents_ `object`: The cart contents with the following keys:
        -   _coupons_ `array`: The coupon items in the cart.
        -   _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
        -   _items_ `array`: The cart items.
        -   _itemsCount_ `number`: The total number of items in the cart
        -   _itemsWeight_ `number`: The total weight of items in the cart.
        -   _crossSells_ `array`: The cross sells items.
        -   _needsPayment_ `boolean`: If the cart needs payment.
        -   _needsShipping_ `boolean`: If the cart needs shipping.
        -   _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
        -   _fees_ `array`: The cart fees.
        -   _totals_ `object`: The cart totals (see `getCartTotals` selector).
        -   _errors_ `array`: The cart errors (see `getCartErrors` selector).
        -   _paymentRequirements_ `object`: The payment requirements for the cart.
        -   _extensions_ `object`: The extensions data.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( receiveCartContents( newCartContents ) );
```

### receiveApplyingCoupon

This action returns an action object used to track when a coupon is applying.

#### _Parameters_ 

-   _couponCode_ `string`: The code of the coupon being applied.

#### _Returns_ 

-   `object`: The action object with following keys:
    -   _type_ `string`: The action type.
    -   _couponCode_ `string`: The code of the coupon being applied.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( receiveApplyingCoupon( couponCode ) );
```

### receiveRemovingCoupon

This action returns an action object used to track when a coupon is removing.

#### _Parameters_ 

-   _couponCode_ `string`: The code of the coupon being removed.

#### _Returns_ 

-   `object`: The action object with the following keys:
    -   _type_ `string`: The action type.
    -   _couponCode_ `string`: The code of the coupon being removed.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( receiveRemovingCoupon( couponCode ) );
```

### receiveCartItem

This action is used to update a specific item in the cart.

#### _Parameters_ 

-   _cartResponseItem_ `object`: Cart response object with the following keys:
    -   _cartItem_ `object`: The cart item (see `getCartItem` selector).

#### _Returns_ 

-   `object`: The action object with the following keys:
    -   _type_ `string`: The action type.
    -   _cartItem_ `object`: The cart item (see `getCartItem` selector).

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( receiveCartItem( CartResponseItem ) );
```

### itemIsPendingQuantity

This action returns an action object to indicate if the specified cart item quantity is being updated.

#### _Parameters_ 

-   _cartItemKey_ `string`: The key of the cart item.
-   _isPending_ `boolean` (default: `true`): Whether the cart item quantity is being updated.

#### _Returns_ 

-   `object`: The action object with following keys:
    -   _type_ `string`: The action type.
    -   _cartItemKey_ `string`: The key of the cart item.
    -   _isPending_ `boolean`: Whether the cart item quantity is being updated.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( itemIsPendingQuantity( cartItemKey, isPending ) );
```

### itemIsPendingDelete

This action returns an action object to indicate if the specified cart item is being deleted.

#### _Parameters_ 

-   _cartItemKey_ `string`: The key of the cart item.
-   _isPending_ `boolean` (default: `true`): Whether the cart item is being deleted.

#### _Returns_ 

-   `object`: The action object with the following keys:
    -   _type_ `string`: The action type.
    -   _cartItemKey_ `string`: The key of the cart item.
    -   _isPending_ `boolean`: Whether the cart item is being deleted.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( itemIsPendingDelete( cartItemKey, isPending ) );
```

### setIsCartDataStale

This action returns an action object to indicate if the cart data is stale.

#### _Parameters_ 

-   _isCartDataStale_ `boolean` (default: `true`): Flag to mark cart data as stale; true if `lastCartUpdate` timestamp is newer than the one in wcSettings.

#### _Returns_ 

-   `object`: The action object with the following keys:
    -   _type_ `string`: The action type.
    -   _isCartDataStale_ `boolean`: Flag to mark cart data as stale; true if `lastCartUpdate` timestamp is newer than the one in wcSettings.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( setIsCartDataStale( isCartDataStale ) );
```

### updatingCustomerData

This action returns an action object to indicate if the customer data (billing and/or shipping address) is being updated.

#### _Parameters_ 

-   _isResolving_ `boolean`: Whether the customer data is being updated.

#### _Returns_ 

-   `object`: The action object with the following keys:
    -   _type_ `string`: The action type.
    -   _isResolving_ `boolean`: Whether the customer data is being updated.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( updatingCustomerData( isResolving ) );
```

### shippingRatesBeingSelected

This action returns an action object to indicate if the shipping rates are being selected.

#### _Parameters_ 

-   _isResolving_ `boolean`: True if shipping rate is being selected.

#### _Returns_ 

-   `object`: The action object with the following keys:
    -   _type_ `string`: The action type.
    -   _isResolving_ `boolean`: True if shipping rate is being selected.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( shippingRatesBeingSelected( isResolving ) );
```

### applyExtensionCartUpdate

This action is used to send POSTs request to the /cart/extensions endpoint with the data supplied by the extension.

#### _Parameters_ 

-   _args_ `object`: The arguments for the request with the following keys:
    -   _extensionId_ `string`: The extension ID.
    -   _data_ `object`: The data to send to the endpoint with the following keys:
        -   _key_ `string`: The key of the extension.
        -   _value_ `string`: The value of the extension.
    -   _overwriteDirtyCustomerData_ `boolean`: Whether to overwrite the customer data in the client with the data returned from the server, even if it is dirty (i.e. it hasn't been pushed to the server yet).

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( applyExtensionCartUpdate( args ) );
```

### applyCoupon

This action is used to apply a coupon to the cart.

#### _Parameters_ 

-   _couponCode_ `string`: The code of the coupon to apply.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( applyCoupon( couponCode ) );
```

### removeCoupon

This action is used to remove a coupon from the cart.

#### _Parameters_ 

-   _couponCode_ `string`: The code of the coupon to remove.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( removeCoupon( couponCode ) );
```

### addItemToCart

This action is used to add an item to the cart.

#### _Parameters_ 

-   _productId_ `number`: Product ID to add to cart.
-   _quantity_ `number` (default: `1`): The quantity of the product to add.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( addItemToCart( productId, quantity ) );
```

### removeItemFromCart

This action is used to remove an item from the cart.

#### _Parameters_ 

-   _cartItemKey_ `string`: Cart item being updated.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( removeItemFromCart( cartItemKey ) );
```

### changeCartItemQuantity

This action is used to change the quantity of an item in the cart.

#### _Parameters_ 

-   _cartItemKey_ `string`: Cart item being updated.
-   _quantity_ `number`: Quantity of the item.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( changeCartItemQuantity( cartItemKey, quantity ) );
```

### selectShippingRate

This action is used to select a shipping rate for the cart.

#### _Parameters_ 

-   _rateId_ `string`: The ID of the shipping rate to select.
-   _packageId_ `number | string` (default: `null`): The key of the packages that will select within the shipping rate.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( selectShippingRate( rateId, packageId ) );
```

### setBillingAddress

This action is used to set the billing address for the cart locally, as opposed to updateCustomerData which sends it to the server.

#### _Parameters_ 

-   _billingAddress_ `object`: Billing address that needs to be set. The keys are as following:
    -   _first_name_ `string`: The first name.
    -   _last_name_ `string`: The last name.
    -   _company_ `string`: The company name.
    -   _address_1_ `string`: The address line 1.
    -   _address_2_ `string`: The address line 2.
    -   _city_ `string`: The city name.
    -   _state_ `string`: The state name.
    -   _postcode_ `string`: The postcode.
    -   _country_ `string`: The country name.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( setBillingAddress( billingAddress ) );
```

### setShippingAddress

This action is used to set the shipping address for the cart locally, as opposed to updateCustomerData which sends it to the server.

#### _Parameters_ 

-   _shippingAddress_ `object`: Shipping address that needs to be set. The keys are as following:
    -   _first_name_ `string`: The first name.
    -   _last_name_ `string`: The last name.
    -   _company_ `string`: The company name.
    -   _address_1_ `string`: The address line 1.
    -   _address_2_ `string`: The address line 2.
    -   _city_ `string`: The city name.
    -   _state_ `string`: The state name.
    -   _postcode_ `string`: The postcode.
    -   _country_ `string`: The country name.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( setShippingAddress( shippingAddress ) );
```

### updateCustomerData

This action is used to updates the shipping and/or billing address for the customer and returns an updated cart.

#### _Parameters_ 

-   _customerData_ `object`: Customer billing and shipping address. The keys are as following:
    -   _shippingAddress_ `object`: The shipping address with the following keys:
        -   _first_name_ `string`: The first name.
        -   _last_name_ `string`: The last name.
        -   _company_ `string`: The company name.
        -   _address_1_ `string`: The address line 1.
        -   _address_2_ `string`: The address line 2.
        -   _city_ `string`: The city name.
        -   _state_ `string`: The state name.
        -   _postcode_ `string`: The postcode.
        -   _country_ `string`: The country name.
    -   _billingAddress_ `object`: The billing address (same keys as shipping address).
-   `editing: boolean` (default: `true`): If the address is being edited, we don't update the customer data in the store from the response.

#### _Example_ 

```js
const { dispatch } = useDispatch( cartStore );
dispatch( updateCustomerData( customerData, editing ) );
```

## Selectors

### getCartData

Returns the Cart data from the state.

#### _Returns_ 

-   `object`: The current cart data with the following keys:
    -   _coupons_ `array`: The coupon items in the cart.
    -   _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
    -   _shippingAddress_ `object`: The shipping address (see `getCustomerData` selector).
    -   _billingAddress_ `object`: The billing address.
    -   _items_ `array`: The cart items.
    -   _itemsCount_ `number`: The total number of items in the cart
    -   _itemsWeight_ `number`: The total weight of items in the cart.
    -   _crossSells_ `array`: The cross sells items.
    -   _needsPayment_ `boolean`: If the cart needs payment.
    -   _needsShipping_ `boolean`: If the cart needs shipping.
    -   _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
    -   _fees_ `array`: The cart fees.
    -   _totals_ `object`: The cart totals (see `getCartTotals` selector).
    -   _errors_ `array`: The cart errors (see `getCartErrors` selector).
    -   _paymentRequirements_ `object`: The payment requirements for the cart.
    -   _extensions_ `object`: The extensions data.

#### _Example_ 

```js
const store = select( cartStore );
const cartData = store.getCartData();
```

### getCustomerData

Returns the shipping and billing address from the state.

#### _Returns_ 

-   `object`: The current shipping and billing address with the following keys:
    -   _shippingAddress_ `object`: The shipping address with the following keys:
        -   _first_name_ `string`: The first name.
        -   _last_name_ `string`: The last name.
        -   _company_ `string`: The company name.
        -   _address_1_ `string`: The address line 1.
        -   _address_2_ `string`: The address line 2.
        -   _city_ `string`: The city name.
        -   _state_ `string`: The state name.
        -   _postcode_ `string`: The postcode.
        -   _country_ `string`: The country name.
    -   _billingAddress_ `object`: The billing address (same keys as shipping address).

#### _Example_ 

```js
const store = select( cartStore );
const customerData = store.getCustomerData();
```

### getShippingRates

Returns the shipping rates from the state.

#### _Returns_ 

-   `array`: The shipping rates. They keys are as following:
    -   _id_ `string`: The shipping rate ID.
    -   _label_ `string`: The shipping rate label.
    -   _cost_ `string`: The shipping rate cost.
    -   _package_id_ `number`: The shipping rate package ID.
    -   _meta_data_ `array`: The shipping rate meta data. The keys are as following:
        -   _id_ `number`: The shipping rate meta data ID.
        -   _key_ `string`: The shipping rate meta data key.
        -   _value_ `string`: The shipping rate meta data value.
    -   _taxes_ `array`: The shipping rate taxes.

#### _Example_ 

```js
const store = select( cartStore );
const shippingRates = store.getShippingRates();
```

### getNeedsShipping

Queries whether the cart needs shipping.

#### _Returns_ 

-   `boolean`: True if the cart needs shipping.

#### _Example_ 

```js
const store = select( cartStore );
const needsShipping = store.getNeedsShipping();
```

### getHasCalculatedShipping

Queries whether the cart shipping has been calculated.

#### _Returns_ 

-   `boolean`: True if the shipping has been calculated.

#### _Example_ 

```js
const store = select( cartStore );
const hasCalculatedShipping = store.getHasCalculatedShipping();
```

### getCartTotals

Returns the cart totals from state.

#### _Returns_ 

-   `object`: The current cart totals with the following keys:
    -   _total_items_ `string`: The sum total of items in the cart without discount, tax or shipping.
    -   _total_items_tax_ `string`: The total tax on all items before discount.
    -   _total_fees_ `string`: The total transaction fees.
    -   _total_fees_tax_ `string`: The tax on the total transaction fees.
    -   _total_discount_ `string`: The total discount applied to the cart.
    -   _total_discount_tax_ `string`: The tax applied to the total discount amount.
    -   _total_shipping_ `string`: The total shipping cost.
    -   _total_shipping_tax_ `string`: The tax applied to the total shipping cost.
    -   _total_tax_ `string`: The total tax applied to the cart.
    -   _total_price_ `string`: The total price of the cart including discount, tax or shipping.
    -   _tax_lines_ `array` of object: The tax lines: `name`, `price`, and `rate`.
    -   _currency_code_ `string`: The currency code for the cart.
    -   _currency_symbol_ `string`: The currency symbol for the cart.
    -   _currency_minor_unit_ `integer`: The currency minor unit for the cart.
    -   _currency_decimal_separator_ `string`: The currency decimal separator for the cart.
    -   _currency_thousand_separator_ `string`: The currency thousand separator for the cart.
    -   _currency_prefix_ `string`: The currency prefix for the cart.
    -   _currency_suffix_ `string`: The currency suffix for the cart.

#### _Example_ 

```js
const store = select( cartStore );
const cartTotals = store.getCartTotals();
```

### getCartMeta

Returns the cart meta from state.

#### _Returns_ 

-   `object`: The current cart meta with the following keys:
    -   _updatingCustomerData_ `boolean`: If the customer data (billing and/or shipping address) is being updated.
    -   _updatingSelectedRate_ `boolean`: If the selected rate is being updated.
    -   _isCartDataStale_ `boolean`: If the cart data is stale.
    -   _applyingCoupon_ `string`: The coupon code being applied.
    -   _removingCoupon_ `string`: The coupon code being removed.

#### _Example_ 

```js
const store = select( cartStore );
const cartMeta = store.getCartMeta();
```

### getCartErrors

Returns the cart errors from state if cart receives customer facing errors from the API.

#### _Returns_ 

-   `array`: The cart errors with the following keys:
    -   _code_ `string`: The error code.
    -   _message_ `string`: The error message.
    -   _data_ `object`: API response data.

#### _Example_ 

```js
const store = select( cartStore );
const cartErrors = store.getCartErrors();
```

### isApplyingCoupon

Queries whether a coupon is being applied.

#### _Returns_ 

-   `boolean`: True if a coupon is being applied.

#### _Example_ 

```js
const store = select( cartStore );
const isApplyingCoupon = store.isApplyingCoupon();
```

### isCartDataStale

Queries whether the cart data is stale.

#### _Returns_ 

-   `boolean`: True if the cart data is stale.

#### _Example_ 

```js
const store = select( cartStore );
const isCartDataStale = store.isCartDataStale();
```

### getCouponBeingApplied

Returns the coupon code being applied.

#### _Returns_ 

-   `string`: The coupon code being applied.

#### _Example_ 

```js
const store = select( cartStore );
const couponBeingApplied = store.getCouponBeingApplied();
```

### isRemovingCoupon

Queries whether a coupon is being removed.

#### _Returns_ 

-   `boolean`: True if a coupon is being removed.

#### _Example_ 

```js
const store = select( cartStore );
const isRemovingCoupon = store.isRemovingCoupon();
```

### getCouponBeingRemoved

Returns the coupon code being removed.

#### _Returns_ 

-   `string`: The coupon code being removed.

#### _Example_ 

```js
const store = select( cartStore );
const couponBeingRemoved = store.getCouponBeingRemoved();
```

### getCartItem( cartItemKey )

Returns a cart item from the state.

#### _Parameters_ 

-   _cartItemKey_ `string`: The cart item key.

#### _Returns_ 

-   `object`: The cart item with the following keys:
    -   _key_ `string`: The cart item key.
    -   _id_ `number`: The cart item id.
    -   _catalog_visibility_ `string`: The catalog visibility.
    -   _quantity_limits_ `object`: The quantity limits.
    -   _name_ `string`: The cart item name.
    -   _summary_ `string`: The cart item summary.
    -   _short_description_ `string`: The cart item short description.
    -   _description_ `string`: The cart item description.
    -   _sku_ `string`: The cart item sku.
    -   _low_stock_remaining_ `null` or `number`: The low stock remaining.
    -   _backorders_allowed_ `boolean` indicating if backorders are allowed.
    -   _show_backorder_badge_ `boolean` indicating if the backorder badge should be shown.
    -   _sold_individually_ `boolean` indicating if the item is sold individually.
    -   _permalink_ `string`: The cart item permalink.
    -   _images_ `array`: The cart item images.
    -   _variation_ `array`: The cart item variation.
    -   _prices_ `object`: The cart item prices with the following keys:
        -   _currency_code_ `string`: The currency code.
        -   _currency_symbol_ `string`: The currency symbol.
        -   _currency_minor_unit_ `number`: The currency minor unit.
        -   _currency_decimal_separator_ `string`: The currency decimal separator.
        -   _currency_thousand_separator_ `string`: The currency thousand separator.
        -   _currency_prefix_ `string`: The currency prefix.
        -   _currency_suffix_ `string`: The currency suffix.
        -   _price_ `string`: The cart item price.
        -   _regular_price_ `string`: The cart item regular price.
        -   _sale_price_ `string`: The cart item sale price.
        -   _price_range_ `string`: The cart item price range.
    -   _totals_ `object`: The cart item totals with the following keys:
        -   _currency_code_ `string`: The currency code.
        -   _currency_symbol_ `string`: The currency symbol.
        -   _currency_minor_unit_ `number`: The currency minor unit.
        -   _currency_decimal_separator_ `string`: The currency decimal separator.
        -   _currency_thousand_separator_ `string`: The currency thousand separator.
        -   _currency_prefix_ `string`: The currency prefix.
        -   _currency_suffix_ `string`: The currency suffix.
        -   _line_subtotal_ `string`: The cart item line subtotal.
        -   _line_subtotal_tax_ `string`: The cart item line subtotal tax.
        -   _line_total_ `string`: The cart item line total.
        -   _line_total_tax_ `string`: The cart item line total tax.

#### _Example_ 

```js
const store = select( cartStore );
const cartItem = store.getCartItem( cartItemKey );
```

### isItemPendingQuantity( cartItemKey )

Queries whether a cart item is pending quantity.

#### _Parameters_ 

-   _cartItemKey_ `string`: The cart item key.

#### _Returns_ 

-   `boolean`: True if the cart item is pending quantity.

#### _Example_ 

```js
const store = select( cartStore );
const isItemPendingQuantity = store.isItemPendingQuantity( cartItemKey );
```

### isItemPendingDelete( cartItemKey )

Queries whether a cart item is pending delete.

#### _Parameters_ 

-   _cartItemKey_ `string`: The cart item key.

#### _Returns_ 

-   `boolean`: True if the cart item is pending delete.

#### _Example_ 

```js
const store = select( cartStore );
const isItemPendingDelete = store.isItemPendingDelete( cartItemKey );
```

### isCustomerDataUpdating

Queries whether the customer data is being updated.

#### _Returns_ 

-   `boolean`: True if the customer data is being updated.

#### _Example_ 

```js
const store = select( cartStore );
const isCustomerDataUpdating = store.isCustomerDataUpdating();
```

### isAddressFieldsForShippingRatesUpdating

Queries whether shipping address fields impacting the shipping rates are being updated.
By default, Store API considers the following shipping fields as essential for shipping rate calculations: `state`, `country`, `postcode`, and `city`.

#### _Returns_ 

-   `boolean`: True if shipping address fields impacting the shipping rates are being updated.

#### _Example_ 

```js
const store = select( cartStore );
const isAddressFieldsForShippingRatesUpdating = store.isAddressFieldsForShippingRatesUpdating();
```

### hasPendingItemsOperations

Queries whether there are any pending cart operations (add, quantity update, or delete items).

#### _Returns_ 

-   `boolean`: True if there are pending cart operations (adding products, updating quantities, or deleting items).

#### _Example_ 

```js
const store = select( cartStore );
const hasPendingItemsOperations = store.hasPendingItemsOperations();
```

### isShippingRateBeingSelected

Queries whether a shipping rate is being selected.

#### _Returns_ 

-   `boolean`: True if a shipping rate is being selected.

#### _Example_ 

```js
const store = select( cartStore );
const isShippingRateBeingSelected = store.isShippingRateBeingSelected();
```

### getItemsPendingQuantityUpdate

Retrieves the item keys for items whose quantity is currently being updated.

#### _Returns_ 

-   `string[]`: An array with the item keys for items whose quantity is currently being updated.

#### _Example_ 

```js
const store = select( cartStore );
const itemsPendingQuantityUpdate = store.getItemsPendingQuantityUpdate();
```

### getItemsPendingDelete

Retrieves the item keys for items that are currently being deleted.

#### _Returns_ 

-   `string[]`: An array with the item keys for items that are currently being deleted.

#### _Example_ 

```js
const store = select( cartStore );
const itemsPendingDelete = store.getItemsPendingDelete();
```


---

## Checkout Store (`wc/store/checkout`)

*Source: block-development/reference/data-store/checkout.md*

# Checkout Store (`wc/store/checkout`) 

> 💡 What's the difference between the Cart Store and the Checkout Store?
>
> The **Cart Store (`wc/store/cart`)** manages and retrieves data about the shopping cart, including items, customer data, and interactions like coupons.
>
> The **Checkout Store (`wc/store/checkout`)** manages and retrieves data related to the checkout process, customer IDs, order IDs, and checkout status.

## Overview

The Checkout Store provides a collection of selectors to access and manage data during the checkout process. These selectors enable developers to fetch key details such as customer information, order status, and other checkout-related data.

## Usage

To utilize this store you will import the `checkoutStore` `StoreDescriptor` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the `StoreDescriptor` via:

```js
const { checkoutStore } = '@woocommerce/block-data'
```

If it is not you can import it via:

```js
const { checkoutStore } = window.wc.wcBlocksData
```

## Selectors

### getCustomerId

Returns the WordPress user ID of the customer whose order is currently processed by the Checkout block.

#### _Returns_ {/* omit in toc */}

-   `number`: The WordPress user ID of the customer.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const customerId = store.getCustomerId();
```

### getOrderId

Returns the WooCommerce order ID of the order that is currently being processed by the Checkout block.

#### _Returns_ {/* omit in toc */}

-   `number`: The WooCommerce order ID.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const orderId = store.getOrderId();
```

### getOrderNotes

Returns the order notes.

#### _Returns_ {/* omit in toc */}

-   `string`: The order notes.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const orderNotes = store.getOrderNotes();
```

### getRedirectUrl

Returns the URL to redirect to after checkout is complete.

#### _Returns_ {/* omit in toc */}

-   `string`: The URL to redirect to.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const redirectUrl = store.getRedirectUrl();
```

### getExtensionData

Returns the extra data registered by extensions.

#### _Returns_ {/* omit in toc */}

-   `object`: The extra data registered by extensions.

```js
{
    [ extensionNamespace ]: {
        [ key ]: value,
    },
}
```

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const extensionData = store.getExtensionData();
```

### getCheckoutStatus

Returns the current status of the checkout process.

#### _Returns_ {/* omit in toc */}

-   `string`: The current status of the checkout process. Possible values are: `pristine`, `before-processing`, `processing`, `after-processing`, `complete`, `idle`.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const checkoutStatus = store.getCheckoutStatus();
```

### getShouldCreateAccount

Returns true if the shopper has opted to create an account with their order.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if the shopper has opted to create an account with their order.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const shouldCreateAccount = store.getShouldCreateAccount();
```

### getUseShippingAsBilling

Returns true if the shopper has opted to use their shipping address as their billing address.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if the shipping address should be used as the billing address.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const useShippingAsBilling = store.getUseShippingAsBilling();
```

### getEditingBillingAddress

Returns true if the billing address is being edited.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if the billing address is being edited.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const editingBillingAddress = store.getEditingBillingAddress();
```

### getEditingShippingAddress

Returns true if the shipping address is being edited.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if the shipping address is being edited.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const editingShippingAddress = store.getEditingShippingAddress();
```

### hasError

Returns true if an error occurred, and false otherwise.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if an error occurred.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const hasError = store.hasError();
```

### hasOrder

Returns true if a draft order had been created, and false otherwise.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if a draft order had been created.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const hasOrder = store.hasOrder();
```

### isIdle

When the checkout status is `IDLE` this flag is true. Checkout will be this status after any change to checkout state after the block is loaded. It will also be this status when retrying a purchase is possible after processing happens with an error.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if the checkout has had some activity, but is currently waiting for user input.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const isIdle = store.isIdle();
```

### isBeforeProcessing

When the checkout status is `BEFORE_PROCESSING` this flag is true. Checkout will be this status when the user submits checkout for processing.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if an order is about to be processed.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const isBeforeProcessing = store.isBeforeProcessing();
```

### isProcessing

When the checkout status is `PROCESSING` this flag is true. Checkout will be this status when all the observers on the event emitted with the `BEFORE_PROCESSING` status are completed without error. It is during this status that the block will be sending a request to the server on the checkout endpoint for processing the order.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if the checkout is processing.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const isProcessing = store.isProcessing();
```

### isAfterProcessing

When the checkout status is `AFTER_PROCESSING` this flag is true. Checkout will have this status after the block receives the response from the server side processing request.

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if an order had just been processed.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const isAfterProcessing = store.isAfterProcessing();
```

### isComplete

When the checkout status is `COMPLETE` this flag is true. Checkout will have this status after all observers on the events emitted during the `AFTER_PROCESSING` status are completed successfully. When checkout is at this status, the shopper's browser will be redirected to the value of `redirectUrl` at that point (usually the `order-received` route).

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if the order is complete.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const isComplete = store.isComplete();
```

### isCalculating

This is true when the total is being re-calculated for the order. There are numerous things that might trigger a recalculation of the total: coupons being added or removed, shipping rates updated, shipping rate selected etc. This flag consolidates all activity that might be occurring (including requests to the server that potentially affect calculation of totals). So instead of having to check each of those individual states you can reliably just check if this boolean is true (calculating) or false (not calculating).

#### _Returns_ {/* omit in toc */}

-   `boolean`: True if there is an in-flight request to update any values.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const isCalculating = store.isCalculating();
```

### prefersCollection

Returns true if the customer prefers to collect their order, and false otherwise.

#### _Returns_ {/* omit in toc */}

-   _prefersCollection_ `boolean`: True if the shopper prefers to collect their order.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const prefersCollection = store.prefersCollection();
```

### getRegisteredAutocompleteProviders

Returns a list of registered address autocomplete provider IDs.

#### _Returns_ {/* omit in toc */}

-   _addressAutocompleteProviders_ `string[]`: A list of registered address autocomplete provider IDs.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const addressAutocompleteProviders = store.getRegisteredAutocompleteProviders();
```

### getActiveAutocompleteProvider

Returns the active address autocomplete provider for a given address type.

#### _Parameters_

-   _type_ `'billing' | 'shipping'`: The address type.

#### _Returns_ {/* omit in toc */}

-   _activeAddressAutocompleteProvider_ `string`: The currently active address autocomplete provider for the passed address type.

#### _Example_ {/* omit in toc */}

```js
const store = select( checkoutStore );
const activeBillingProvider = store.getActiveAutocompleteProvider( 'billing' );
```


## Actions

### setPrefersCollection

Sets the `prefersCollection` flag to true or false.

#### _Parameters_ {/* omit in toc */}

-   _prefersCollection_ `boolean`: True if the shopper prefers to collect their order.

#### _Example_ {/* omit in toc */}

```js
const store = dispatch( checkoutStore );
store.setPrefersCollection( true );
```

### setEditingBillingAddress

Set the billing address to editing state or collapsed state. Note that if the address has invalid fields, it will not be set to collapsed state.

#### _Parameters_ {/* omit in toc */}

-   _isEditing_ `boolean`: True to set the billing address to editing state, false to set it to collapsed state.

#### _Example_ {/* omit in toc */}

```js
const store = dispatch( checkoutStore );
store.setEditingBillingAddress( true );
```

### setEditingShippingAddress

Set the shipping address to editing state or collapsed state. Note that if the address has invalid fields, it will not be set to collapsed state.

#### _Parameters_ {/* omit in toc */}

-   _isEditing_ `boolean`: True to set the shipping address to editing state, false to set it to collapsed state.

#### _Example_ {/* omit in toc */}

```js
const store = dispatch( checkoutStore );
store.setEditingShippingAddress( true );
```

### addAddressAutocompleteProvider

Adds an address autocomplete provider 

#### _Parameters_ {/* omit in toc */}

-   _providerId_ `string`: The provider's name. Note, providers should be registered with `wc.addressAutocomplete.registerAddressAutocompleteProvider`.

#### _Example_ {/* omit in toc */}

```js
const store = dispatch( checkoutStore );
store.addAddressAutocompleteProvider( 'my-address-provider' );
```

### setActiveAddressAutocompleteProvider

Adds an address autocomplete provider 

#### _Parameters_ {/* omit in toc */}

-   _providerId_ `string`: Sets the active autocomplete provider's id. Note, providers should be registered with `wc.addressAutocomplete.registerAddressAutocompleteProvider`.
-   _addressType_ `'billing' | 'shipping'`: Which address type this is the active provider for. Since billing and shipping can be in different countries, there may be a different provider for each country.

#### _Example_ {/* omit in toc */}

```js
const store = dispatch( checkoutStore );
store.setActiveAddressAutocompleteProvider( 'my-address-provider', 'billing' );
```


---

## Collections Store (`wc/store/collections`)

*Source: block-development/reference/data-store/collections.md*

# Collections Store (`wc/store/collections`) 

## Overview

The Collections Store allows to retrieve product-related collections within WooCommerce Blocks.

## Usage

To utilize this store you will import the COLLECTIONS_STORE_KEY in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via:

```js
const { COLLECTIONS_STORE_KEY } = window.wc.wcBlocksData;
```

## Actions

### receiveCollection( namespace, resourceName, queryString, ids = [], items = [], replace = false )

This will return an action object for the given arguments used in dispatching the collection results to the store.

> ⚠️ You should rarely have to dispatch this action directly as it is used by the resolver for the `getCollection` selector.

#### _Parameters_ 

-   _namespace_ `string`: The route namespace for the collection, eg. `/wc/blocks`.
-   _resourceName_ `string`: The resource name for the collection (eg. `products/attributes`.
-   _queryString_ `string`: An additional query string to add to the request for the collection. Note, collections are cached by the query string, eg. `?order=ASC`.
-   _ids_ `array`: If the collection route has placeholders for ids, you provide them via this argument in the order of how the placeholders appear in the route.
-   _response_ `Object`: An object containing a `items` property with the collection items from the response (array), and a `headers` property that is matches the `window.Headers` interface containing the headers from the response.
-   _replace_ `boolean`: Whether or not to replace any existing items in the store for the given indexes (namespace, resourceName, queryString) if there are already values in the store.

#### _Example_ 

```js
const { dispatch } = useDispatch( COLLECTIONS_STORE_KEY );
dispatch( receiveCollection( namespace, resourceName, queryString, ids, response ) );
```

### receiveCollectionError

This will return an action object for the given arguments used in dispatching an error to the store.

#### _Parameters_ 

-   _namespace_ `string`: The route namespace for the collection, eg. `/wc/blocks`.
-   _resourceName_ `string`: The resource name for the collection, eg. `products/attributes`.
-   _queryString_ `string`: An additional query string to add to the request for the collection. Note, collections are cached by the query string, eg. `?order=ASC`.
-   _ids_ `array`: If the collection route has placeholders for ids, you provide them via this argument in the order of how the placeholders appear in the route.
-   _error_ `object`: The error object with the following keys:
   	-   _code_ `string`: The error code.
   	-   _message_ `string`: The error message.
   	-   _data_ `object`: The error data with the following keys:
      		-   _status_ `number`: The HTTP status code.
      		-   _params_ `object`: The parameters for the error.
      		-   _headers_ `object`: The headers for the error.

#### _Example_ 

```js
const { dispatch } = useDispatch( COLLECTIONS_STORE_KEY );
dispatch( receiveCollectionError( namespace, resourceName, queryString, ids, error ) );
```

### receiveLastModified

This will return an action object for the given arguments used in dispatching the last modified date to the store.

#### _Parameters_ 

-   _timestamp_ `number`: The timestamp of the last modified date.

#### _Example_ 

```js
const { dispatch } = useDispatch( COLLECTIONS_STORE_KEY );
dispatch( receiveLastModified( timestamp ) );
```

## Selectors

### getFromState

This selector will return the state from the collections store.

#### _Returns_ 

-   `object`: The state from the collections store with the following properties:
   	- _namespace_ `string`: The route namespace for the collection, eg. `/wc/blocks`.
    - _resourceName_ `string`: The resource name for the collection, eg. `products/attributes`.
    - _query_ `object`: The query arguments for the collection, eg. `{ order: 'ASC', sortBy: Price }`.
    - _ids_ `array`: If the collection route has placeholders for ids you provide the values for those placeholders in this array (in order).
   	- _type_ `string`: type of the collections ie `items`.

or

- `array` | `null` | `undefined`: Returns a fallback value (specified as a parameter) when the collection lacks matching headers for the provided arguments.

#### _Example_ 

```js
const store = select( COLLECTIONS_STORE_KEY );
const state = store.getFromState( state, namespace, resourceName, queryString, ids, type, fallback );
```

### getCollection

This selector will return the collection for the given arguments. It has a sibling resolver, so if the selector has never been resolved, the resolver will make a request to the server for the collection and dispatch results to the store.

#### _Returns_ 

-   `object`:  Returns the `getFromState` object (see [`getFromState`](#getfromstate)).

### getCollectionHeader

This selector will return a header from the collection response using the given arguments. It has a sibling resolver that will resolve `getCollection` using the arguments if that has never been resolved.

#### _Returns_ 

-   `undefined`: If the collection has headers but not a matching header for the given `header` argument, then `undefined` will be returned.

or

-   `null`: If the collection does not have any matching headers for the given arguments, then `null` is returned.

or

-   `object`: If the collection has a matching header for the given arguments, then an object is returned with the following properties:
    -   _namespace_ `string`: The route namespace for the collection, eg. `/wc/blocks`.
    -   _resourceName_ `string`: The resource name for the collection, eg. `products/attributes`.
    -   _header_ `string`: The header key for the header.
    -   _query_ `Object`: The query arguments for the collection, eg. `{ order: 'ASC', sortBy: Price }`.
    -   _ids_ `Array`: If the collection route has placeholders for ids you provide the values for those placeholders in this array (in order).

### getCollectionHeaders

This selector will return the headers for a collection.

#### _Returns_ 

-   `object`:  Returns the `getFromState` object (see [`getFromState`](#getfromstate)).

#### _Example_ 

```js
const store = select( COLLECTIONS_STORE_KEY );
const headers = store.getCollectionHeaders( state, namespace, resourceName, queryString );
```

### getCollectionError

This selector will return any error that occurred while fetching a collection.

#### _Returns_ 

-   `object`:  Returns the `getFromState` object (see [`getFromState`](#getfromstate)).

#### _Example_ 

```js
const store = select( COLLECTIONS_STORE_KEY );
const error = store.getCollectionError( state, namespace, resourceName, queryString );
```

### getCollectionLastModified

This selector will return the last modified date for a collection.

#### _Returns_ 

-   `number`: The last modified date for the collection, or `0` if there was no last modified date.

#### _Example_ 

```js
const store = select( COLLECTIONS_STORE_KEY );
const lastModified = store.getCollectionLastModified( state, namespace, resourceName, queryString );
```



---

## Payment Store (`wc/store/payment`)

*Source: block-development/reference/data-store/payment.md*

# Payment Store (`wc/store/payment`) 

## Overview

The payment data store is used to store payment method data and payment processing information. When the payment status changes, the data store will reflect this.

**⚠️ Currently, all the actions are internal-only while we determine which ones will be useful for extensions to interact with. We do not encourage extensions to dispatch actions onto this data store yet.**

An example of data held within the Payment Data Store is shown below. This example shows the state with several Payment Gateways active, and a saved token.

```js
{
    status: 'idle',
    activePaymentMethod: 'stripe',
    activeSavedToken: '1',
    availablePaymentMethods: {
      bacs: {
        name: 'bacs'
      },
      cheque: {
        name: 'cheque'
      },
      cod: {
        name: 'cod'
      },
      stripe: {
        name: 'stripe'
      }
    },
     availableExpressPaymentMethods: {
      payment_request: {
        name: 'payment_request'
      }
    },
    savedPaymentMethods: {
      cc: [
        {
          method: {
            gateway: 'stripe',
            last4: '4242',
            brand: 'Visa'
          },
          expires: '12/32',
          is_default: true,
          actions: {
            'delete': {
              url: 'https://store.local/checkout/delete-payment-method/1/?_wpnonce=123456',
              name: 'Delete'
            }
          },
          tokenId: 1
        }
      ]
    },
    paymentMethodData: {
      token: '1',
      payment_method: 'stripe',
      'wc-stripe-payment-token': '1',
      isSavedToken: true
    },
    paymentResult: null,
    paymentMethodsInitialized: true,
    expressPaymentMethodsInitialized: true,
    shouldSavePaymentMethod: false
}
```

## Usage

To utilize this store you will import the `paymentStore` `StoreDescriptor` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via:

```js
const { paymentStore } = window.wc.wcBlocksData;
```

## Selectors

### getState

Returns the current state of the payment store.

> 🚨 Instead of using this selector, the focused selectors should be used. This selector should only be used to mock selectors in our unit tests.

#### _Returns_ 

-   `object`: The current state of the payment store with the following properties:
   	-  _status_ `string`: The current status of the payment process. Possible values are: `idle`, `started`, `processing`, `ready`, `error`, `success`, `failed`.
   	-  _activePaymentMethod_ `string`: The ID of the active payment method.
   	-  _activeSavedToken_ `string`: The ID of the active saved token.
   	-  _availablePaymentMethods_ `object`: The available payment methods. This is currently just an object keyed by the payment method IDs. Each member contains a `name` entry with the payment method ID as its value.
   	-  _availableExpressPaymentMethods_ `object`: The available express payment methods. This is currently just an object keyed by the payment method IDs. Each member contains a `name` entry with the payment method ID as its value.
   	-  _savedPaymentMethods_ `object`: The saved payment methods for the current customer. This is an object, it will be specific to each payment method. As an example, Stripe's saved tokens are returned like so:
   	- _paymentMethodData_ `object`: The current payment method data. This is specific to each payment method so further details cannot be provided here.
   	- _paymentResult_ `object`: An object with the following properties:
      		- _message_ `string`: The message returned by the payment gateway.
      		- _paymentStatus_ `string`: The status of the payment. Possible values are: `success`, `failure`, `pending`, `error`, `not set`.
      		- _paymentDetails_ `object`: The payment details returned by the payment gateway.
      		- _redirectUrl_ `string`: The URL to redirect to after checkout is complete.
   	- _paymentMethodsInitialized_ `boolean`: True if the payment methods have been initialized, false otherwise.
   	- _expressPaymentMethodsInitialized_ `boolean`: True if the express payment methods have been initialized, false otherwise.
   	- _shouldSavePaymentMethod_ `boolean`: True if the payment method should be saved, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const currentState = store.getState();
```

### isPaymentIdle

Queries if the status is `idle`.

#### _Returns_ 

-   `boolean`: True if the payment status is `idle`, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const isPaymentIdle = store.isPaymentIdle();
```

### isExpressPaymentStarted

Queries if an express payment method has been clicked.

#### _Returns_ 

-   `boolean`: True if the button for an express payment method has been clicked, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const isExpressPaymentStarted = store.isExpressPaymentStarted();
```

### isPaymentProcessing

Queries if the status is `processing`.

#### _Returns_ 

-   `boolean`: True if the payment status is `processing`, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const isPaymentProcessing = store.isPaymentProcessing();
```

### isPaymentReady

Queries if the status is `ready`.

#### _Returns_ 

-   `boolean`: True if the payment status is `ready`, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const isPaymentReady = store.isPaymentReady();
```

### hasPaymentError

Queries if the status is `error`.

#### _Returns_ 

-   `boolean`: True if the payment status is `error`, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const hasPaymentError = store.hasPaymentError();
```

### isExpressPaymentMethodActive

Returns whether an express payment method is active, this will be true when the express payment method is open and taking user input. In the case of Google Pay it is when the modal is open but other payment methods may have different UIs.

#### _Returns_ 

-   `boolean`: Whether an express payment method is active.

#### _Example_ 

```js
const store = select( paymentStore );
const isExpressPaymentMethodActive = store.isExpressPaymentMethodActive();
```

### getActiveSavedToken

Returns the active saved token. Payment methods that customers have saved to their account have tokens associated with them. If one of these is selected then this selector returns the token that is currently active. If one is not selected this will return an empty string.

#### _Returns_ 

-   `string`: The active saved token ID, or empty string if a saved token is not selected.

#### _Example_ 

```js
const store = select( paymentStore );
const activeSavedToken = store.getActiveSavedToken();
```

### getActivePaymentMethod

Returns the active payment method's ID.

#### _Returns_ 

-   `string`: The active payment method's ID.

#### _Example_ 

```js
const store = select( paymentStore );
const activePaymentMethod = store.getActivePaymentMethod();
```

### getAvailablePaymentMethods

Returns the available payment methods. This does not include express payment methods.

#### _Returns_ 

-   `object`: The available payment methods. This is currently just an object keyed by the payment method IDs. Each member contains a `name` entry with the payment method ID as its value.

#### _Example_ 

```js
const store = select( paymentStore );
const availablePaymentMethods = store.getAvailablePaymentMethods();
```

`availablePaymentMethods` will look like this:

```js
{
    "cheque": {
        name: "cheque",
    },
    "cod": {
        name: "cod",
    },
    "bacs": {
        name: "bacs",
    },
}
```

### getAvailableExpressPaymentMethods

Returns the available express payment methods.

#### _Returns_ 

-   `object`: The available express payment methods. This is currently just an object keyed by the payment method IDs. Each member contains a `name` entry with the payment method ID as its value.

#### _Example_ 

```js
const store = select( paymentStore );
const availableExpressPaymentMethods =
	store.getAvailableExpressPaymentMethods();
```

`availableExpressPaymentMethods` will look like this:

```js
{
    "payment_request": {
        name: "payment_request",
    },
    "other_express_method": {
        name: "other_express_method",
    },
}
```

### getPaymentMethodData

Returns the current payment method data. This will change every time the active payment method changes and is not persisted for each payment method. For example, if the customer has PayPal selected, the payment method data will be specific to that payment method. If they switch to Stripe, the payment method data will be overwritten by Stripe, and the previous value (when PayPal was selected) will not be available anymore.

#### _Returns_ 

-   `object`: The current payment method data. This is specific to each payment method so further details cannot be provided here.

#### _Example_ 

```js
const store = select( paymentStore );
const paymentMethodData = store.getPaymentMethodData();
```

### getSavedPaymentMethods

Returns all saved payment methods for the current customer.

#### _Returns_ 

-   `object`: The saved payment methods for the current customer. This is an object, it will be specific to each payment method. As an example, Stripe's saved tokens are returned like so:

```js
savedPaymentMethods: {
	cc: [
		{
			method: {
				gateway: 'stripe',
				last4: '4242',
				brand: 'Visa',
			},
			expires: '04/24',
			is_default: true,
			actions: {
				wcs_deletion_error: {
					url: '#choose_default',
					name: 'Delete',
				},
			},
			tokenId: 2,
		},
	];
}
```

#### _Example_ 

```js
const store = select( paymentStore );
const savedPaymentMethods = store.getSavedPaymentMethods();
```

### getActiveSavedPaymentMethods

Returns the saved payment methods for the current customer that are active, i.e. the ones that can be used to pay for the current order.

#### _Returns_ 

`object` - The saved payment methods for the current customer that are active, i.e. the ones that can be used to pay for this order. This is an object, it will be specific to each payment method. As an example, Stripe's saved tokens are returned like so:

```js
activeSavedPaymentMethods: {
	cc: [
		{
			method: {
				gateway: 'stripe',
				last4: '4242',
				brand: 'Visa',
			},
			expires: '04/24',
			is_default: true,
			actions: {
				wcs_deletion_error: {
					url: '#choose_default',
					name: 'Delete',
				},
			},
			tokenId: 2,
		},
	];
}
```

#### _Example_ 

```js
const store = select( paymentStore );
const activeSavedPaymentMethods = store.getActiveSavedPaymentMethods();
```

### getIncompatiblePaymentMethods

Returns the list of payment methods that are incompatible with Checkout block.

#### _Returns_ 

-   `object`: A list of incompatible payment methods with the following properties, or an empty object if no payment or express payment methods have been initialized:
   	-  _name_ `string`: The name of the payment method.

#### _Example_ 

```js
const store = select( paymentStore );
const incompatiblePaymentMethods = store.getIncompatiblePaymentMethods();
```

### getShouldSavePaymentMethod

Returns whether the payment method should be saved to the customer's account.

#### _Returns_ 

-   `boolean`: True if the payment method should be saved, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const shouldSavePaymentMethod = store.getShouldSavePaymentMethod();
```

### paymentMethodsInitialized

Returns whether the payment methods have been initialized.

#### _Returns_ 

-   `boolean`: True if the payment methods have been initialized, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const paymentMethodsInitialized = store.paymentMethodsInitialized();
```

### expressPaymentMethodsInitialized

Returns whether the express payment methods have been initialized.

#### _Returns_ 

`boolean`: True if the express payment methods have been initialized, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const expressPaymentMethodsInitialized =
	store.expressPaymentMethodsInitialized();
```

### getPaymentResult

Returns the result of the last payment attempt.

#### _Returns_ 

-   `object`: An object with the following properties:

```ts
{
	message: string;
	paymentStatus: 'success' | 'failure' | 'pending' | 'error' | 'not set';
	paymentDetails: Record< string, string > | Record< string, never >;
	redirectUrl: string;
}
```

#### _Example_ 

```js
const store = select( paymentStore );
const paymentResult = store.getPaymentResult();
```

### (@deprecated) isPaymentPristine

Queries if the status is `pristine`.

> ⚠️ This selector is deprecated and will be removed in a future release. Please use `isPaymentIdle` instead.

#### _Returns_ 

-   `boolean`: True if the payment status is `pristine`, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const isPaymentPristine = store.isPaymentPristine();
```

### (@deprecated) isPaymentStarted

Queries if the status is `started`.

> ⚠️ This selector is deprecated and will be removed in a future release. Please use `isExpressPaymentStarted` instead.

#### _Returns_ 

-   `boolean`: True if the payment status is `started`, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const isPaymentStarted = store.isPaymentStarted();
```

### (@deprecated) isPaymentSuccess

Queries if the status is `success`.

> ⚠️ This selector is deprecated and will be removed in a future release. Please use `isPaymentReady` instead.

#### _Returns_ 

-   `boolean`: True if the payment status is `success`, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const isPaymentSuccess = store.isPaymentSuccess();
```

### (@deprecated) isPaymentFailed

Queries if the status is `failed`.

> ⚠️ This selector is deprecated and will be removed in a future release. Please use `hasPaymentError` instead.

#### _Returns_ 

-   `boolean`: True if the payment status is `failed`, false otherwise.

#### _Example_ 

```js
const store = select( paymentStore );
const isPaymentFailed = store.isPaymentFailed();
```

### (@deprecated) getCurrentStatus

Returns an object with booleans representing the payment status.

> ⚠️ This selector is deprecated and will be removed in a future release. Please use the selectors above.

#### _Returns_ 

-   `object`: The current payment status with the following keys:
    -   _isPristine_ `boolean`: True if the payment process has not started, does not have an error and has not finished. This is true initially.
    -   _isStarted_ `boolean`: True if the payment process has started.
    -   _isProcessing_ `boolean`: True if the payment is processing.
    -   _hasError_ `boolean`: True if the payment process has resulted in an error.
    -   _hasFailed_ `boolean`: True if the payment process has failed.
    -   _isSuccessful_ `boolean`: True if the payment process is successful.
    -   _isDoingExpressPayment_ `boolean`: True if an express payment method is active, false otherwise

#### _Example_ 

```js
const store = select( paymentStore );
const currentStatus = store.getCurrentStatus();
```



---

## Query State Store (`wc/store/query-state`)

*Source: block-development/reference/data-store/query-state.md*

# Query State Store (`wc/store/query-state`) 

## Overview

The Query State Store offers actions to handle and manipulate query-related data within specific contexts, such as individual blocks. This facilitates the dynamic updating and retrieval of query-state values, ensuring accurate and context-specific data management within WooCommerce Blocks.

## Usage

To utilize this store you will import the `QUERY_STATE_STORE_KEY` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via:

```js
const { QUERY_STATE_STORE_KEY } = window.wc.wcBlocksData;
```

## Actions

> ⚠️ New values will always overwrite any existing entry in the store.

### setQueryValue( context, queryKey, value )

This will set a single query-state value for a given context.

#### _Parameters_ 

-   _context_ `string`: The context for the query state being stored, eg. the block name so you can keep query-state specific per block.
-   _queryKey_ `string`: The reference for the value being stored.
-   _value_ `mixed`: The actual value being stored for the query-state.

### setValueForQueryContext( context ,value )

This will set the query-state for a given context. Typically this is used to set/replace the entire query-state for a given context rather than the individual keys for the context via `setQueryValue`.

#### _Parameters_ 

-   _context_ `string`: The context for the query state being stored, eg. the block name so you can keep query-state specific per block.
-   _value_ `object`: An object of key/value pairs for the query state being attached to the context.



---

## Schema Store (`wc/store/schema`)

*Source: block-development/reference/data-store/schema.md*

# Schema Store (`wc/store/schema`) 

## Overview

The Schema Store manages the routes associated with WooCommerce Blocks, enabling efficient retrieval and updating of route data for a given namespace. This store streamlines the interaction with resource routes, ensuring that modules can easily access endpoint paths as needed.

## Usage

To utilize this store you will import the `SCHEMA_STORE_KEY` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via:

```js
const { SCHEMA_STORE_KEY } = window.wc.wcBlocksData;
```

## Actions

> ⚠️ You should rarely need to use any of these actions directly as they are mostly used internally by the resolvers.

### receiveRoutes( routes, namespace)

This returns an action object used to update the store with the provided list of resource routes.

#### _Parameters_ 

-   _routes_ `array`: An array of routes attached for the given namespace, eg. `[ '/wc/blocks/products', '/wc/blocks/products/attributes/(?P<id>[\d]+)' ]`.
-   _namespace_ `string`: The namespace the routes belong to, eg. `/wc/blocks`.

#### _Returns_ 

-   `object`: An action object used to update the store with the provided list of resource routes with the following keys:
    -   _type_ `string`: The action type.
    -   _routes_ `object`: An object of routes keyed by the route name.
    -   _namespace_ `string`: The namespace the routes belong to, eg. `/wc/blocks`.

## Selectors

### getRoute( state, namespace, resourceName, ids = [] )

This is used for retrieving a route for the given namespace, resource name and (if necessary) ids.

#### _Parameters_ 

-   _state_ `object`: The original state.
-   _namespace_ `string`: The namespace for the route, eg. `/wc/blocks`,
-   _resourceName_ `string`: The resource being requested, eg. `products/attributes/terms`.
-   _ids_ `array`: Only needed if the route has placeholders for ids.

#### _Returns_ 

-   `string`: The route if it is available.

#### _Examples_ 

If you are looking for a route for a single product on the `wc/blocks` namespace, then you'd have `[ 20 ]` as the ids:

```js
// '/wc/blocks/products/20'
wp.data.select( SCHEMA_STORE_KEY ).getRoute( '/wc/blocks', 'products', [ 20 ] );
```

### getRoutes( state, namespace )

This will return all the registered routes for the given namespace as a flat array.

#### _Parameters_ 

-   _state_ `object`: The current state.
-   namespace `string`: The namespace to return routes for.

#### _Returns_ 

-   `array`: An array of all routes for the given namespace.

### getRouteFromResourceEntries

This will returns the route from the given slice of the route state.

#### _Parameters_ 

-   _stateSlice_ `object`: Slice of the route state from a given namespace and resource name.
-   _ids_ `array` (default: `[]`): An array of id references that are to be replaced in route placeholders.

#### _Returns_ 

-   `string`: The route for the given resource entries, or an empty string if no route is found.

#### _Example_ 

```js
const store = select( SCHEMA_STORE_KEY );
const route = store.getRouteFromResourceEntries( stateSlice, ids );
```

### assembleRouteWithPlaceholders

This will return the assembled route with placeholders.

#### _Parameters_ 

-   _route_ `string`: The route to assemble.
-   _routePlaceholders_ `array`: An array of route placeholders.
-   _ids_ `array`: An array of id references that are to be replaced in route placeholders.

#### _Returns_ 

-   `string`: The assembled route with placeholders replaced by actual values.

#### _Example_ 

```js
const store = select( SCHEMA_STORE_KEY );
const route = store.assembleRouteWithPlaceholders( route, routePlaceholders, ids );
```


---

## Store Notices Store (`wc/store/store-notices`)

*Source: block-development/reference/data-store/store-notices.md*

# Store Notices Store (`wc/store/store-notices`) 

## Overview

The Store Notices Store allows to register and unregister containers for notices. This is useful for displaying notices in a specific location, such as a custom block.

## Usage

To utilize this store you will import the `storeNoticesStore` `StoreDescriptor` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the `StoreDescriptor` via:

```js
import { storeNoticesStore } from '@woocommerce/block-data';
```

If it's not, then access it from the window like so:

```js
const { storeNoticesStore } = window.wc.wcBlocksData;
```

## Example

The following code snippet demonstrates how to register a container for notices.

```js
import { store as noticesStore } from '@wordpress/notices';

export default function Block( attributes ) {
	const context = 'your-namespace/custom-form-step';

	dispatch( noticesStore ).createNotice(
		'error',
		'This is an example of an error notice.',
		{ context }
	);

	return (
		<>
			<StoreNoticesContainer context={ context } />
			{ /* Your custom block code here */ }
		</>
	);
}
```

> 💡 Internally, the `StoreNoticesContainer` component will dispatch the `registerContainer` action.

Please note that this is a simple example. In practice, you will want to trigger the `createNotice` action in response to a user action, such as submitting a form.

## Actions

### registerContainer( containerContext )

This action will register a new container.

#### _Parameters_ 

-   _containerContext_ `string`: The context or identifier of the container to be registered.

#### _Returns_ 

-   `object`: An action object with the following properties:
    -   _type_ `string`: The type of the action.
    -   _containerContext_ `string`: The passed _containerContext_.

#### _Example_ 

```javascript
import { storeNoticesStore } from '@woocommerce/block-data';

dispatch( storeNoticesStore ).registerContainer( 'someContainerContext' );
```

### unregisterContainer( containerContext )

This action will unregister an existing container.

#### _Parameters_ 

-   _containerContext_ `string`: The context or identifier of the container to be unregistered.

#### _Returns_ 

-   `object`: An action object with the following properties:
    -   _type_ `string`: The type of the action.
    -   _containerContext_ `string`: The passed _containerContext_.

#### _Example_ 

```js
import { storeNoticesStore } from '@woocommerce/block-data';

dispatch( storeNoticesStore ).unregisterContainer( 'someContainerContext' );
```

## Selectors

### getRegisteredContainers

Returns the list of currently registered containers from the state.

#### _Returns_ 

-   `string[]`: An array of strings with the registered container contexts.

#### _Example_ 

```js
import { storeNoticesStore } from '@woocommerce/block-data';

const store = select( storeNoticesStore );
const registeredContainers = store.getRegisteredContainers();
```


---

## Validation Store (`wc/store/validation`)

*Source: block-development/reference/data-store/validation.md*

# Validation Store (`wc/store/validation`) 

## Overview

The validation data store provides a way to show errors for fields in the Cart or Checkout blocks.

The data in the store should be a single object, the keys of which are the _error IDs_ and values are the data associated with that error message. The values in the object should contain _message_ and _hidden_. The _message_ is the error message to display and _hidden_ is a boolean indicating whether the error should be shown or not.

An example of how the data should be structured:

```js
{
    "error-id-1": {
        message: "This is an error message",
        hidden: false,
    },
    "error-id-2": {
        message: "This is another error message",
        hidden: true,
    },
}
```

When the checkout process begins, it will check if this data store has any entries, and if so, it will stop the checkout process from proceeding. It will also show any errors that are hidden. Setting an error to hidden will not clear it from the data store!

## Usage

To utilize this store you will import the `validationStore` `StoreDescriptor` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the `StoreDescriptor` via:

```js
const { validationStore } = window.wc.wcBlocksData;
```

## Example

To better understand the Validation Store, let's use the required checkbox of the Terms and Conditions as an example. In the page editor, a merchant can define that a buyer must agree to the Terms and Conditions by making the checkbox required.

![image](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-24-at-17.22.45.png)

In WooCommerce Blocks, we're using a `useEffect` hook to check if the checkbox is required and if it is checked. If the checkbox is required and not checked, we're adding a validation error to the store. If the checkbox is required and checked, we're clearing the validation error from the store.

```ts
useEffect( () => {
	if ( ! checkbox ) {
		return;
	}
	if ( checked ) {
		clearValidationError( validationErrorId );
	} else {
		setValidationErrors( {
			[ validationErrorId ]: {
				message: __(
					'Please read and accept the terms and conditions.',
					'woo-gutenberg-products-block'
				),
				hidden: true,
			},
		} );
	}
	return () => {
		clearValidationError( validationErrorId );
	};
}, [
	checkbox,
	checked,
	validationErrorId,
	clearValidationError,
	setValidationErrors,
] );
```

By default, the validation error is hidden. This is because we don't want to show the error message until the buyer has tried to submit the form. Before submitting the checkout form, the validation message can already be seen in the Validation Store.

![image](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-24-at-17.28.56.png)

When a buyer submits the checkout form without checking the Terms and Conditions checkbox, the entry `hidden: true` will be changed to `hidden: false` and the validation message is shown.

![image](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-24-at-17.33.01.png)

In WooCommerce Blocks, we're checking if text input fields have a validation error using the following code:

```ts
const hasError = validationError?.message && ! validationError?.hidden;
```

> 💡 The main point to remember from this example is:
>
> -   `hidden: true` means there's a validation error, but it's kept from the user's view.
> -   `hidden: false` indicates that the validation error is actively being shown to the user.

In the example above, the `message` is hidden and only the text color is changed to red, highlighting that this field has a validation error.

In some cases, it's desired to show the validation error message to the user. For example, if the buyer tries to submit the checkout form without filling in the required fields. An example can seen when leaving the first name, last name and address fields empty:

![image](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-25-at-18.28.30.png)

In WooCommerce Blocks, the following function handles the display logic of the validation error message:

```ts
export const ValidationInputError = ( {
	errorMessage = '',
	propertyName = '',
	elementId = '',
}: ValidationInputErrorProps ): JSX.Element | null => {
	const { validationError, validationErrorId } = useSelect( ( select ) => {
		const store = select( validationStore );
		return {
			validationError: store.getValidationError( propertyName ),
			validationErrorId: store.getValidationErrorId( elementId ),
		};
	} );

	if ( ! errorMessage || typeof errorMessage !== 'string' ) {
		if ( validationError?.message && ! validationError?.hidden ) {
			errorMessage = validationError.message;
		} else {
			return null;
		}
	}

	return (
		<div className="wc-block-components-validation-error" role="alert">
			<p id={ validationErrorId }>{ errorMessage }</p>
		</div>
	);
};
```

A simplified version of the code snippet above would be the following:

```js
{
	validationError?.hidden === false && (
		<div className="wc-block-components-validation-error" role="alert">
			<p>{ validationError?.message }</p>
		</div>
	);
}
```

## Actions

### clearValidationError( errorId )

Clears a validation error.

#### _Parameters_ 

-   _errorId_ `string`: The error ID to clear validation errors for.

#### _Example_ 

```js
const store = dispatch( validationStore );
store.clearValidationError( 'billing-first-name' );
```

### clearValidationErrors( errors )

Clears multiple validation errors at once. If no error IDs are passed, all validation errors will be cleared.

#### _Parameters_ 

-   _errors_ `string[]` or `undefined`: The error IDs to clear validation errors for. This can be undefined, and if it is, all validation errors will be cleared.

#### _Example_ 

This will clear only the validation errors passed in the array:

```js
const store = dispatch( validationStore );
store.clearValidationErrors( [
	'billing-first-name',
	'billing-last-name',
	'terms-and-conditions',
] );
```

This will clear all validation errors:

```js
const store = dispatch( validationStore );
store.clearValidationErrors();
```

### setValidationErrors( errors )

Sets the validation errors. The entries in _errors_ will be _added_ to the list of validation errors. Any entries that already exist in the list will be _updated_ with the new values.

#### _Parameters_ 

-   _errors_ `object`: The new validation errors, the keys of the object are the validation error IDs, and the values should be objects containing _message_ `string` and _hidden_ `boolean`.

#### _Example_ 

```js
const { dispatch } = wp.data;
const { setValidationErrors } = dispatch( validationStore );

setValidationErrors( {
	'billing-first-name': {
		message: 'First name is required.',
		hidden: false,
	},
	'billing-last-name': {
		message: 'Last name is required.',
		hidden: false,
	},
} );
```

### hideValidationError( errorId )

Hides a validation error by setting the `hidden` property to `true`. This will _not_ clear it from the data store!

#### _Parameters_ 

-   _errorId_ `string`: The error ID to hide.

#### _Example_ 

```js
const { dispatch } = wp.data;
const { hideValidationError } = dispatch( validationStore );

hideValidationError( 'billing-first-name' );
```

### showValidationError( errorId )

Shows a validation error by setting the `hidden` property to `false`.

#### _Parameters_ 

-   _errorId_ `string`: The error ID to show.

#### _Example_ 

```js
const { dispatch } = wp.data;
const { showValidationError } = dispatch( validationStore );

showValidationError( 'billing-first-name' );
```

### showAllValidationErrors

Shows all validation errors by setting the `hidden` property to `false`.

#### _Example_ 

```js
const { dispatch } = wp.data;
const { showAllValidationErrors } = dispatch( validationStore );

showAllValidationErrors();
```

### clearAllValidationErrors

Clears all validation errors by removing them from the store.

#### _Example_ 

```js
const { clearAllValidationErrors } = dispatch( validationStore );
clearAllValidationErrors();
```

## Selectors

### getValidationError( errorId )

Returns the validation error.

#### _Parameters_ 

-   _errorId_ `string`: The error ID to get validation errors for.

#### _Returns_ 

-   `object`: The validation error which is an object containing _message_ `string` and _hidden_ `boolean`.

#### _Example_ 

```js
const store = select( validationStore );
const billingFirstNameError = store.getValidationError( 'billing-first-name' );
```

### getValidationErrorId( errorId )

Gets a validation error ID for use in HTML which can be used as a CSS selector, or to reference an error message. This will return the error ID prefixed with `validate-error-`, unless the validation error has `hidden` set to true, or the validation error does not exist in the store.

#### _Parameters_ 

-   _errorId_ `string`: The error ID to get the validation error ID for.

#### _Returns_ 

-   `string`: The validation error ID for use in HTML.

#### _Example_ 

```js
const store = select( validationStore );
const billingFirstNameErrorId =
	store.getValidationErrorId( 'billing-first-name' );
```

### getValidationErrors

Returns all validation errors in the store.

#### _Returns_ 

-   `Record<string, FieldValidationStatus>`: All validation errors where keys are error IDs and values are FieldValidationStatus objects containing _message_ `string` and _hidden_ `boolean`.

#### _Example_ 

```js
const store = select( validationStore );
const allValidationErrors = store.getValidationErrors();
```

### hasValidationErrors

Returns true if validation errors occurred, and false otherwise.

#### _Returns_ 

-   `boolean`: Whether validation errors occurred.

#### _Example_ 

```js
const store = select( validationStore );
const hasValidationErrors = store.hasValidationErrors();
```


---

## Hooks

*Source: block-development/reference/hooks/README.md*

# Hooks

We have several hooks that can be used by extensions, some are new and some are hooks that already exist in WooCommerce core.

- [Filters](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md)
- [Actions](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md)

We also have a list of hooks that have been migrated from WooCommerce Core, but that have been renamed.

- [List of migrated hooks](./migrated-hooks.md)


---

## Hook alternatives

*Source: block-development/reference/hooks/hook-alternatives.md*

# Hook alternatives

These are the hooks that run when loading the Cart/Checkout shortcodes and blocks. Some are general WooCommerce lifecycle hooks, some are specific to the Cart and Checkout pages. These were generated by logging each call to `do_action` and `apply_filters` and reviewing the issues mentioning "hooks" and "filter(s)" in the old [WooCommerce Blocks repository](https://github.com/woocommerce/woocommerce-blocks/).

## Legend

| Icon | Description |
| --- | --- |
| ✅ | Fully supported |
| 🔶 | Partially supported |
| ❌ | Not supported |
| ❓ | Unknown |

If a hook is marked as Unknown ❓(Unknown) it means we were not able to verify whether the hook is supported for some reason. As time goes on, we will attempt to validate more of these hooks. The goal is to have no hooks with an Unknown ❓status remaining in any of the tables.

### WooCommerce lifecycle _actions_

These hooks run on every Woo page load, some affect the blocks, some don't, some only affect them partially.

| Old hook | Works in blocks? | Notes |
| --- | --- | --- |
| `woocommerce_load_cart_from_session` | Fully supported ✅ | |
| `woocommerce_cart_loaded_from_session` | Fully supported ✅ | |
| `woocommerce_set_cart_cookies` | Fully supported ✅ | |
| `woocommerce_shipping_zone_loaded` | Fully supported ✅ | |
| `woocommerce_check_cart_items` | Fully supported ✅ | May be better to use `woocommerce_store_api_validate_cart_item` |
| `woocommerce_before_calculate_totals` | Fully supported ✅ | |
| `woocommerce_shipping_init` | Fully supported ✅ | |
| `woocommerce_load_shipping_methods` | Fully supported ✅ | |
| `woocommerce_cart_calculate_fees` | Fully supported ✅ | |
| `woocommerce_calculate_totals` | Fully supported ✅ | |
| `woocommerce_after_calculate_totals` | Fully supported ✅ | |
| `woocommerce_cart_updated` | Fully supported ✅ | |
| `woocommerce_before_get_rates_for_package` | Fully supported ✅ | |
| `woocommerce_after_get_rates_for_package` | Fully supported ✅ | |
| `woocommerce_checkout_init` | Fully supported ✅ | |
| `woocommerce_customer_loaded` | Fully supported ✅ | |

### WooCommerce lifecycle _filters_

| Old hook | Works in blocks? | Notes |
| --- | --- | --- |
| `woocommerce_notice_types` | Unknown ❓ | WC Blocks does not handle additional notice types outside of the core ones. Non-supported notices would be displayed as "info" notices. |
| `woocommerce_kses_notice_allowed_tags` | Unknown ❓ | |
| `woocommerce_product_get_stock_status` | Fully supported ✅ | |
| `woocommerce_product_is_in_stock` | Fully supported ✅ | |
| `woocommerce_product_get_manage_stock` | Unknown ❓ | |
| `woocommerce_product_get_tax_class` | Fully supported ✅ | |
| `woocommerce_product_get_tax_status` | Unknown ❓ | |
| `woocommerce_prices_include_tax` | Unknown ❓ | |
| `woocommerce_apply_base_tax_for_local_pickup` | Unknown ❓ | |
| `woocommerce_local_pickup_methods` | Not supported ❌ | Does not affect the blocks-based local pickup methods |
| `woocommerce_customer_get_shipping_postcode` | Fully supported ✅ | |
| `woocommerce_customer_get_shipping_city` | Fully supported ✅ | |
| `woocommerce_customer_taxable_address` | Unknown ❓ | |
| `woocommerce_shipping_methods` | Fully supported ✅ | |
| `woocommerce_format_localized_price` | Unknown ❓ | |
| `woocommerce_shipping_local_pickup_option` | Not supported ❌ | Does not affect the blocks-based local pickup methods |
| `woocommerce_shipping_pickup_location_option` | Unknown ❓ | Unsure if changing this changes the way local pickup shows in the Cart/Checkout |
| `woocommerce_shipping_method_supports` | Fully supported ✅ | |
| `woocommerce_get_tax_location` | Unknown ❓ | |
| `woocommerce_format_postcode` | Unknown ❓ | |
| `woocommerce_matched_tax_rates` | Unknown ❓ | |
| `woocommerce_find_rates` | Unknown ❓ | |
| `woocommerce_matched_rates` | Unknown ❓ | |
| `woocommerce_cart_totals_get_item_tax_rates` | Fully supported ✅ | |
| `woocommerce_adjust_non_base_location_prices` | Unknown ❓ | |
| `woocommerce_product_is_taxable` | Fully supported ✅ | |
| `woocommerce_price_ex_tax_amount` | Fully supported ✅ | |
| `woocommerce_tax_round` | Fully supported ✅ | |
| `woocommerce_calc_tax` | Fully supported ✅ | |
| `woocommerce_calculate_item_totals_taxes` | Fully supported ✅ | |
| `woocommerce_cart_ready_to_calc_shipping` | Fully supported ✅ | |
| `woocommerce_product_get_virtual` | Fully supported ✅ | |
| `woocommerce_is_virtual` | Fully supported ✅ | |
| `woocommerce_product_needs_shipping` | Fully supported ✅ | |
| `woocommerce_cart_needs_shipping` | Fully supported ✅ | |
| `woocommerce_customer_get_shipping_address_1` | Fully supported ✅ | |
| `woocommerce_customer_get_shipping_address_2` | Fully supported ✅ | |
| `woocommerce_cart_display_prices_including_tax` | Fully supported ✅ | |
| `woocommerce_cart_get_subtotal` | Fully supported ✅ | |
| `woocommerce_cart_shipping_packages` | Fully supported ✅ | |
| `woocommerce_product_get_shipping_class_id` | Fully supported ✅ | |
| `woocommerce_countries_shipping_countries` | Fully supported ✅ | |
| `woocommerce_get_zone_criteria` | Fully supported ✅ | |
| `woocommerce_shipping_zone_shipping_methods` | Fully supported ✅ | |
| `woocommerce_shipping_free_shipping_is_available` | Unknown ❓ | |
| `woocommerce_product_get_name` | Fully supported ✅ | |
| `woocommerce_shipping_method_add_rate` | Fully supported ✅ | |
| `woocommerce_shipping_flat_rate_is_available` | Fully supported ✅ | |
| `woocommerce_evaluate_shipping_cost_args` | Fully supported ✅ | |
| `woocommerce_calc_shipping_tax` | Fully supported ✅ | |
| `woocommerce_localisation_address_formats` | Fully supported ✅ | |
| `woocommerce_countries_base_country` | Unknown ❓ | |
| `woocommerce_formatted_address_force_country_display` | Unknown ❓ | |
| `woocommerce_states` | Fully supported ✅ | |
| `woocommerce_formatted_address_replacements` | Unknown ❓ | |
| `woocommerce_package_rates` | Fully supported ✅ | |
| `woocommerce_shipping_packages` | Fully supported ✅ | |
| `woocommerce_shipping_rate_method_id` | Fully supported ✅ | |
| `woocommerce_shipping_rate_taxes` | Fully supported ✅ | |
| `woocommerce_shipping_rate_cost` | Fully supported ✅ | |
| `woocommerce_cart_totals_get_fees_from_cart_taxes` | Fully supported ✅ | |
| `woocommerce_calculated_total` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_cart_get_discount_total` | Fully supported ✅ | |
| `woocommerce_cart_get_cart_contents_total` | Fully supported ✅ | |
| `woocommerce_get_price_excluding_tax` | Not supported ❌ | This does not seem to have any effect |
| `raw_woocommerce_price` | Not supported ❌ | This does not seem to have any effect |
| `formatted_woocommerce_price` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_price_trim_zeros` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_get_cart_page_permalink` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_get_cart_url` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_checkout_registration_enabled` | Fully supported ✅ | This does not seem to have any effect |
| `woocommerce_get_checkout_page_permalink` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_get_checkout_url` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_checkout_get_value` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_default_address_fields` | Not supported ❌ | This does not seem to have any effect |
| `default_checkout_billing_country` | Not supported ❌ | This does not seem to have any effect |
| `default_checkout_shipping_country` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_get_country_locale` | Fully supported ✅ | |
| `woocommerce_get_country_locale_default` | Unknown ❓ | |
| `woocommerce_get_country_locale_base` | Unknown ❓ | |
| `woocommerce_billing_fields` | Partially supported 🔶 | Editing core fields is not supported, but adding them is via Additional Checkout Fields API |
| `woocommerce_shipping_fields` | Partially supported 🔶 | Editing core fields is not supported, but adding them is via Additional Checkout Fields API |
| `woocommerce_checkout_fields` | Partially supported 🔶 | Editing core fields is not supported, but adding them is via Additional Checkout Fields API |
| `woocommerce_cart_item_product` | Not supported ❌ | Modifying individual cart items is not possible |
| `woocommerce_payment_gateway_supports` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_first_name` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_last_name` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_company` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_address_1` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_address_2` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_city` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_postcode` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_phone` | Fully supported ✅ | |
| `woocommerce_customer_get_shipping_first_name` | Fully supported ✅ | |
| `woocommerce_customer_get_shipping_last_name` | Fully supported ✅ | |
| `woocommerce_customer_get_shipping_company` | Fully supported ✅ | |
| `woocommerce_get_item_data` | Partially supported 🔶 | Checkout blocks strip most HTML from metadata, allowing only a, b, em, i, strong, br, abbr, and span. |
| `woocommerce_cart_get_subtotal_tax` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_shipping_package_name` | Fully supported ✅ | |
| `woocommerce_shipping_rate_id` | Unknown ❓ | |
| `woocommerce_shipping_rate_label` | Fully supported ✅ | |
| `woocommerce_cart_get_shipping_taxes` | Fully supported ✅ | |
| `woocommerce_cart_get_fee_taxes` | Fully supported ✅ | |
| `woocommerce_cart_get_taxes` | Fully supported ✅ | |
| `woocommerce_rate_code` | Unknown ❓ | |
| `woocommerce_rate_compound` | Unknown ❓ | |
| `woocommerce_rate_label` | Fully supported ✅ | |
| `woocommerce_cart_hide_zero_taxes` | Unknown ❓ | |
| `woocommerce_cart_tax_totals` | Fully supported ✅ | |
| `woocommerce_cart_needs_payment` | Fully supported ✅ | |
| `woocommerce_order_class` | Fully supported ✅ | |
| `woocommerce_checkout_registration_required` | Unknown ❓ | |
| `woocommerce_privacy_policy_page_id` | Fully supported ✅ | |
| `woocommerce_get_terms_page_id` | Unknown ❓ | |
| `woocommerce_terms_and_conditions_page_id` | Unknown ❓ | |
| `woocommerce_cart_contents_count` | Unknown ❓ | |
| `woocommerce_country_locale_field_selectors` | Not supported ❌ | |
| `woocommerce_get_return_url` | Fully supported ✅ | |
| `woocommerce_cart_hash` | Fully supported ✅ | |
| `woocommerce_cart_get_fee_tax` | Fully supported ✅ | |
| `woocommerce_customer_default_location_array` | Fully supported ✅ | |
| `woocommerce_countries` | Fully supported ✅ | |
| `woocommerce_sort_countries` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_countries_allowed_countries` | Fully supported ✅ | |
| `woocommerce_customer_default_location_array` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_country` | Fully supported ✅ | |
| `woocommerce_customer_get_shipping_country` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_state` | Fully supported ✅ | |
| `woocommerce_customer_get_shipping_state` | Fully supported ✅ | |
| `woocommerce_customer_get_billing_email` | Fully supported ✅ | |
| `woocommerce_cart_session_initialize` | Fully supported ✅ | |
| `woocommerce_get_checkout_page_id` | Fully supported ✅ | |
| `woocommerce_get_cart_page_id` | Fully supported ✅ | |
| `woocommerce_is_checkout` | Fully supported ✅ | |
| `woocommerce_currency` | Fully supported ✅ | |
| `woocommerce_currency_symbols` | Fully supported ✅ | |
| `woocommerce_currency_symbol` | Fully supported ✅ | |
| `woocommerce_price_format` | Fully supported ✅ | |
| `woocommerce_coupons_enabled` | Fully supported ✅ | |
| `woocommerce_get_shop_page_id` | Fully supported ✅ | |
| `current_theme_supports-woocommerce` | Fully supported ✅ | |
| `woocommerce_payment_gateways` | Partially supported 🔶 | Integration with WC Blocks is still required, beyond unsetting gateways, manipulating the payment gateways here may not work in the Cart and Checkout blocks |
| `woocommerce_get_base_location` | Fully supported ✅ | |
| `woocommerce_gateway_icon` | Not supported ❌ | This hook has no effect since icons are not displayed. |
| `woocommerce_get_image_size_thumbnail` | Fully supported ✅ | |
| `woocommerce_get_image_size_single` | Fully supported ✅ | |
| `woocommerce_product_stock_status_options` | Fully supported ✅ | |
| `woocommerce_cart_item_name` | Not supported ❌ | Use the [`itemName` checkout filter](https://developer.woocommerce.com/docs/cart-and-checkout-filters-cart-line-items/#2-itemname). |
| `woocommerce_product_get_status` | Fully supported ✅ | |
| `woocommerce_product_get_price` | Fully supported ✅ | |
| `woocommerce_is_purchasable` | Fully supported ✅ | |
| `woocommerce_cart_item_is_purchasable` | Fully supported ✅ | |
| `woocommerce_cart_item_data_to_validate` | Fully supported ✅ | |
| `woocommerce_get_cart_item_from_session` | Fully supported ✅ | |
| `woocommerce_cart_contents_changed` | Fully supported ✅ | |
| `woocommerce_get_cart_contents` | Fully supported ✅ | |
| `woocommerce_stock_amount` | Fully supported ✅ | |
| `woocommerce_cart_item_remove_link` | Not supported ❌ | Use the [`showRemoveItemLink` checkout filter](https://developer.woocommerce.com/docs/cart-and-checkout-filters-cart-line-items/#4-showremoveitemlink). |
| `woocommerce_cart_item_quantity` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_product_get_image` | Not supported ❌ | Use `woocommerce_store_api_cart_item_images` ([PR Link](https://github.com/woocommerce/woocommerce/pull/52310) with example.) |
| `woocommerce_cart_no_shipping_available_html` | Not supported ❌ | This is not editable |
| `woocommerce_available_payment_gateways` | Partially supported 🔶 | Integration with WC Blocks is still required, beyond unsetting gateways, manipulating the payment gateways here may not work in the Cart and Checkout blocks |
| `woocommerce_cart_get_total` | Fully supported ✅ | |
| `woocommerce_cart_get_fee_tax` | Fully supported ✅ | |
| `woocommerce_cart_get_cart_contents_tax` | Fully supported ✅ | |
| `woocommerce_cart_get_shipping_tax` | Fully supported ✅ | |
| `woocommerce_cart_get_shipping_total` | Fully supported ✅ | |

### Cart _actions_

| Old hook | Works in blocks? | Notes |
| --- | --- | --- |
| `woocommerce_before_cart` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. It is also possible to use the [`render_block_{$name}`](https://developer.wordpress.org/reference/hooks/render_block_this-name/) filter to render before and after blocks using PHP. |
| `woocommerce_before_cart_table` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_before_cart_contents` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_after_cart_item_name` | Not supported ❌ | Use the [`itemName` checkout filter](https://developer.woocommerce.com/docs/cart-and-checkout-filters-cart-line-items/#2-itemname). |
| `woocommerce_before_quantity_input_field` | Not supported ❌ | No equivalent now. |
| `woocommerce_after_quantity_input_field` | Not supported ❌ | No equivalent now. |
| `woocommerce_cart_contents` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_cart_coupon` | Not supported ❌ | [`ExperimentalDiscountsMeta` slot/fill](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#3-experimentaldiscountsmeta) |
| `woocommerce_cart_actions` | Not supported ❌ | [`ExperimentalOrderMeta` slot/fill](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#0-experimentalordermeta) |
| `woocommerce_after_cart_contents` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_after_cart_table` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_before_cart_collaterals` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_cart_collaterals` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_before_cart_totals` | Not supported ❌ | [`ExperimentalOrderMeta` slot/fill](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#0-experimentalordermeta) |
| `woocommerce_cart_totals_before_shipping` | Not supported ❌ | [ExperimentalOrderShippingPackages](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#1-experimentalordershippingpackages) |
| `woocommerce_after_shipping_rate` | Not supported ❌ | [ExperimentalOrderShippingPackages](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#1-experimentalordershippingpackages) |
| `woocommerce_before_shipping_calculator` | Not supported ❌ | No specific equivalent. Closest thing is ExperimentalOrderShippingPackages |
| `woocommerce_after_shipping_calculator` | Not supported ❌ | No specific equivalent. Closest thing is ExperimentalOrderShippingPackages |
| `woocommerce_cart_totals_after_shipping` | Not supported ❌ | No specific equivalent. Closest thing is ExperimentalOrderShippingPackages |
| `woocommerce_cart_totals_before_order_total` | Not supported ❌ | No specific equivalent but we do have the totals footer item filters |
| `woocommerce_cart_totals_after_order_total` | Not supported ❌ | No specific equivalent but we do have the totals footer item filters |
| `woocommerce_proceed_to_checkout` | Not supported ❌ | No specific equivalent but the Checkout and Place Order button filters may work |
| `woocommerce_after_cart_totals` | Not supported ❌ | [`ExperimentalOrderMeta` slot/fill](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#0-experimentalordermeta) |
| `woocommerce_after_cart` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Cart items" block could work, but it would have to be positioned manually by the merchant. |

### Cart _filters_

| Old hook | Works in blocks? | Notes |
| --- | --- | --- |
| `woocommerce_cart_item_product_id` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_cart_item_visible` | Not supported ❌ | This does not seem to have any effect |
| `woocommerce_get_remove_url` | Not supported ❌ | The removal of items is handled async in the Cart block. |
| `woocommerce_cart_item_remove_link` | Not supported ❌ | The removal of items is handled async in the Cart block. |
| `woocommerce_cart_item_thumbnail` | Not supported ❌ | Changing the thumbnail this way is not supported. See `woocommerce_store_api_cart_item_images` ([PR Link](https://github.com/woocommerce/woocommerce/pull/52310) with example.) |
| `woocommerce_cart_product_price` | Not supported ❌ | |
| `woocommerce_cart_item_price` | Not supported ❌ | |
| `woocommerce_quantity_input_classes` | Not supported ❌ | |
| `woocommerce_quantity_input_max` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_quantity_input_min` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_quantity_input_step` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_quantity_input_pattern` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_quantity_input_inputmode` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_quantity_input_placeholder` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_quantity_input_autocomplete` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_quantity_input_args` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_quantity_input_type` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_cart_item_quantity` | Not supported ❌ | This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{$value_type}` filter. |
| `woocommerce_cart_product_subtotal` | Not supported ❌ | |
| `woocommerce_cart_item_subtotal` | Not supported ❌ | |
| `woocommerce_cross_sells_columns` | Not supported ❌ | The cross sells are rendered as an inner block. |
| `woocommerce_cross_sells_orderby` | Not supported ❌ | The cross sells are rendered as an inner block. |
| `woocommerce_cross_sells_order` | Not supported ❌ | The cross sells are rendered as an inner block. |
| `woocommerce_cross_sells_total` | Not supported ❌ | The cross sells are rendered as an inner block. |
| `woocommerce_product_cross_sells_products_heading` | Not supported ❌ | This can be modified in the editor. |
| `woocommerce_is_downloadable` | Not supported ❌ | Does not seem to have any effect in Cart/Checkout blocks. |
| `woocommerce_loop_product_link` | Not supported ❌ | Changing the product links is not supported in the Cart block. |
| `woocommerce_product_loop_title_classes` | Not supported ❌ | Changing classes to product titles is not supported in the Cart block. |
| `woocommerce_product_add_to_cart_aria_describedby` | Not supported ❌ | Changing `aria-describedby` on products is not supported in the Cart block. |
| `woocommerce_sale_flash` | Not supported ❌ | This can be modified with the [`saleBadgePriceFormat` checkout filter](https://developer.woocommerce.com/docs/cart-and-checkout-filters-cart-line-items/#3-salebadgepriceformat). |
| `woocommerce_cart_subtotal` | Not supported ❌ | Modifying the cart subtotal display is not supported in the Cart/Checkout blocks |
| `oocommerce_shipping_package_details_array` | Not supported ❌ | This hook is not fired during Cart block rendering |
| `woocommerce_shipping_show_shipping_calculator` | Not supported ❌ | This is only used when rendering cart templates, which does not happen in the blocks. |
| `woocommerce_cart_shipping_method_full_label` | Not supported ❌ | This hook has no effect in the Cart/Checkout blocks. |
| `woocommerce_get_shipping_tax` | Not supported ❌ | This filter is not used in the Cart/Checkout blocks. |
| `woocommerce_shipping_calculator_enable_country` | Not supported ❌ | This filter is not used in the Cart/Checkout blocks. |
| `woocommerce_shipping_calculator_enable_state` | Not supported ❌ | This filter is not used in the Cart/Checkout blocks. |
| `woocommerce_shipping_calculator_enable_city` | Not supported ❌ | This filter is not used in the Cart/Checkout blocks. |
| `woocommerce_shipping_calculator_enable_postcode` | Not supported ❌ | This filter is not used in the Cart/Checkout blocks. |
| `woocommerce_cart_totals_fee_html` | Not supported ❌ | Modifying the fees display is not supported in the Cart/Checkout blocks |
| `woocommerce_countries_estimated_for_prefix` | Not supported ❌ | |
| `woocommerce_cart_total` | Not supported ❌ | Modifying the cart total using this hook is not supported in the Cart/Checkout blocks |
| `woocommerce_cart_totals_order_total_html` | Not supported ❌ | Modifying the cart total using this hook is not supported in the Cart/Checkout blocks |

### Checkout _actions_

| Old hook | Works in blocks? | Notes |
| --- | --- | --- |
| `woocommerce_before_checkout_form_cart_notices` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_before_checkout_form` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_before_customer_details` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_billing` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_before_checkout_billing_form` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_after_checkout_billing_form` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_shipping` | Not supported ❌ | Not directly equivalent due to positioning, but [ExperimentalOrderShippingPackages](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#1-experimentalordershippingpackages) could work - so could adding an inner block to the shipping block |
| `woocommerce_before_checkout_shipping_form` | Not supported ❌ | Not directly equivalent due to positioning, but [ExperimentalOrderShippingPackages](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#1-experimentalordershippingpackages) could work - so could adding an inner block to the shipping block |
| `woocommerce_after_checkout_shipping_form` | Not supported ❌ | Not directly equivalent due to positioning, but [ExperimentalOrderShippingPackages](https://developer.woocommerce.com/docs/cart-and-checkout-available-slots/#1-experimentalordershippingpackages) could work - so could adding an inner block to the shipping block |
| `woocommerce_before_order_notes` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_after_order_notes` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_after_customer_details` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_before_order_review_heading` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_before_order_review` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_order_review` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_before_cart_contents` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_after_cart_contents` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_before_shipping` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_after_shipping_rate` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_after_shipping` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_before_order_total` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_after_order_total` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_before_payment` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block or Payment block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_before_terms_and_conditions` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_terms_and_conditions` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_after_terms_and_conditions` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_before_submit` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_after_submit` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_review_order_after_payment` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block or Payment block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_after_order_review` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Order Summary" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_after_checkout_form` | Not supported ❌ | No specific equivalent and no Slot/fill for this area. Maybe adding an inner block to the "Checkout Fields" block could work, but it would have to be positioned manually by the merchant. |
| `woocommerce_checkout_update_order_review` | Not supported ❌ | These type of AJAX events do not occur when using the Cart/Checkout blocks |

### Checkout _filters_

| Old hook | Works in blocks? | Notes |
| --- | --- | --- |
| `woocommerce_add_notice` | Partially supported 🔶 | These notices are only added on page load of the Cart/Checkout blocks. Any that happen during API requests are stored and output on the next full page load. |
| `woocommerce_checkout_coupon_message` | Not supported ❌ | The coupon message cannot be customised using this filter. |
| `woocommerce_form_field_args` | Not supported ❌ | Modifying core form fields is not supported yet in the Cart/Checkout blocks. |
| `woocommerce_form_field_text` | Not supported ❌ | Modifying core form fields is not supported yet in the Cart/Checkout blocks. |
| `woocommerce_form_field` | Not supported ❌ | Modifying core form fields is not supported yet in the Cart/Checkout blocks. |
| `woocommerce_form_field_country` | Not supported ❌ | Modifying core form fields is not supported yet in the Cart/Checkout blocks. |
| `woocommerce_form_field_state` | Not supported ❌ | Modifying core form fields is not supported yet in the Cart/Checkout blocks. |
| `woocommerce_form_field_tel` | Not supported ❌ | Modifying core form fields is not supported yet in the Cart/Checkout blocks. |
| `woocommerce_form_field_email` | Not supported ❌ | Modifying core form fields is not supported yet in the Cart/Checkout blocks. |
| `woocommerce_cart_needs_shipping_address` | Not supported ❌ | The [`wc/store/cart` data store](../data-store/cart.md) should be used to control this. |
| `woocommerce_ship_to_different_address_checked` | Not supported ❌ | The [`wc/store/checkout` data store](../data-store/checkout.md) should be used to check if this checkbox is checked. |
| `woocommerce_enable_order_notes_field` | Not supported ❌ | This block must be removed in the editor, this filter will not affect its presence in the Checkout block |
| `woocommerce_form_field_textarea` | Not supported ❌ | Modifying core form fields is not supported yet in the Cart/Checkout blocks. |
| `woocommerce_checkout_cart_item_visible` | Not supported ❌ | It is not possible to filter cart items from the order summary in the Cart/Checkout blocks. |
| `woocommerce_cart_item_class` | Not supported ❌ | It is not possible to add classes to specific cart items in the order summary in the Cart/Checkout blocks. |
| `woocommerce_checkout_cart_item_quantity` | Not supported ❌ | It is not possible to modify the quantity display of cart items in the order summary in the Cart/Checkout blocks. |
| `woocommerce_cart_product_subtotal` | Not supported ❌ | Modifying the product subtotal display is not supported in the Cart/Checkout blocks |
| `woocommerce_cart_item_subtotal` | Not supported ❌ | Modifying the product subtotal display is not supported in the Cart/Checkout blocks |
| `woocommerce_cart_subtotal` | Not supported ❌ | Modifying the cart subtotal display is not supported in the Cart/Checkout blocks |
| `woocommerce_cart_shipping_method_full_label` | Not supported ❌ | Modifying the shipping method display is not supported in the Cart/Checkout blocks |
| `woocommerce_get_shipping_tax` | Not supported ❌ | This filter is not used in the Cart/Checkout blocks. |
| `woocommerce_cart_totals_fee_html` | Not supported ❌ | Modifying the fees display is not supported in the Cart/Checkout blocks |
| `woocommerce_cart_total` | Not supported ❌ | Modifying the cart total using this hook is not supported in the Cart/Checkout blocks |
| `woocommerce_cart_totals_order_total_html` | Not supported ❌ | Modifying the order total html using this hook is not supported in the Cart/Checkout blocks - edit it using the editor. |
| `woocommerce_order_button_text` | Not supported ❌ | Modifying the order button html using this hook is not supported in the Cart/Checkout blocks - edit it using the editor. |
| `woocommerce_gateway_title` | Not supported ❌ | These can be included in the "Content" rendered by gateways registered with the Cart/Checkout block but it is not possible to control this via PHP filters. |
| `woocommerce_gateway_icon` | Not supported ❌ | Gateway icons are not shown. They can be included in the "Content" rendered by gateways registered with the Cart/Checkout block but it is not possible to control this via PHP filters. |
| `woocommerce_gateway_description` | Not supported ❌ | Changing gateways this way is not possible, gateways need to register with the Cart/Checkout blocks using JavaScript and third party extensions can't modify these front-end details. |
| `woocommerce_checkout_show_terms` | Not supported ❌ | This is not controllable via this filter. The block can be removed in the editor. |
| `woocommerce_get_privacy_policy_text` | Not supported ❌ | Modifying the privacy policy text using this filter is not supported. It can be modified in the editor. |
| `woocommerce_order_button_html` | Not supported ❌ | Modifying the order button html using this hook is not supported in the Cart/Checkout blocks - edit it using the editor. |
| `woocommerce_update_order_review_fragments` | Not supported ❌ | Fragments are not used on the Cart/Checkout blocks. |

### Place order _actions_

This section is a work in progress.

### Place order _filters_

This section is a work in progress.

### Order summary _actions_

This section is a work in progress.

### Order summary _filters_

This section is a work in progress.

## Common extensibility paths

### Cart and Checkout blocks

#### Fully supported with no modification needed

- Modifying fees and other prices on the cart (`woocommerce_cart_calculate_fees`)
- Updating customer information during the WC lifecycle events, e.g. on `woocommerce_init`, updating a customer's address would reflect in the Cart/Checkout blocks.
- Adding Shipping methods
- Changing product names using woocommerce_product_get_name

#### Partially supported or supported by alternative approach

- Modifying the layout, e.g. inserting content before/after specific sections such as shipping, payment, and the billing/shipping addresses. Examples include: Outputting content in various places, e.g. before the cart contents are printed (`woocommerce_cart_contents`) and before the shipping rates (`woocommerce_before_shipping_rate`):
    - This is supported by our use of Slot/Fill and by registering inner blocks as children of the block you want to show them after.
- Adding payment methods
    - Simply adding the payment method is not enough, developers need to register a React component to show in the payments block as well.
- Adding shipping methods for local pickup
    - Should work as normal, but does require the method to support collectable
- Modify the names of items in the cart
    - Requires the developer to use a JS filter rather than PHP filter

#### Not supported at all

- Modifying individual cart line items to add or change content/change HTML (outside of what is offered by our checkout filters).

### Checkout block

#### Fully supported with no modification needed

- Pre-filling values on the form (Some merchants achieve this by overriding their values using `woocommerce_checkout_get_value`)
    - This is supported insofar as we respect what has been set on the cart/customer object when loading the cart. `woocommerce_checkout_get_value` is not supported in the Checkout block, but this is this hooks only use-case.

#### Partially supported or supported by alternative approach

- Adding new Checkout fields (commonly achieved with the `woocommerce_checkout_fields` hook)
    - Supported by the Additional Checkout Fields API, not all field types are supported right now
- Custom field validation using hooks such as woocommerce_checkout_process
    - Supported by hooking into the payment processing events - validation at the point of pressing "Place order" this is only be possible for payment methods. Other extensions could add validation errors to the data store prior to the button being pressed, and this would prevent checkout, but it is not a good solution, especially if the validation checks are expensive.
- Updating orders/customers with hooks before/during/after order placement
    - We have some hooks that fire during checkout:
        - `woocommerce_store_api_checkout_order_processed` - fired when the order has been placed
        - `woocommerce_store_api_checkout_update_customer_from_request` - fired when the customer is being updated with data from the checkout request
        - `woocommerce_store_api_checkout_update_order_meta` - fired when order meta data is being updated with data from the request
    - Any other WC hooks that fire in the Shortcode process (e.g. `woocommerce_checkout_order_processed` will not fire on Store API requests from the blocks)
- Customising the place order button text using `woocommerce_order_button_text`
    - Not supported with hooks but it is possible in the editor. There is no programmatic way to achieve this right now.

#### Not supported at all

- Changing existing core fields (commonly achieved with the `woocommerce_checkout_fields` hook)
- Removing billing/shipping addresses (using the above method)
- Performanign actions just before the order is finalised (`woocommerce_checkout_create_order`)

### Cart block

#### Fully supported with no modification needed

- None that aren't already covered by "both blocks" section.

#### Partially supported or supported by alternative approach

- Limiting quantity selections on cart items, e.g. minimum, maximum or step values. Previously this would be done using filters such as `woocommerce_quantity_input_step`
    - This is possible by modifying the quantity_limits property of the cart item in the `woocommerce_store_api_product_quantity_{`$value_type`}` filter.

#### Not supported at all

- Modifying the layout by altering template files (unless using a block theme and a custom template)


---

## Migrated legacy hooks

*Source: block-development/reference/hooks/migrated-hooks.md*

# Migrated legacy hooks

Below are the hooks that exist in WooCommerce core and that were brought over to WooCommerce Blocks.

Please note that the actions and filters here run on the server side. The client-side blocks won't necessarily change based on a callback added to a server side hook. [Please see our documentation relating to APIs for manipulating the blocks on the client-side](./README.md).

## Legacy Filters

- [wc_session_expiration](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#wc_session_expiration)
- [woocommerce_add_cart_item](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_cart_item)
- [woocommerce_add_cart_item_data](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_cart_item_data)
- [woocommerce_add_to_cart_quantity](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_to_cart_quantity)
- [woocommerce_add_to_cart_sold_individually_quantity](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_to_cart_sold_individually_quantity)
- [woocommerce_add_to_cart_validation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_to_cart_validation)
- [woocommerce_adjust_non_base_location_prices](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_adjust_non_base_location_prices)
- [woocommerce_apply_individual_use_coupon](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_apply_individual_use_coupon)
- [woocommerce_apply_with_individual_use_coupon](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_apply_with_individual_use_coupon)
- [woocommerce_cart_contents_changed](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_cart_contents_changed)
- [woocommerce_cart_item_permalink](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_cart_item_permalink)
- [woocommerce_get_item_data](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_get_item_data)
- [woocommerce_loop_add_to_cart_args](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_loop_add_to_cart_args)
- [woocommerce_loop_add_to_cart_link](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_loop_add_to_cart_link)
- [woocommerce_pay_order_product_has_enough_stock](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_pay_order_product_has_enough_stock)
- [woocommerce_pay_order_product_in_stock](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_pay_order_product_in_stock)
- [woocommerce_show_page_title](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_show_page_title)

## Legacy Actions

- [woocommerce_add_to_cart](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_add_to_cart)
- [woocommerce_after_main_content](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_after_main_content)
- [woocommerce_after_shop_loop](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_after_shop_loop)
- [woocommerce_applied_coupon](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_applied_coupon)
- [woocommerce_archive_description](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_archive_description)
- [woocommerce_before_main_content](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_before_main_content)
- [woocommerce_before_shop_loop](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_before_shop_loop)
- [woocommerce_check_cart_items](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_check_cart_items)
- [woocommerce_no_products_found](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_no_products_found)
- [woocommerce_shop_loop](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_shop_loop)


---

## Handling scripts, styles, and data

*Source: block-development/reference/integration-interface.md*

# Handling scripts, styles, and data

## The problem

You are an extension developer, and to allow users to interact with your extension on the client-side, you have written some CSS and JavaScript that you would like to be included on the page. Your JavaScript also relies on some server-side data, and you'd like this to be available to your scripts.

## The solution

You may use the `IntegrationRegistry` to register an `IntegrationInterface` this will be a class that will handle the enqueuing of scripts, styles, and data. You may have a different `IntegrationInterface` for each block (Mini-Cart, Cart and Checkout), or you may use the same one, it is entirely dependent on your use case.

You should use the hooks: `woocommerce_blocks_mini-cart_block_registration`. `woocommerce_blocks_cart_block_registration` and `woocommerce_blocks_checkout_block_registration`. These hooks pass an instance of [`IntegrationRegistry`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/Integrations/IntegrationRegistry.php) to the callback.

You may then use the `register` method on this object to register your `IntegrationInterface`.

## `IntegrationInterface` methods

To begin, we'll need to create our integration class, our `IntegrationInterface`. This will be a class that implements WooCommerce Blocks' interface named [`IntegrationInterface`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/Integrations/IntegrationInterface.php).

In this section, we will step through the interface's members and discuss what they are used for.

### `get_name()`

This is the `IntegrationInterface`'s way of namespacing your integration. The name chosen here should be unique to your extension. This method should return a string.

### `initialize()`

This is where any setup, or initialization for your integration should be placed. For example, you could register the scripts and styles your extension needs here. This method should not return anything.

### `get_script_handles()`

This is where the handles of any scripts you want to be enqueued on the client-side in the frontend context should be placed. This method should return an array of strings.

### `get_editor_script_handles()`

This is where the handles of any scripts you want to be enqueued on the client-side in the editor context should be placed. This method should return an array of strings.

### `get_script_data()`

This is where you can set values you want to be available to your scripts on the frontend. This method should return an associative array, the keys of which will be used to get the data using the JavaScript function `getSetting`.

The keys and values of this array should all be serializable.

## Usage example

Let's suppose we're the author of an extension: `WooCommerce Example Plugin`. We want to enqueue scripts, styles, and data on the frontend when either the Mini-Cart, Cart or Checkout blocks are being used.

We also want some data from a server-side function to be available to our front-end scripts.

You will notice that in the example below, we reference the `/build/index.asset.php` file. This is created by the [`DependencyExtractionWebpackPlugin`](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin) which creates a PHP file mapping the dependencies of your client-side scripts, so that they can be added in the `dependencies` array of `wp_register_script`.

Let's create our `IntegrationInterface`.

```php
<?php
use Automattic\WooCommerce\Blocks\Integrations\IntegrationInterface;

/**
 * Class for integrating with WooCommerce Blocks
 */
class WooCommerce_Example_Plugin_Integration implements IntegrationInterface {
	/**
	 * The name of the integration.
	 *
	 * @return string
	 */
	public function get_name() {
		return 'woocommerce-example-plugin';
	}

	/**
	 * When called invokes any initialization/setup for the integration.
	 */
	public function initialize() {
		$script_path = '/build/index.js';
		$style_path = '/build/style-index.css';

    /**
     * The assets linked below should be a path to a file, for the sake of brevity
     * we will assume \WooCommerce_Example_Plugin_Assets::$plugin_file is a valid file path
    */
		$script_url = plugins_url( $script_path, \WooCommerce_Example_Plugin_Assets::$plugin_file );
		$style_url = plugins_url( $style_path, \WooCommerce_Example_Plugin_Assets::$plugin_file );

		$script_asset_path = dirname( \WooCommerce_Example_Plugin_Assets::$plugin_file ) . '/build/index.asset.php';
		$script_asset      = file_exists( $script_asset_path )
			? require $script_asset_path
			: array(
				'dependencies' => array(),
				'version'      => $this->get_file_version( $script_path ),
			);

		wp_enqueue_style(
			'wc-blocks-integration',
			$style_url,
			[],
			$this->get_file_version( $style_path )
		);

		wp_register_script(
			'wc-blocks-integration',
			$script_url,
			$script_asset['dependencies'],
			$script_asset['version'],
			true
		);
		wp_set_script_translations(
			'wc-blocks-integration',
			'woocommerce-example-plugin',
			dirname( \WooCommerce_Example_Plugin_Assets::$plugin_file ) . '/languages'
		);
	}

	/**
	 * Returns an array of script handles to enqueue in the frontend context.
	 *
	 * @return string[]
	 */
	public function get_script_handles() {
		return array( 'wc-blocks-integration' );
	}

	/**
	 * Returns an array of script handles to enqueue in the editor context.
	 *
	 * @return string[]
	 */
	public function get_editor_script_handles() {
		return array( 'wc-blocks-integration' );
	}

	/**
	 * An array of key, value pairs of data made available to the block on the client side.
	 *
	 * @return array
	 */
	public function get_script_data() {
	    $woocommerce_example_plugin_data = some_expensive_serverside_function();
	    return [
	        'expensive_data_calculation' => $woocommerce_example_plugin_data
        ];
	}

	/**
	 * Get the file modified time as a cache buster if we're in dev mode.
	 *
	 * @param string $file Local path to the file.
	 * @return string The cache buster value to use for the given file.
	 */
	protected function get_file_version( $file ) {
		if ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG && file_exists( $file ) ) {
			return filemtime( $file );
		}

		// As above, let's assume that WooCommerce_Example_Plugin_Assets::VERSION resolves to some versioning number our
		// extension uses.
		return \WooCommerce_Example_Plugin_Assets::VERSION;
	}
}
```

As mentioned, we will need register our `IntegrationInterface` with WooCommerce Blocks, as we want our scripts to be included when either the Mini-Cart, Cart or Checkout is used, we need to register callbacks for three actions.

```php
add_action(
    'woocommerce_blocks_mini-cart_block_registration',
    function( $integration_registry ) {
        $integration_registry->register( new WooCommerce_Example_Plugin_Integration() );
    }
);
add_action(
    'woocommerce_blocks_cart_block_registration',
    function( $integration_registry ) {
        $integration_registry->register( new WooCommerce_Example_Plugin_Integration() );
    }
);
add_action(
    'woocommerce_blocks_checkout_block_registration',
    function( $integration_registry ) {
        $integration_registry->register( new WooCommerce_Example_Plugin_Integration() );
    }
);
```

Now, when we load a page containing either block, we should see the scripts we registered in `initialize` being loaded!

### Getting data added in `get_script_data`

We associated some data with the extension in the `get_script_data` method of our interface, we need to know how to get this!

On the client, read it with `getSetting` from the `wc.wcSettings` global, which the `wc-settings` script provides. Make sure your script lists `wc-settings` as a dependency and loads in the footer, as the example above does with the last `wp_register_script` argument; WooCommerce moves header scripts that depend on `wc-settings` to the footer and logs a console warning. The name of the setting containing the data added in `get_script_data` is the name of your integration (i.e. the value returned by `get_name`) suffixed with `_data`. In our example it would be: `woocommerce-example-plugin_data`.

```js
const { getSetting } = window.wc.wcSettings;

const data = getSetting( 'woocommerce-example-plugin_data', {} );
```

If you build with [`@woocommerce/dependency-extraction-webpack-plugin`](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/dependency-extraction-webpack-plugin), you can write `import { getSetting } from '@woocommerce/settings';` instead. The build maps that import to the same global and adds `wc-settings` to your script dependencies for you. `@woocommerce/settings` is an alias handled by the build, not the npm package of that name, which is deprecated.

The value returned here is a plain old JavaScript object, keyed by the keys of the array returned by `get_script_data`, the values will be serialized.


---

## Overview of data flow between client and server

*Source: block-development/reference/overview-of-data-flow.md*

# Overview of data flow between client and server

In the WooCommerce Cart and Checkout blocks, the server is the source of truth for critical transactional and persistent data. This includes:

-   Cart item details (items, quantities, and prices)
-   Cart totals (e.g. taxes, fees, subtotals)
-   Customer information (shipping and billing addresses, other customer data)
    -   Additional fields added using the [Additional Checkout Fields API](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/additional-checkout-fields/) are also persisted server-side.
-   Shipping methods and rates
-   Other cart details, such as applied coupons

Such data must be persisted server-side to ensure accuracy, consistency, and reliability across different user sessions and devices.
Ephemeral UI state—such as temporary validation states, or UI-specific interactions like expanded/collapsed sections should remain client-side and not be automatically persisted on the server, unless the specific state needs to be maintained across page loads or is critical to the user's checkout process.

You may wish to get data from the server into the client, and vice/versa. This document will outline the general concepts and data flow in the Cart/Checkout blocks, and provide links, or guidance on some common use cases.

## Where is data stored?

All the data relating to a cart, customer, and order is stored on the server, either in the database or in the customer's session. When it is sent to the client, it is stored in [`@wordpress/data`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/) data stores.

## How do I get my Server-side (PHP) data into the client (JavaScript) and vice/versa

Since the server is the source of truth, all data from the client should eventually make its way there if it needs to be persisted with the order.

There is also the case that your client needs data that can only be derived server-side, such as configuration options set in the WooCommerce settings dashboard, or data coming from external services (e.g. courier rates or payment APIs).

### Server (PHP) to Client (JavaScript)

There are two ways to get your data from the server to the client, depending on whether it is static or dynamic.

#### Static data

Static data is not likely to change based on actions the shopper takes, for example, an option from the WooCommerce settings dashboard. The recommended way of getting this data to the client is using the `AssetDataRegistry`.

When data is added here, it is serialized and sent to the client on page load. It will not change based on actions the shopper takes, e.g. adding items to the cart or changing their address.

A key/value pair can be added to the registry like so:

```php
add_action(
    'woocommerce_blocks_loaded',
    function() {
      $asset_data_registry = \Automattic\WooCommerce\Blocks\Package::container()->get( \Automattic\WooCommerce\Blocks\Assets\AssetDataRegistry::class );
      $asset_data_registry->add( 'namespace/value', 'this is a custom value' );
    }
);
```

If a duplicate key exists, it will not be overwritten. Using a unique identifier is important, the recommendation is `namespace/value` to help ensure the key is unique.

To get this data on the client, use `wc.wcSettings.getSetting` like so:

```js
const myCustomValue = wc.wcSettings.getSetting(
	'namespace/value',
	'Fallback value.'
);
```

#### Dynamic data

Dynamic data is data that is likely to change in response to the shopper's actions, for example, changing location, or items in the cart. In this case, you need to add this to the cart API response. The cart response is sent on many routes during the shopper's journey, and on almost every API response triggered by the Cart/Checkout blocks.

To add data here, you'll need to extend the API response. See [Exposing your data in the Store API](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-add-data.md).

### Client (JavaScript) to Server (PHP)

Getting data from the client to the server can be done in three different ways:

#### Checkout field updates

When the shopper updates a checkout field, the data is sent to the server immediately. For Additional Fields, this is sent via a PUT request to the `/checkout` endpoint. For address fields, this is sent via a POST request to the `cart/update-customer` endpoint (via batch). Both will return an updated cart, which is then applied to the client and totals are updated.

#### Piggybacking on a Store API request

This is useful for things that don't require an immediate response from the server, for example if you've added a new block to the Checkout and it contains a form field that should be saved along with the order. If this form field just needs to be saved and doesn't need to update any other values in the cart, then the data should be sent with the checkout request. The [Add a new inner block containing a custom field to the WooCommerce Checkout Block](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-add-custom-fields.md) documentation provides a worked example of using `setExtensionData` along with extending the Store API to receive your data in an existing request.

#### Sending data on-demand using `extensionCartUpdate`

You may wish to send your data to the server immediately, rather than waiting for a Store API request to be made. This may be desired if the data may update the cart, for example adding fees, changing which shipping methods are available, or changing the tax rates.

The [Updating the cart on-demand with the Store API](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-update-cart.md) document outlines how to do this. 

## When is data sent/received in the Cart/Checkout blocks?

### Page load

On page load, if the Cart or Checkout block is present, the cart state is sent along with the initial request, and is hydrated into a client-side [`@wordpress/data`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/) data store.

On page load, the `wc/store/cart` and `wc/store/checkout` data stores are hydrated with the data from the server. The `wc/store/payment` data store is populated partly with data from the server, but needs some client-side processing to finish before all payment methods are registered there.

### Entering customer data into the checkout form

When the shopper enters data into the form, the data is immediately written to the `wc/store/cart` data store, and a debounced method called [`pushChanges`](https://github.com/woocommerce/woocommerce/blob/4861ec250ef1789f814f4209755165e8abe7b838/plugins/woocommerce-blocks/assets/js/data/cart/push-changes.ts#L167) is called. This method sends the customer data to the server where it is persisted against the customer. The full cart is sent back as a response, and the data store is updated with this.

This is important to note, because if any code is running on the server that modifies the customer addresses, then it will be reflected in the response.

For example, if a plugin modifies the address data to ensure all city names are capitalised, and the shopper enters "london" into the city, when the data is returned to the client, the text would change to "London" and the input field would update.

Modifying form fields while the shopper is interacting with them is a jarring experience, so instead of making these changes while the user is interacting with the form, consider making them while processing the checkout action on the server.

### Adding coupons

When the shopper expands the coupon form, the state is stored locally. This kind of data is not sent to the server. The request to add the coupon is made when the shopper presses the Apply button. A Store API request is made and it returns a new cart which is then applied.

### Changing shipping method

When the shopper changes shipping method, a Store API request is made and it returns a new cart which is then applied.

### Changing payment method

When the shopper changes payment method, it does not automatically send a Store API request to the server. If you need to update the server when the payment method is changed and before the order is placed, the correct approach would be to use [`cartExtensionUpdate`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-update-cart.md).

### Adding/editing order notes

Adding or editing order notes is stored locally on the client, these notes are not sent to the server until the shopper submits the checkout form.

## Cart

The items listed in the Checkout section above also apply to the Cart block (besides changing payment method, the shopper cannot select their payment method on the Cart block unless it's an express payment method, which behaves differently and is implemented entirely client-side).

### Changing item quantity, adding, or removing items

When the shopper updates an item's quantity, removes an item from their cart, or adds an item (e.g. from the Cart cross-sells block) a Store API request is made. The local cart is updated with the response.

### Using the shipping calculator

This behaves the same way as the address forms in the Checkout block, however the address in the shipping calculator is only sent to the server if the postcode is valid, and all required fields have values.


---

## Slot and fill

*Source: block-development/reference/slot-fills.md*

# Slot and fill

## The problem

You added custom data to the [Store API](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-add-data.md). You changed several strings using [Checkout filters](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/filters-in-cart-and-checkout/). Now you want to render your own components in specific places in the Cart and Checkout.

## Solution

Slot and Fill are a pair of components that add the possibility to render your own HTML in pre-defined places in the Cart and Checkout. Your component will get access to contextual data and will get re-rendered when needed.

A _Slot_ is a place in the Cart and Checkout that can render an indefinite number of external components.

A _Fill_ is the component provided by third-party developers to render inside a _Slot_.

Slot and Fill use WordPress' API, and you can learn more about how they work in [the Slot and Fill documentation.](https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/slot-fill).

## Basic Usage

`ExperimentalOrderMeta` is a fill that will render in a slot below the Order summary section in the Cart and Checkout blocks.
The `ExperimentalOrderMeta` will automatically pass props to its top level child:

-   `cart` which contains cart data
-   `extensions` which contains data registered with `ExtendSchema::class` in `wc/store/cart` endpoint
-   `context`, equal to the name of the Block in which the fill is rendered: `woocommerce/cart` or `woocommerce/checkout`

```jsx
const { registerPlugin } = wp.plugins;
const { ExperimentalOrderMeta } = wc.blocksCheckout;

const MyCustomComponent = ( { cart, extensions } ) => {
	return <div className="my-component">Hello WooCommerce</div>;
};

const render = () => {
	return (
		<ExperimentalOrderMeta>
			<MyCustomComponent />
		</ExperimentalOrderMeta>
	);
};

registerPlugin( 'my-plugin-namespace', {
	render,
	scope: 'woocommerce-checkout',
} );
```

## registerPlugin

In the above example, we're using `registerPlugin`. This plugin will take our component and render it, but it won't make it visible. The SlotFill part is the one responsible for actually having it show up in the correct place.

You use `registerPlugin` to feed in your plugin namespace, your component `render`, and the scope of your `registerPlugin`. The value of scope should always be `woocommerce-checkout`.

## Requirements

For this to work, your script must be enqueued after Cart and Checkout. You can follow the [IntegrationInterface](https://developer.woocommerce.com/docs/block-development/reference/integration-interface/#the-problem) documentation for enqueueing your script.


---

## How to Add Additional Fields to the WooCommerce Checkout Block

*Source: block-development/tutorials/how-to-additional-checkout-fields-guide.md*

# How to Add Additional Fields to the WooCommerce Checkout Block

This feature requires a minimum version of WooCommerce 8.9.0

The WooCommerce Checkout Block provides a powerful API for developers to add additional fields to collect information from customers during the checkout process. Whether you need to gather special delivery instructions, business details, or marketing preferences, additional checkout fields make it easy to extend your store’s functionality.

In this guide, we’ll walk through the process of adding your own additional fields to your checkout form and show you practical examples you can implement right away.

## Getting Started

To add additional checkout fields, you’ll use the `woocommerce_register_additional_checkout_field()` function. This should be called after the `woocommerce_init` action to ensure WooCommerce is fully loaded.

Here's the basic structure:

```php
add_action( 'woocommerce_init', function() {
    if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
        return;
    }
    
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'your-namespace/field-name',
            'label'    => __( 'Your Field Label', 'your-text-domain'),
            'location' => 'contact', // or 'address' or 'order'
            'type'     => 'text',    // or 'select', 'checkbox' or 'date'
            'required' => false,
        )
    );
});
```

## Field Locations: Where Your Fields Appear

You can place your additional fields in three different locations:

![Additional field for contact](/img/doc_images/woo-local-checkout.png)

### Contact Information (`contact`)

Fields here appear at the top of the checkout form alongside the email field. Data saved here becomes part of the customer’s account and will be visible in their “Account details” section.

Example:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/marketing-opt-in',
        'label'    => __('Subscribe to our newsletter?', 'your-text-domain'),
        'location' => 'contact',
        'type'     => 'checkbox',
    )
);
```

![Additional field for contact](/img/doc_images/additional-field-contact.png)

### Address (`address`)

These fields appear in both the shipping and billing address forms. They’re saved to both the customer and the order, so returning customers won’t need to refill them.

Example:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/delivery-instructions',
        'label'    => __('Special delivery instructions', 'your-text-domain'),
        'location' => 'address',
        'type'     => 'text',
    )
);
```

![Additional field for address](/img/doc_images/additional-field-address.png)

### Order Information (`order`)

Fields in this location appear in a separate “Order information” block and are saved only to the order, not the customer’s account. Perfect for order-specific details that don’t need to be remembered for future purchases.

Example:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/gift-message',
        'label'    => __('Gift message', 'your-text-domain'),
        'location' => 'order',
        'type'     => 'text',
    )
);
```

![Additional field for order](/img/doc_images/additional-field-order.png)

## Supported Field Types

The API supports four field types:

### Text Fields

Perfect for collecting short text input:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/company-vat',
        'label'    => __('VAT Number', 'your-text-domain'),
        'location' => 'address',
        'type'     => 'text',
        'required' => true,
    )
);
```

### Select Dropdowns

Great for predefined options:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/preferred-delivery-time',
        'label'    => __('Preferred delivery time', 'your-text-domain'),
        'location' => 'order',
        'type'     => 'select',
        'options'  => array(
            array(
                'value' => 'morning',
                'label' => __('Morning (9AM - 12PM)', 'your-text-domain')
            ),
            array(
                'value' => 'afternoon',
                'label' => __('Afternoon (12PM - 5PM)', 'your-text-domain')
            ),
            array(
                'value' => 'evening',
                'label' => __('Evening (5PM - 8PM)', 'your-text-domain')
            ),
        ),
    )
);
```

### Checkboxes

Ideal for yes/no questions or opt-ins:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'           => 'my-plugin/age-verification',
        'label'        => __('I confirm I am over 18 years old', 'your-text-domain'),
        'location'     => 'contact',
        'type'         => 'checkbox',
        'required'     => true,
        'error_message' => __('You must be over 18 to place this order.', 'your-text-domain'),
    )
);
```

### Date Fields

Ideal for non-time-zone-sensitive dates like delivery dates, birthdays, and specific dates:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/delivery-date',
        'label'    => __('Preferred delivery date', 'your-text-domain'),
        'location' => 'order',
        'type'     => 'date',
        'required' => true,
    )
);
```

The field input value will follows the shopper's browser and OS locale. The value is always stored as `YYYY-MM-DD`, and it is displayed using the site's date format (**Settings → General**) in emails, order screens, and other places the value is rendered.

Use `min` and `max` to limit the range of dates a shopper can pick. Both accept an absolute date in `Y-m-d` format, or a duration relative to today in the [ISO 8601-2 duration format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#iso_8601_duration_format), such as `P1D`, `-P5D` or `-P18Y`:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/delivery-date',
        'label'    => __('Preferred delivery date', 'your-text-domain'),
        'location' => 'order',
        'type'     => 'date',
        'required' => true,
        'min'      => 'P1D',
        'max'      => 'P30D',
    )
);
```

Pass the duration rather than resolving it yourself with `strtotime()` or `date()`. WooCommerce resolves it against the current date each time the field is rendered or validated, so it stays correct behind a page cache and across midnight.

## Adding Field Attributes

You can enhance your fields with HTML attributes for better user experience:
Example:

```php
woocommerce_register_additional_checkout_field(
    array(
        'id'         => 'my-plugin/phone-number',
        'label'      => __('Alternative phone number', 'your-text-domain'),
        'location'   => 'contact',
        'type'       => 'text',
        'attributes' => array(
            'autocomplete' => 'tel',
            'pattern'      => '[0-9]{10}',
            'title'        => __('Please enter a 10-digit phone number', 'your-text-domain'),
            'placeholder'  => '1234567890',
        ),
    )
);
```

## Validation and Sanitization

To ensure the data entered into your custom fields is valid and secure, you can add custom validation and sanitization functions.

```php
add_action( 'woocommerce_init', function() {
    woocommerce_register_additional_checkout_field(
        array(
            'id'                => 'my-plugin/business-email',
            'label'             => __('Business Email', 'your-text-domain'),
            'location'          => 'contact',
            'type'              => 'text',
            'required'          => true,
            'sanitize_callback' => function( $value ) {
                return sanitize_email( $value );
            },
            'validate_callback' => function( $value ) {
                if ( ! is_email( $value ) ) {
                    return new WP_Error( 
                        'invalid_business_email', 
                        __('Please enter a valid business email address.', 'your-text-domain') 
                    );
                }
            },
        )
    );
});
```

### Validation

You can also use WordPress action hooks for validation:

```php
add_action( 'woocommerce_validate_additional_field', function( $errors, $field_key, $field_value ) {
    if ( 'my-plugin/business-email' === $field_key ) {
        if ( ! is_email( $field_value ) ) {
            $errors->add( 'invalid_business_email', __('Please enter a valid email address.', 'your-text-domain') );
        }
    }
}, 10, 3 );
```

## Accessing Field Values

After checkout, you can retrieve the field values using helper methods:

```php
use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\Domain\Services\CheckoutFields;

$checkout_fields = Package::container()->get( CheckoutFields::class );
$order = wc_get_order( $order_id );

// Get a specific field value
$business_email = $checkout_fields->get_field_from_object( 
    'my-plugin/business-email', 
    $order, 
    'other' // Use 'billing' or 'shipping' for address fields
);

// Get all additional fields
$all_fields = $checkout_fields->get_all_fields_from_object( $order, 'other' );
```

### Complete Example

```php
add_action( 'woocommerce_init', function() {
    if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
        return;
    }

    // Company information
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'my-business-store/company-size',
            'label'    => __('Company size', 'your-text-domain'),
            'location' => 'contact',
            'type'     => 'select',
            'required' => true,
            'options'  => array(
                array( 'value' => '1-10', 'label' => __('1-10 employees', 'your-text-domain') ),
                array( 'value' => '11-50', 'label' => __('11-50 employees', 'your-text-domain') ),
                array( 'value' => '51-200', 'label' => __('51-200 employees', 'your-text-domain') ),
                array( 'value' => '200+', 'label' => __('200+ employees', 'your-text-domain') ),
            ),
        )
    );

    // Delivery preferences
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'my-business-store/requires-appointment',
            'label'    => __('Delivery requires appointment', 'your-text-domain'),
            'location' => 'address',
            'type'     => 'checkbox',
        )
    );

    // Order-specific notes
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'my-business-store/po-number',
            'label'    => __('Purchase Order Number', 'your-text-domain'),
            'location' => 'order',
            'type'     => 'text',
        )
    );
});
```

## Next Steps

You now have the foundation for adding additional checkout fields to your WooCommerce store using the checkout block.

The additional checkout fields API provides a robust foundation for customizing your checkout experience while maintaining compatibility with WooCommerce’s block-based checkout system. Start with simple fields and gradually add more sophisticated validation and conditional logic as your needs grow.


---

## How to Make Your WooCommerce Additional Checkout Fields Conditionally Visible in the Checkout Block

*Source: block-development/tutorials/how-to-conditional-additional-fields.md*

# How to Make Your WooCommerce Additional Checkout Fields Conditionally Visible in the Checkout Block

This feature requires a minimum version of WooCommerce 9.9.0

Conditional visibility allows you to create smart, adaptive checkout forms that only show relevant fields when needed, reducing form clutter and improving the customer experience.

## Why Use Conditional Visibility?

Conditional fields help you:

* Reduce form complexity by hiding irrelevant fields
* Create dynamic checkout flows based on customer selections
* Show specialized fields only for specific products or customer types
* Improve conversion rates with cleaner, more focused forms
* Collect contextual information that's only relevant in certain situations

## Understanding JSON Schema for Conditions

WooCommerce’s additional checkout fields use JSON Schema to define conditional logic. Don’t worry if you’re not familiar with JSON Schema – we’ll walk through practical examples that you can adapt for your needs.

The basic structure looks like this:

```php
'required' => [
    // Define when the field must be filled in here
],
'hidden' => [
    // Define when the field should be hidden here
]
```

## Where Each Field's Value Is Stored

Conditions are evaluated against a single JSON structure (internally called the *document object*) that mirrors the state of the cart, the customer, and the checkout. To reference another field in a condition, you need to point at the correct subtree for that field's `location`.

| Field's `location` | Subtree the value lives in | Path to use in conditions |
| --- | --- | --- |
| `contact` | `customer.additional_fields` | `customer.additional_fields.<field-id>` |
| `order` | `checkout.additional_fields` | `checkout.additional_fields.<field-id>` |
| `address` | `customer.billing_address` and `customer.shipping_address`. Also `customer.address` when the field being evaluated is itself at `address`. | `customer.billing_address.<field-id>` or `customer.shipping_address.<field-id>` or `customer.address.<field-id>` |

Each field's value only appears in the subtree above, so a condition that points at the wrong subtree will silently have no effect.

## Common Conditional Scenarios

### Show Fields Based on Shipping Method

One of the most common use cases is showing fields only when specific shipping methods are selected (e.g., Local Pickup):

```php
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/delivery-instructions',
		'label'    => __('Special delivery instructions', 'your-text-domain'),
		'location' => 'order',
		'type'     => 'text',
		'required' => [
			'cart' => [
				'properties' => [
					'prefers_collection' => [
						'const' => true
					]
				]
			]
		],
		'hidden' => [
			'cart' => [
				'properties' => [
					'prefers_collection' => [
						'const' => false
					]
				]
			]
		]
	)
);
```

### Show Fields Based on Cart Contents

Display fields only when specific products are in the cart:

```php
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/fragile-handling',
		'label'    => __('This order contains fragile items - special handling required?','your-text-domain'),
		'location' => 'order',
		'type'     => 'checkbox',
		'required' => [
			'cart' => [
				'properties' => [
					'items' => [
						'contains' => [
							'enum' => [2766, 456, 789] // Product IDs for fragile items
						]
					]
				]
			]
		],
		'hidden' => [
			'cart' => [
				'properties' => [
					'items' => [
						'not' => [
							'contains' => [
								'enum' => [2766, 456, 789] // Hide unless a fragile item is in the cart
							]
						]
					]
				]
			]
		]
	)
);
```

### Show Fields Based on Cart Value

Display premium service options only for high-value orders:

```php
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/white-glove-service',
		'label'    => __('Add white glove delivery service?', 'your-text-domain'),
		'location' => 'order',
		'type'     => 'checkbox',
		'hidden' => [
			'cart' => [
				'properties' => [
					'totals' => [
						'properties' => [
							'total_price' => [
								'maximum' => 50000 // Hide if cart total is less than $500 (in cents)
							]
						]
					]
				]
			]
		]
	)
);
```

### Show Fields Based on Customer Location

Display fields only for customers from specific countries:

```php
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/tax-exemption-number',
		'label'    => __('Tax exemption number', 'your-text-domain'),
		'location' => 'address',
		'type'     => 'text',
		'required' => [
			'customer' => [
				'properties' => [
					'address' => [
						'properties' => [
							'country' => [
								'enum' => ['US', 'CA'] // Required only for US and Canada
							]
						]
					]
				]
			]
		],
		'hidden' => [
			'customer' => [
				'properties' => [
					'address' => [
						'properties' => [
							'country' => [
								'not' => [
									'enum' => ['US', 'CA'] // Hide for countries other than US and Canada
								]
							]
						]
					]
				]
			]
		]
	)
);
```

### Show Fields Based on Other Field Values

Create dependent fields where one field's visibility depends on another field's value. The schema path is determined by the **source field's `location`** (see [Where Each Field's Value Is Stored](#where-each-fields-value-is-stored)), not the dependent field's.

Same-location example: both fields at `order`, so the rule looks under `checkout.additional_fields`.

```php
// Source (order location) - value at checkout.additional_fields.<id>.
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/service-type',
		'label'    => __('Type of service needed', 'your-text-domain'),
		'location' => 'order',
		'type'     => 'select',
		'options'  => array(
			array( 'value' => 'standard', 'label' => 'Standard' ),
			array( 'value' => 'express', 'label' => 'Express' ),
			array( 'value' => 'custom', 'label' => 'Custom' ),
		),
	)
);

// Dependent - shown only when "custom" is selected.
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/custom-requirements',
		'label'    => __('Describe your custom requirements', 'your-text-domain'),
		'location' => 'order',
		'type'     => 'text',
		'required' => [
			'checkout' => [
				'properties' => [
					'additional_fields' => [
						'properties' => [
							'my-plugin/service-type' => [
								'const' => 'custom'
							]
						]
					]
				]
			]
		],
		'hidden' => [
			'checkout' => [
				'properties' => [
					'additional_fields' => [
						'properties' => [
							'my-plugin/service-type' => [
								'not' => [
									'const' => 'custom'
								]
							]
						]
					]
				]
			]
		]
	)
);
```

For a `contact` or `address` source field the shape is identical; swap the path for the one in the [lookup table](#where-each-fields-value-is-stored).

### Mixing Locations

The two fields don't have to share a `location`. The rule always follows the source; see the [lookup table](#where-each-fields-value-is-stored) for the subtree mapping.

:::warning

Address-location values are **not** stored under `additional_fields`. Assuming `additional_fields` is the universal path is a common cause of rules that silently have no effect.

:::

```php
woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/customer-type',
		'label'    => __('Customer type', 'your-text-domain'),
		'location' => 'address',
		'type'     => 'select',
		'options'  => array(
			array( 'value' => 'private',  'label' => __('Private', 'your-text-domain') ),
			array( 'value' => 'business', 'label' => __('Business', 'your-text-domain') ),
		),
	)
);

woocommerce_register_additional_checkout_field(
	array(
		'id'       => 'my-plugin/invoice-notes',
		'label'    => __('Invoice notes', 'your-text-domain'),
		'location' => 'order',
		'type'     => 'text',
		'hidden' => [
			'customer' => [
				'properties' => [
					'billing_address' => [
						'properties' => [
							'my-plugin/customer-type' => [
								'not' => [
									'const' => 'business'
								]
							]
						]
					]
				]
			]
		]
	)
);
```

## Practical Complete Example

Here’s a comprehensive example for a store that offers both digital and physical products:

```php
add_action( 'woocommerce_init', function() {
	if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
		return;
	}

	// Delivery preference - only for physical products
	woocommerce_register_additional_checkout_field(
		array(
			'id'       => 'my-store/delivery-preference',
			'label'    => __('Delivery preference', 'your-text-domain'),
			'location' => 'order',
			'type'     => 'select',
			'options'  => array(
				array( 'value' => 'doorstep', 'label' => __('Leave at doorstep', 'your-text-domain') ),
				array( 'value' => 'neighbor', 'label' => __('Leave with neighbor', 'your-text-domain') ),
				array( 'value' => 'pickup_point', 'label' => __('Delivery to pickup point', 'your-text-domain') ),
			),
			'required' => [
				'cart' => [
					'properties' => [
						'needs_shipping' => [
							'const' => true
						]
					]
				]
			],
			'hidden' => [
				'cart' => [
					'properties' => [
						'needs_shipping' => [
							'const' => false
						]
					]
				]
			]
		)
	);

	// Delivery instructions - only when 'doorstep' is selected
	woocommerce_register_additional_checkout_field(
		array(
			'id'       => 'my-store/doorstep-instructions',
			'label'    => __('Specific doorstep delivery instructions', 'your-text-domain'),
			'location' => 'order',
			'type'     => 'text',
			'required' => [
				'checkout' => [
					'properties' => [
						'additional_fields' => [
							'properties' => [
								'my-store/delivery-preference' => [
									'const' => 'doorstep'
								]
							]
						]
					]
				]
			],
			'hidden' => [
				'checkout' => [
					'properties' => [
						'additional_fields' => [
							'properties' => [
								'my-store/delivery-preference' => [
									'not' => [
										'const' => 'doorstep'
									]
								]
							]
						]
					]
				]
			]
		)
	);

	// Digital delivery email - only for digital products
	woocommerce_register_additional_checkout_field(
		array(
			'id'       => 'my-store/digital-delivery-email',
			'label'    => __('Alternative email for digital products', 'your-text-domain'),
			'location' => 'contact',
			'type'     => 'text',
			'required' => [
				'cart' => [
					'properties' => [
						'needs_shipping' => [
							'const' => false
						]
					]
				]
			],
			'hidden' => [
				'cart' => [
					'properties' => [
						'needs_shipping' => [
							'const' => true
						]
					]
				]
			],
			'sanitize_callback' => function ( $field_value ) {
				return sanitize_email( $field_value );
			},
			'validate_callback' => function ( $field_value ) {
				if ( ! is_email( $field_value ) ) {
					return new \WP_Error( 'invalid_alt_email', __('Please ensure your alternative email matches the correct format.', 'your-text-domain') );
				}
			},
		)
	);
});
```

## Available data for conditions

You can create conditions based on various checkout data:

1. Cart information under `cart.*`: `total_price`, `items`, `shipping_rates`, `coupons`, `items_weight`, `needs_shipping`, `prefers_collection`, and more.
2. Customer data under `customer.*`: `id`, `billing_address`, `shipping_address`, the contextual `address`, and `additional_fields` for contact-location values.
3. Checkout data under `checkout.*`: `payment_method`, `create_account`, `customer_note`, and `additional_fields` for order-location values.

When referencing another additional checkout field, pick the subtree that matches that field's `location`. See [Where Each Field's Value Is Stored](#where-each-fields-value-is-stored).

## Next Steps

Conditional visibility transforms static checkout forms into dynamic, intelligent interfaces that adapt to your customers’ needs. Combined with the basic additional fields from our previous post, you can create sophisticated checkout experiences that collect exactly the right information at exactly the right time.

Start experimenting with simple conditions and gradually build more complex logic as you become comfortable with the JSON Schema syntax. Your customers will appreciate the cleaner, more relevant checkout experience!


---

## Integrating Protection with the Checkout Block

*Source: block-development/tutorials/integrating-protection-checkout-block.md*

# Integrating Protection with the Checkout Block

If you're a developer of a Captcha or fraud protection plugin, make sure your solution is hooking into the [Store API](/docs/apis/store-api/) and integrating with the Checkout block. This tutorial will guide you through the process of adding protection mechanisms to the WooCommerce Checkout block.

## Overview

The WooCommerce Checkout block uses the [Store API](/docs/apis/store-api/) for processing orders, which provides a secure, unauthenticated API for customer-facing functionality. To integrate protection mechanisms like CAPTCHA or fraud detection, you'll need to:

1. **Render your protection element** in the checkout block using WordPress block filters
2. **Handle client-side validation** using the checkout data store
3. **Validate on the server-side** using the Store API authentication hooks

## Step 1: Rendering Your Protection Element

The first step is to render your CAPTCHA or protection element in the checkout block. You can use the `render_block` filter to inject your HTML before or after specific checkout blocks.

### Using the render_block Filter

The `render_block` filter allows you to modify the output of any WordPress block. For the checkout block, you'll want to target the `woocommerce/checkout-actions-block` which contains the "Place order" button.

```php
add_filter(
    'render_block_woocommerce/checkout-actions-block',
    function( $block_content ) {
        ob_start();
        ?>
        <div class="my-captcha-element" data-sitekey="<?php echo esc_attr( get_option( 'plugin_captcha_sitekey' ) ); ?>">
        </div>
        <?php
        echo $block_content;
        $block_content = ob_get_contents();
        ob_end_clean();
        return $block_content;
    },
    999,
    1
);
```

**Key points about this code:**

-   The filter targets `woocommerce/checkout-actions-block` which is the block containing the place order button
-   We use a priority of `999` to ensure our content is added after other modifications
-   The `data-sitekey` attribute stores your CAPTCHA configuration, but this may be different for your plugin
-   We append our protection element after the original block content.

## Step 2: Client-Side Integration

Once your protection element is rendered, you need to integrate it with the checkout data store to capture the validation token and pass it to the server.

### Using the Checkout Data Store

The checkout block uses a data store to manage state. You can use the `setExtensionData` method to pass your protection token to the server.

```js
/* Woo Checkout Block */
document.addEventListener( 'DOMContentLoaded', function () {
	if ( wp && wp.data ) {
		var unsubscribe = wp.data.subscribe( function () {
			const turnstileItem = document.querySelector(
				'.my-captcha-element'
			);

			if ( turnstile && turnstileItem ) {
				turnstile.render( turnstileItem, {
					sitekey: turnstileItem.dataset.sitekey,
					callback: function ( data ) {
						wp.data
							.dispatch( 'wc/store/checkout' )
							.setExtensionData( 'plugin-namespace-turnstile', {
								token: data,
							} );
					},
				} );

				unsubscribe();
			}
		}, 'wc/store/cart' );
	}
} );
```

**Key points about this JavaScript:**

-   We subscribe to the cart data store to detect when the checkout is ready
-   The `turnstile.render()` method initializes your CAPTCHA (replace with your specific implementation)
-   `setExtensionData()` stores the token in the checkout data store
-   The namespace should be unique to your plugin (e.g., `my-plugin-turnstile`)

### Data Store Integration

For more information about the checkout data store and available methods, see the [Checkout Data Store documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/third-party-developers/extensibility/data-store/checkout.md).

## Step 3: Server-Side Validation

The most critical step is validating the protection token on the server side. This should happen early in the authentication process to prevent any unauthorized checkout attempts.

### Using the core `rest_authentication_errors` filter

The [`rest_authentication_errors`](https://developer.wordpress.org/reference/hooks/rest_authentication_errors/) filter is the ideal place to validate your protection token because it runs before any checkout processing begins.

```php
add_filter( 'rest_authentication_errors', 'plugin_check_turnstile_token' );

function plugin_check_turnstile_token( $result ) {
    // Skip if this is not a POST request.
    if ( isset( $_SERVER['REQUEST_METHOD'] ) && $_SERVER['REQUEST_METHOD'] !== 'POST' ) {
        // Always return the result or an error, never a boolean. This ensures other checks aren't thrown away like rate limiting or authentication.
        return $result;
    }

    // Skip if this is not the checkout endpoint.
    if ( ! preg_match( '#/wc/store(?:/v\d+)?/checkout#', $GLOBALS['wp']->query_vars['rest_route'] ) ) {
        return $result;
    }

    // get request body
    $request_body = json_decode( \WP_REST_Server::get_raw_data(), true );

    if ( isset( $request_body['payment_method'] ) ) {
        $chosen_payment_method = sanitize_text_field(  $request_body['payment_method'] );

        // Provide ability to short circuit the check to allow express payments or hosted checkouts to bypass the check.
        $selected_payment_methods = apply_filters(  'plugin_payment_methods_to_skip', array('woocommerce_payments' ) );
        if( is_array( $selected_payment_methods ) ) {
            if ( in_array( $chosen_payment_method, $selected_payment_methods, true ) ) {
                return $result;
            }
        }
    }

    $extensions = $request_body['extensions'];
    if ( empty( $extensions ) || ! isset( $extensions['plugin-namespace-turnstile'] ) ) {
        return new WP_Error( 'challenge_failed', 'Captcha challenge failed' );
    }
    $token = sanitize_text_field( $extensions['plugin-namespace-turnstile']['token'] );

    /**
     * Note: The function `my_token_check_function` would be
     * implemented in your plugin to handle token validation.
     **/
    $check = my_token_check_function( $token );
    $success = $check['success'];

    if( $success !== true ) {
        return new WP_Error( 'challenge_failed', 'Captcha challenge failed' );
    }

    return $result;
}
```

**Key points about server-side validation:**

-   We check for POST requests to the checkout endpoint specifically
-   The protection token is accessed via `$request_body['extensions']['your-namespace']`
-   Always return the `$result` parameter to avoid interfering with other authentication checks
-   Return a `WP_Error` object if validation fails
-   Consider allowing certain payment methods to bypass protection (e.g., express payments)

## Important Notes

### Security Considerations

1. **Always validate on the server side** - Client-side validation can be bypassed
2. **Use HTTPS** - Protection tokens should be transmitted securely
3. **Rate limiting** - Consider implementing [rate limiting](/docs/apis/store-api/rate-limiting/) for your protection endpoints
4. **Token expiration** - Ensure your protection tokens have appropriate expiration times

### Testing Your Integration

When testing your protection integration:

1. Test with the checkout block enabled
2. Verify that validation fails when no token is provided
3. Test with different payment methods
4. Ensure the protection doesn't interfere with legitimate checkout flows


---

## Using the Code Snippets Plugin

*Source: code-snippets/README.md*

# Using the Code Snippets Plugin

## What is a Code Snippet?  

Customizing WooCommerce functionality often requires adding code snippets to modify behavior, enhance features, or integrate with third-party tools. Instead of editing theme files or the `functions.php` file directly, we recommend using the **Code Snippets** plugin from the WordPress.org repository. This approach ensures a safer, more manageable, and more organized way to add custom code to your WooCommerce store.  

## Why Use the Code Snippets Plugin?  

Editing your theme’s `functions.php` file or adding custom code directly to WooCommerce files can lead to several issues:  

- **Loss of Custom Code on Theme Updates:** When you update your theme, modifications made in `functions.php` are lost.  
- **Potential for Errors and Site Breakage:** A single syntax error can make your website inaccessible.  
- **Difficult Debugging:** Managing multiple customizations in a single `functions.php` file can become unorganized.  

The **Code Snippets** plugin addresses these issues by allowing you to:  

- Add, activate, and deactivate snippets without modifying core files.  
- Organize custom snippets with descriptions and tags.  
- Avoid losing changes when updating your theme or WooCommerce.  
- Debug and test code safely before deploying to a live site.  

## How to Install the Code Snippets Plugin  

1. Log in to your WordPress admin dashboard.  
2. Navigate to **Plugins > Add New**.  
3. Search for **"Code Snippets"** in the search bar.  
4. Click **Install Now** on the "Code Snippets" plugin by **Code Snippets Pro**.  
5. After installation, click **Activate**.  

## Adding Custom WooCommerce Snippets  

Once the plugin is installed and activated, follow these steps to add a WooCommerce customization:  

1. Navigate to **Snippets** in your WordPress dashboard.  
2. Click **Add New**.  
3. Give your snippet a descriptive title.  
4. Enter your WooCommerce-specific PHP code in the code editor.  
5. Select **Only run in administration area** or **Run everywhere**, depending on your needs.  
6. Click **Save Changes and Activate**.  

## Example: Add a Custom Message to the WooCommerce Checkout Page  

```php
add_action('woocommerce_before_checkout_form', function() {
    echo '<p style="color: red; font-weight: bold;">Reminder: Ensure your shipping address is correct before placing your order.</p>';
});
``` 

## Managing and Troubleshooting Snippets  

- **Deactivating Snippets:** If a snippet causes issues, simply deactivate it from the Code Snippets interface without affecting the rest of your site.  
- **Error Handling:** The plugin detects fatal errors and automatically deactivates problematic snippets.  
- **Backup and Export:** You can export your snippets for backup or transfer to another site.  

## Next Steps  

For more advanced customizations, refer to the [WooCommerce Developer Documentation](https://developer.woocommerce.com/) to build blocks, extensions, and more!  



---

## Add a country

*Source: code-snippets/add-a-country.md*

# Add a country

Add a country using to your countries list using this code snippet:

```php
if ( ! function_exists( 'YOUR_PREFIX_add_country_to_countries_list' ) ) {
  /**
   * Add a country to countries list
   * 
   * @param array $countries Existing country list.
   * @return array $countries Modified country list.
   */
  function YOUR_PREFIX_add_country_to_countries_list( $countries ) {
    $new_countries = array(
      'NIRE'  => __( 'Northern Ireland', 'YOUR-TEXTDOMAIN' ),
    );

    return array_merge( $countries, $new_countries );
  }
  add_filter( 'woocommerce_countries',  'YOUR_PREFIX_add_country_to_countries_list' );
}

if ( ! function_exists( 'YOUR_PREFIX_add_country_to_continents_list' ) ) {
  /**
   * Add a country to continents list
   * 
   * @param array $continents Existing continents list.
   * @return array $continents Modified continents list.
   */
  function YOUR_PREFIX_add_country_to_continents_list( $continents ) {
    $continents['EU']['countries'][] = 'NIRE';

    return $continents;
  }
  add_filter( 'woocommerce_continents', 'YOUR_PREFIX_add_country_to_continents_list' );
}
```


---

## Add currencies and symbols

*Source: code-snippets/add-a-currency-symbol.md*

# Add currencies and symbols

Add custom currencies to your currencies list:

```php
if ( ! function_exists( 'YOUR_PREFIX_add_currency_name' ) ) {
  /**
   * Add custom currency
   * 
   * @param array $currencies Existing currencies.
   * @return array $currencies Updated currencies.
   */
  function YOUR_PREFIX_add_currency_name( $currencies ) {
    $currencies['ABC'] = __( 'Currency name', 'YOUR-TEXTDOMAIN' );

    return $currencies;
  }
  add_filter( 'woocommerce_currencies', 'YOUR_PREFIX_add_currency_name' );
}

if ( ! function_exists( 'YOUR_PREFIX_add_currency_symbol' ) ) {
  /**
   * Add custom currency symbol
   * 
   * @param string $currency_symbol Existing currency symbols.
   * @param string $currency Currency code.
   * @return string $currency_symbol Updated currency symbol(s).
   */
  function YOUR_PREFIX_add_currency_symbol( $currency_symbol, $currency ) {
    switch( $currency ) {
      case 'ABC': $currency_symbol = '$'; break;
    }

    return $currency_symbol;
  }
  add_filter('woocommerce_currency_symbol', 'YOUR_PREFIX_add_currency_symbol', 10, 2);
}
```


---

## Add or modify states

*Source: code-snippets/add-or-modify-states.md*

# Add or modify states

Add your own or modify shipping states in WooCommerce.

> Note: you **must** replace both instances of XX with your country code. This means each state id in the array must have your two letter country code before the number you assign to the state.

```php
if ( ! function_exists( 'YOUR_PREFIX_add_or_modify_states' ) ) {
  /**
   * Add or modify States
   * 
   * @param array $states Existing country states.
   * @return array $states Modified country states.
   */
  function YOUR_PREFIX_add_or_modify_states( $states ) {
    $states['XX'] = array(
      'XX1' => __( 'State 1', 'YOUR-TEXTDOMAIN' ),
      'XX2' => __( 'State 2', 'YOUR-TEXTDOMAIN' ),
    );

    return $states;
  }
  add_filter( 'woocommerce_states', 'YOUR_PREFIX_add_or_modify_states' );
}
```


---

## Adjust the quantity input values

*Source: code-snippets/adjust-quantity-input-values.md*

# Adjust the quantity input values

Set the starting value, maximum value, minimum value, and increment amount for quantity input fields on product pages.

```php
if ( ! function_exists( 'YOUR_PREFIX_woocommerce_quantity_input_args' ) ) {
	/**
	 * Adjust the quantity input values for simple products
	 */
	function YOUR_PREFIX_woocommerce_quantity_input_args( $args, $product ) {
		// Only affect the starting value on product pages, not the cart
		if ( is_singular( 'product' ) ) {
			$args['input_value'] = 4;
		}

		$args['max_value'] 	= 10; // Maximum value
		$args['min_value'] 	= 2;  // Minimum value
		$args['step'] 		= 2;  // Quantity steps

		return $args;
	}

	add_filter( 'woocommerce_quantity_input_args', 'YOUR_PREFIX_woocommerce_quantity_input_args', 10, 2 );
}

if ( ! function_exists( 'YOUR_PREFIX_woocommerce_available_variation' ) ) {
	/**
	 * Adjust the quantity input values for variations
	 */
	function YOUR_PREFIX_woocommerce_available_variation( $args ) {
		$args['max_qty'] = 20; // Maximum value (variations)
		$args['min_qty'] = 2;  // Minimum value (variations)

		// Note: the starting value and step for variations is controlled
		// from the 'woocommerce_quantity_input_args' filter shown above for
    // simple products

		return $args;
	}

	add_filter( 'woocommerce_available_variation', 'YOUR_PREFIX_woocommerce_available_variation' );
}
```

If you are looking for a little more power, check out our [Min/Max Quantities](https://woocommerce.com/products/minmax-quantities) extension!


---

## Add a message above the login / register form

*Source: code-snippets/before-login--register-form.md*

# Add a message above the login / register form

This code will add a custom message above the login/register form on the user's my-account page.

```php
if ( ! function_exists( 'YOUR_PREFIX_login_message' ) ) {
    /**
     * Add a message above the login / register form on my-account page
     */
    function YOUR_PREFIX_login_message() {
        if ( get_option( 'woocommerce_enable_myaccount_registration' ) == 'yes' ) {
            ?>
            <div class="woocommerce-info">
            <p><?php _e( 'Returning customers login. New users register for next time so you can:', 'YOUR-TEXTDOMAIN' ); ?></p>
            <ul>
                <li><?php _e( 'View your order history', 'YOUR-TEXTDOMAIN' ); ?></li>
                <li><?php _e( 'Check on your orders', 'YOUR-TEXTDOMAIN' ); ?></li>
                <li><?php _e( 'Edit your addresses', 'YOUR-TEXTDOMAIN' ); ?></li>
                <li><?php _e( 'Change your password', 'YOUR-TEXTDOMAIN' ); ?></li>
            </ul>
            </div>
            <?php
        }
    }
    add_action( 'woocommerce_before_customer_login_form', 'YOUR_PREFIX_login_message' );
}
```

Please note that for this code to work, the following options must be checked in the WooCommerce "Accounts & Privacy" settings:

-   Allow customers to create an account during checkout.
-   Allow customers to create an account on the "My Account" page.


---

## Change a currency symbol

*Source: code-snippets/change-a-currency-symbol.md*

# Change a currency symbol

In WooCommerce, each currency is associated with a code and a symbol. For example, the Australian dollar has the code `AUD` and the symbol `$` (if you are interested, you can see a full list of codes and symbols in the [source code](https://github.com/woocommerce/woocommerce/blob/9.6.1/plugins/woocommerce/includes/wc-core-functions.php#L682)). 

However, there may be situations where you wish to change the symbol. Taking our example of the Australian dollar, it uses the same symbol as many other dollar currencies and so, in certain situations where this could lead to confusion, it might be useful to change it to `AUD$`. The following snippet outlines how this might be done:

```php
if ( ! function_exists( 'YOUR_PREFIX_change_currency_symbol' ) ) {
  /**
   * Change a currency symbol
   * 
   * @param string $currency_symbol Existing currency symbols.
   * @param string $currency Currency code.
   * @return string $currency_symbol Updated currency symbol(s).
   */  
  function YOUR_PREFIX_change_currency_symbol( $currency_symbol, $currency ) {
    switch ( $currency ) {
      case 'AUD': $currency_symbol = 'AUD$'; break;
    }

    return $currency_symbol;       
  }
  add_filter( 'woocommerce_currency_symbol', 'YOUR_PREFIX_change_currency_symbol', 10, 2 );  
}
```

You can add additional cases within the switch statements to make the same sort of change for any other currencies you support.


---

## Check if a Payment Method Support Refunds, Subscriptions or Pre-orders

*Source: code-snippets/check_payment_method_support.md*

# Check if a Payment Method Support Refunds, Subscriptions or Pre-orders

If a payment method's documentation doesn’t clearly outline the supported features, you can often find what features are supported by looking at payment methods code.

Payment methods can add support for certain features from WooCommerce and its extensions. For example, a payment method can support refunds, subscriptions or pre-orders functionality.

## Simplify Commerce example

Taking the Simplify Commerce payment method as an example, open the plugin files in your favorite editor and search for `$this->supports`. You'll find the supported features:

```php
class WC_Gateway_Simplify_Commerce extends WC_Payment_Gateway {    

/**      * Constructor   */
    public function __construct() {
        $this->id
                 = 'simplify_commerce';
        $this->method_title
       = __( 'Simplify Commerce', 'woocommerce' );
        $this->method_description = __( 'Take payments via Simplify Commerce - uses simplify.js to create card tokens and the Simplify Commerce SDK. Requires SSL when sandbox is disabled.', 'woocommerce' );
        $this->has_fields         = true;
        $this->supports           = array(
            'subscriptions',
            'products',
            'subscription_cancellation',
            'subscription_reactivation',
            'subscription_suspension',
            'subscription_amount_changes',
            'subscription_payment_method_change',
            'subscription_date_changes',
            'default_credit_card_form',
            'refunds',
            'pre-orders'
        );    
```

If you don't find `$this->supports` in the plugin files, that may mean that the payment method isn't correctly declaring support for refunds, subscripts or pre-orders.


---

## Code snippets for configuring special tax scenarios

*Source: code-snippets/configuring_special_tax_scenarios.md*

# Code snippets for configuring special tax scenarios

## Scenario A: Charge the same price regardless of location and taxes

If a store enters product prices including taxes, but levies various location-based tax rates, the prices will appear to change depending on which tax rate is applied. In reality, the base price remains the same, but the taxes influence the total. [Follow this link for a detailed explanation](https://woocommerce.com/document/how-taxes-work-in-woocommerce/#cross-border-taxes).

Some merchants prefer to dynamically change product base prices to account for the changes in taxes and so keep the total price consistent regardless of tax rate. Enable that functionality by adding the following snippet to your child theme's functions.php file or via a code snippet plugin.

```php
<?php

add_filter( 'woocommerce_adjust_non_base_location_prices', '__return_false' );
```

## Scenario B: Charge tax based on the subtotal amount

The following snippet is useful in case where a store only ads taxes when the subtotal reaches a specified minimum. In the code snippet below that minimum is 110 of the store's currency. Adjust the snippet according to your requirements. 

```php
<?php

add_filter( 'woocommerce_product_get_tax_class', 'big_apple_get_tax_class', 1, 2 );

function big_apple_get_tax_class( $tax_class, $product ) {
	if ( WC()->cart->subtotal <= 110 )
		$tax_class = 'Zero Rate';

	return $tax_class;
}
```

## Scenario C: Apply different tax rates based on the customer role

Some merchants may require different tax rates to be applied based on a customer role to accommodate for wholesale status or tax exemption.

To enable this functionality, add the following snippet to your child theme's functions.php file or via a code snippet plugin. In this snippet, users with "administrator" capabilities will be assigned the **Zero rate tax class**. Adjust it according to your requirements.

```php
<?php
/**
 * Apply a different tax rate based on the user role.
 */
function wc_diff_rate_for_user( $tax_class, $product ) {
	if ( is_user_logged_in() && current_user_can( 'administrator' ) ) {
		$tax_class = 'Zero Rate';
	}

	return $tax_class;
}
add_filter( 'woocommerce_product_get_tax_class', 'wc_diff_rate_for_user', 1, 2 );
add_filter( 'woocommerce_product_variation_get_tax_class', 'wc_diff_rate_for_user', 1, 2 );
```

## Scenario D: Show 0 value taxes

Taxes that have 0-value are hidden by default. To show them regardless, add the following snippet to your theme's functions.php file or via a code snippet plugins: 

```php
add_filter( 'woocommerce_order_hide_zero_taxes', '__return_false' );
```

## Scenario E: Suffixes on the main variable product

One of the tax settings for WooCommerce enables the use of suffixes to add additional information to product prices. It's available for use with the variations of a variable product, but is disabled at the main variation level as it can impact website performance when there are many variations. 

The method responsible for the related price output can be customized via filter hooks if needed for variable products. This will require customization that can be implemented via this filter:

```php
add_filter( 'woocommerce_show_variation_price', '__return_true' );
```




---

## Customizing checkout fields using actions and filters

*Source: code-snippets/customising-checkout-fields.md*

# Customizing checkout fields using actions and filters

If you are unfamiliar with code and resolving potential conflicts, we have an extension that can help: [WooCommerce Checkout Field Editor](https://woocommerce.com/products/woocommerce-checkout-field-editor/). Installing and activating this extension overrides any code below that you try to implement; and you cannot have custom checkout field code in your functions.php file when the extension is activated.

Custom code should be copied into your child theme's **functions.php** file.

## Note

Some parts of this document only applies to the shortcode Checkout, for adding fields to the Checkout block, consult [the additional checkout fields documentation](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/additional-checkout-fields/).

## How Are Checkout Fields Loaded to WooCommerce?

The billing and shipping fields for checkout pull from the countries class `class-wc-countries.php` and the **`get_address_fields`** function. This allows WooCommerce to enable/disable fields based on the user's location.

Before returning these fields, WooCommerce puts the fields through a _filter_. This allows them to be edited by third-party plugins, themes and your own custom code.

Billing:

```php
$address_fields = apply_filters( 'woocommerce_billing_fields', $address_fields );
```

Shipping:

```php
$address_fields = apply_filters( 'woocommerce_shipping_fields', $address_fields );
```

The checkout class adds the loaded fields to its `checkout_fields` array, as well as adding a few other fields like "order notes".

```php
$this->checkout_fields['billing']  = $woocommerce->countries->get_address_fields( $this->get_value( 'billing_country' ), 'billing_' );
$this->checkout_fields['shipping'] = $woocommerce->countries->get_address_fields( $this->get_value( 'shipping_country' ), 'shipping_' );
$this->checkout_fields['account']  = array(
    'account_username'   => array(
        'type'        => 'text',
        'label'       => __( 'Account username', 'woocommerce' ),
        'placeholder' => _x( 'Username', 'placeholder', 'woocommerce' ),
    ),
    'account_password'   => array(
        'type'        => 'password',
        'label'       => __( 'Account password', 'woocommerce' ),
        'placeholder' => _x( 'Password', 'placeholder', 'woocommerce' ),
        'class'       => array( 'form-row-first' )
    ),
    'account_password-2' => array(
        'type'        => 'password',
        'label'       => __( 'Account password', 'woocommerce' ),
        'placeholder' => _x( 'Password', 'placeholder', 'woocommerce' ),
        'class'       => array( 'form-row-last' ),
        'label_class' => array( 'hidden' )
    ),
);
$this->checkout_fields['order']   = array(
    'order_comments' => array(
        'type'        => 'textarea',
        'class'       => array( 'notes' ),
        'label'       => __( 'Order Notes', 'woocommerce' ),
        'placeholder' => _x( 'Notes about your order, e.g. special notes for delivery.', 'placeholder', 'woocommerce' )
    )
);
```

This array is also passed through a filter:

```php
$this->checkout_fields = apply_filters( 'woocommerce_checkout_fields', $this->checkout_fields );
```

That means you have **full control** over checkout fields - you only need to know how to access them.

## Overriding Core Fields

Hooking into the **`woocommerce_checkout_fields`** filter lets you override any field. As an example, let's change the placeholder on the order_comments fields. Currently, it's set to:

```php
_x( 'Notes about your order, e.g. special notes for delivery.', 'placeholder', 'woocommerce' );
```

We can change this by adding a function to our theme functions.php file:

```php
// Hook in
add_filter( 'woocommerce_checkout_fields' , 'custom_override_checkout_fields' );

// Our hooked in function - $fields is passed via the filter!
function custom_override_checkout_fields( $fields ) {
    $fields['order']['order_comments']['placeholder'] = 'My new placeholder';
    return $fields;
}
```

You can override other parts, such as labels:

```php
// Hook in
add_filter( 'woocommerce_checkout_fields' , 'custom_override_checkout_fields' );

// Our hooked in function - $fields is passed via the filter!
function custom_override_checkout_fields( $fields ) {
    $fields['order']['order_comments']['placeholder'] = 'My new placeholder';
    $fields['order']['order_comments']['label']       = 'My new label';
    return $fields;
}
```

Or remove fields:

```php
// Hook in
add_filter( 'woocommerce_checkout_fields' , 'custom_override_checkout_fields' );

// Our hooked in function - $fields is passed via the filter!
function custom_override_checkout_fields( $fields ) {
    unset( $fields['order']['order_comments'] );

    return $fields;
}
```

Here's a full list of fields in the array passed to `woocommerce_checkout_fields`:

-   Billing
    -   `billing_first_name`
    -   `billing_last_name`
    -   `billing_company`
    -   `billing_address_1`
    -   `billing_address_2`
    -   `billing_city`
    -   `billing_postcode`
    -   `billing_country`
    -   `billing_state`
    -   `billing_email`
    -   `billing_phone`
-   Shipping
    -   `shipping_first_name`
    -   `shipping_last_name`
    -   `shipping_company`
    -   `shipping_address_1`
    -   `shipping_address_2`
    -   `shipping_city`
    -   `shipping_postcode`
    -   `shipping_country`
    -   `shipping_state`
-   Account
    -   `account_username`
    -   `account_password`
    -   `account_password-2`
-   Order
    -   `order_comments`

Each field contains an array of properties:

-   `type` - type of field (text, textarea, password, select)
-   `label` - label for the input field
-   `placeholder` - placeholder for the input
-   `class` - class for the input
-   `required` - true or false, whether or not the field is require
-   `clear` - true or false, applies a clear fix to the field/label
-   `label_class` - class for the label element
-   `options` - for select boxes, array of options (key => value pairs)

In specific cases you need to use the **`woocommerce_default_address_fields`** filter. This filter is applied to all billing and shipping default fields:

-   `country`
-   `first_name`
-   `last_name`
-   `company`
-   `address_1`
-   `address_2`
-   `city`
-   `state`
-   `postcode`

For example, to make the `address_1` field optional:

```php
// Hook in
add_filter( 'woocommerce_default_address_fields' , 'custom_override_default_address_fields' );

// Our hooked in function - $address_fields is passed via the filter!
function custom_override_default_address_fields( $address_fields ) {
    $address_fields['address_1']['required'] = false;

    return $address_fields;
}
```

### Defining select options

If you are adding a field with type 'select', as stated above you would define key/value pairs. For example:

```php
$fields['billing']['your_field']['options'] = array(
    'option_1' => 'Option 1 text',
    'option_2' => 'Option 2 text'
);
```

## Priority

Priority in regards to PHP code helps establish when a bit of code - called a function - runs in relation to a page load. It is set inside of each function and is useful when overriding existing code for custom display.

Code with a higher number set as the priority will run after code with a lower number, meaning code with a priority of 20 will run after code with 10 priority.

The priority argument is set during the [add_action](https://developer.wordpress.org/reference/functions/add_action/) function, after you establish which hook you're connecting to and what the name of your custom function will be.

In the example below, blue text is the name of the hook we're modifying, green text is the name of our custom function, and red is the priority we set.

![Setting priority for the hooked function](https://developer.woocommerce.com/wp-content/uploads/2023/12/priority-markup.png)

## Examples

### Change Return to Shop button redirect URL

In this example, the code is set to redirect the "Return to Shop" button found in the cart to a category that lists products for sale at `http://example.url/category/specials/`.

```php
/**
 * Changes the redirect URL for the Return To Shop button in the cart.
 */
function wc_empty_cart_redirect_url() {
    return 'http://example.url/category/specials/';
}

add_filter( 'woocommerce_return_to_shop_redirect', 'wc_empty_cart_redirect_url', 10 );
```

There, we can see the priority is set to 10. This is the typical default for WooCommerce functions and scripts, so that may not be sufficient to override that button's functionality.

Instead, we can change the priority to any number greater than 10. While 11 would work, best practice dictates we use increments of ten, so 20, 30, and so on.

```php
/**
 * Changes the redirect URL for the Return To Shop button in the cart.
 */
function wc_empty_cart_redirect_url() {
    return 'http://example.com/category/specials/';
}

add_filter( 'woocommerce_return_to_shop_redirect', 'wc_empty_cart_redirect_url', 20 );
```

With priority, we can have two functions that are acting on the same hook. Normally this would cause a variety of problems, but since we've established one has a higher priority than the other, our site will only load the appropriate function, and we will be taken to the Specials page as intended with the code below.

```php
/**
 * Changes the redirect URL for the Return To Shop button in the cart.
 * BECAUSE THIS FUNCTION HAS THE PRIORITY OF 20, IT WILL RUN AFTER THE FUNCTION BELOW (HIGHER NUMBERS RUN LATER)
 */
function wc_empty_cart_redirect_url() {
    return 'http://example.com/category/specials/';
}

add_filter( 'woocommerce_return_to_shop_redirect', 'wc_empty_cart_redirect_url', 20 );

/**
 * Changes the redirect URL for the Return To Shop button in the cart.
 * EVEN THOUGH THIS FUNCTION WOULD NORMALLY RUN LATER BECAUSE IT'S CODED AFTERWARDS, THE 10 PRIORITY IS LOWER THAN 20 ABOVE
 */
function wc_empty_cart_redirect_url() {
    return 'http://example.com/shop/';
}

add_filter( 'woocommerce_return_to_shop_redirect', 'wc_empty_cart_redirect_url', 10 );
```

### Adding Custom Shipping And Billing Fields

Adding fields is done in a similar way to overriding fields. For example, let's add a new field to shipping fields - `shipping_phone`:

```php
// Hook in
add_filter( 'woocommerce_checkout_fields' , 'custom_override_checkout_fields' );

// Our hooked in function - $fields is passed via the filter!
function custom_override_checkout_fields( $fields ) {
     $fields['shipping']['shipping_phone'] = array(
        'label'       => __( 'Phone', 'woocommerce' ),
        'placeholder' => _x( 'Phone', 'placeholder', 'woocommerce' ),
        'required'    => false,
        'class'       => array( 'form-row-wide' ),
        'clear'       => true
     );

     return $fields;
}

/**
 * Display field value on the order edit page
 */
add_action( 'woocommerce_admin_order_data_after_shipping_address', 'my_custom_checkout_field_display_admin_order_meta', 10, 1 );

function my_custom_checkout_field_display_admin_order_meta($order){
    echo '<p><strong>'. esc_html__( 'Phone From Checkout Form' ) . ':</strong> ' . esc_html( $order->get_meta( '_shipping_phone', true ) ) . '</p>';
}
```

![adding custom sthipping and billing fields](https://developer.woocommerce.com/wp-content/uploads/2023/12/Webp-to-PNG-Shipping-Field-Hook.png)

It's alive!

What do we do with the new field? Nothing. Because we defined the field in the `checkout_fields` array, the field is automatically processed and saved to the order post meta (in this case, `_shipping_phone`). If you want to add validation rules, see the checkout class where there are additional hooks you can use.

### Adding a Custom Special Field

To add a custom field is similar. Let's add a new field to checkout, after the order notes, by hooking into the following:

```php
/**
 * Add the field to the checkout
 */
add_action( 'woocommerce_after_order_notes', 'my_custom_checkout_field' );

function my_custom_checkout_field( $checkout ) {

    echo '<div id="my_custom_checkout_field"><h2>' . esc_html__( 'My Field' ) . '</h2>';

    woocommerce_form_field(
        'my_field_name',
        array(
            'type'        => 'text',
            'class'       => array( 'my-field-class form-row-wide' ),
            'label'       => __( 'Fill in this field' ),
            'placeholder' => __( 'Enter something' ),
        ),
        $checkout->get_value( 'my_field_name' )
    );

    echo '</div>';

}
```

This gives us:

![WooCommerce Codex - Checkout Field Hook](https://developer.woocommerce.com/wp-content/uploads/2023/12/WooCommerce-Codex-Checkout-Field-Hook.png)

Next we need to validate the field when the checkout form is posted. For this example let's check that the field contains only letters:

```php
/**
 * Process the checkout
 */
add_action( 'woocommerce_checkout_process', 'my_custom_checkout_field_process' );

function my_custom_checkout_field_process() {
    // Check if this field contains just letters.
    if ( ! preg_match( '/^[a-zA-Z]+$/', $_POST['my_field_name'] ) ) {
		wc_add_notice( esc_html__( 'Please enter only letters into this new shiny field.' ), 'error' );
	}
}
```

A checkout error is displayed if the field is blank:

![WooCommerce Codex - Checkout Field Notice](https://developer.woocommerce.com/wp-content/uploads/2023/12/WooCommerce-Codex-Checkout-Field-Notice.png)

Finally, let's save the new field to order custom fields using the following code:

```php
/**
 * Update the order meta with field value
 */
add_action( 'woocommerce_checkout_update_order_meta', 'my_custom_checkout_field_update_order_meta' );

function my_custom_checkout_field_update_order_meta( $order_id ) {
    if ( ! empty( $_POST['my_field_name'] ) ) {
        $order = wc_get_order( $order_id );
        $order->update_meta_data( 'My Field', sanitize_text_field( $_POST['my_field_name'] ) );
        $order->save_meta_data();
    }
}
```

The field is now saved to the order.

If you wish to display the custom field value on the admin order edition page, you can add this code:

```php
/**
 * Display field value on the order edit page
 */
add_action( 'woocommerce_admin_order_data_after_billing_address', 'my_custom_checkout_field_display_admin_order_meta', 10, 1 );

function my_custom_checkout_field_display_admin_order_meta( $order ){
    echo '<p><strong>' . esc_html__( 'My Field' ) . ':</strong> ' . esc_html( $order->get_meta( 'My Field', true ) ) . '</p>';
}
```

This is the result:

![checkout_field_custom_field_admin](https://developer.woocommerce.com/wp-content/uploads/2023/12/checkout_field_custom_field_admin.png)

### Make phone number not required

```php
add_filter( 'woocommerce_billing_fields', 'wc_npr_filter_phone', 10, 1 );

function wc_npr_filter_phone( $address_fields ) {
	$address_fields['billing_phone']['required'] = false;
	return $address_fields;
}
```


---

## Customize the failed order message

*Source: code-snippets/customize-failed-order-message.md*

# Customize the failed order message

WooCommerce displays a message on the order confirmation page when an order fails. In WooCommerce 11.2 and later, use the `woocommerce_thankyou_order_failed_text` filter to customize this message in both the classic and block-based order confirmation pages.

The filter receives the current message and the failed order, so the message can include order details:

When packaging this snippet in a plugin or theme, replace `your-text-domain` with the plugin or theme's text domain so its translation catalog can include the message.

```php
/**
 * Customize the message shown for failed orders.
 *
 * @param string   $message Current failed order message.
 * @param WC_Order $order   Failed order.
 * @return string
 */
function your_prefix_customize_failed_order_message( $message, $order ) {
	return sprintf(
		/* translators: %s: Order number. */
		__( 'We could not process order #%s. Please try again or contact us for help.', 'your-text-domain' ),
		esc_html( $order->get_order_number() )
	);
}
add_filter( 'woocommerce_thankyou_order_failed_text', 'your_prefix_customize_failed_order_message', 10, 2 );
```

The callback must return a string. Safe inline HTML is allowed and is sanitized before WooCommerce displays it.


---

## Disabling Marketplace Suggestions Programmatically

*Source: code-snippets/disabling_marketplace_suggestions_programmatically.md*

# Disabling Marketplace Suggestions Programmatically


For those who prefer to programmatically disable marketplace suggestions that are fetched from woocommerce.com, add the `woocommerce_allow_marketplace_suggestions` filter to your theme’s `functions.php` or a custom plugin. 

For example: 

```php
add_filter( 'woocommerce_allow_marketplace_suggestions', '__return_false' );
```

This filter will completely remove Marketplace Suggestions from your WooCommerce admin.


---

## Displaying custom fields in your theme or site

*Source: code-snippets/displaying_custom_fields_in_your_theme_or_site.md*

# Displaying custom fields in your theme or site

You can use the metadata from custom fields you add to your products to display the added information within your theme or site.

To display the custom fields for each product, you have to edit your theme’s files. Here’s an example of how you might display a custom field within the single product pages after the short description:

![image](./_media/custom-field-value.png)

```php
<?php

// Display a product custom field within single product pages after the short description 

function woocommerce_custom_field_example() {

    if ( ! is_product() ) {
        return;
    }
   
    global $product;

    if ( ! is_object( $product ) ) {
        $product = wc_get_product( get_the_ID() );
    }

    $custom_field_value = get_post_meta( $product->get_id(), 'woo_custom_field', true );
    
    if ( ! empty( $custom_field_value ) ) {
       echo '<div class="custom-field">' . esc_html( $custom_field_value ) . '</div>';
    }
}

add_action( 'woocommerce_before_add_to_cart_form', 'woocommerce_custom_field_example', 10 );
```


---

## Free Shipping Customizations

*Source: code-snippets/free_shipping_customization.md*

# Free Shipping Customizations

## Free Shipping: Advanced Settings/Customization

### Overview

By default, WooCommerce shows all shipping methods that match the customer and the cart contents. This means Free Shipping also shows along with Flat Rate and other Shipping Methods. 

The functionality to hide all other methods, and only show Free Shipping, requires either custom PHP code or a plugin/extension.

### Adding code

Before adding snippets, clear your WooCommerce cache. Go to WooCommerce > System Status > Tools > WooCommerce Transients > Clear transients.

## Code Snippets

### How do I only show Free Shipping?

The following snippet will hide all other shipping methods if Free Shipping is available for the customer.

```php
/**
 * Hide other shipping rates when free shipping is available.
 *
 * @param array $rates Array of rates found for the package.
 *
 * @return array
 */
function fsc_hide_shipping_rates_when_free_is_available( $rates ) {
	// Go through each rate found.
	foreach ( $rates as $rate_id => $rate ) {
		// If Free Shipping is found, define it as the only rate and break out of the foreach.
		if ( 'free_shipping' === $rate->method_id ) {
			$rates = [ $rate_id => $rate ];
			break;
		}
	}
	return $rates;
}
add_filter( 'woocommerce_package_rates', 'fsc_hide_shipping_rates_when_free_is_available', 10, 1 );
```

### How do I only show Local Pickup and Free Shipping?

The following snippet will hide all other shipping methods but Free Shipping and Local Pickup if they are available for the customer.

```php
/**
 * If Free Shipping is available hide other rates, excluding Local Pickup.
 *
 * @param array $rates Array of rates found for the package.
 *
 * @return array
 */
function fsc_hide_shipping_rates_when_free_is_available_excluding_local( $rates ) {
	// Define arrays to hold our Free Shipping and Local Pickup methods, if found.
	$free_shipping = [];
	$local_pickup  = [];

	// Go through each rate received.
	foreach ( $rates as $rate_id => $rate ) {
		// If either method is found, add them to their respective array.
		if ( 'free_shipping' === $rate->method_id ) {
			$free_shipping[ $rate_id ] = $rate;
			continue;
		}
		if ( 'pickup_location' === $rate->method_id ) {
			$local_pickup[ $rate_id ] = $rate;
		}
	}

	// If the free_shipping array contains a method, then merge the local_pickup into it, and overwrite the rates array.
	if ( ! empty( $free_shipping ) ) {
		$rates = array_merge( $free_shipping, $local_pickup );
	}

	return $rates;
}

add_filter( 'woocommerce_package_rates', 'fsc_hide_shipping_rates_when_free_is_available_excluding_local', 10, 1 );
```

### Enabling or Disabling Free Shipping via Hooks

If you would like to know if Free Shipping is available programmatically, this is possible. WooCommerce applies a filter like the below:

```php
return apply_filters( 'woocommerce_shipping_' . $this->id . '_is_available', $is_available );
```

This means you can use `add_filter()` on `woocommerce_shipping_free_shipping_is_available` and receive `true` or `false` if Free Shipping is enabled. For example, this next snippet would log if Free Shipping is available or not:

```php
/**
 * Log if Free Shipping is available or not.
 *
 * @param bool $is_available If Free Shipping is available, then `true`, `false` if not.
 *
 * @return bool
 */
function fsc_free_shipping_is_available( $is_available ) {
	if ( $is_available ) {
		error_log( 'Free shipping is available' );
	} else {
		error_log( 'Free shipping is NOT available' );
	}
	return $is_available;
}
add_filter( 'woocommerce_shipping_free_shipping_is_available', 'fsc_free_shipping_is_available', 10, 1 );
```

### Enable Shipping Methods on a per Class / Product Basis, split orders, or other scenarios?

Need more flexibility? Take a look at our [premium Shipping Method extensions](https://woocommerce.com/product-category/woocommerce-extensions/shipping-methods/).


---

## Advanced settings and customization for legacy Local Pickup

*Source: code-snippets/legacy_local_pickup_advanced_settings_and_customization.md*

# Advanced settings and customization for legacy Local Pickup

## Disable local taxes when using local pickup

Local Pickup calculates taxes based on your store's location (address) by default, and not the customer's address. Add this snippet at the end of your theme's `functions.php` to use your standard tax configuration instead:

```php
add_filter( 'woocommerce_apply_base_tax_for_local_pickup', '__return_false' );
```

Regular taxes is then used when local pickup is selected, instead of store-location-based taxes. 

## Changing the location for local taxes

To charge local taxes based on the postcode and city of the local pickup location, you need to define the shop's base city and post code using this example code:

```php
add_filter( 'woocommerce_countries_base_postcode', create_function( '', 'return "80903";' ) );
add_filter( 'woocommerce_countries_base_city', create_function( '', 'return "COLORADO SPRINGS";' ) );
```

Update `80903` to reflect your preferred postcode/zip, and `COLORADO SPRINGS` with your preferred town or city.

## Custom emails for local pickup

_Shipping Address_ is not displayed on the admin order emails when Local Pickup is used as the shipping method.

Since all core shipping options use the standard order flow, customers receive the same order confirmation email whether they select local pickup or any other shipping option. 
Use this guide to create custom emails for local pickup if you'd like to send a separate email for local pickup orders: [How to Add a Custom WooCommerce Email](https://www.skyverge.com/blog/how-to-add-a-custom-woocommerce-email/).



---

## Add link to logged data

*Source: code-snippets/link-to-logged-data.md*

# Add link to logged data

[Logging](/docs/best-practices/data-management/logging) is a crucial part of any WooCommerce extension. It helps you track errors and debug issues. A common pattern is to have a setting in your extension to enable logging when the user needs to troubleshoot an issue. The following code snippet shows an example of how to add this setting, as well as a link to the log viewer, in the context of the [Settings API](/docs/extensions/settings-and-config/settings-api).

```php
use Automattic\WooCommerce\Utilities\LoggingUtil;

// Define the label and description for the logging option
$label = __( 'Enable logging', 'your-textdomain-here' );
$description = __( 'Log events and errors to help with troubleshooting.', 'your-textdomain-here' );

// Check if WooCommerce's logging feature is enabled.
if ( LoggingUtil::logging_is_enabled() ) {
    // The source value you use for your extension's log entries. Could be the same as your text domain.
    $source = 'yourpluginslug';
    
    $logs_url = add_query_arg(
        'source',
        $source,
        LoggingUtil::get_logs_tab_url()
    );
    
    $label .= ' | ' . sprintf(
        __( '<a href="%s">View logs</a>', 'your-textdomain-here' ),
        $logs_url
    );
}

// Add the logging option to the form fields.
$form_fields['yourpluginslug_debug'] = array(
  'title'       => __( 'Debugging', 'your-textdomain-here' ),
  'label'       => $label,
  'description' => $description,
  'type'        => 'checkbox',
  'default'     => 'no'
);
```


---

## Making your translation upgrade safe

*Source: code-snippets/making_translations_upgrade_safe.md*

# Making your translation upgrade safe

Like all other plugins, WooCommerce keeps translations in `wp-content/languages/plugins`. 

However, if you want to include a custom translation, you can add them to `wp-content/languages/woocommerce`, or you can use a snippet to load a custom translation stored elsewhere:

```php
// Code to be placed in functions.php of your theme or a custom plugin file.
add_filter( 'load_textdomain_mofile', 'load_custom_plugin_translation_file', 10, 2 );

/*
 * Replace 'textdomain' with your plugin's textdomain. e.g. 'woocommerce'. 
 * File to be named, for example, yourtranslationfile-en_GB.mo
 * File to be placed, for example, wp-content/lanaguages/textdomain/yourtranslationfile-en_GB.mo
 */
function load_custom_plugin_translation_file( $mofile, $domain ) {
  if ( 'textdomain' === $domain ) {
    $mofile = WP_LANG_DIR . '/textdomain/yourtranslationfile-' . get_locale() . '.mo';
  }
  return $mofile;
}
```


---

## Change number of related products displayed

*Source: code-snippets/number-of-products-per-row.md*

# Change number of related products displayed

Add code to your child theme's functions.php file or via a plugin that allows custom functions to be added, such as the [Code snippets](https://wordpress.org/plugins/code-snippets/) plugin. Avoid adding custom code directly to your parent theme's `functions.php` file as this will be wiped entirely when you update the theme.

Please note that it does not work for all themes because of the way they're coded.

```php
if ( ! function_exists( 'YOUR_PREFIX_related_products_args' ) ) {
	/**
	 * Change number of related products output.
	 *
	 * @param  array $args The related products args.
	 * @return array The modified related products args.
	 */
	function YOUR_PREFIX_related_products_args( $args ) {
		if ( ! is_array( $args ) ) {
			$args = array();
		}

		$args['posts_per_page'] = 4; // 4 related products.
		$args['columns']        = 2; // Arranged in 2 columns.

		return $args;
	}
}
add_filter( 'woocommerce_output_related_products_args', 'YOUR_PREFIX_related_products_args', 20 );
```


---

## Override loop template and show quantities next to add to cart buttons

*Source: code-snippets/override-loop-template-show-quantities-next-add-cart.md*

# Override loop template and show quantities next to add to cart buttons

Add this code to your child theme’s `functions.php` file or via a plugin that allows custom functions to be added, such as the [Code Snippets](https://wordpress.org/plugins/code-snippets/) plugin. Avoid adding custom code directly to your parent theme’s functions.php file, as this will be wiped entirely when you update the theme.

```php
if ( ! function_exists( 'YOUR_PREFIX_quantity_inputs_for_woocommerce_loop_add_to_cart_link' ) ) {
  /**
   * Override loop template and show quantities next to add to cart buttons
   * @param  string $html    Default loop template.
   * @param  object $product Product data.
   * @return string          Modified loop template.
   */
	function YOUR_PREFIX_quantity_inputs_for_woocommerce_loop_add_to_cart_link( $html, $product ) {
		if ( $product && $product->is_type( 'simple' ) && $product->is_purchasable() && $product->is_in_stock() && ! $product->is_sold_individually() ) {
			$html  = '<form action="' . esc_url( $product->add_to_cart_url() ) . '" class="cart" method="post" enctype="multipart/form-data">';
			$html .= woocommerce_quantity_input( array(), $product, false );
			$html .= '<button type="submit" class="button alt">' . esc_html( $product->add_to_cart_text() ) . '</button>';
			$html .= '</form>';
		}

		return $html;
	}
	add_filter( 'woocommerce_loop_add_to_cart_link', 'YOUR_PREFIX_quantity_inputs_for_woocommerce_loop_add_to_cart_link', 10, 2 );
}
```


---

## Prevent PO Box addresses in the Checkout block

*Source: code-snippets/prevent-po-box-addresses-in-checkout-block.md*

# Prevent PO Box addresses in the Checkout block

The Checkout block uses the Store API checkout flow, so shortcode checkout hooks such as `woocommerce_after_checkout_validation` do not run there. To validate orders submitted through the Checkout block, use the `woocommerce_checkout_validate_order_before_payment` hook.

The following snippet checks the shipping address when one exists, and falls back to billing details when checkout does not include a separate shipping address. Add it with the Code Snippets plugin and set it to run everywhere.

```php
/**
 * Prevent Checkout block orders from using PO Box addresses.
 *
 * @param WC_Order $order  Checkout order.
 * @param WP_Error $errors Validation errors.
 */
function wc_prevent_checkout_block_po_box_addresses( $order, $errors ) {
	$address = $order->has_shipping_address()
		? $order->get_shipping_address_1() . ' ' . $order->get_shipping_address_2()
		: $order->get_billing_address_1() . ' ' . $order->get_billing_address_2();

	$postcode = $order->has_shipping_address()
		? $order->get_shipping_postcode()
		: $order->get_billing_postcode();

	$normalized_address = strtolower( str_replace( array( ' ', '.', ',' ), '', $address . ' ' . $postcode ) );

	if ( false !== strpos( $normalized_address, 'pobox' ) ) {
		$errors->add(
			'po_box_address',
			__( 'Sorry, we cannot ship to PO Box addresses.', 'woocommerce' )
		);
	}
}
add_action( 'woocommerce_checkout_validate_order_before_payment', 'wc_prevent_checkout_block_po_box_addresses', 10, 2 );
```

For example, the snippet blocks address formats such as `PO Box 123`, `P.O. Box 123`, and `POBOX 123`.


---

## Rename a country

*Source: code-snippets/rename-a-country.md*

# Rename a country

Rename a country in your countries list:

```php
if ( ! function_exists( 'YOUR_PREFIX_rename_country' ) ) {
  /**
   * Rename a country
   *
   * @param array $countries Existing country names
   * @return array $countries Updated country name(s)
   */
  function YOUR_PREFIX_rename_country( $countries ) {
     $countries['IE'] = __( 'Ireland (Changed)', 'YOUR-TEXTDOMAIN' );

     return $countries;
  }
  add_filter( 'woocommerce_countries', 'YOUR_PREFIX_rename_country' );
}
```


---

## SSL and HTTPS and WooCommerce

*Source: code-snippets/ssl_and_https_and_woocommerce_websites_behind_load_balanacers_or_reverse_proxies.md*

# SSL and HTTPS and WooCommerce

## Websites behind load balancers or reverse proxies

WooCommerce uses the `is_ssl()` WordPress function to verify if your website using SSL or not.

`is_ssl()` checks if the connection is via HTTPS or on Port 443. However, this won't work for websites behind load balancers, especially websites hosted at Network Solutions. For details, read [WordPress is_ssl() function reference notes](https://codex.wordpress.org/Function_Reference/is_ssl#Notes).

Websites behind load balancers or reverse proxies that support `HTTP_X_FORWARDED_PROTO` can be fixed by adding the following code to the `wp-config.php` file, above the require_once call:

```php
if ( isset( $_SERVER['HTTP_X_FORWARDED_PROTO'] ) && 'https' == $_SERVER['HTTP_X_FORWARDED_PROTO'] ) {
    $_SERVER['HTTPS'] = 'on';
}
```

**Note:** If you use CloudFlare, you need to configure it. Check their documentation.


---

## Unhook and remove WooCommerce emails

*Source: code-snippets/unhook--remove-woocommerce-emails.md*

# Unhook and remove WooCommerce emails

This code allows you to unhook and remove the default WooCommerce emails.

```php
if ( ! function_exists( 'YOUR_PREFIX_unhook_woocommerce_emails' ) ) {
	/**
	 * Callback for woocommerce_email action hook
	 *
	 * @param WC_Email $email_class An Email class instance.
	 * @return void
	 */
	function YOUR_PREFIX_unhook_woocommerce_emails( $email_class ) {
		/**
		 * Hooks for sending emails during store events.
		 */
		remove_action( 'woocommerce_low_stock_notification', array( $email_class, 'low_stock' ) );
		remove_action( 'woocommerce_no_stock_notification', array( $email_class, 'no_stock' ) );
		remove_action( 'woocommerce_product_on_backorder_notification', array( $email_class, 'backorder' ) );

		// New order emails.
		remove_action( 'woocommerce_order_status_pending_to_processing_notification', array( $email_class->emails['WC_Email_New_Order'], 'trigger' ) );
		remove_action( 'woocommerce_order_status_pending_to_completed_notification', array( $email_class->emails['WC_Email_New_Order'], 'trigger' ) );
		remove_action( 'woocommerce_order_status_pending_to_on-hold_notification', array( $email_class->emails['WC_Email_New_Order'], 'trigger' ) );
		remove_action( 'woocommerce_order_status_failed_to_processing_notification', array( $email_class->emails['WC_Email_New_Order'], 'trigger' ) );
		remove_action( 'woocommerce_order_status_failed_to_completed_notification', array( $email_class->emails['WC_Email_New_Order'], 'trigger' ) );
		remove_action( 'woocommerce_order_status_failed_to_on-hold_notification', array( $email_class->emails['WC_Email_New_Order'], 'trigger' ) );

		// Processing order emails.
		remove_action( 'woocommerce_order_status_pending_to_processing_notification', array( $email_class->emails['WC_Email_Customer_Processing_Order'], 'trigger' ) );
		remove_action( 'woocommerce_order_status_pending_to_on-hold_notification', array( $email_class->emails['WC_Email_Customer_On_Hold_Order'], 'trigger' ) );

		// Completed order emails.
		remove_action( 'woocommerce_order_status_completed_notification', array( $email_class->emails['WC_Email_Customer_Completed_Order'], 'trigger' ) );

		// Note emails.
		remove_action( 'woocommerce_new_customer_note_notification', array( $email_class->emails['WC_Email_Customer_Note'], 'trigger' ) );
	}
}
add_action( 'woocommerce_email', 'YOUR_PREFIX_unhook_woocommerce_emails' );
```


---

## Uninstall and remove all WooCommerce Data

*Source: code-snippets/uninstall_remove_all_woocommerce_data.md*

# Uninstall and remove all WooCommerce Data

The WooCommerce plugin can be uninstalled like any other WordPress plugin. By default, the WooCommerce data is left in place though. 

If you need to remove *all* WooCommerce data as well, including products, order data, coupons, etc., you need to to modify the site's `wp-config.php` *before* deactivating and deleting the WooCommerce plugin.

As this action is destructive and permanent, the information is provided as is. WooCommerce Support cannot help with this process or anything that happens as a result. 

To fully remove all WooCommerce data from your WordPress site, open `wp-config.php`, scroll down to the bottom of the file, and add the following constant on its own line above `/* That's all, stop editing. */`.

```php
define( 'WC_REMOVE_ALL_DATA', true );

/* That's all, stop editing! Happy publishing. */ 
```

Then, once the changes are saved to the file, when you deactivate and delete WooCommerce, all of its data is removed from your WordPress site database.

![Uninstall WooCommerce WPConfig](https://woocommerce.com/wp-content/uploads/2020/03/uninstall_wocommerce_plugin_wpconfig.png)

## Removing the Action Scheduler tables

WooCommerce uses [Action Scheduler](https://actionscheduler.org/) to run background tasks. Action Scheduler is a shared library that other plugins can also bundle, so its database tables (`actionscheduler_actions`, `actionscheduler_claims`, `actionscheduler_groups` and `actionscheduler_logs`) are **not** removed by `WC_REMOVE_ALL_DATA`, even when the constant is set to `true`. Keeping them avoids deleting scheduled tasks that another active plugin might still rely on.

If you are certain that no other plugin on the site uses Action Scheduler, you can also remove those tables by adding the `WC_REMOVE_ACTION_SCHEDULER` constant alongside `WC_REMOVE_ALL_DATA` in `wp-config.php`:

```php
define( 'WC_REMOVE_ALL_DATA', true );
define( 'WC_REMOVE_ACTION_SCHEDULER', true );

/* That's all, stop editing! Happy publishing. */
```

Both constants are required: `WC_REMOVE_ALL_DATA` triggers the removal of WooCommerce data, and `WC_REMOVE_ACTION_SCHEDULER` additionally drops the Action Scheduler tables.


---

## Useful core functions

*Source: code-snippets/useful-functions.md*

# Useful core functions

WooCommerce core functions are available on both front-end and admin. They can be found in `includes/wc-core-functions.php` and can be used by themes in plugins.

## Conditional Functions

WooCommerce conditional functions help determine the current query/page.

### is_woocommerce

Returns true if on a page which uses WooCommerce templates (cart and checkout are standard pages with shortcodes and thus are not included).

```php
is_woocommerce()
```

### is_shop

Returns true when viewing the product type archive (shop).

```php
is_shop()
```

### is_product

Returns true when viewing a single product.

```php
is_product()
```

## Coupon Functions

### wc_get_coupon_code_by_id

Get coupon code by coupon ID.

```php
wc_get_coupon_code_by_id( $id )
```

The argument `$id` is the coupon ID.

### wc_get_coupon_id_by_code

Gets the coupon ID by code.

```php
wc_get_coupon_id_by_code( $code, $exclude = 0 )
```

`$code` is the coupon code and `$exclude` is to exclude an ID from the check if you're checking existence.

## User Functions

### wc_customer_bought_product

Checks if a customer has bought an item. The check can be done by email or user ID or both.

```php
wc_customer_bought_product( $customer_email, $user_id, $product_id )
```

### wc_get_customer_total_spent

Gets the total spent for a customer.

```php
wc_get_customer_total_spent( $user_id )
```

`$user_id` is the user ID of the customer.

### wc_get_customer_order_count

Gets the total orders for a customer.

```php
wc_get_customer_order_count( $user_id )
```

`$user_id` is the user ID of the customer.

## Formatting Functions

### wc_get_dimension

Takes a measurement `$dimension` measured in WooCommerce's dimension unit and converts it to the target unit `$to_unit`.

```php
wc_get_dimension( $dimension, $to_unit, $from_unit = '' )
```

Example usages:

```php
wc_get_dimension( 55, 'in' );
wc_get_dimension( 55, 'in', 'm' );
```

### wc_get_weight

Takes a weight `$weight` weighed in WooCommerce's weight unit and converts it to the target weight unit `$to_unit`.

```php
wc_get_weight( $weight, $to_unit, $from_unit = '' )
```

Example usages:

```php
wc_get_weight( 55, 'kg' );
wc_get_weight( 55, 'kg', 'lbs' );
```

### wc_clean

Clean variables using `sanitize_text_field`. Arrays are cleaned recursively. Non-scalar values are ignored.

```php
wc_clean( $var )
```

### wc_price

Formats a passed price with the correct number of decimals and currency symbol.

```php
wc_price( $price, $args = array() )
```

The ` $args` array has an option called ` ex_tax_label` - if true then an `excluding tax` message will be appended.

## Order Functions

### wc_get_orders

This function is the standard way of retrieving orders based on certain parameters. This function should be used for order retrieval so that when we move to custom tables, functions still work.

```php
wc_get_orders( $args )
```

[Arguments and usage](/docs/features/orders/wc-get-orders/)

### wc_get_order

This is the main function for returning orders, uses the `WC_Order_Factory` class.

```php
wc_get_order( $the_order = false )
```

The `the_order` parameter can be a post object or post ID of the order.

### wc_orders_count

Returns the orders count of a specific order status.

```php
wc_orders_count( $status, string $type = '' )
```

### wc_order_search

Searches orders based on the given `$term`.

```php
wc_order_search( $term )
```

## Page Functions

### wc_get_page_id

Gets a WooCommerce page ID by name, e.g. thankyou

```php
wc_get_page_id( $page )
```

### wc_get_endpoint_url

Gets the URL for an `$endpoint`, which varies depending on permalink settings.

```php
wc_get_endpoint_url( $endpoint, $value = '', $permalink = '' )
```

## Product Functions

### wc_get_products

This function is the standard way of retrieving products based on certain parameters.

```php
wc_get_products( $args )
```

[Arguments and usage](/docs/features/products/wc-get-products/)

### wc_get_product

This is the main function for returning products. It uses the `WC_Product_Factory` class.

```php
wc_get_product( $the_product = false )
```

The argument `$the_product` can be a post object or post ID of the product.

### wc_get_product_ids_on_sale

Returns an array containing the IDs of the products that are on sale.

```php
wc_get_product_ids_on_sale()
```

### wc_get_featured_product_ids

Returns an array containing the IDs of the featured products.

```php
wc_get_featured_product_ids()
```

### wc_get_related_products

Gets the related products for product based on product category and tags.

```php
wc_get_related_products( $product_id, $limit = 5, $exclude_ids = array() )
```

## Account Functions

### wc_get_account_endpoint_url

Gets the account endpoint URL.

```php
wc_get_account_endpoint_url( $endpoint )
```

## Attribute Functions

### wc_get_attribute_taxonomies

Gets the taxonomies of product attributes.

```php
wc_get_attribute_taxonomies()
```

### wc_attribute_taxonomy_name

Gets the taxonomy name for a given product attribute.

```php
wc_attribute_taxonomy_name( $attribute_name )
```

### wc_attribute_taxonomy_id_by_name

Gets a product attribute ID by name.

```php
wc_attribute_taxonomy_id_by_name( $name )
```

## REST Functions

### wc_rest_prepare_date_response

Parses and formats a date for ISO8601/RFC3339.

```php
wc_rest_prepare_date_response( $date, $utc = true )
```

Pass `$utc` as `false` to get local/offset time.

### wc_rest_upload_image_from_url

Uploads an image from a given URL.

```php
wc_rest_upload_image_from_url( $image_url )
```

### wc_rest_urlencode_rfc3986

Encodes a `$value` according to RFC 3986.

```php
wc_rest_urlencode_rfc3986( $value )
```

### wc_rest_check_post_permissions

Checks permissions of posts on REST API.

```php
wc_rest_check_post_permissions( $post_type, $context = 'read', $object_id = 0 )
```

The available values for `$context` which is the request context are `read`, `create`, `edit`, `delete` and `batch`.


---

## Using NGINX server to protect your upload directory

*Source: code-snippets/using_nginx_server_to_protect_your_uploads_directory.md*

# Using NGINX server to protect your upload directory

If you using NGINX server for your site along with **X-Accel-Redirect/X-Sendfile** or **Force Downloads** download method, it is necessary that you add this configuration for better security:

```php
# Protect WooCommerce upload folder from being accessed directly.
# You may want to change this config if you are using "X-Accel-Redirect/X-Sendfile" or "Force Downloads" method for downloadable products.
# Place this config towards the end of "server" block in NGINX configuration.
location ~* /wp-content/uploads/woocommerce_uploads/ {
    if ( $upstream_http_x_accel_redirect = "" ) {
        return 403;
    }
    internal;
}
```

And this the configuration in case you are using **Redirect only** download method:

```php
# Protect WooCommerce upload folder from being accessed directly.
# You may want to change this config if you are using "Redirect Only" method for downloadable products.
# Place this config towards the end of "server" block in NGINX configuration.
location ~* /wp-content/uploads/woocommerce_uploads/ {
    autoindex off;
}
```

If you do not know which web server you are using, please reach out to your host along with a link to this support page.


---

## CSS SASS coding guidelines and naming conventions

*Source: contribution/contributing/CSS-SASS-coding-guidelines-and-naming-conventions.md*

# CSS SASS coding guidelines and naming conventions

Our guidelines are based on those used in [Calypso](https://github.com/Automattic/wp-calypso) which itself follows the BEM methodology. Refer to [this doc](https://wpcalypso.wordpress.com/devdocs/docs/coding-guidelines/css.md?term=css) for full details. There are a few differences in WooCommerce however which are outlined below;

## Prefixing

As a WordPress plugin WooCommerce has to play nicely with WordPress core and other plugins / themes. To minimise conflict potential all classes should be prefixed with `.woocommerce-`.

## Class names

Calypso is built in React and uses component names to formulate CSS class names. WooCommerce Core has none of these components so uses a more traditional [BEM](http://getbem.com/) approach to [naming classes](http://cssguidelin.es/#bem-like-naming). 

When adding classes just remember;

* **Block** - Standalone entity that is meaningful on its own.
* **Element** - Parts of a block and have no standalone meaning. They are semantically tied to its block.
* **Modifier** - Flags on blocks or elements. Use them to change appearance or behaviour.

### Example

* `.woocommerce-loop {}` (block).
* `.woocommerce-loop-product {}` (nested block).
* `.woocommerce-loop-product--sale {}` (modifier).
* `.woocommerce-loop-product__link {}` (element).
* `.woocommerce-loop-product__title {}` (element).
* `.woocommerce-loop-product__price {}` (element).
* `.woocommerce-loop-product__rating {}` (element).
* `.woocommerce-loop-product__button-add-to-cart {}` (element).
* `.woocommerce-loop-product__button-add-to-cart--added {}` (modifier).

**Note:** `.woocommerce-loop-product` is not the chosen classname _because_ the block is nested within `.woocommerce-loop`. It's to be specific so that we can have separate classes for single products, cart products etc. _Nested blocks do not need to inherit their parents full name_.

You can read more about BEM key concepts [in the BEM methodology documentation](https://en.bem.info/methodology/key-concepts/).

#### TL;DR

* Follow the [WP Coding standards for CSS](https://make.wordpress.org/core/handbook/best-practices/coding-standards/css/) unless it contradicts anything here.
* Follow [Calypso guidelines](https://wpcalypso.wordpress.com/devdocs/docs/coding-guidelines/css.md?term=css).
* Use BEM for [class names](https://en.bem.info/methodology/naming-convention/).
* Prefix all the things.


---

## Contribute to Woo

*Source: contribution/contributing/README.md*

# Contribute to Woo

Interested in joining the Woo contributor community? The links in this doc summarize and direct you to the order of operations you will need to make your first contribution. If you are a seasoned WooCommerce developer, feel free to skip ahead and utilize the template links, or the reference docs and guides below.

## Contributing to WooCommerce Core

The WooCommerce core plugin code can be found in our [monorepo](https://github.com/woocommerce/woocommerce). Here you can contribute to: 

- [WooCommerce Core Plugin](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce)
- [WooCommerce Blocks](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks) 

## Setting up your development environment

Please check out [our getting started guide](https://github.com/woocommerce/woocommerce#getting-started) for information about prerequisites and initial setup.

We also have [more in-depth documentation](https://github.com/woocommerce/woocommerce/blob/trunk/DEVELOPMENT.md) on how to develop in our repository. This also includes information about how to set up the development environment.

## Code of Conduct

Contributing to an open source project requires cooperation amongst individuals and organizations all working to make our project a stable and safe place to build and ask questions. Please thoroughly read our [Code of Conduct](https://github.com/woocommerce/woocommerce/blob/trunk/CODE_OF_CONDUCT.md) to get familiar with our standards and processes.

## Contributor Guidelines

Our [contributor guidelines](https://github.com/woocommerce/woocommerce/blob/trunk/.github/CONTRIBUTING.md) layout the first steps to contributing.

- [Prerequisites and developer tools to get started](https://github.com/woocommerce/woocommerce/blob/trunk/README.md#getting-started)
- [PNPM commands, plugin development environment packages, and troubleshooting](https://github.com/woocommerce/woocommerce/blob/trunk/DEVELOPMENT.md)
- [Coding standards, E2E testing links](https://github.com/woocommerce/woocommerce/blob/trunk/.github/CONTRIBUTING.md) 
- [Community contributions](/docs/contribution/contributing/community-contributions/)
- [WordPress and WooCommerce version support policy](/docs/contribution/contributing/version-support-policy/)

## Templates, Bug Reports, and Feature Requests

- [Pull Request template](https://github.com/woocommerce/woocommerce/blob/trunk/.github/PULL_REQUEST_TEMPLATE.md)
- [Core Issue template](https://github.com/woocommerce/woocommerce/blob/trunk/.github/ISSUE_TEMPLATE.md)
- [Bug Report template](https://github.com/woocommerce/woocommerce/blob/trunk/.github/ISSUE_TEMPLATE/1-bug-report.yml)
- [Enhancement template](https://github.com/woocommerce/woocommerce/blob/trunk/.github/ISSUE_TEMPLATE/2-enhancement.yml)
- [Feature requests](https://woocommerce.com/feature-requests/woocommerce/)

## Security

Security and safety for data management are incredibly important to us at Woo. Please check out the [Automattic security policy](https://automattic.com/security/) to learn about our foundational requirements.

Please report any vulnerabilities or security issues by reading through Woo's [security policy](https://github.com/woocommerce/woocommerce/blob/trunk/SECURITY.md).


---

## Common issues

*Source: contribution/contributing/common-issues.md*

# Common issues

This page aims to document a comprehensive list of known issues, commonly encountered problems, and their solutions or workarounds. If you have encountered an issue that is not mentioned here and should be, please don't hesitate to add to the list.

## Composer error on `Automattic\Jetpack\Autoloader\AutoloadGenerator`

```bash
[ErrorException]
  Declaration of Automattic\Jetpack\Autoloader\AutoloadGenerator::dump(Composer\Config $config, Composer\Repository\Inst
  alledRepositoryInterface $localRepo, Composer\Package\PackageInterface $mainPackage, Composer\Installer\InstallationMa
  nager $installationManager, $targetDir, $scanPsrPackages = false, $suffix = NULL) should be compatible with Composer\A
  utoload\AutoloadGenerator::dump(Composer\Config $config, Composer\Repository\InstalledRepositoryInterface $localRepo,
  Composer\Package\RootPackageInterface $rootPackage, Composer\Installer\InstallationManager $installationManager, $targ
  etDir, $scanPsrPackages = false, $suffix = '')
```

A recent [change](https://github.com/composer/composer/commit/b574f10d9d68acfeb8e36cad0b0b25a090140a3b#diff-67d1dfefa9c7b1c7e0b04b07274628d812f82cd82fae635c0aeba643c02e8cd8) in composer 2.0.7 made our autoloader incompatible with the new `AutoloadGenerator` signature. Try to downgrading to composer 2.0.6 by using `composer self-update 2.0.6`.

## VVV: HostsUpdater vagrant plugin error

```bash
...vagrant-hostsupdater/HostsUpdater.rb:126:in ``digest': no implicit conversion of nil into String (TypeError)
```

You might be running an unsupported version of Vagrant. At the time of writing, VVV works with Vagrant 2.2.7. Please check VVV's [requirements](https://github.com/Varying-Vagrant-Vagrants/VVV#minimum-system-requirements).

## VVV: `install-wp-tests.sh` error

```bash
mysqladmin: CREATE DATABASE failed; error: 'Access denied for user 'wp'@'localhost' to database 'wordpress-one-tests''
```

To fix:

-   Open MySQL with `sudo mysql`.
-   Run `GRANT ALL PRIVILEGES ON * . * TO 'wp'@'localhost';`. Exit by typing `exit;`.
-   Run the `install-wp-tests.sh` script again.

## Timeout / 404 errors while running e2e tests

```bash
 Store owner can complete onboarding wizard › can complete the product types section

    TimeoutError: waiting for function failed: timeout 30000ms exceeded

      1 | export const waitForElementCount = function ( page, domSelector, count ) {
    > 2 | 	return page.waitForFunction(
        | 	            ^
      3 | 		( domSelector, count ) => {
      4 | 			return document.querySelectorAll( domSelector ).length === count;
      5 | 		},
```

Timeouts or 404 errors in the e2e tests signal that the existing build might be broken. Run `npm install && npm run clean && npm run build` to generate a fresh build. It should also be noted that some of our npm scripts also remove the current build, so it's a good practice to always run a build before running e2e tests.

## Docker container couldn't be built when attempting e2e test

```bash
Thu Dec  3 11:55:56 +08 2020 - Docker container is still being built
Thu Dec  3 11:56:06 +08 2020 - Docker container is still being built
Thu Dec  3 11:56:16 +08 2020 - Docker container is still being built
Thu Dec  3 11:56:26 +08 2020 - Docker container couldn't be built
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! @woocommerce/e2e-environment@0.1.6 test:e2e: `bash ./bin/wait-for-build.sh && ./bin/e2e-test-integration.js`
npm ERR! Exit status 1
```

Ensure that Docker is running. While the script says `Docker container is still being built`, it is not actually responsible for running Docker; it's just waiting for an existing docker instance to respond. Run `npm run docker:up` if it's not.

## Set up WooCommerce Payments dev mode

Add this to `wp-config.php`:

```php
define( 'WCPAY_DEV_MODE', true );
```

Also see [this document](https://woocommerce.com/document/woopayments/testing-and-troubleshooting/test-accounts/).

## WooCommerce Admin install timestamp

To get the install timestamp (used in `wc_admin_active_for()` in `NoteTraits` for example) try this SQL:

```sql
SELECT * FROM wp_options WHERE option_name = 'woocommerce_admin_install_timestamp'
```

## Reset the onboarding wizard

Delete the `woocommerce_onboarding_profile` option:

```sql
DELETE FROM wp_options WHERE option_name = 'woocommerce_onboarding_profile'
```

## Enable tracks debugging in the console

```javascript
localStorage.setItem( 'debug', 'wc-admin:tracks' );
```

and set Chrome's log level "verbose" to checked.

## Running PHP unit tests using Vagrant (VVV)

1. SSH into Vagrant box (`vagrant ssh`)
2. `cd /srv/www/<WP_INSTANCE>/public_html/wp-content/plugins/woocommerce-admin`
3. Set up: `bin/install-wp-tests.sh wc-admin-tests root root`
4. Fast tests: `./vendor/bin/phpunit --group fast`
5. All tests: `./vendor/bin/phpunit`

You might need to `composer install` if `phpunit` doesn't exist.


---

## Community contributions

*Source: contribution/contributing/community-contributions.md*

# Community contributions

WooCommerce is open-source software that welcomes community contributions. To help us review your contribution quickly, please follow these guidelines.

## Before you submit

1. **Link to a related issue** - If one exists, reference it in your PR. Before starting work, comment on the issue (particularly when it already has an assignee) to avoid duplicate effort and check that it's been triaged by the maintainers. If you're proposing a new feature or significant change, [open an issue](https://github.com/woocommerce/woocommerce/issues/new/choose) first to discuss it.

2. **Run tests locally** - Some of the CI workflows are not automatically triggered for community contributions, so please verify your changes pass relevant tests and linting locally before submitting.

3. **Consolidate related changes** - If you have multiple similar fixes (e.g., typos, documentation updates), combine them into a single PR when appropriate.

## PR requirements

When you open a PR, you'll receive an immediate review from our AI code reviewer. Before a maintainer reviews your PR, please:

1. **Fill out the entire PR template** - Include a clear description of your changes and test steps.
2. **Respond to all AI review feedback** - Review automated feedback and either address it, or explain why it does not apply.
3. **Confirm tests pass** - Note in your PR that you've run the test suite locally.

## AI-assisted contributions

We welcome AI-assisted contributions, but the same quality standards apply whether code is written by hand or with AI tools. As the contributor, you are responsible for:

- Understanding the code you submit
- Verifying the changes work as intended
- Following all contribution guidelines

## What happens next

After you submit a PR that meets these requirements:

1. A maintainer will triage your PR
2. You may receive additional feedback or change requests
3. Once approved by a maintainer (see [review requirements](/docs/contribution/contributing/deciding-pr-high-impact#review-requirements)), your PR will be merged into an upcoming release

If your PR needs changes, we'll add a `needs: author feedback` label. Please respond to feedback promptly to keep your contribution moving forward, as stale PRs with that label are automatically closed after a period of time.

## Getting help

- [WooCommerce Community Slack](https://woocommerce.com/community-slack/)
- [Developer Documentation](https://developer.woocommerce.com/docs/)
- [Open an Issue](https://github.com/woocommerce/woocommerce/issues/new/choose)


---

## How to assess the impact of a pull request

*Source: contribution/contributing/deciding-pr-high-impact.md*

# How to assess the impact of a pull request

Deciding if a Pull Request should be declared High-Impact is a complex task. To achieve it, we need to assess and estimate the impact that the changes introduced in the Pull Request have in WooCommerce, which is usually a subjective task and sometimes inaccurate, due to the huge knowledge it demands of the WooCommerce product details, technical details and even customers issues history.

On this page, we will share some guidelines to help you assess the impact degree of a Pull Request.

## You should mark a Pull Request as High-Impact if

- It adds a **new feature** to WooCommerce, except if it's behind a feature flag.
- Modifies **critical functionality** that shoppers or merchants rely on to run a store.
- It fixes a **high-priority bug** (this includes Blocks fix releases core version bumps).
- It contains a **security fix**.
- Changes affecting **privacy** (how personal or store data is collected, stored, or shared).
- Updates **SQL queries**.
- Touches any of the **$_REQUEST** family of variables.
- Any kind of **data migration/update**, or other changes affecting **data integrity**.
- Changes affecting **backward compatibility** (public APIs, hook signatures or timing, templates, or anything third-party code consumes).
- Changes to **performance-sensitive paths**.
- Changes to **emails** sent from WooCommerce.
- Changes to WooCommerce **hooks/actions/filters**.
- Changes to **REST API endpoints**.
- It's a **big PR** (i.e. adds several changes in many files).
- It has **i18n changes** (for example, any file from `woocommerce/i18n` is modified).

## You should not mark a Pull Request as High-Impact if

- It only updates automated tests, things related to infrastructure not included in the WooCommerce release package, or other projects in the monorepo not included in the release package.
- It only contains readme or changelog changes.
- Fixes a low-priority bug such as a typo etc.
- Doesn't need to be verified in multiple environment types.
- Regular scheduled (not a fix release) core version bumps for the Blocks package (as testing will already be scheduled).
- It's part of a feature that hasn't been released as a whole yet (i.e. it's behind a feature flag currently in progress).

## My PR is High-Impact. What's next?

If your PR is High-Impact, be sure to label it with `impact: high` and the WooCommerce Core team will keep special considerations for testing it.

## Review requirements

Pull requests against `trunk` require an approving review before merge. That is the default for every change, because an independent reviewer brings experience, product knowledge, and assumptions that the author does not have. AI tooling working from the author's context does not add that independence.

The impact assessment above is also the reference for when that requirement can be relaxed and when it must not be.

### When a PR may be merged without a formal approval

Contributors with permission to bypass the review requirement may use their judgment to merge a PR without a formal approval when it clearly fits the "should not mark as High-Impact" list above: documentation, changelog, or typo changes; updates to automated tests; and tooling or infrastructure changes not shipped in the release package.

Bypassing the requirement is an exception for low-risk changes, not an alternative default. If you are unsure whether your change qualifies, request a review from a human.

### When an independent human review is always required

A PR matching anything in the High-Impact list above must receive an independent human review before merge, no matter who (or what) authored it.

Two things do not count as an independent human review:

- **The author's own review of AI-generated code.** The author drives the agent, provides its context, and shapes its solution. The author and the agent are a single workflow, not two reviewers. A single workflow can produce a convincing implementation of the wrong approach and not notice.
- **An AI review, automated or requested by anyone.** AI reviews are encouraged as an additional safety net, but they complement an independent human review rather than replace it.

[Community PRs](/docs/contribution/contributing/community-contributions) always require a review and should only be merged with approval from a human.


---

## Deprecation in core

*Source: contribution/contributing/deprecation-in-core.md*

# Deprecation in core

Deprecation is a method of discouraging usage of a feature or practice in favour of something else without breaking backwards compatibility or totally prohibiting its usage. To quote the Wikipedia article on Deprecation:

> While a deprecated software feature remains in the software, its use may raise warning messages recommending alternative practices; deprecated status may also indicate the feature will be removed in the future. Features are deprecated rather than immediately removed, to provide backward compatibility and give programmers time to bring affected code into compliance with the new standard.

There are various reasons why a function, method, or feature may be deprecated. To name a few:

- We may want to remove a function we do not use any longer.
- We may decide to change or improve how a function works, but due to breaking backwards compatibility we need to deprecate the old function instead.
- We may want to standardise naming conventions.
- We may find opportunities to merge similar functions to avoid reusing the same code in difference places.

Whilst deprecation notices are not ideal or attractive, they are just _warnings_ - not errors. 

_*Store owners:* deprecation warnings do not mean your store is broken, it just serves as a reminder that code will need to be updated._

## How do we deprecate functions?

When we deprecate something in WooCommerce, we take a few actions to make it clear to developers and to maintain backwards compatibility.

1. We add a docblock to the function or method showing what version the function was deprecated in, e.g., `@deprecated 2.x.x`.
2. We add a warning notice using our own `wc_deprecated_function` function that shows what version, what function, and what replacement is available. More on that in a bit.
3. We remove usage of the deprecated function throughout the codebase.

The function or method itself is not removed from the codebase. This preserves backwards compatibility until removed - usually over a year or several major releases into the future.

We mentioned `wc_deprecated_function` above - this is our own wrapper for the `_deprecated_function` WordPress function. It works very similar except for that it forces a log entry instead of displaying it - regardless of the value of `WP_DEBUG` during AJAX events - so that AJAX requests are not broken by the notice.

## What happens when a deprecated function is called?

If an extension or theme uses a deprecated function, you may see a warning like the following example:

```bash
Notice: woocommerce_show_messages is deprecated since version 2.1! Use wc_print_notices instead. in /srv/www/wordpress-default/wp-includes/functions.php on line 3783
```

This tells you what is deprecated, since when, where, and what replacement is available.

Notices and warnings are usually shown inline, but there are some plugins you can use to collect and show them nicely in the footer of your site. Consider, for example, [Query Monitor](https://wordpress.org/plugins/query-monitor/).

### Warnings in production (store owners - read this!)

Showing PHP notices and warnings (or any error for that matter) is highly discouraged on your production stores. They can reveal information about your setup that a malicious user could exploit to gain access to your store. Make sure they are hidden from public view and optionally logged instead.

In WordPress you can do this by adding or modifying some constants in `wp-config.php`:

```php
define( 'WP_DEBUG', false );
```

On some hosts, errors may still be visible due to the hosts configuration. To force them to not display you might need to add this to `wp-config.php` as well:

```php
@ini_set( 'display_errors', 0 );
```

To log notices instead of displaying them, use:

```php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
```

The default location of the WordPress error log is `wp-content/debug.log`.

Note that this log can be publicly accessible, which could also pose a security risk. To keep it private, you can use a plugin or define a custom path in `wp-config.php`.

```php
<?php
/**
 * Plugin Name: Custom Debug Log Path
 */

ini_set( 'error_log', '/path/to/site/logs/debug.log' );
```


---

## Handling SCSS and JS minification in WooCommerce

*Source: contribution/contributing/minification-of-SCSS-and-JS.md*

# Handling SCSS and JS minification in WooCommerce

## SCSS

When updating SCSS files in the WooCommerce project, please **commit only your changes to unminified SCSS files**. The minification will be handled as part of the release process.

To get the minified CSS files, run `pnpm --filter='@woocommerce/classic-assets' build` from the repository root directory. To set up the development environment from scratch, see the section on [how to install dependencies and generate assets](https://github.com/woocommerce/woocommerce/blob/trunk/DEVELOPMENT.md) in the guide to set up a WooCommerce development environment.

## Javascript

When changing the JS files, please **commit only unminified files** (i.e. the readable JS files). The minification will be handled as part of the release process.

To ensure you can test your changes, run with `SCRIPT_DEBUG` turned on, i.e. add `define( 'SCRIPT_DEBUG', true );` to your wp-config.php file.


---

## Naming conventions

*Source: contribution/contributing/naming-conventions.md*

# Naming conventions

## PHP

WooCommerce core generally follows [WordPress PHP naming conventions](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#naming-conventions). On top of that, function, class, and hook names should be prefixed. For functions the prefix is `wc_`, for classes is `WC_` and for hooks is `woocommerce_`.

Function name examples:

- `wc_get_product()`
- `wc_is_active_theme()`

Class name examples:

- `WC_Breadcrumb`
- `WC_Cart`

Hook name examples (actions or filters):

- `woocommerce_after_checkout_validation`
- `woocommerce_get_formatted_order_total`

There are however some exceptions which apply to classes defined inside `src/`. Within this directory:

- We do not use the `WC_` prefix for class names (the prefix is not needed, because all of the classes in this location live within the `Automattic\WooCommerce` namespace)
- Classes are named using the `CamelCase` convention (however, method names should still be `underscore_separated`)
- Class files should match the class name and do not need the `class-` prefix (for example, the filename for the `StringUtil` class is `StringUtil.php`)

## JS

WooCommerce core follows [WordPress JS naming conventions](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/#naming-conventions). As with PHP, function, class, and hook names should be prefixed, but the convention for JS is slightly different, and camelCase is used instead of snake_case. For functions, the prefix is `wc`, for classes is `WC` and for hooks is `woocommerce`.

Function name example:

- `wcSettings()`

Class name example:

- `WCOrdersTable`

Hook name example (actions or filters):

- `woocommerceTracksEventProperties`

## CSS and SASS

See [CSS SASS coding guidelines and naming conventions](/docs/contribution/contributing/CSS-SASS-coding-guidelines-and-naming-conventions/).


---

## Reporting security issues

*Source: contribution/contributing/reporting-security-issues.md*

# Reporting security issues

WooCommerce cares deeply about security and works hard to keep our merchants and their customers safe. 

You can find our security policy [over here](https://github.com/woocommerce/woocommerce/security/policy) and, if you believe you have discovered a vulnerability, we encourage you to follow it and submit your findings via [HackerOne](https://hackerone.com/automattic?type=team)-a trusted third party service that facilitates reporting of security issues. Please refer to the policy for more details, however some key points are as follows:

- We operate a [bug bounty program](https://hackerone.com/automattic?type=team), so you can be rewarded for valid reports, but not everything is in scope. Please check the guidance before posting.
- We strongly encourage [responsible disclosure](https://www.hackerone.com/disclosure-guidelines). To better protect everyone, please use HackerOne and **do not** post your findings in a public forum.

Thank you for being a responsible reporter!


---

## String localization

*Source: contribution/contributing/string-localisation-guidelines.md*

# String localization

WooCommerce is translation-ready out of the box. This page covers how to write localizable strings, contribute translations, create custom translations, and update locale-specific data such as countries and subdivisions.

## Translating WooCommerce

WooCommerce is already translated into several languages and only needs a translation file for your language. In most cases, you can contribute translations on [translate.wordpress.org](https://translate.wordpress.org/projects/wp-plugins/woocommerce/).

To create custom translations, you can also use a tool such as [Poedit](https://poedit.net/).

### Set up WordPress in your language

To set your WordPress site's language:

1. Go to `WP Admin > Settings > General` and adjust the `Site Language`.
2. Go to `WP Admin > Dashboard > Updates` and click the `Update Translations` button.

Once this has been done, the shop displays in your locale if the language file exists. Otherwise, you need to create the language files.

### Writing localizable strings

1. Use the `woocommerce` textdomain in all strings.
2. When using dynamic strings in `printf()` or `sprintf()`, use numbered arguments if you are replacing more than one string. For example, `Test %s string %s.` should be `Test %1$s string %2$s.`
3. Use sentence case. For example, `Some Thing` should be `Some thing`.
4. Avoid HTML. If needed, insert the HTML using `sprintf()`.

For more information, see the WordPress core documentation for [i18n for WordPress Developers](https://codex.wordpress.org/I18n_for_WordPress_Developers).

### Contribute translations to core

We encourage contributions to our translations. If you want to add translated strings or start a new translation, register at WordPress.org and submit your translations to [translate.wordpress.org](https://translate.wordpress.org/projects/wp-plugins/woocommerce/) for approval.

Both stable and development versions of WooCommerce are available for translation. When you install or update WooCommerce, WordPress will automatically fetch a 100% complete translation for your language. If such a translation isn't available, you can download it manually or contribute to complete the translation, benefiting all users.

If you're new to translating, check out the [Translators Handbook](https://make.wordpress.org/polyglots/handbook/tools/glotpress-translate-wordpress-org/) to get started.

### Download translations manually

1. Go to [translate.wordpress.org](https://translate.wordpress.org/projects/wp-plugins/woocommerce) and look for your language in the list.
2. Click the title to be taken to the section for that language.

    ![Screenshot of WooCommerce translation page on WordPress.org](https://developer.woocommerce.com/wp-content/uploads/2023/12/2016-02-17-at-09.57.png)

3. Click the heading under `Set/Sub Project` to view and download a Stable version.

    ![List of versions available for selected language](https://developer.woocommerce.com/wp-content/uploads/2023/12/2016-02-17-at-09.59.png)

4. Scroll to the bottom for export options. Export a `.mo` file for use on your site.
5. Rename this file to `woocommerce-YOURLANG.mo`. For example, Great Britain English should be `woocommerce-en_GB.mo`. The corresponding language code can be found by opening the desired language on [translate.wordpress.org](https://translate.wordpress.org/projects/wp-plugins/woocommerce/). The language code is visible in the upper-right corner.

    ![Screenshot of plugin card with associated language code](https://developer.woocommerce.com/wp-content/uploads/2023/12/Screenshot-2023-10-17-at-09.44.53.png)

6. Upload the file to your site under `wp-content/languages/woocommerce/`. Once uploaded, this translation file may be used.

## Creating custom translations

WooCommerce includes a language file (`.pot` file) that contains all of the English text. You can find this language file inside the plugin folder in `woocommerce/i18n/languages/`.

### Create custom translations with Poedit

WooCommerce comes with a `.pot` file that can be imported into Poedit to translate.

To get started:

1. Open Poedit and select `Create new translation from POT template`.
2. Choose `woocommerce.pot` and Poedit will show the catalog properties window.

    ![Poedit catalog properties window](https://developer.woocommerce.com/wp-content/uploads/2023/12/Screen-Shot-2013-05-09-at-10.16.46.png)

3. Enter your name and details, so other translators know who you are, and click `OK`.
4. Save your `.po` file. Name it based on what you are translating to, such as `woocommerce-en_GB.po` for a Great Britain English translation. Now the strings are listed.

    ![Poedit strings list](https://developer.woocommerce.com/wp-content/uploads/2023/12/Screen-Shot-2013-05-09-at-10.20.58.png)

5. Save after translating strings. The `.mo` file is generated automatically.
6. Update your `.po` file by opening it and then going to `Catalog > Update from POT file`.
7. Choose the file and it will be updated accordingly.

### Make custom translations upgrade safe

WooCommerce keeps translations in `wp-content/languages/plugins`, like all other plugins. If you wish to include a custom translation, you can use the directory `wp-content/languages/woocommerce`, or you can use a snippet to load a custom translation stored elsewhere:

```php
// Code to be placed in functions.php of your theme or a custom plugin file.
add_filter( 'load_textdomain_mofile', 'load_custom_plugin_translation_file', 10, 2 );

/**
 * Replace 'textdomain' with your plugin's textdomain. e.g. 'woocommerce'.
 * File to be named, for example, yourtranslationfile-en_GB.mo
 * File to be placed, for example, wp-content/languages/textdomain/yourtranslationfile-en_GB.mo
 */
function load_custom_plugin_translation_file( $mofile, $domain ) {
    if ( 'textdomain' === $domain ) {
        $mofile = WP_LANG_DIR . '/textdomain/yourtranslationfile-' . get_locale() . '.mo';
    }

    return $mofile;
}
```

## Translation tools

Some third-party tools can help with translations:

- [Loco Translate](https://wordpress.org/plugins/loco-translate/) provides in-browser editing of WordPress translation files and integration with automatic translation services.
- [Say what?](https://wordpress.org/plugins/say-what/) allows you to translate or modify specific words without editing a WordPress theme's `.po` file.
- [String Locator](https://wordpress.org/plugins/string-locator/) enables quick searches within themes, plugins, or WordPress core, displaying a list of files with the matching text and its line number.

## FAQ

### Why are some Checkout page strings not being translated?

You may see that some Checkout page strings are not translated. For example, the `Local pickup` shipping method, `Cash on delivery` payment method, or a Privacy Policy message may remain in English while the rest of the form is translated:

![Checkout page with some strings not translated](https://developer.woocommerce.com/wp-content/uploads/2023/12/not_translated.jpg)

This usually happens when you first install WooCommerce with the default site language, English, and later change the site language to another one. In WooCommerce, the strings that have not been translated in the screenshot are stored in the database after the initial WooCommerce installation. Therefore, if the site language is changed to another one, there is no way for WooCommerce to detect a translatable string since these are database entries.

To fix it, navigate to the WooCommerce settings corresponding to the string you need to change and update the translation there directly.

For `Local pickup`:

1. Go to `WooCommerce > Settings > Shipping > Shipping Zones`.
2. Select the shipping zone where "Local pickup" is listed.
3. Open "Local pickup" settings.
4. Rename the method using your translation.
5. Save the setting.

For `Cash on delivery`:

1. Go to `WooCommerce > Settings > Payments`.
2. Select the "Cash on delivery" payment method.
3. Open its settings.
4. Rename the method title, description, and instructions using your translation.
5. Save the setting.

For the privacy policy message:

1. Go to `WooCommerce > Settings > Accounts & Privacy`.
2. Scroll to the "Privacy policy" section.
3. Edit both the `Registration privacy policy` and `Checkout privacy policy` fields with your translation.
4. Save the settings.

Navigate back to the Checkout page. Translations should be reflected there.

### Why do some translated strings not show up on the front end?

If some of your translated strings don't show up as expected on your WooCommerce site, first check if these strings have both a single and plural form in the Source text section. To do so, open the corresponding translation on [translate.wordpress.org](https://translate.wordpress.org/projects/wp-plugins/woocommerce/), such as [the translation for Product and Products](https://translate.wordpress.org/projects/wp-plugins/woocommerce/stable/de/default/?filters%5Bstatus%5D=either&filters%5Boriginal_id%5D=577764&filters%5Btranslation_id%5D=24210880).

This screenshot shows that the singular translation is available:

![Screenshot showing that the singular translation is available](https://developer.woocommerce.com/wp-content/uploads/2023/12/Screenshot-2023-10-17-at-10.10.06.png)

This screenshot shows that the plural translation is not available:

![Screenshot showing that the plural translation is not available](https://developer.woocommerce.com/wp-content/uploads/2023/12/Screenshot-2023-10-17-at-10.10.21.png)

## Countries and subdivisions

WooCommerce comes complete with a comprehensive list of countries and subdivisions, such as provinces or states, that are used in various parts of the user interface.

Countries and their subdivisions periodically change. In these cases, you can file a [bug report](https://github.com/woocommerce/woocommerce/issues/new?template=1-bug-report.yml) or [submit a pull request](/docs/contribution/contributing). However, our policy is only to accept changes if they align with the current version of the [CLDR project](https://cldr.unicode.org/). It is generally best to review CLDR and, if necessary, propose a change there first before asking that it be adopted by WooCommerce.

This approach may not be suitable in all cases, because it can take time for CLDR to accept updates. In such cases, you can still modify the lists of countries and subdivisions by using custom snippets like the following:

- [Snippet to add a country](/docs/code-snippets/add-a-country)
- [Snippet to add or modify states](/docs/code-snippets/add-or-modify-states)

### Updating an existing country or subdivision code

Adding a new country or subdivision code is safe, and so is changing a display name, since names are just translatable strings. Renaming or removing an existing **code** is different: the old code may already be stored in customer orders, shipping zones, tax rates, and the store's default country setting, so it often needs a database migration too. For subdivision codes, use `MigrationHelper::migrate_country_states()` (`Automattic\WooCommerce\Database\Migrations\MigrationHelper`). There's an example in `wc_update_721_adjust_new_zealand_states()` (`wc-update-functions.php`). The helper only covers subdivision codes, so country or other changes might need a custom migration routine.


---

## WordPress and WooCommerce version support policy

*Source: contribution/contributing/version-support-policy.md*

# WordPress and WooCommerce version support policy

Woo uses a latest-minus-one (L-1) policy for WordPress and WooCommerce version
compatibility. This policy defines the versions that we officially test and
support as dependencies; it is separate from entitlement to customer support services.

L-1 includes:

- The current stable release series (latest).
- The stable release series immediately before it (latest minus one).

Within each release series, only the latest patch release is officially
supported. For example, if `6.8` and `6.7` are the two supported release
series, testing should use the latest available `6.8.x` and `6.7.x` releases.

## How the policy applies

| Project | Supported versions |
| --- | --- |
| WooCommerce Core | The latest and immediately previous WordPress release series. |
| Woo-owned extensions | The latest and immediately previous release series of both WordPress and WooCommerce. |

The policy for WooCommerce Core refers to the versions of WordPress on which
Core runs. Woo-owned extensions also depend on WooCommerce, so they apply L-1
to both WordPress and WooCommerce.

Third-party extension authors control their own version requirements. They can
adopt a wider compatibility window, but should test every version they claim
to support and publish accurate requirements.

## When the support window changes

When a new stable WordPress or WooCommerce release series becomes available:

1. The new release series becomes the latest supported version.
2. The former latest release series becomes the L-1 version.
3. The older release series moves outside the official support window.

Beta and release candidate versions do not move the support window. Older
versions might continue to work, but they are not part of the official test
matrix unless a project documents an exception.

## Plugin version metadata

Keep plugin headers and `readme.txt` metadata aligned with the support window:

- `Requires at least` identifies the earliest supported WordPress release
  series.
- `Tested up to` identifies the latest tested WordPress release series.
- `WC requires at least` identifies an extension's earliest supported
  WooCommerce release series.
- `WC tested up to` identifies an extension's latest tested WooCommerce
  release series.

For an extension following L-1, the two "requires at least" fields should
identify the immediately previous release series, while the two "tested up to"
fields should identify the current release series. See the
[example WordPress plugin header comment](/docs/extensions/core-concepts/example-header-plugin-comment/)
for header formatting.


---

## WooCommerce Git Flow

*Source: contribution/contributing/woocommerce-git-flow.md*

# WooCommerce Git Flow

## Conventions

### Branch Naming

While we don't enforce any naming conventions except for release branches (which always start with `release/`), prefixes help indicate the type of branch or change they refer to. Some common prefixes include `fix/`, `feature/`, `add/`, and `update/`.

In particular, when creating a **fix branch**, use the correct prefix and the issue number (e.g., `fix/12345`) or summarize the change (e.g., `fix/12345-shipping-tax-rate-saving`).

## Releases

For core development, we use the following structure and flow.

![Release Cycle flow chart](/img/doc_images/release-branches.png)

Refer to the [release schedule](/docs/contribution/releases/schedule) document for more details.


---

## Contributing technical documentation

*Source: contribution/contributing-docs/contributing-docs.md*

# Contributing technical documentation

Thanks for helping improve WooCommerce's developer documentation. Our docs are powered by Docusaurus, and live inside the [`woocommerce/docs/`](https://github.com/woocommerce/woocommerce/tree/trunk/docs) folder of the monorepo.

This guide walks you through the structure, tooling, and process for contributing effectively.

## Getting started 

> This guide presumes that you're familiar with basic Git and GitHub functionality, that you're signed into a GitHub account, and that you have Git setup locally. If you're new to GitHub, we recommend reading their [quickstart](https://docs.github.com/en/get-started/quickstart/hello-world) and [working with forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) guides before getting started.

### Initial setup

1. Fork the [WooCommerce monorepo](https://github.com/woocommerce/woocommerce) on GitHub. If asked, you can safely check the `copy the trunk branch only` option.
2. [Clone the fork that you just created](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository). This will allow you to edit it locally.

### Making changes

1. Prior to making any changes, ensure your `trunk` branch is up to date with the monorepo's `trunk` [by syncing it](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
2. For each modification you'd like to make, create a new branch off `trunk` in your fork that starts with `docs/`. For example, if you're adding a doc about improving extension performance, you could call your branch `docs/improve-extension-performance`.
3. Create or edit markdown files inside the appropriate folder under `docs/`.
4. If needed, update the folder's `_category_.json` (for sidebar label/position).
5. Run a build to verify changes, confirm that the sitemaps and llms-txt files are updated, and detect markdown linting errors and broken links (link checking only happens on build):

    ```bash
    npm run build
    ```

### Opening a pull request

1. Commit and push your changes to your fork.
2. [Open a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to woocommerce/woocommerce, targeting the trunk branch.
3. Use a descriptive title, and fill out the PR template. Include:
    * Rationale for new files or categories
    * A note about any sidebar or structure changes
4. The WooCommerce Developer Advocacy team will review and merge your changes.

## Docs folder anatomy

### Tooling and configuration

* **Supporting tooling and config** lives in:
    * [`woocommerce/docs/_docu-tools/`](https://github.com/woocommerce/woocommerce/blob/trunk/docs/_docu-tools/)
* **Top-level sidebar and navbar** are configured in:
    * [`sidebars.ts`](https://github.com/woocommerce/woocommerce/blob/trunk/docs/_docu-tools/sidebars.ts)
    * [`docusaurus.config.ts`](https://github.com/woocommerce/woocommerce/blob/trunk/docs/_docu-tools/docusaurus.config.ts)

### Documentation files

* **Docs location**: All documentation lives inside of [`woocommerce/docs/`](https://github.com/woocommerce/woocommerce/blob/trunk/docs/)
* **Each folder is sidebar or top nav category**, for example: `getting-started`, `code-snippets`, etc.
* **Sidebar configuration** for each category is managed using a `_category_.json` file inside each category folder:

    ```json
    {
        "position": 7,
        "label": "Code snippets"
    }
    ```

## Adding images

All documentation images are stored in:

```bash
docs/_docu-tools/static/img/doc_images/
```

To include an image in a markdown file, reference it like this:

```markdown
![Alt text](/img/doc_images/your-image-name.png)
```

## Creating New Categories

Before creating a new category, you should consider whether it is truly necessary to do so. Where possible, you should default to creating content in an existing category. If you do need to create a new category, follow these steps:

1. Inside the `/docs` folder, create a sub-folder with a descriptive name. For example, if you wanted to create a `Checkout design guidelines` section, you'd create a folder called `/docs/checkout-design-guidelines`.

2. Create a `_category_.json` file inside each category folder and give it a position it should have in the sidebar as well as a label:

    ```json
    {
        "position": 10,
        "label": "Checkout design guidelines"
    }
    ```

When creating new categories, please include rationale about why the category was created in your pull request's description.

## Writing guidelines and references

* Use short, URL-friendly file names (kebab-case, no spaces)
* Avoid pasting from rich text editors like Google Docs, which may introduce invalid characters
* Check our [docs style guide](style-guide) for detailed writing guidelines
* Reference the [Docusaurus documentation](https://docusaurus.io/docs) for additional guidance



---

## Technical Documentation Style Guide

*Source: contribution/contributing-docs/style-guide.md*

# Technical Documentation Style Guide

This style guide is intended to provide guidelines for creating effective and user-friendly tutorials and how-to guides for WooCommerce technical documentation that will live in repo and be editable and iterative by open source contributors and WooCommerce teams.

## Writing style

### Language style

- It's important to use clear and concise language that is easy to understand. Use active voice and avoid using jargon or technical terms that may be unfamiliar to the user. The tone should be friendly and approachable, and should encourage the user to take action.

- Articles are written in the 3rd-person voice.
  Example: "Add an embed block to your page."

- Use American English for spelling and punctuation styles, or consider using a different word that doesn't have a different spelling in other English variants.

- Use sentence case (not title case) for docs titles and subheadings.
  Example: "Introduction to the launch experience" rather than "Introduction to the Launch Experience."

- When referring to files or directories, the text formatting eliminates the need to include articles such as "the" and clarifying nouns such as "file" or "directory".
  Example: "files stored in ~~the~~ `/wp-content/uploads/` ~~directory~~" or "edit ~~the~~ `/config/config.yml` ~~file~~ with"

### Writing tips

- Our target audience has a range of roles and abilities. When creating a tutorial or how-to guide, it's important to consider the intended audience. Are they beginners or advanced users? What is their technical background? Understanding the audience can help guide the level of detail and the choice of language used in the guide.

- Use language understandable even by readers with little technical knowledge and readers whose first language might not be English.

- Consider that this might be the first WooCommerce documentation page the reader has seen. They may have arrived here via a Google search or another website. Give the reader enough context about the topic and link words and phrases to other relevant Docs articles as often as possible.

- Consider notes and sections that provide insights, tips, or cautionary information to expand on topics with context that would be relevant to the reader.

- When providing specific direction, best practices, or requirements, we recommend including a description of the potential consequences or impacts of not following the provided guidance. This can help seed additional search keywords into the document and provide better context when support links to the documentation.

- Always write a conceptual, high-level introduction to the topic first, above any H2 subheading.

### Tutorials

Tutorials are comprehensive and designed to teach a new skill or concept.

> You are the teacher, and you are responsible for what the student will do. Under your instruction, the student will execute a series of actions to achieve some end.
> 
> [Divio Framework on Tutorial Writing](https://documentation.divio.com/tutorials/)

### How-to guides

How-to guides are focused and specific, providing instructions on how to accomplish a particular task or solve a particular problem.

> How-to guides are wholly distinct from tutorials and must not be confused with them:
> 
> - A tutorial is what you decide a beginner needs to know.
> - A how-to guide is an answer to a question that only a user with some experience could even formulate.
> 
> [Divio Framework on How-to-Guide Writing](https://documentation.divio.com/how-to-guides/)

## Custom Linting Rules

At WooCommerce, we're dedicated to maintaining a consistent and high-quality standard for our technical documentation. Our documents primarily adhere to the linting rules provided by `markdownlint`. To assist our contributors, we've detailed our custom configurations and exceptions below.

Note: While we've outlined specific rules above, all other default linting rules from `markdownlint` apply unless otherwise stated. We've only highlighted custom configurations or exceptions here. For a complete list of `markdownlint` rules, you can refer to [this link](https://github.com/DavidAnson/markdownlint/blob/3561fc3f38b05b3c55f44e371c2cd9bda194598a/doc/Rules.md).

1. **Headings Style**: 
    - Use the ATX-style (`#`) for headers.

    ```markdown
      # This is an H1
      ## This is an H2
    ```

   [Reference: MD003](https://github.com/DavidAnson/markdownlint/blob/3561fc3f38b05b3c55f44e371c2cd9bda194598a/doc/Rules.md#md003---heading-style)

2. **List Indentation**: 
    - Indent list items with 4 spaces.

    ```markdown
      - Item 1
          - Subitem 1.1
    ```

   [Reference: MD007](https://github.com/DavidAnson/markdownlint/blob/3561fc3f38b05b3c55f44e371c2cd9bda194598a/doc/Rules.md#md007---unordered-list-indentation)

3. **Line Length**: 
    - No specific restriction on the line length, but keep paragraphs and sentences readable.
    
    [Reference: MD013](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length)

4. **Multiple Headings with the Same Content**: 
    - Multiple headings with the same content are permissible as long as they are not siblings.
    
    [Reference: MD024](https://github.com/DavidAnson/markdownlint/blob/3561fc3f38b05b3c55f44e371c2cd9bda194598a/doc/Rules.md#md024---no-multiple-headings-with-the-same-content)

5. **Inline HTML**: 
    - Only the `video` element is allowed when using inline HTML.

    ```markdown
    <video src="path_to_video.mp4" controls></video>
    ```

   [Reference: MD033](https://github.com/DavidAnson/markdownlint/blob/3561fc3f38b05b3c55f44e371c2cd9bda194598a/doc/Rules.md#md033---inline-html)

6. **Tabs and Whitespace**: 
    - We're flexible with the use of hard tabs and trailing whitespace. However, for consistency, we recommend using spaces over tabs and avoiding trailing whitespaces.
    
    [Reference: no-hard-tabs & whitespace](https://github.com/DavidAnson/markdownlint/blob/3561fc3f38b05b3c55f44e371c2cd9bda194598a/doc/Rules.md)

## Formatting

### Visual style

- Use the H2 style for main headings to be programmatically listed in the articles table of contents.
- File names and directory paths should be stylized as code per the [HTML spec](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element).
  Example: `/wp-content/uploads/`
- References to a single directory should have a trailing slash (eg. "/" appended) to the name.
  Example: "uploads/"
- References to repositories should appear without forward slashes and not be formatted in any way. The first appearance of a repository in article content should link to the URL of the repository source whenever possible.
  Example: "[woocommerce-blocks](https://github.com/woocommerce/woocommerce-blocks)" followed by "woocommerce-blocks"
- Inline references to functions and command line operations should be formatted as inline code.
  Example: "Use `dig` to retrieve DNS information."
- Functions should be styled with "Inline code" formatting and retain upper and lower case formatting as established from their source.
  Example: `WP_Query` (not WP_query)

### Visual aids

Visual aids such as screenshots, diagrams, code snippets and videos can be very helpful in a how-to guide. They provide a visual reference that can help the user understand the instructions more easily. When including visual aids, be sure to label them clearly and provide a caption or description that explains what is being shown.

### Acronyms

Phrases that are more familiarly known in their acronym form can be used. The first time an acronym appears on any page, the full phrase must be included, followed by its acronym in parentheticals.

Example: We've enhanced the querying functionality in WooCommerce with the introduction of High Performance Order Storage (HPOS).

After that, the acronym can be used for the remainder of the page.

When deciding if a term is common, consider the impact on translation and future internationalization (i18n) efforts.

## Patterning

### Article content

When creating a how-to guide, it's important to use a consistent and easy-to-follow format. Here is a suggested template for a software how-to guide:

**Introduction**: Provide an overview of the task or feature that the guide covers.

**Prerequisites**: List any prerequisites that are required to complete the task or use the feature.

**Step-by-step instructions**: Provide detailed, step-by-step instructions for completing the task or using the feature. Use numbered steps and include screenshots or other visual aids where appropriate.

**Troubleshooting**: Include a troubleshooting section that addresses common issues or errors that users may encounter.

**Conclusion**: Summarize the key points covered in the guide and provide any additional resources or references that may be helpful.

## Terminology

### Reference to components and features

- "**WordPress Admin dashboard**" should be presented in its complete form the first time it appears in an article, followed by its abbreviated form in parentheses ("WP Admin"). Thereafter the abbreviated form can be used for any reference to the WordPress Admin dashboard within the same article.
- When referring to the URL of the WordPress Admin dashboard, the shortened form `wp-admin` can be used.

## Testing

Before publishing a tutorial or guide, it's important to test it thoroughly to ensure that the instructions are accurate and easy to follow.

## Structure

### Atomizing the docs

Articles that cover too many topics in one place can make it difficult for users to find the information they are looking for. "Atomizing" the Docs refers to breaking down extensive articles into a group of smaller related articles. This group of articles often has a main "landing page" with a high-level overview of the group of articles, and the descriptive text provides links to the related articles that a user will find relevant. These groups of articles can be considered an information "molecule" formed by the smaller, atomized articles.

Breaking out smaller chunks of content into their own articles makes it easier to link to specific topics rather than relying on links to more extensive articles with anchor tags. This more specific linking approach is helpful to our Support team but is also useful for cross-linking articles throughout the Docs site.


---

## Releasing WooCommerce

*Source: contribution/releases/README.md*

# Releasing WooCommerce

The WooCommerce release process is managed by a rotating release lead, alongside two standing Product DRI seats in `@woo-core-release` (see [release roles](/docs/contribution/releases/readiness#release-roles)).  The documentation below outlines the process for managing releases.  To get started with a new release, see [Building and Publishing WooCommerce](/docs/contribution/releases/building-and-publishing).

## Process Overview

* [Building and Publishing](/docs/contribution/releases/building-and-publishing)
* [Readiness and Go/No-Go](/docs/contribution/releases/readiness)
* [Decision Matrix](/docs/contribution/releases/decision-matrix)
* [Troubleshooting](/docs/contribution/releases/troubleshooting)
* [Point Releases](/docs/contribution/releases/point-releases)
* [Security Support](/docs/contribution/releases/security-support)
* [Cherry-picking](/docs/contribution/releases/backporting)
* [Pre-releases](/docs/contribution/releases/prereleases)
* [Release Schedule](/docs/contribution/releases/schedule)
* [Release Monitoring](/docs/contribution/releases/monitoring)
* [Package Releases](/docs/contribution/releases/package-releases)
* [Workflows](/docs/contribution/releases/workflows)


---

## Cherry-picking in WooCommerce

*Source: contribution/releases/backporting.md*

# Cherry-picking in WooCommerce

Cherry-picking is the process of applying changes between `trunk` and a release branch (in either direction). This page is the canonical reference for the cherry-pick mechanics used by both pre-release stabilization (beta, RC) and patch releases.

For the patch-release-specific process (when a patch is warranted, who creates the tracking issue, and how it ships), see the [Point Releases guide](/docs/contribution/releases/point-releases).

## Release Branch Lifecycle

When a release branch is created, it is copied from `trunk` at the time of feature freeze. After creation:

- The release branch no longer receives new feature updates.
- Only critical changes are allowed.
- Because we do not merge release branches back into `trunk`, any fix landed on a release branch must also be applied to `trunk` (and, when applicable, to the next frozen release branch).

### What "frozen release" means

A frozen release branch is the most recent `release/x.y` cut from `trunk` for the next upcoming version. While the previous release is still in maintenance, this branch is the one feature work has already moved on to. The `cherry pick to frozen release` label forward-ports a fix from the current maintenance branch to this branch so the same fix also ships in the next major version. Frozen releases only accept critical bug fixes, the same bar as any other release branch.

## Qualifying Changes for Cherry-picking

Changes qualify for cherry-picking only if they are:

- **Bug fixes** that affect the release.
- **Performance improvements** that impact WooCommerce functionality.
- **Time-sensitive features** that impact business goals.
- **Contractually required features** for WooCommerce.

## Cherry-pick Workflows

### Standard Workflow: `trunk` to Release Branch

**When to use:** Most cherry-pick scenarios, including the preferred path for patch release fixes.

1. **Target `trunk`** as the base branch.
2. **Set the milestone** to the release series (e.g. `9.8.0`). WooCommerce milestones use the `.0` form for the whole `X.Y.x` series, so a fix targeting `X.Y.1` still uses milestone `X.Y.0`.
3. **Get the PR reviewed and merged** into `trunk`.
4. A cherry-pick PR against the release branch is opened automatically.
5. **The author** (or whoever merged the original PR) reviews, tests against the release branch, and merges the cherry-pick PR. The cherry-pick PR shares the same milestone as the original fix and must land before the release is published.

For urgent fixes near release deadlines, reach out to the release lead in the `#woo-core-releases` Slack channel.

### Alternative Workflow: Release Branch to `trunk`

**When to use:** The fix doesn't apply cleanly to `trunk`, or the branches have diverged enough that landing on `release/x.y` first is simpler.

1. **Target the release branch** (e.g. `release/9.8`) as the base branch.
2. **Apply labels** for any branches that need the forward-port:
    - `cherry pick to trunk` to forward-port to `trunk`.
    - `cherry pick to frozen release` to forward-port to the next frozen release branch (see [frozen release definition above](#what-frozen-release-means)).
3. **Include a changelog entry** and set the milestone to the release series (`X.Y.0`).
4. **Get the PR reviewed and merged** into the release branch.
5. The cherry-pick automation opens follow-up PRs against `trunk` and/or the frozen branch based on which labels are present.
6. **The author** reviews and merges the follow-up PRs promptly. They share the same milestone as the original fix and must land before the release is published.


---

## Building and Publishing a Release

*Source: contribution/releases/building-and-publishing.md*

# Building and Publishing a Release

:::important

While this guide can be used as reference, keep in mind that version-specific instructions are provided in the [release tracking issues](https://github.com/woocommerce/woocommerce/issues?q=state%3Aopen%20label%3A%22Release%22%20author%3Aapp%2Flinear%20tracking) created ahead of the release cycle, and should be preferred.

:::

This page provides an overview of the steps required to build any WooCommerce release from the release branch. Review the flowchart to understand the overall process and the decision table. Step-by-step instructions are provided below.

## Overview

![Release Process flow chart](/img/doc_images/release-process.png)

## Instructions

Perform all the steps below in order. When running _any_ GitHub workflow, ensure you do it from the `trunk` branch (the default) and input the release version or branch as indicated.

Keep the _[Release Troubleshooting & Recovery](/docs/contribution/releases/troubleshooting)_ guide handy, in case you encounter any issues.

### Steps

#### 1. Pre-build checks

- [ ] Confirm [GitHub services](https://www.githubstatus.com/) are operational.
- [ ] Verify no open issues or pull requests exist against the [release milestone](https://github.com/woocommerce/woocommerce/milestones/). Ping authors as needed to merge or close; for betas, marking a PR as a draft works as a temporary workaround.
- [ ] Ensure that there aren't any pull requests [with label "cherry pick failed"](https://github.com/woocommerce/woocommerce/pulls?q=is:pr+label:%22cherry+pick+failed%22) that apply to this release that haven't been actioned.
- [ ] Confirm the `Stable tag` value in the readme.txt on the release branch matches the one [on WordPress.org's `trunk`](https://plugins.trac.wordpress.org/browser/woocommerce/trunk/readme.txt#L7).

#### 2. Build the release package

- [ ] Run workflow **[Release: Bump version number](https://github.com/woocommerce/woocommerce/actions/workflows/release-bump-version.yml)**: enter the release main version (`x.y`) as _Release branch_ and choose the release type from the dropdown.
- [ ] Review and merge the PR that was generated against the release branch.
- [ ] Run workflow **[Release: Compile changelog](https://github.com/woocommerce/woocommerce/actions/workflows/release-compile-changelog.yml)**: enter the release main version (`x.y`) as _Version_ and leave _Release date_ empty, except when building the package ahead of schedule.
- [ ] Review and merge the PRs that were generated: one against `trunk` and another one against the release branch. Both should be under the release milestone.
- [ ] Run workflow **[Release: Build ZIP file](https://github.com/woocommerce/woocommerce/actions/workflows/release-build-zip-file.yml)** to build the asset and create the GitHub release: enter the release main version (`x.y`) as _Release branch_ and check _Create GitHub release_.
- [ ] Confirm that a draft release [was created in the repository](https://github.com/woocommerce/woocommerce/releases) with an attached `woocommerce.zip` asset.

#### 3. Upload the release to WordPress.org

- [ ] Run workflow **[Release: Upload release to WordPress.org](https://github.com/woocommerce/woocommerce/actions/workflows/release-upload-to-wporg.yml)**: enter the release version (`x.y.z`) as _Release tag to upload_ and make sure to check off the confirmation box.
- [ ] Confirm that SVN tag [exists on WordPress.org SVN](https://plugins.svn.wordpress.org/woocommerce/tags/).
- [ ] [Log into WordPress.org](https://wordpress.org/plugins/developers/releases/) using the credentials from the `WordPress.org "WooCommerce" user account` secret in the secret store and approve the release.
- [ ] After a few minutes, confirm that the release package [is available for download](https://wordpress.org/plugins/woocommerce/advanced/).

#### 4. Deploy to the staging environment

:::caution
This step only applies to `rc` or stable (`x.y.0`  onwards) releases.
:::

- [ ] Follow the [guide to deploy to the staging environment](https://wp.me/PCYsg-18BQ) and monitor for 4 hours (RC) or 2 hours (stable) after deploy.
- [ ] Create a thread in the releases Slack channel for monitoring and discussion of this release.

##### If a critical issue was detected while monitoring

- [ ] Request a revert in the staging environment.
- [ ] Pause the release process and **do not continue with any steps on this issue**. Follow the procedure in the [troubleshooting guide](https://developer.woocommerce.com/docs/contribution/releases/troubleshooting/#a-serious-bug-was-detected-during-internal-checks--monitoring) instead.

#### 5. Publish the release

- [ ] **(Only for stable releases)** Run workflow **[Release: Update stable tag](https://github.com/woocommerce/woocommerce/actions/workflows/release-update-stable-tag.yml)**: enter the release version (`x.y.z`) as _Version_ and make sure to check off the confirmation box.
- [ ] Publish the [release draft](https://github.com/woocommerce/woocommerce/releases) that was previously created, as well as any other release drafts that might exist from previous attempts. **Ensure** that "Set as the latest release" is checked **only** for stable releases.

#### 6. Post-release tasks

:::caution
This step only applies to stable (`x.y.0`  onwards) releases.
:::

- [ ] Wait at least 1 hour for all automations to complete and make sure to merge any follow-up PRs under the [release milestone](https://github.com/woocommerce/woocommerce/milestones/).
- [ ] Continue monitoring for bugs related to the release for at least 3 days. See the [release monitoring guide](https://developer.woocommerce.com/docs/contribution/releases/monitoring/) for more details.


---

## Release Decision Matrix

*Source: contribution/releases/decision-matrix.md*

# Release Decision Matrix

Every finding against a release gets a verdict - at the readiness review, at the go/no-go, and when weighing whether an already-shipped issue warrants a point release. This page is the criteria for picking that verdict. The decision points themselves are described in [Readiness and Go/No-Go](/docs/contribution/releases/readiness); the criteria apply to Core and Woo-owned extension releases, for all release types.

The matrix guides the people making the call - the release lead and the Product DRI. It does not change which automated checks gate a build.

## Verdicts

| Verdict | Meaning |
| --- | --- |
| **Release-blocking** | The release does not ship with this issue in it: hold the date or remove the change. Found after shipping: point release now. |
| **Fix in a point release** | Ship on schedule. The fix has an issue, an owner, and a target release *before* the go decision - without those, it re-enters as release-blocking. |
| **Next release** | Ship. The fix rides the next scheduled release. |
| **Not a bug** | Expected behavior, or an invalid finding. |

A finding no one can reproduce - tried on at least two independent stacks - gets **Next release, with a named owner**: it does not block the release, and the issue stays open rather than being closed as not a bug. A finding that reproduces anywhere keeps its impact-class verdict.

## Default verdict by impact class

| Impact class | Default verdict | Example |
| --- | --- | --- |
| Checkout or revenue interruption - a store cannot take payments | Release-blocking; no modifiers apply | - |
| Site down or fatal on load, in Core or any Woo-owned extension - including older extension versions running with the new Core | Release-blocking | [#64394](https://github.com/woocommerce/woocommerce/pull/64394) forced the revert after 10.9.0; [#65957](https://github.com/woocommerce/woocommerce/pull/65957) rescheduled 11.0.0 after a fatal surfaced on an early deployment |
| Data loss or corruption | Release-blocking | - |
| A break in a public contract or shared surface with consumers in the wild - PHP API, hooks, REST, datastore behavior | Release-blocking | [#65595](https://github.com/woocommerce/woocommerce/pull/65595) changed datastore behavior extensions relied on and forced a revert; [#66382](https://github.com/woocommerce/woocommerce/pull/66382) removed released public methods, restored within a day by [#66822](https://github.com/woocommerce/woocommerce/pull/66822) |
| A contract change whose surface has no known consumers, or that went through the deprecation path in the repository's [`AGENTS.md`](https://github.com/woocommerce/woocommerce/blob/trunk/AGENTS.md) | Next release | - |
| WordPress forward-compatibility - the release breaks under a WordPress version shipping before our next release | Fix in a point release scheduled before the WordPress date; release-blocking if the breakage is site-down class | [#67061](https://github.com/woocommerce/woocommerce/pull/67061) shipped WordPress 7.1 fixes inside the 11.0.0 rebuild, because 7.1 lands before 11.1.0 |
| Broken upgrade path - the update itself fails or leaves a site inconsistent | Release-blocking if deterministic; fix in a point release if transient and self-healing | The 10.9.1 upgrade race self-healed on cache refresh and produced a single report - no point release was needed |
| A regression in a default-on, merchant-facing feature | Release-blocking without a workaround; fix in a point release with one | - |
| A regression behind a flag that is off by default | Next release | An 11.0 REST API field inconsistency was judged non-blocking because the flag is off by default, with the rename scheduled for a later release |
| A performance regression | Release-blocking at scale with no mitigation; otherwise fix in a point release with the mitigation named | [#66088](https://github.com/woocommerce/woocommerce/pull/66088) had a filter mitigation available immediately; the fix ([#66786](https://github.com/woocommerce/woocommerce/pull/66786)) was backported into the next build |
| Cosmetic and UX papercuts | Next release | - |

Security issues follow the security team's process, not this matrix. Sensitive fixes may ship as a dedicated point release immediately after stable - coordinate with the security team.

## Modifiers

A modifier moves a verdict one level, never past the floor: **checkout, data, and site-down verdicts do not demote.** A verdict moves at most one level in total: when a row already prices in a modifier's condition - as the off-by-default flag row does - that modifier does not apply again; the more specific row wins. A fatal with a documented workaround is still a fatal for every store that hits it before reading the workaround.

- **Feature flags, by trajectory.** A flag that is off by default demotes the verdict one level - unless the flag is scheduled to default on in the next release, in which case no demotion applies: for release purposes it is already on. When nobody can state the flag's trajectory, the demotion applies, the verdict records the assumption ("assumes the flag stays off through next cycle"), and the unanswered question goes to the feature's owner.
- **Blast radius.** How many stores are exposed, and how fast. Managed hosting platforms can deploy an update to every site at once rather than following WordPress.org's staged rollout, so managed-fleet exposure weighs heavier than install counts alone. This extends the scope and commonality criteria in [Point Releases](/docs/contribution/releases/point-releases).
- **Workaround.** A documented workaround that merchants can apply themselves demotes one level - never past the floor. This matches the workaround criterion in [Point Releases](/docs/contribution/releases/point-releases).

## Response times

| Verdict | Response time |
| --- | --- |
| Release-blocking | The verdict is recorded the same day the finding is raised; the release does not proceed to the next run-book step until it is. |
| Fix in a point release | The fix is scheduled - issue, owner, target release - before the go decision. For findings that surface after shipping: within the [monitoring window](/docs/contribution/releases/monitoring) (3 days after a major release, 1 day after a point release). |
| Next release | The issue is filed and milestoned when the verdict is recorded: before the go decision for findings against an unshipped release, within the same monitoring window for findings that surface after shipping. |
| Not a bug | The verdict and the reasoning are recorded on the linked issue when it is closed. |

These are verdict-and-scheduling times, not fix-delivery guarantees.

## Decision rules

1. **Revert over rush.** When a fix cannot get the same validation the original change had before the release date, remove the change instead of patching under pressure.
2. **Silence is not a pass.** Every signal read at the readiness review and go/no-go has a named responder. An unreviewed signal counts as missing, not green.
3. **Verdicts are recorded, with names.** The release lead and the Product DRI record each verdict on the linked issue. Disputes over a classification are argued and settled on that issue, so the reasoning is written down where the verdict lives.
4. **The same matrix applies to extensions**, in both directions of the Core-extension version pairing. Extensions maintained by partners route through the owning team's channel.


---

## WooCommerce Release Monitoring

*Source: contribution/releases/monitoring.md*

# WooCommerce Release Monitoring

After the release, the release lead should continue to monitor the following for any bugs directly related to the latest version.  Monitoring should continue for 3 days after a major release and 1 day for a point release.

If there are questions whether a specific issue is critical enough to warrant a new point release, check the [release decision matrix](/docs/contribution/releases/decision-matrix) first; for genuine ties, start a discussion in the `#woo-core-releases` Slack channel.

## WordPress.org Forums

Check newly created threads on the [WordPress.org Forums](https://wordpress.org/support/plugin/woocommerce/) for any issues that appear to be caused by the latest update.

## WooCommerce GitHub Repository Issues

Watch the [Newest Created Issues](https://github.com/woocommerce/woocommerce/issues?q=is%3Aissue%20state%3Aopen%20sort%3Acreated-desc) and verify that none are critical.

## Extension Fatal-Error Alerts

Every Woo-owned extension has a Grafana fatal-error alert on WP Cloud, backed by the internal *Woo\* Fatals on WP Cloud* dashboard. Alerts post to the owning team's channel and to `#woo-core-releases-notifications`. Watch that channel during the monitoring window.

When an alert fires, open the linked dashboard panel to see how many sites are affected, then reply on the alert to ping the owning team - triage is theirs. If the fatal traces back to the release, treat it as a candidate critical issue (see below).

An old extension version can point to a compatibility issue, but it does not prove the release caused the fatal. Compare the affected WooCommerce and extension versions before calling it a non-regression.

## Handling Critical Issues

If monitoring uncovers a bug that **cannot wait** for the next scheduled release, plan a point release. The [release decision matrix](/docs/contribution/releases/decision-matrix) is the criteria set for that call: look up the finding's impact class and apply the modifiers from there. Checkout, data-loss, and site-down issues warrant a point release even when a workaround exists; below that floor, limited scope, low commonality, and a documented workaround can support a lower verdict, subject to the matrix's one-level modifier cap.

If the verdict is a point release, follow the [Point Releases guide](/docs/contribution/releases/point-releases) to create a tracking issue, prepare the fix, and ship the patch.


---

## JavaScript Package Releases

*Source: contribution/releases/package-releases.md*

# JavaScript Package Releases

The WooCommerce monorepo includes numerous JavaScript packages to support WooCommerce development, such as `@woocommerce/components`, distributed via NPM. This release process is managed via GitHub Actions.

For the full documentation on how to release a JavaScript package, see the [package release tool documentation](https://github.com/woocommerce/woocommerce/tree/trunk/tools/package-release).


---

## Point Releases

*Source: contribution/releases/point-releases.md*

# Point Releases

:::important
The formal Point Release Request (PRR) issue template ([`new-prr-template.yml`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/ISSUE_TEMPLATE/new-prr-template.yml)) is no longer required for point release fixes; it is preserved only for reference. In practice, coordinating directly with the release lead is sufficient to get fixes included in a point release, and is the most important step. The rest of this document covers what types of fixes qualify for point releases and how to prepare them in the repository.
:::

Point releases are patch releases that address specific issues in an already-shipped WooCommerce version (for example `9.9.0 → 9.9.1`) without adding new functionality. They apply only to versions that are already in customer production environments.

## What qualifies as a point release

Changes appropriate for a point release are:

- **Critical bug fixes** affecting store functionality (checkout, orders, payments, product visibility).
- **Security patches** for urgent vulnerabilities ([which versions receive them](/docs/contribution/releases/security-support)).
- **Severe performance regressions** introduced by the shipped release.
- **Compliance fixes** required for regulatory or legal reasons.
- **Compatibility fixes** for WordPress, theme, or plugin conflicts that are breaking stores.

The following are **not** point release material and should ride the next regular release instead:

- New features or enhancements.
- Non-critical bug fixes.
- Code refactoring or cleanup.
- Documentation updates.

In all cases, point releases must remain backward compatible. No breaking changes are allowed in a patch.

⚠️ Security vulnerability reports must **not** go through this flow. Report them privately via Automattic's HackerOne program: [https://hackerone.com/automattic/](https://hackerone.com/automattic/).

## Evaluating whether to ship a point release

Use your best judgement based on the urgency and severity of the outstanding issue. These criteria align with the [release decision matrix](/docs/contribution/releases/decision-matrix), which maps impact classes to default verdicts. The release lead and the reporter should weigh:

| Criterion | Guidance |
| --- | --- |
| **Scope of impact** | How many stores are already affected? Larger reach increases urgency. |
| **Error commonality** | Does the problem stem from a widely-used core flow, plugin, or theme? Issues in common components usually merit faster action. |
| **Workarounds** | Is there an easy, documented workaround (a filter, setting toggle, or temporary feature disable) that store owners can apply? Readily available workarounds lower the need for a point release - except for checkout, data-loss, and site-down issues, where the matrix calls for a point release regardless. |
| **Impact severity** | Does the bug block critical commerce functionality (checkout, payments, product visibility)? The more business-critical the failure, the higher the priority. |

Some practical timing notes:

- If the issue is not very urgent, consider waiting 3–4 days to see if additional related issues are reported before proceeding. This consolidates fixes and reduces the number of patch releases.
- For high-severity or critical issues, prioritize releasing as soon as possible.
- For security issues, coordinate with the team that implemented the fix to help determine urgency if it is not clear.
- Consider whether other known issues already being worked on could be included in the same release.

## Process

The work is split between the **fix author** and the **release lead**. These tasks can happen in parallel. The author does not need to wait for the tracking issue before opening a PR, and the release lead can create the tracking issue independently once a point release is on the table.

### For the fix author: prepare the fix

Two paths are acceptable. The first is preferred when the fix applies cleanly to both branches.

- **Preferred:** merge to `trunk` with the `X.Y.0` milestone set. The cherry-pick automation handles the rest. See the [Cherry-picking guide](/docs/contribution/releases/backporting) for the full flow, including your responsibility for reviewing and merging the auto-generated cherry-pick PR.
- **Alternative:** PR directly against the `release/X.Y` branch when the fix doesn't apply cleanly to `trunk`. Use the [cherry-pick label flow](/docs/contribution/releases/backporting) to forward-port to `trunk` (and the next frozen release if applicable).

Once the PR and any cherry-pick follow-ups have been reviewed, merged, and milestoned, the rest is on the release lead.

### For the release lead: create the tracking issue and cut the release

Run the [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/actions/workflows/release-create-tracking-issue.yml) workflow for the target point release version (e.g. `9.9.1`). Do **not** reuse an existing tracking issue, even if a previous release in the same series was blocked. The workflow automatically nests the new Linear issue under the `[X.Y] Release tracking` parent for that release series, so the entire release series remains a single tree in Linear.

The tracking issue contains the version-specific checklist for cutting and publishing the release. Follow it from there. For underlying mechanics (workflows, draft releases, stable tag updates), refer to [Building and Publishing](/docs/contribution/releases/building-and-publishing).


---

## WooCommerce Pre-releases

*Source: contribution/releases/prereleases.md*

# WooCommerce Pre-releases

WooCommerce pre-releases provide early access to upcoming features and improvements, allowing developers, testers, and the community to prepare for future releases.

This document outlines the different types of pre-releases available, their timing, and how they fit into the overall release cycle.

| Release Name      | Estimated Timing                                                |
|-------------------|-----------------------------------------------------------------|
| `nightly`         | Every night                                                     |
| `-dev`            | At feature freeze                                               |
| `-beta.1`         | 1 week after feature freeze                                     |
| `-beta.2`, ...    | At least 1 more, as needed before `-rc.1`                       |
| `-rc.1`           | Shortly (~1 day) before final release                           |
| `-rc.2`, ...      | As needed, when a critical bug is detected during RC monitoring |

## Nightlies

Regenerated every night based on the current contents of `trunk`. Found [under the `nightly` tag on GitHub](https://github.com/woocommerce/woocommerce/releases/tag/nightly).

These are only available in the GitHub repository, and are neither announced publicly nor uploaded to WordPress.org.

## Release cycle pre-releases

Once the feature freeze for the upcoming main version (`X.Y.0`) happens, a release-specific branch is created (named `release/x.y`) which is used for stabilization, fixing regressions, and building all the pre-releases tied to that release cycle.

These releases are tagged at various points in time as described below. As usual, the source of truth for any specific dates is [our release calendar](https://developer.woocommerce.com/release-calendar/).

### `-dev` release

This is an auto-generated tag that is created at the same time as the feature freeze happens for the current cycle. For example, when the feature freeze for `10.1.0` happened, `10.1.0-dev` was tagged.

This is an internal development tag, available only in the GitHub repository and not on WordPress.org.

### Beta

Meant to be used by plugin authors and early adopters to test the features and functionality in an upcoming version. The first beta is usually released 1 week after the feature freeze.

Betas are versioned incrementally, starting with `-beta.1`, then `-beta.2`, and so on.

We aim to release at least 2 betas per cycle, but more are possible if any important bug fixes or functionality require additional testing or receive an important update before the final stable release.

All beta versions are available both on GitHub and WordPress.org.

For guidance on how to participate in WooCommerce beta testing and contribute valuable feedback, refer to our [beta testing documentation](/docs/contribution/testing/beta-testing/).

### Release Candidate (RC)

These are pre-release versions that are feature-complete and considered stable enough for final testing. RCs are typically released shortly before the final release and are used internally for a final round of testing and checks.

They are versioned incrementally as `-rc.1`, `-rc.2`, and so on.

We aim to release at least one RC before the final release, which will not be publicly announced but will be tagged and available for download on both GitHub and WordPress.org.

Additional RCs (`-rc.2` onwards) are only cut when monitoring uncovers a critical bug. Their tracking issues are not created by the regular release-assignment automation; they are created on demand by running [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/actions/workflows/release-create-tracking-issue.yml). See the [troubleshooting guide](/docs/contribution/releases/troubleshooting#a-serious-bug-was-detected-during-internal-checks--monitoring) for the full recovery procedure.


---

## Release Readiness and Go/No-Go

*Source: contribution/releases/readiness.md*

# Release Readiness and Go/No-Go

Two explicit decision points anchor every release cycle. Both live as checklists in the release tracking sub-issues, so each release leaves a written trail of what was checked, what was decided, and by whom. This page explains what each point is for; the checklists themselves are in the sub-issues the [Release: Assignment workflow](/docs/contribution/releases/workflows) creates.

## Release roles

Each cycle has two named owners, listed on the parent tracking issue:

* **Release lead** (engineering) - runs the release process end to end: builds, publishes, monitors, and executes the run-books.
* **Product DRI** - the product-side counterpart. Joins the readiness review at RC and the go/no-go before stable, and owns the product read on open findings: what blocks the release, what waits for a point release, and what ships with a known-issues note.

The release lead is assigned by rotation via the [Release: Assignment workflow](/docs/contribution/releases/workflows). The Product DRI role is covered by two standing Product seats in Slack's `@woo-core-release` group. Their names are on the tracking issue. If you're unsure who to loop in, ping the handle.

The handle also holds a standing set of engineering members and the current and previous release leads, who rotate at each feature freeze.

## Readiness review (at RC)

The RC is the last point where finding a problem is cheap: nothing has shipped, and delaying costs a day, not a revert. The review runs before the RC build starts and answers one question - is there anything we know about that should stop this release?

The checklist covers four areas:

* **Compatibility evidence.** The QIT compatibility regression sweep runs automatically against each prerelease and reports which extension versions the release would break. Introduced issues need a verdict, not just a look.
* **Open findings.** Bug reports, testing threads, and monitoring alerts against the release each get a linked issue and a verdict per the [release decision matrix](/docs/contribution/releases/decision-matrix): release-blocking, fix in a point release, next release, or not a bug.
* **Rollback path.** Who reverts, how, and what revert means for this version - answered before it's needed, not during an incident.
* **Comms.** Changelog in shape, and a known-issues list when verdicts left something open.

## Go/no-go (24-48 hours before stable)

A deliberate decision to ship, made while there is still time to not ship. The release lead and the Product DRI confirm the readiness verdicts still hold and nothing blocking has appeared since the readiness review, then record the decision on the release sub-issue: **go**, **no-go**, or **go with conditions** - with names.

Recorded decisions are the input for release retrospectives and future updates to these checklists.

## For point releases

Point releases have no RC, so both decision points fold into the go/no-go on the release sub-issue: the release lead and the Product DRI run the readiness criteria above over the changes being shipped, then record the decision. An unscheduled point release shipping an urgent fix compresses this further: a quick go/no-go with the Product DRI in `#woo-core-releases`, recorded on the release sub-issue. The criteria for whether an issue warrants a point release at all are in [Release Monitoring](/docs/contribution/releases/monitoring).


---

## WooCommerce Release Schedule

*Source: contribution/releases/schedule.md*

# WooCommerce Release Schedule

WooCommerce operates on a predictable release schedule, delivering updates with new features, enhancements, and bug fixes roughly every five weeks.
This page summarizes the main stages of our release process, such as feature freeze, beta and release candidate periods, and the timing of final and patch releases.

Additional details on how the release cycle looks inside the monorepo can be found on our [Git Flow docs](/docs/contribution/contributing/woocommerce-git-flow)

:::tip

To view the actual schedule for current and upcoming releases, see our [release calendar](https://developer.woocommerce.com/release-calendar/).

:::

![Release Cycle flow chart](/img/doc_images/release-cycle.png)

## Milestones

### Feature Freeze & `-dev` release (day 1)

As a result of the feature freeze automation, a few things happen:

- A dedicated release branch is created (`release/x.y`), where the future release undergoes testing and stabilization. No new features are included on this branch, only bug fixes.
- A `-dev` release is built and made available on GitHub.
- Development of new features continues on `trunk`.
- A pre-release post is published on our developer website ([example](https://developer.woocommerce.com/2025/05/12/woocommerce-9-9-pre-release-updates/)).

### Beta 1 (+1 week)

At this stage, various testing processes take place:

- (Internally) Regression testing with Woo-maintained extensions, regression testing in multiple environments, and exploratory testing (including by contributing teams).
- (Community) The pre-release is announced so the community can [begin testing](/docs/contribution/testing/beta-testing/).

Any issues found during the beta period are addressed either directly against the release branch or by backporting fixes from `trunk` (preferred). Refer to the [cherry-picking guide](/docs/contribution/releases/backporting) for more details.

`release/x.y` remains the source of truth for anything going into the upcoming release.

### Beta 2 (+1 week)

At this stage, we release regression fixes discovered in `-beta.1` as part of release stabilization. The pre-release announcement continues to be updated.

### RC 1 (+1 week)

Last round of (internal) checks before the final release.

If anything is found at this stage, a fix is merged into the release branch (`release/x.y`) as in the beta phase.

### Final Release (+1 day)

We make the stable release version available to everyone.
At this point, the Developer Advocacy team publishes release highlights that are prepared in advance ([example](https://developer.woocommerce.com/2025/06/09/woocommerce-9-9-its-fast-period/)).

### Point/Patch Releases

Patch releases ship important bug fixes detected after the final release. They are versioned `x.y.z` where `z` is non-zero. See the [Point Releases guide](/docs/contribution/releases/point-releases) for the full process, including how a patch is evaluated, prepared, and shipped.


## Delays

Due to business needs or any critical bugs discovered during testing, the release dates may be subject to change.

We do not take this decision lightly and only do so to guarantee the stability of a release. When this happens, we will always communicate the situation ([example](https://developer.woocommerce.com/2025/06/02/woocommerce-9-9-release-is-delayed/)) and update the release calendar.

For details on how a delay is managed, refer to the [release troubleshooting guide](/docs/contribution/releases/troubleshooting/#the-release-needs-to-be-delayed-what-should-we-do).


---

## Security Patch Support Policy

*Source: contribution/releases/security-support.md*

# Security Patch Support Policy

When a security fix warrants it (CVSS score >=9), WooCommerce will provide security patches for the **last 21 major versions**. If the current stable WooCommerce version is 11.1, that means version **9.1 and newer**. Otherwise, we publish fixes for the latest version.

"Major version" follows WooCommerce's release numbering (`10.8`, `10.9`, `11.0`, ...), not semantic versioning. At the current release cadence, 21 major versions correspond to roughly two years of releases.

## What this means

- When the impact of a security issue warrants it (CVSS score >=9) - security fixes are backported to every supported major version affected by the vulnerability (within the established support window), and ship as [point releases](/docs/contribution/releases/point-releases).
- Versions older than the support window do not receive security patches. Stores on unsupported versions must update to a supported version to receive fixes.
- The window is a rolling count: each new major release moves the floor up by one version.

## Exceptions

For some classes of critical vulnerabilities, we may as a courtesy, backport outside the established policy.

## Reporting

Security vulnerabilities must be reported privately through Automattic's HackerOne program: [https://hackerone.com/automattic/](https://hackerone.com/automattic/). Never report them in public issues.

## Keeping this page current

When the stable release of a new major version is published, an automated workflow opens a pull request that bumps the minimum supported version on this page. The release DRI reviews and merges it as part of the post-release tasks.


---

## Release Troubleshooting & Recovery

*Source: contribution/releases/troubleshooting.md*

# Release Troubleshooting & Recovery

This page provides guidance for troubleshooting and recovering from issues that may arise during the WooCommerce release process. It covers common scenarios, recommended actions, and best practices to help ensure releases are handled smoothly and any problems are resolved efficiently.

:::tip

`@woo-core-release` in `#woo-core-releases` is the point of contact for release-process questions in general, not just the scenarios below. Use it for escalations, second opinions, or anything this doc doesn't answer.

:::

## Scenarios / FAQ

### A workflow failed while building the release

1. **Open the workflow run details** in GitHub (under the **Actions** tab) to see exactly where and why the failure occurred. Most of the time, the workflow will display a clear error message.
2. **Read the error message carefully.** Sometimes the problem is as simple as a missing workflow configuration or skipped step.
3. **If you're unsure what the error means or how to proceed,** don't hesitate to ask for help in the release Slack channel. It's better to get a second opinion than to guess.

⚠️ _Do not re-run any workflows until you understand the cause of the failure._ Re-running without fixing the root issue can make things more complicated.

### CI is failing on a release-related PR

During the release process, you may encounter CI test failures on release-related PRs. These failures sometimes occur because test fixes were merged to trunk but not backported to the release branch before it was cut.

1. **Check [GitHub's status page](https://www.githubstatus.com/) first**: PRs stuck on _"Waiting for status to be reported"_ or entire batches of failing jobs are often caused by a GitHub Actions incident, not by the release.
2. **Identify the cause**: Check if the failing tests pass on trunk. If they do, the fix likely needs to be backported.
3. **Backport test fixes**: If possible, [backport](/docs/contribution/releases/backporting) the relevant test fixes from trunk to the release branch, then re-run the CI workflow.
4. **Re-run before assuming a regression**: If nothing relevant changed since the last green run, the failure is likely flakiness. If a test keeps flaking on the release branch, file an issue for the owning team and don't let it block the release.
5. **Handle complex cases**: If backporting isn't possible due to dependencies or the cause isn't clear, document what you've found and ask for help in the release Slack channel.

Note that a failing check that is not required and is clearly unrelated to the change (for example, a comparison job that references code only present on trunk) does not have to block merging a release-related PR. When in doubt, ask in the release Slack channel before merging over a failure.

### The "Build ZIP file" workflow refuses to build because of open PRs

The workflow checks two criteria: open PRs based on the release branch, and open PRs carrying the release milestone (on any base branch). Draft PRs are ignored, so switching a PR to draft is a quick way to bypass the check temporarily. The workflow's error message lists the offending PRs: merge the ones that belong in the release, and close stale or redundant ones (including auto-generated backport PRs whose changes are already on the release branch).

### Something looks wrong in the final release ZIP. Can I start over?

If, after downloading and unzipping the generated artifact, something seems off (e.g., missing files, incorrect changelog, or version mismatch), this usually means:

- A required workflow didn't run or failed (for example, the changelog step was skipped).
- An auto-generated PR from a workflow wasn't merged into the release branch before building the ZIP.

**Before you try to build the version again:**

1. Delete any GitHub draft release or tag for the incorrect release:
   - Go to **Code > Releases** and delete the draft release.
   - In **Code > Tags**, delete the tag for the incorrect version. _If you skip this, the final release may point to the wrong commit in history._
2. Check the status of the `release/X.Y` branch (either in the GitHub UI or locally after pulling the latest changes).
3. Figure out which step failed. For example, if the plugin header version is correct but the changelog is missing, only the changelog step needs to be re-run.
4. Review any [auto-generated PRs](https://github.com/woocommerce/woocommerce/pulls?q=is%3Aopen+is%3Apr+author%3Aapp%2Fgithub-actions+label%3ARelease): if there are open PRs that weren't merged and are no longer needed, close them and delete their branches.

**Once you know which step failed,** re-run only that step as described in the [Building & Publishing guide](/docs/contribution/releases/building-and-publishing). Make sure to run skipped workflows in the correct order and double-check all configuration (version number, release type, etc.) before proceeding.

### The "Upload release to WordPress.org" workflow failed

When this workflow fails, it reports the state of the SVN side in the run summary; check it before doing anything else. Two things worth knowing:

- **If the SVN tag for the version exists, the upload succeeded** even though the run is red: continue with the release process. Re-running against an existing tag fails validation.
- **`E175013: Access to '/!svn/me' forbidden` means invalid SVN credentials**: update the SVN credentials secret from the secret store and re-run.

### A serious bug was detected during internal checks / monitoring

For RC and stable releases, deploying to our staging environment and monitoring for errors is required before the release is made publicly available. If a serious bug is detected during this monitoring period, follow these steps:

1. **Request a revert** of the deploy in the staging environment.
2. **Pause the release process** immediately and do not continue with any remaining steps in the tracking issue.
3. **Update the tracking issue** to reflect that the release is blocked, including details about the bug.
4. **Do not publish** any of the draft GitHub releases that were created, but also **do not delete** them. They will be published later along with the version that passes validation.
5. **Coordinate with the relevant engineering team(s)** to develop a fix.
6. **Involve Developer Advocacy** if the release schedule needs to be adjusted or communicated publicly ([read more on delays below](#the-release-needs-to-be-delayed-what-should-we-do)).

#### How to proceed once the bug fix is merged into the release branch?

1. **Create a new tracking issue** for the new version (e.g., `-rc.2` if the bug was detected during `-rc.1`, or `x.y.2` if detected while monitoring `x.y.1`) by running the [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/actions/workflows/release-create-tracking-issue.yml) workflow. Do not reuse the existing tracking issue. The new issue is automatically nested under the `[X.Y] Release tracking` parent in Linear.
2. **Follow the release procedure as normal** for the new version.
3. **Publish all draft releases** for the affected version series. Even if the prior version wasn't made publicly available, it must be published along with the valid version. Each version will have its own changelog section.

### A critical bug surfaced after the release was marked stable on WordPress.org

If a severe regression or bug is discovered (e.g., checkout failure or unrecoverable data loss):

1. Immediately notify the relevant engineering team(s).
2. If the severity warrants it (e.g., checkout failure, data loss, or other critical impact affecting many stores), temporarily move the stable tag on WordPress.org back to the previous known-good version, so new installs and updates stop landing on the broken version while the fix is being prepared:
   - Identify the correct previous version and note its exact number.
   - Use the [`Release: Update stable tag`](https://github.com/woocommerce/woocommerce/actions/workflows/release-update-stable-tag.yml) workflow, making sure to check the _Revert_ option to allow downgrading.
   - Merge any auto-generated PRs right away: the revert opens PRs updating the `Stable tag` in `readme.txt` on `trunk` and the affected release branches, and the next build and upload will fail if the stable tag doesn't match SVN.
3. Follow the [Point Releases guide](/docs/contribution/releases/point-releases) to create a tracking issue, prepare the fix, and ship the patch.

### The release is out, but sites don't see the update yet

This is usually not a problem:

- WordPress checks for plugin updates roughly every 12 hours by default, so it can take a while for a newly published release to be offered on any given site.
- WordPress.org now also applies a delay of up to 24 hours before offering new releases ([announcement](https://wordpress.org/news/2026/06/pts/)), so the update may not appear immediately even after a site's update check runs.
- Only the `Stable tag` in the `readme.txt` on WordPress.org's SVN `trunk` controls what the updater offers. The `readme.txt` bundled inside a released ZIP always shows the previous version as stable: that's expected, since published releases are frozen and can't be edited.

### The release needs to be delayed. What should we do?

1. Create an internal Slack thread to communicate with the engineering teams as well as Dev Advocacy. This also provides an opportunity for teams to share any additional context and verify or challenge schedule changes.
2. Ask Dev Advocacy to communicate the delay publicly.
3. If there's a clear ETA on the patch release with a fix, [update the release calendar](https://developer.woocommerce.com/release-calendar/) with the new dates.

Remember to not plan the patch release [too close to the weekend](#the-release-was-delayed-can-we-still-release-after-tuesday).

### The release was delayed. Can we still release after Tuesday?

In general, avoid releasing after Tuesday, especially close to a weekend.

Even if a patch is ready and seems to fix the problem, it's hard to be sure there aren't other hidden issues and a rushed release late in the week means most of the team won't be available to monitor or respond to problems.

As a rule of thumb, when in doubt, consider to delay the release by a week for confidence.


---

## Release Workflows

*Source: contribution/releases/workflows.md*

# Release Workflows

The WooCommerce release process is supported by a set of GitHub Actions workflows that automate repetitive tasks, enforce process guardrails, and send notifications. This page provides a reference of all release-related workflows, organized by how they are triggered.

All workflows are defined in the [`.github/workflows/`](https://github.com/woocommerce/woocommerce/tree/trunk/.github/workflows) directory.

## Scheduled workflows

These workflows run automatically on a daily schedule.

| Workflow | Schedule | What it does | When it acts |
| -------- | -------- | ------------ | ------------ |
| [Release: Assignment](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-assignment.yml) | Daily at 18:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/), assigns the release lead, and creates the parent tracking issue along with the four standard sub-issues for the cycle: `beta.1`, `beta.2`, `rc.1`, and the final `.0` release. Calls *Create Tracking Issue* for each sub-issue. Also triggers an internal post announcing the new release lead to the team. Tracking issues for patch releases, extra RCs, or extra betas are **not** created by this workflow; see the note below the "Tracking and analysis" table. | ~8 weeks before feature freeze. |
| [Release: Enforce Feature Freeze](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-code-freeze.yml) | Daily at 18:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/) and creates the release branch from `trunk`, bumps `trunk` to the next dev version, publishes a dev release, cleans up old milestones, and sends Slack notifications. Calls *Bump version number* and *Build ZIP file*. Also triggers an internal call for testing to canonical extension teams. | On the feature freeze date. |
| [Release: Feature highlight notification](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-feature-highlights-notification.yml) | Daily at 09:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/) and sends a Slack reminder to teams about the upcoming feature freeze deadline. | ~1 week before feature freeze. |
| [Release: Open Issue Warning](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-open-issue-warning.yml) | Daily at 18:00 UTC | Checks the [release calendar](https://developer.woocommerce.com/release-calendar/) and looks for open items in release milestones, sending a Slack notification listing them with assignees. | Within 72 hours of a release date. |
| [Nightly builds](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/nightly-builds.yml) | Daily at 00:00 UTC | Builds a nightly ZIP from `trunk` and uploads it to a GitHub release. Runs every day, independent of the release calendar. | Every day. |

## Event-driven workflows

These workflows are triggered automatically by GitHub events such as pull requests being merged, releases being published, or issues being labeled.

### Cherry-pick and backport

| Workflow | Trigger | What it does |
| -------- | ------- | ------------ |
| [Cherry-pick Milestoned PRs to Release Branches](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/cherry-pick-milestoned-prs.yml) | PR closed or milestoned on `trunk` | Cherry-picks from `trunk` to the `release/x.y` branch matching the PR milestone. Uses [`shared-cherry-pick`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/shared-cherry-pick.yml) for the core logic. |
| [Cherry-pick to Frozen Release](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/cherry-pick-to-frozen.yml) | PR merged on a `release/x.y` branch with the `cherry pick to frozen release` label | Cherry-picks from a `release/x.y` branch to the next (frozen) `release/x.y` branch. Uses [`shared-cherry-pick`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/shared-cherry-pick.yml) for the core logic. |
| [Cherry Pick to Trunk](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/cherry-pick-to-trunk.yml) | PR merged on a `release/x.y` branch with the `cherry pick to trunk` label | Cherry-picks from a `release/x.y` branch back to `trunk`. Uses [`shared-cherry-pick`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/shared-cherry-pick.yml) for the core logic. |
| [Block merge if cherry-pick conflicts exist](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-cherry-pick-pr-check-conflicts.yml) | PR events on `cherry-pick-*` branches | Fails CI when the `cherry pick has conflicts` label is present, preventing the PR from being merged until conflicts are resolved and the label is removed. |

### Milestoning

| Workflow | Trigger | What it does |
| -------- | ------- | ------------ |
| [Auto-Add Milestone to Release PRs](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/auto-milestone-release-prs.yml) | PR opened or reopened on a `release/x.y` branch | Assigns the matching milestone to PRs targeting a release branch. |
| [Auto-assign milestone on merge](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/pr-auto-milestone-on-merge.yml) | PR closed on `trunk` | Assigns a milestone to PRs merged to `trunk` that don't already have one. |

### Release events and validation

| Workflow | Trigger | What it does |
| -------- | ------- | ------------ |
| [Release: Release events proxy](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-release-events-proxy.yml) | Release published or prereleased | Delegates to [`release-new-release-published`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-new-release-published.yml) to run post-release actions: sends Slack notifications, updates the global changelog for stable releases, bumps the minimum [security-support](/docs/contribution/releases/security-support) version when the release is the first of a new major version, and calls *Generate Number of Commits and Contributors* for beta releases. |
| [Release checks run](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/tests-on-release.yml) | Release published or edited | Runs the CI test suite against published releases. Also runs nightly on a schedule. |

## Manual workflows

These workflows are triggered by the release lead during the release process. They are the workflows referenced in the [building and publishing guide](/docs/contribution/releases/building-and-publishing) and in the release tracking issues.

### Building and publishing

| Workflow | What it does |
| -------- | ------------ |
| [Release: Bump version number](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-bump-version.yml) | Updates version numbers across plugin files and creates a PR against the release branch. |
| [Release: Compile changelog](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-compile-changelog.yml) | Compiles changelog entries and creates PRs against both `trunk` and the release branch. |
| [Release: Build ZIP file](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-build-zip-file.yml) | Builds the release ZIP and optionally creates a draft GitHub release. |
| [Release: Upload release to WordPress.org](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-upload-to-wporg.yml) | Uploads the release ZIP to WordPress.org SVN. |
| [Release: Update stable tag](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-update-stable-tag.yml) | Updates the stable tag on WordPress.org and creates PRs to sync it in the repository. |

### Tracking and analysis

| Workflow | What it does |
| -------- | ------------ |
| [Release: Create Tracking Issue](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-create-tracking-issue.yml) | Creates a Linear tracking issue for a specific release version using the templates in `.linear/`. |
| [Release: Generate Number of Commits and Contributors](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-commits-and-contributors.yml) | Generates release statistics (commit count, contributors list) and sends a Slack notification. |
| [Release: analyze trends (CFEs and PRRs)](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-trends-analysis.yml) | Creates GitHub issues requesting AI analysis of Code Freeze Exceptions and Point Release Requests for a milestone. |

:::note
Tracking issues for **patch releases, extra RCs, and extra betas** are not created automatically by `Release: Assignment`. Run [`Release: Create Tracking Issue`](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-create-tracking-issue.yml) manually for those. See the [Point Releases](/docs/contribution/releases/point-releases) and [Troubleshooting](/docs/contribution/releases/troubleshooting) guides for context on when each is needed.
:::

## Deprecated

| Workflow | What it did |
| -------- | ----------- |
| [Release: CFE and PRR issue validation](https://github.com/woocommerce/woocommerce/blob/trunk/.github/workflows/release-cfe-prr-issue-validation.yml) | Validated Code Freeze Exception and Point Release Request issues, applied labels and milestones to the associated PR, and sent Slack notifications. The PRR/CFE process is no longer part of the standard flow; see the [Point Releases guide](/docs/contribution/releases/point-releases) for current practice. |


---

## Testing

*Source: contribution/testing/README.md*

# Testing

Setting up your test environment and writing tests when contributing to WooCommerce Core are essential parts of our development pipeline. The links below are also included in our [Contributing Guidelines](https://github.com/woocommerce/woocommerce/blob/trunk/.github/CONTRIBUTING.md) on GitHub.

If you have questions about testing, reach out to the developer community in our public channels: [Developer Blog](https://developer.woocommerce.com/blog/), [GitHub Discussions](https://github.com/woocommerce/woocommerce/discussions), or [Community Slack](https://woocommerce.com/community-slack/).

## Unit testing

[Unit tests](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/tests/README.md) run against the WooCommerce PHP test suite. The recommended local setup uses `wp-env`.

## End-to-end testing

[End-to-end tests](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/tests/e2e) are powered by Playwright. The test site is spun up using `wp-env`.

## API testing

[API tests](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/tests/e2e/tests/api-tests) are part of the Playwright suite and use the same `wp-env` test environment as end-to-end tests.

## PHP version coverage

Use the [PHP version guidelines](/docs/contribution/testing/php-version-coverage/) to understand how to choose representative, minimum, and latest PHP versions, and where each belongs in E2E and PHP unit testing.

## Testing instructions

When opening a pull request, use the [testing instructions guide](/docs/contribution/testing/writing-high-quality-testing-instructions/) to write clear steps that cover the behavior changed in the PR.

## Calls for testing

Keep tabs on calls for testing on our [developer blog](https://developer.woocommerce.com/blog/), and read our [beta testing instructions](/docs/contribution/testing/beta-testing/) to help us build new features and enhancements.


---

## Beta Testing

*Source: contribution/testing/beta-testing.md*

# Beta Testing

Beta testing is vital to ensuring our releases are as bug free as possible and to ensure we hear user feedback before putting changes live. Anyone can beta test; shop owners, plugin developers, theme developers, translators, any and all help is welcome.

We do understand however that the process of testing can be a little bit of a hassle since you need to download a tagged release and then upload it to your testing site manually. Sometimes this can also cause issues with plugin directory naming as well, because tagged releases will not have a directory named `woocommerce`. This can break extensions.

To make this process easier, we have released a beta testing plugin to help install the WooCommerce beta versions, and to ensure the directory names are kept correct.

Please ensure you test responsibly, it is not a good idea to run beta versions on a production site unless you have experience and can anticipate changes and failures.

## Installing the Beta Tester Plugin

To get started, go to Plugins > Add New > Upload plugin, and install the beta tester plugin which you can download from:

[WooCommerce Beta Tester](https://woocommerce.com/products/woocommerce-beta-tester/)

This plugin will give you access to all of the WooCommerce versions uploaded to [WordPress.org]. This includes beta releases and release candidates.

## Giving Feedback

During testing, if you come across a bug or want to propose or contribute an enhancement, [submit an issue on GitHub](https://github.com/woocommerce/woocommerce/issues/new?assignees=&labels=type%3A+enhancement%2Cstatus%3A+awaiting+triage&template=2-enhancement.yml&title=%5BEnhancement%5D%3A+). Ensure you read our guidelines on contributing and note which version you are using specifically. It is also possible to easily submit a new GitHub issue through the [beta tester plugin](https://woocommerce.com/products/woocommerce-beta-tester/).

Sometimes we may also ask for feedback via other means, such as the surveys and calls for testing on the [developer blog](https://developer.woocommerce.com/blog/). We appreciate immediate feedback, comments, and responses to surveys as it helps us judge how well received our releases and betas are and will help us shape future versions.

Thanks for testing WooCommerce!


---

## WooCommerce core critical flows

*Source: contribution/testing/core-critical-flows.md*

# WooCommerce core critical flows

We have identified what we consider to be our most critical user flows within WooCommerce Core. These flows will help us focus and prioritize our testing efforts. They will also help us consider the impact of changes and priority of issues.

These flows will continually evolve as the platform evolves with flows updated, added or re-prioritised.

## Shopper critical flow areas

-   [Shopper > Shop](#shopper---shop)
-   [Shopper > Product](#shopper---product)
-   [Shopper > Cart](#shopper---cart)
-   [Shopper > Checkout](#shopper---checkout)
-   [Shopper > Email](#shopper---email)
-   [Shopper > My Account](#shopper---my-account)

## Merchant critical flow areas

-   [Merchant > Onboarding](#merchant---onboarding)
-   [Merchant > Dashboard](#merchant---dashboard)
-   [Merchant > Settings](#merchant---settings)
-   [Merchant > Coupons](#merchant---coupons)
-   [Merchant > Marketing](#merchant---marketing)
-   [Merchant > Analytics](#merchant---analytics)
-   [Merchant > Products](#merchant---products)
-   [Merchant > Orders](#merchant---orders)
-   [Merchant > Customers](#merchant---customers)
-   [Merchant > Email](#merchant---email)
-   [Merchant > Plugins](#merchant---plugins)
-   [Merchant > My Subscriptions](#merchant---my-subscriptions)
-   [Merchant > Pages](#merchant---pages)
-   [Merchant > Posts](#merchant---posts)

### Shopper - Shop

| User Type | Flow Area | Flow Name                                   |
| --------- | --------- | ------------------------------------------- |
| Shopper   | Shop      | Search Store                                |
| Shopper   | Shop      | Browse by categories                        |
| Shopper   | Shop      | Can sort items                              |
| Shopper   | Shop      | Add Simple Product to Cart (from shop page) |
| Shopper   | Shop      | Display shop catalog                        |
| Shopper   | Shop      | Products by tag                             |
| Shopper   | Shop      | Products by attribute                       |
| Shopper   | Shop      | Use product filters                         |

### Shopper - Product

| User Type | Flow Area | Flow Name                                            |
| --------- | --------- | ---------------------------------------------------- |
| Shopper   | Product   | Add Simple Product to Cart                           |
| Shopper   | Product   | Add Grouped Product to Cart                          |
| Shopper   | Product   | Variable Product info updates depending on variation |
| Shopper   | Product   | Add Variable Product to Cart                         |
| Shopper   | Product   | Display up-sell product                              |
| Shopper   | Product   | Display related products                             |
| Shopper   | Product   | Display reviews                                      |
| Shopper   | Product   | Add review                                           |
| Shopper   | Product   | View product images                                  |
| Shopper   | Product   | View product descriptions                            |

### Shopper - Cart

| User Type | Flow Area | Flow Name                                  |
| --------- | --------- | ------------------------------------------ |
| Shopper   | Cart      | Add to cart redirects to cart when enabled |
| Shopper   | Cart      | View cart                                  |
| Shopper   | Cart      | Update product quantity within limits      |
| Shopper   | Cart      | Remove products from cart                  |
| Shopper   | Cart      | Apply all coupon types                     |
| Shopper   | Cart      | Display shipping options by address        |
| Shopper   | Cart      | View empty cart                            |
| Shopper   | Cart      | Display correct tax                        |
| Shopper   | Cart      | Respect coupon usage constraints           |
| Shopper   | Cart      | Display cross-sell products                |
| Shopper   | Cart      | Proceed to checkout                        |

### Shopper - Checkout

| User Type | Flow Area | Flow Name                                |
| --------- | --------- | ---------------------------------------- |
| Shopper   | Checkout  | Correct item in Order Review             |
| Shopper   | Checkout  | Can add shipping address                 |
| Shopper   | Checkout  | Guest can place order                    |
| Shopper   | Checkout  | Create an account                        |
| Shopper   | Checkout  | Login to existing account                |
| Shopper   | Checkout  | Existing customer can place order        |
| Shopper   | Checkout  | Use all coupon types                     |
| Shopper   | Checkout  | View checkout                            |
| Shopper   | Checkout  | Receive warnings when form is incomplete |
| Shopper   | Checkout  | Add billing address                      |
| Shopper   | Checkout  | Respect coupon usage constraints         |
| Shopper   | Checkout  | Display correct tax in checkout          |
| Shopper   | Checkout  | View order confirmation page             |

### Shopper - Email

| User Type | Flow Area | Flow Name                             |
| --------- | --------- | ------------------------------------- |
| Shopper   | Email     | Customer Account Emails Received      |
| Shopper   | Email     | Customer Order Detail Emails Received |

### Shopper - My Account

| User Type | Flow Area  | Flow Name                 |
| --------- | ---------- | ------------------------- |
| Shopper   | My Account | Create an account         |
| Shopper   | My Account | Login to existing account |
| Shopper   | My Account | View Account Details      |
| Shopper   | My Account | Update Addresses          |
| Shopper   | My Account | View Orders               |
| Shopper   | My Account | Pay for Order             |
| Shopper   | My Account | View Downloads            |

### Merchant - Onboarding

| User Type | Flow Area      | Flow Name                                                      |
| --------- | -------------- | -------------------------------------------------------------- |
| Merchant  | Core Profiler  | Introduction & opt-in                                          |
| Merchant  | Core Profiler  | User profile information                                       |
| Merchant  | Core Profiler  | Business information                                           |
| Merchant  | Core Profiler  | Extensions page                                                |
| Merchant  | Core Profiler  | WooPayments included in extensions for eligible criteria       |
| Merchant  | Core Profiler  | WooPayments not included in extensions for ineligible criteria |
| Merchant  | Core Profiler  | Install all default extensions                                 |
| Merchant  | Core Profiler  | Complete site setup                                            |
| Merchant  | Core Profiler  | Skip introduction and confirm business location                |
| Merchant  | NOX Onboarding | Open onboarding from Payments settings                         |

### Merchant - Dashboard

| User Type | Flow Area      | Flow Name                                              |
| --------- | -------------- | ------------------------------------------------------ |
| Merchant  | WC Home        | Completing profiler redirects to home                  |
| Merchant  | WC Home        | Complete all steps on task list                        |
| Merchant  | WC Home        | Hide the task list                                     |
| Merchant  | WC Home        | Store management displayed after task list finished    |
| Merchant  | WC Home        | Direct access to analytics reports from stats overview |
| Merchant  | WC Home        | Preserve task list completion status after upgrade     |
| Merchant  | WC Home        | Interact with extended task list                       |
| Merchant  | Activity Panel | Interact with activity button                          |
| Merchant  | Inbox          | Interact with notes and perform CTAs                   |
| Merchant  | Inbox          | Dismiss single note and all notes                      |

### Merchant - Settings

| User Type | Flow Area | Flow Name                              |
| --------- | --------- | -------------------------------------- |
| Merchant  | Settings  | Update General Settings                |
| Merchant  | Settings  | Add Tax Rates                          |
| Merchant  | Settings  | Add Shipping Zones                     |
| Merchant  | Settings  | Add Shipping Classes                   |
| Merchant  | Settings  | Enable local pickup for checkout block |
| Merchant  | Settings  | Update payment settings                |
| Merchant  | Settings  | Handle Product Brands                  |

### Merchant - Coupons

| User Type | Flow Area | Flow Name             |
| --------- | --------- | --------------------- |
| Merchant  | Coupons   | Add all coupon types  |
| Merchant  | Coupons   | Add restricted coupon |

### Merchant - Marketing

| User Type | Flow Area | Flow Name                  |
| --------- | --------- | -------------------------- |
| Merchant  | Marketing | Display marketing overview |

### Merchant - Analytics

| User Type | Flow Area | Flow Name                                          |
| --------- | --------- | -------------------------------------------------- |
| Merchant  | Analytics | View revenue report                                |
| Merchant  | Analytics | View overview report                               |
| Merchant  | Analytics | Confirm correct summary numbers on overview report |
| Merchant  | Analytics | Use date filter on overview page                   |
| Merchant  | Analytics | Customize performance indicators on overview page  |
| Merchant  | Analytics | Use date filter on revenue report                  |
| Merchant  | Analytics | Download revenue report as CSV                     |
| Merchant  | Analytics | Use advanced filters on orders report              |
| Merchant  | Analytics | Analytics settings                                 |
| Merchant  | Analytics | Set custom date range on revenue report            |

### Merchant - Products

| User Type | Flow Area      | Flow Name                      |
| --------- | -------------- | ------------------------------ |
| Merchant  | Products       | View all products              |
| Merchant  | Products       | Search products                |
| Merchant  | Products       | Add simple product             |
| Merchant  | Products       | Add variable product           |
| Merchant  | Products       | Edit product details           |
| Merchant  | Products       | Add virtual product            |
| Merchant  | Products       | Import products CSV            |
| Merchant  | Products       | Add downloadable product       |
| Merchant  | Products       | View product reviews list      |
| Merchant  | Products       | View all products reviews list |
| Merchant  | Products       | Edit product review            |
| Merchant  | Products       | Trash product review           |
| Merchant  | Products       | Bulk edit products             |
| Merchant  | Products       | Remove products                |
| Merchant  | Products       | Manage product images          |
| Merchant  | Products       | Manage product inventory       |
| Merchant  | Products       | Manage product attributes      |
| Merchant  | Products       | Manage global attributes       |
| Merchant  | Products       | Add up-sell                    |
| Merchant  | Products       | Add cross-sell                 |
| Merchant  | Products (New) | Disable new product experience |
| Merchant  | Products (New) | Add simple product             |
| Merchant  | Products (New) | Edit simple product            |
| Merchant  | Products (New) | Manage product images          |
| Merchant  | Products (New) | Manage product inventory       |
| Merchant  | Products (New) | Manage product attributes      |

### Merchant - Orders

| User Type | Flow Area | Flow Name                                                        |
| --------- | --------- | ---------------------------------------------------------------- |
| Merchant  | Orders    | View all orders                                                  |
| Merchant  | Orders    | Can add new order basic                                          |
| Merchant  | Orders    | View single order                                                |
| Merchant  | Orders    | Update order status to completed                                 |
| Merchant  | Orders    | Update order status to cancelled                                 |
| Merchant  | Orders    | Update order details                                             |
| Merchant  | Orders    | Customer payment page                                            |
| Merchant  | Orders    | Refund order                                                     |
| Merchant  | Orders    | Apply coupon                                                     |
| Merchant  | Orders    | Can add new order complex - multiple product types & tax classes |
| Merchant  | Orders    | Search orders                                                    |
| Merchant  | Orders    | Filter orders by order status                                    |
| Merchant  | Orders    | Bulk change order status                                         |
| Merchant  | Orders    | Add order notes                                                  |

### Merchant - Customers

| User Type | Flow Area | Flow Name             |
| --------- | --------- | --------------------- |
| Merchant  | Customers | Display customer list |

### Merchant - Email

| User Type | Flow Area | Flow Name                                          |
| --------- | --------- | -------------------------------------------------- |
| Merchant  | Email     | Receive and check content of new order email       |
| Merchant  | Email     | Receive and check content of cancelled order email |
| Merchant  | Email     | Receive and check content of failed order email    |
| Merchant  | Email     | Resend new order email                             |
| Merchant  | Email     | Send invoice/order details to customer via Email   |

### Merchant - Plugins

| User Type | Flow Area | Flow Name              |
| --------- | --------- | ---------------------- |
| Merchant  | Plugins   | Can update WooCommerce |

### Merchant - My Subscriptions

| User Type | Flow Area        | Flow Name                               |
| --------- | ---------------- | --------------------------------------- |
| Merchant  | My Subscriptions | Can initiate WooCommerce.com Connection |

### Merchant - Pages

| User Type | Flow Area | Flow Name             |
| --------- | --------- | --------------------- |
| Merchant  | Pages     | Can create a new page |

### Merchant - Posts

| User Type | Flow Area | Flow Name             |
| --------- | --------- | --------------------- |
| Merchant  | Posts     | Can create a new post |


---

## Guidelines for choosing PHP versions in tests

*Source: contribution/testing/php-version-coverage.md*

# Guidelines for choosing PHP versions in tests

Use [WordPress.org PHP usage statistics](https://wordpress.org/about/stats/) to choose the most widely used version within WooCommerce's supported range for representative coverage. Also test the minimum and latest supported versions. PHP unit tests cover all three roles in routine CI; broader E2E coverage runs nightly to limit CI cost.

| Version choice | Configured PHP | E2E coverage | PHP unit coverage | Why |
| --- | --- | --- | --- | --- |
| Representative version | 8.3 | PR, push, release, pre-release, and nightly | PR and push, with latest WordPress | Focus frequent checks on a widely used PHP runtime, using WordPress.org adoption data to guide the choice. |
| Minimum supported by WooCommerce | 7.4 | Standard Core and Blocks nightly suites | PR and push, with WordPress L-1; optional WordPress pre-release | Preserve minimum-version compatibility through PHP behavior checks and complete user flows. |
| Latest supported by WooCommerce | 8.5 | Standard Core and Blocks nightly suites; existing Core jobs also run on PR, release, and pre-release | PR and push, with latest WordPress, including HPOS disabled | Catch compatibility problems as merchants adopt newer PHP releases. |


---

## Writing high quality testing instructions

*Source: contribution/testing/writing-high-quality-testing-instructions.md*

# Writing high quality testing instructions

## Introduction

Having clear testing Instructions on pull requests is the first level of quality engineering in WooCommerce, which is key for testing early and minimizing the impact of unexpected effects in the upcoming versions of WooCommerce.

This page contains the following sections:

-   [What is a test?](#what-is-a-test)
-   [What to cover with the testing instructions](#what-to-cover-with-the-testing-instructions)
-   [Flow to write good testing instructions](#flow-to-write-good-testing-instructions)
-   [Examples](#examples)

## What is a test?

A test is a method that we can use to check that something meets certain criteria. It is typically defined as a procedure which contains the steps required to put the system under test in a certain state before executing the action to be checked. Therefore, a test consists of the following stages:

-   **Preconditions:** All the steps that need to be performed to put the system in the desired state before executing the action we want to check. A test could have many preconditions.
-   **Action:** This is the exact step that causes the change we want to check in the system. It should be only one because each test should ideally cover one thing at a time.
-   **Validation:** Relates to the steps to be performed in order to validate the result of performing the action in the system. A test could validate more than one thing.

For example, in the process of adding an item to the cart:

-   The **preconditions** would be all the steps involved in:
    -   The product creation process.
    -   Logging as a shopper.
    -   Heading to the shop page where the products are listed.
-   The **action** would be clicking the _"Add to cart"_ button in the desired product.
-   The **validation** stage would include checking that the cart icon (if any) shows 1 more item and the product we selected is now included in the cart.

Specifying the preconditions, actions and validations can be quite beneficial when understanding the scope of a test, because:

-   The **preconditions** describe what we have to do so that we can execute the test successfully.
-   The **action** lets us know the purpose of the test, in other words, it is the key to understanding what we need to test.
-   The **validation** stage lets us know what to expect when executing the test.

In this context, we will refer to testing instructions as the tests we need to execute in order to validate that the changes delivered in a pull request or release work as expected. This means the testing instructions could refer to a test or more, involving the happy path and potential edge cases.

## What to cover with the testing instructions

As stated in the previous section, a test (in our context, a testing instruction) is a method to check that a new change or set of changes meets certain criteria.

Therefore, a PR could have testing instructions for multiple scenarios, in fact, it is recommended to include testing instructions for as many scenarios as needed to cover the changes introduced in the PR. In other words, please **add as many testing instructions as needed to cover the acceptance criteria**, understanding acceptance criteria as _the conditions that a software product must satisfy to be accepted by a user, customer or other stakeholders_ or, in the context of a PR, the conditions that this PR must satisfy to be accepted by users, developers and the WooCommerce community as per requirements.

## Flow to write good testing instructions

1. **Outline the user flows** you want to cover.
2. **Define the environment** where the testing instructions should be executed (server, PHP version, WP version, required plugins, etc), and start writing the testing instructions as if you were starting from a fresh install.
3. Identify the **preconditions**, **action** and **validation** steps.
4. Write **as many preconditions as you need** to explain how to set up the state of WooCommerce so that you can execute the desired action to test every flow.
    1. Try to be detailed when explaining the interactions the user needs to perform in WooCommerce.
    2. If there are several preconditions for a user flow that is explained in a public guide, feel free to simply link the guide in the testing instructions instead of writing several steps. For example, _"Enable dev mode in WooCommerce Payments by following the steps mentioned [in the test accounts documentation](https://woocommerce.com/document/woopayments/testing-and-troubleshooting/test-accounts/)"_.
5. Write **the action step**, which should cover the specific action that we want to test as part of this user flow.
6. Write **as many validation steps** as needed in order to assess that the actual result meets expectations.
    1. Bear in mind to check only the steps needed to validate that this change works.

### Considerations for writing high-quality testing instructions

-   Define the testing instructions in a way that they can be **understood and followed by everybody**, even for people new to WooCommerce.
-   Make sure to describe every detail and **avoid assuming knowledge**, the spectrum of readers might be wide and some people would not know the concepts behind what is being assumed. For example, instead of saying _"Enable the [x] experiment"_, say something like:

```text
- Install the WooCommerce Beta Tester plugin.
- Go to `Tools > WCA Test Helper > Experiments`.
- Toggle the [x] experiment.
```

-   Always try to explain in detail **where the user should head to**, for example instead of saying "Go to the Orders page as admin", say "Go to [url]" or even "Go to WooCommerce > Orders".
-   Try to use real test data. For example, instead of saying _"Enter a name for the product"_, say something like _"Enter 'Blue T-Shirt' as the product name"_. This will make it more self-explanatory and remove potential doubts related to assuming knowledge.
-   Make sure you **keep your testing instructions updated** if they become obsolete as part of a new commit.
-   If the testing instructions require to add custom code, please **provide the code snippet**.
-   If the testing instructions require to install a plugin, please **provide a link to this plugin, or the zip file** to install it.
-   If the testing instructions require to hit an API endpoint, please provide the **link to the endpoint documentation**.
-   Ideally **provide screenshots and/or videos** that supported what the testing instructions are explaining. If you are using links to collaborative tools then also provide an equivalent screenshot/video for those who do not have access.

## Examples

### Good quality testing instructions

#### Example 1

![Sample of good quality instructions](https://developer.woocommerce.com/wp-content/uploads/2023/12/213682695-3dc51613-b836-4e7e-93ef-f75078ab48ac.png)

#### Example 2

![Another sample of good quality instructions](https://developer.woocommerce.com/wp-content/uploads/2023/12/213682778-b552ab07-a518-48a7-9358-16adc5762aca.png)

### Improving real testing instructions

In this section, you will see some real examples of testing instructions that have room for improvement (before) and how we can tweak them (after).

Before:

![Instructions needing improvement](https://developer.woocommerce.com/wp-content/uploads/2023/12/213682396-8c52d20e-1fca-4ac1-8345-f381c15a102a.png)

After:

![Improved instructions](https://developer.woocommerce.com/wp-content/uploads/2023/12/213682480-c01e0e84-5969-4456-8f43-70cbb8509e8d.png)

Improvements:

![Changes made](https://developer.woocommerce.com/wp-content/uploads/2023/12/213682597-8d06e638-35dd-4ff8-9236-63c6ec5d05b8.jpg)

Before:

![example before providing improved instructions](https://developer.woocommerce.com/wp-content/uploads/2023/12/216365611-b540a814-3b8f-40f3-ae64-81018b9f97fb.png)

After:

![example after providing improved instructions](https://developer.woocommerce.com/wp-content/uploads/2023/12/216366043-967e5daa-6a23-4ab8-adda-5f3082d1ebf7.png)

Improvements:

![example of improvements](https://developer.woocommerce.com/wp-content/uploads/2023/12/216366152-b331648d-bcef-443b-b126-de2621a20862.png)

Before:

![example before providing improved instructions](https://developer.woocommerce.com/wp-content/uploads/2023/12/216388785-8806ea74-62e6-42da-8887-c8e291e7dfe2-1.png)

After:

![example after providing improved instructions](https://developer.woocommerce.com/wp-content/uploads/2023/12/216388842-e5ab433e-d288-4306-862f-72f6f81ab2cd.png)

Improvements:

![example of improvements](https://developer.woocommerce.com/wp-content/uploads/2023/12/216388874-c5b21fc3-f693-4a7e-a58a-c5d1b6606682.png)


---

## Accessibility Best Practices

*Source: extensions/best-practices-extensions/accessibility.md*

# Accessibility Best Practices

In many places around the world, ecommerce stores are required to be accessible to people with disabilities. As a WooCommerce extension developer, your code directly impacts the accessibility of the shops that use it and can impact merchants’ compliance with accessibility laws.

This page is a resource for developers who want to ensure their extensions comply with accessibility standards and best practices. It is recommended that all WooCommerce extensions follow accessibility best practices to provide the best experience for merchants and their customers.

## Accessibility Laws

Two examples of laws that require ecommerce websites to be accessible include the [Americans with Disabilities Act (ADA)](https://ada.gov/) in the United States and the [European Accessibility Act (EAA)](https://employment-social-affairs.ec.europa.eu/policies-and-activities/social-protection-social-inclusion/persons-disabilities/union-equality-strategy-rights-persons-disabilities-2021-2030/european-accessibility-act_en), a directive that applies to all EU member countries. There are also laws requiring website accessibility in Australia, Canada, Israel, and many other countries. The W3C maintains a list of [web accessibility laws worldwide](https://www.w3.org/WAI/policies/) if you want to research laws in your country.

Most laws require websites to conform to Web Content Accessibility Guidelines (WCAG) as a measure of accessibility. To ensure that merchants can use your extension on their websites, it should also be WCAG conformant. 

If your extension is not WCAG conformant, you may receive complaints about accessibility issues from merchants. You may also be included in lawsuits or legal cases about accessibility problems caused by your extension. 

## Web Content Accessibility Guidelines (WCAG)

The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/TR/WCAG22) are internationally recognized standards designed to make websites accessible to everyone, including people with disabilities. WCAG is made up of *success criteria* (specific, testable rules) that fall under four key principles:

### Four Key Principles

- **Perceivable**  
  Content should be available in ways users can perceive, even if they do not have all five senses. Information should be transformable from one form to another (e.g., text alternatives for images or captions for videos).

- **Operable**  
  Users should be able to interact with the site easily using alternative devices (such as a keyboard only or screen reader without a mouse), and there should be no time-sensitive actions.

- **Understandable**  
  Content and interfaces should be clear and consistent with simple language and predictable navigation.

- **Robust**  
  Websites should work well with assistive technologies and across different devices.

### Compliance Levels

WCAG has three levels of compliance:

- **Level A** – Basic
- **Level AA** – Mid-range (required by most laws)
- **Level AAA** – Highest

Most regulations require **Level AA**, meaning you need to meet all **A** and **AA** success criteria.

### Current Version

The current version of WCAG is **2.2**.  
**Extension developers should aim for WCAG 2.2 Level AA compliance** as a best practice.

## Manual compatibility testing

It’s important to test your extension for [WCAG conformance](https://www.w3.org/TR/WCAG22) as you design and develop new features. Testing for accessibility is just as important as testing for security or WordPress coding standards. If you have not previously tested your extension for accessibility, start testing today and add accessibility bug fixes in future releases.

### Automated Testing

The easiest way to start accessibility testing is with an automated testing tool. Automated tools can quickly identify problems like empty buttons, ambiguous links, color contrast failures, missing alternative text, and more.

[Accessibility Checker](https://wordpress.org/plugins/accessibility-checker/) is a free WordPress plugin that you can use to test your extension. Simply install it in your test environment and add blocks or shortcodes created by your extension to a page. When you save the page, Accessibility Checker will scan the blocks or rendered shortcodes and provide a list of issues to address.

The [WAVE browser extension](https://wave.webaim.org/extension/) is another free automated testing tool. This browser extension can be used on any website and is helpful if you want to find accessibility problems on your extension’s admin pages.

### Keyboard Testing

After resolving issues from automated testing, the next step is to ensure that your extension can be used without a mouse and with a keyboard alone.

To test your extension for keyboard accessibility, go to the part of a test site controlled by your extension. Using the Tab key, move forward through the web page, ensuring that the following is true:

- All interactive components (buttons, links, inputs, etc.) can be reached by hitting the Tab key.
- Focus moves intuitively from left to right and top to bottom down the page.
- You can move backward through the components by hitting Shift + Tab.
- There are no keyboard traps. A keyboard trap is when focus lands on an element and then cannot go forward or backward.
- There is a visible focus outline on all interactive components. Also confirm that you have never set `:focus` in your stylesheet to `outline:none;` or `outline:0;`. It is never correct to remove focus outlines.
- If a button triggers a modal or dialog, focus should be moved into the dialog, and it should not be possible to tab out of the dialog without closing it.
- Buttons should be able to be triggered with both the Spacebar and the Return key. 
- Links should be able to be triggered with the Return key.

Test all aspects of your extension on the front end and in the admin for full functionality without a mouse.

### Test When Zoomed 

Ensure your extension can be used by low-vision users interacting with their browser zoomed in. Set your browser zoom to both 200% and 400% and ensure that no content overlaps or is lost and that the extension’s components can be used while the site is zoomed in.

### Screen Reader Testing

Familiarize yourself with screen readers, the assistive technology used by people who are blind or visually impaired, and use them to test your extension. There are two free screen readers that you can use for testing:

- **VoiceOver**: If you have a Mac, VoiceOver is built into your computer and is a great place to start, but it is not the preferred screen reader for blind desktop users.
- **NVDA**: NVDA is a free, open-source screen reader that you can download and use on your PC. This is the preferred screen reader for testing, as most blind people are Windows users.

To test your extension for screen reader accessibility, turn on the screen reader and use your keyboard to navigate the web page. Have the screen reader read the entire web page for you and listen for the following:

- All content and elements are read out – nothing meaningful is skipped.
- Images and graphics have accurate descriptions.
- Decorative images are skipped.
- Elements have the correct role: buttons should be announced as buttons, links as links, etc.
- Links and buttons have names that describe their purpose.
- Form fields are correctly labeled.
- States of components like tabs, accordions, and toggle buttons are announced as collapsed, selected, pressed, etc.
- Status changes are announced by the screen reader (e.g., success and error messages, changes in the number of visible products, opening of a modal or dialog, etc.).
- Hidden content is not read out.

### Test for Motion Sensitivity 

Website animations and motion can be distracting or cause physical illness for some users. To ensure your extension passes WCAG success criteria for motion:

- Provide a pause button for any auto-playing content that lasts longer than 5 seconds (e.g., videos, background videos, sliders/carousels, or animated GIFs).
- Avoid flashing content that exceeds three flashes per second, as it can potentially trigger seizures.
- Ensure all animations are disabled if the user has enabled the “reduce motion” setting in their operating system.

You can test if your animations respect the “prefers reduced motion” setting by enabling it on your operating system. Here’s how to do this:

- **On Windows 11**: Go to *Settings > Accessibility > Visual Effects > Animation Effects*.
- **On macOS**: Navigate to *System Preferences > Accessibility > Display > Reduce motion*.

Learn more about coding [prefers-reduced-motion media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion).

### User Testing 

Consider bringing in actual users with disabilities to test your extensions for accessibility. Seeing someone who relies on a screen reader or other assistive device use your products can be very enlightening. Ask your customer base to see if you already have people with disabilities in your audience available to test and provide feedback. Here’s a great resource on [how to run user testing sessions](https://www.w3.org/WAI/test-evaluate/involving-users/).

If you don’t want to run your own user testing sessions, there are [WooExperts](https://woocommerce.com/for-agencies/) who can help with this.

## Additional Considerations

### Make Your Website Accessible

In addition to testing your extension for accessibility best practices, you should be thinking about the accessibility of your own website and documentation. If your business meets certain revenue thresholds, the ecommerce store where people buy your products must be accessible and WCAG conformant.

### Include Captions for Your Videos 

If your documentation includes videos, those videos must be captioned and include transcripts. This is important to ensure everyone can access your documentation and learn to use your extension.

### Guiding Your Customers 

Even if your extension is perfectly accessible, merchants can introduce accessibility problems when configuring your extension or adding content. Whenever possible, define accessible defaults. For example, the default colors in your extension should always pass WCAG AA color contrast requirements. Merchants may change these colors to a combination that fails contrast, but you can say your extension is “accessibility-ready” if the default passes.

Consider adding functionality in the admin that alerts merchants when they make a choice that negatively impacts accessibility. For example, you can flag color combinations that fail contrast checks, similar to how it’s done in WordPress core. Other things you might warn merchants about include empty field labels, headings out of order, empty alt text, or choosing settings you must maintain for backward compatibility but know are not accessible.

### Create an Accessibility Conformance Report 

Many organizations, especially in government and education, require an Accessibility Conformance Report (ACR) before purchasing software. An ACR can speed up the procurement process if your extension is sold to large businesses, government, or educational institutions.

An Accessibility Conformance Report is a document that outlines the accessibility compliance of a digital product, against recognized accessibility standards like WCAG, Section 508 (US), and Europe’s EN 301 549 accessibility standard.

ACRs are created using a Voluntary Product Accessibility Template (VPAT), a standardized format for assessing and reporting accessibility features. You can download this template for free and fill it in yourself, or hire an accessibility specialist to audit your extension and complete the VPAT for you.

### Get Help With Compliance 

WCAG compliance doesn’t have to feel overwhelming! You can test and fix one issue at a time, incrementally improving your extension. However, accessibility goes faster if you don’t have to memorize WCAG or learn how to test first. Consider hiring an accessibility specialist to help with auditing or user testing your extension. The right company or consultant will help you find problems quickly, prioritize fixes, and train your team so fewer accessibility issues will be added in the future.

You can find accessibility-focused developers in our [WooExperts directory](https://woocommerce.com/for-agencies/).

## Learning More About Accessibility 

We recommend these resources if you want to learn more about website accessibility:

- [WordPress Accessibility Meetup](https://www.meetup.com/wordpress-accessibility-meetup/)
- [WP Accessibility Day Conference](https://wpaccessibility.day/)
- [WordPress Accessibility Ready Requirements](https://make.wordpress.org/themes/handbook/review/accessibility/)
- [WordCamp Europe Accessibility Testing Workshop](https://europe.wordcamp.org/2023/accessibility-testing-workshop/)
- [Web Accessibility Specialist Certification from the International Association of Accessibility Professionals](https://www.accessibilityassociation.org/specialist)


---

## Compatibility and interoperability for WooCommerce extensions

*Source: extensions/best-practices-extensions/compatibility.md*

# Compatibility and interoperability for WooCommerce extensions

Ensuring your WooCommerce extension is compatible and interoperable with the core platform, various components, and other extensions is fundamental to providing a seamless experience for users. This document covers the importance of compatibility, the process for self-declared compatibility checks, manual testing for compatibility issues, and troubleshooting common problems.

## Compatibility importance

Compatibility ensures that your extension works as expected across different environments, including various versions of WordPress and WooCommerce, as well as with other plugins and themes. Ensuring compatibility is crucial for:

- **User experience**: Preventing conflicts that can lead to functionality issues or site downtime.
- **Adoption and retention**: Users are more likely to install and keep updates if they're assured of compatibility.
- **Security and performance**: Compatible extensions are less likely to introduce vulnerabilities or degrade site performance.

## Self-declared compatibility checks

Developers should declare their extension's compatibility with the latest versions of WordPress and WooCommerce, as well as with specific components like Cart & Checkout blocks, High Performance Order Storage (HPOS), Product Editor, and Site Editor. This process involves:

1. **Testing**: Before release, thoroughly test the extension with the latest versions of WordPress and WooCommerce, as well as the specified components.
2. **Declaration**: Update the extension's documentation and metadata to reflect its compatibility with these platforms and components.
3. **Communication**: Inform users of the compatible versions in the extension's change log, website, or repository.

## Manual compatibility testing

Manual testing is essential to identify and resolve potential compatibility issues. Follow these steps for effective manual compatibility testing:

1. **Set up a testing environment** that mirrors a typical user setup, including the latest versions of WordPress and WooCommerce.
2. **Test with core components**: Verify the extension's functionality with core components like Cart & Checkout blocks, HPOS, Product Editor, and Site Editor.
3. **Cross-plugin compatibility**: Activate your extension alongside other commonly used plugins to check for conflicts.
4. **Theme compatibility**: Test your extension with several popular themes to ensure it works correctly and maintains a consistent appearance.

## Troubleshooting and resolving compatibility issues

Despite thorough testing, compatibility issues may arise. Here are common problems and steps to resolve them:

### Conflicts with other extensions

- **Diagnosis**: Use tools like [Health Check & Troubleshooting plugin](https://wordpress.org/plugins/health-check/) to identify conflicting plugins.
- **Resolution**: Contact the other plugin's developer for collaboration, or implement conditional logic in your extension to avoid the conflict.

### Theme Compatibility Issues

- **Diagnosis**: Check for styling or layout issues when your extension is used with different themes.
- **Resolution**: Use more generic CSS selectors and provide configuration options for better theme integration.

### Updates breaking compatibility

- **Preventive measures**: Subscribe to the [WooCommerce developer blog](https://developer.woocommerce.com) to stay informed about upcoming changes.
- **Quick fixes**: Prepare patches or minor updates to address compatibility issues as soon as possible after a core update.

### No Errors with multiple extensions activated

- **Best practice**: Regularly test your extension in a multi-plugin environment to ensure it does not cause or suffer from conflicts.

## Conclusion

Maintaining compatibility and interoperability is a continuous effort that requires regular testing, updates, and communication with your users and the broader developer community. By following these guidelines, you can enhance the reliability, user satisfaction, and success of your WooCommerce extension.


---

## WooCommerce extension development best practices

*Source: extensions/best-practices-extensions/extension-development-best-practices.md*

# WooCommerce extension development best practices

Want to create a plugin to extend WooCommerce? You're in the right place.

WooCommerce extensions are the same as regular WordPress plugins. For more information, visit [Writing a plugin](https://developer.wordpress.org/plugins/).

Your WooCommerce extension should:

- Adhere to all WordPress plugin coding standards, as well as [best practice guidelines](https://developer.wordpress.org/plugins/plugin-basics/best-practices/) for harmonious existence within WordPress and alongside other WordPress plugins.
- Have a single core purpose and use WooCommerce features as much as possible.
- Not do anything malicious, illegal, or dishonest - for example, inserting spam links or executable code via third-party systems if not part of the service or  explicitly permitted in the service's terms of use.
- Not subvert or override Marketplace connections in core — for example, extensions cannot create branded top-level menu items or introduce their own telemetry.
- Adhere to WooCommerce [compatibility and interoperability guidelines](https://woocommerce.com/document/marketplace-overview/#section-9).

Merchants make use of WooCommerce extensions daily, and should have a unified and pleasant experience while doing so without advertising invading their WP Admin or store.

## Best Practices

1. **Check if WooCommerce is active**. Most WooCommerce plugins do not need to run unless WooCommerce is already active. [Learn how to check if WooCommerce is active](/docs/extensions/core-concepts/check-if-woo-is-active).
2. **The main plugin file should adopt the name of the plugin**. For example: A plugin with the directory name `plugin-name` would have its main file named `plugin-name.php`.
3. **The text domain should match your plugin directory name**. For example: A plugin with a directory name of `plugin-name` would have the text domain `plugin-name`. Do not use underscores. 
4. **Internationalization**: Follow guidelines for [Internationalization for WordPress Developers](https://codex.wordpress.org/I18n_for_WordPress_Developers)
5. **Localization**: All text strings within the plugin code should be in English. This is the WordPress default locale, and English should always be the first language. If your plugin is intended for a specific market (e.g., Spain or Italy), include appropriate translation files for those languages within your plugin package. Learn more at [Using Makepot to translate your plugin](https://codex.wordpress.org/I18n_for_WordPress_Developers#Translating_Plugins_and_Themes).
6. **Follow WordPress PHP Guidelines**. WordPress has a [set of guidelines](http://make.wordpress.org/core/handbook/coding-standards/php/) to keep all WordPress code consistent and easy to read. This includes quotes, indentation, brace style, shorthand php tags, yoda conditions, naming conventions, and more. Please review the guidelines.
7. **Avoid creating custom database tables**. Whenever possible, use WordPress [post types](http://codex.wordpress.org/Post_Types#Custom_Post_Types), [taxonomies](http://codex.wordpress.org/Taxonomies), and [options](http://codex.wordpress.org/Creating_Options_Pages). For more, check out our [primer on data storage](/docs/best-practices/data-management/data-storage).
8. **Prevent Data Leaks** by ensuring you aren't providing direct access to PHP files. [Find out how](/docs/best-practices/security/prevent-data-leaks). 
9. **All plugins need a [standard WordPress README](http://wordpress.org/plugins/about/readme.txt)**. See an example in the [WordPress plugin README file standard](https://wordpress.org/plugins/readme.txt).
10. **All plugins need a changelog file.** See an example of a changelog file and different changelog entry types in the [changelog.txt documentation](/docs/extensions/core-concepts/changelog-txt).
11. **Follow our conventions for your Plugin header comment**. View our [example WordPress plugin header comment](/docs/extensions/core-concepts/example-header-plugin-comment) and follow the conventions listed, including: `Author:`,  `Author URI:` , `Developer:`, `Developer URI`, `WC requires at least:`and `WC tested up to:`, and `Plugin URI:`.
12. **Make it extensible**: use WordPress actions and filters to allow for modification/customization, and if your plugin creates a front-end output, we recommend having a templating engine in place so users can create custom template files in their theme's WooCommerce folder to overwrite the plugin's template files.For more information, check out Pippin's post on [Writing Extensible Plugins with Actions and Filters](http://code.tutsplus.com/tutorials/writing-extensible-plugins-with-actions-and-filters--wp-26759).
13. **Avoid external libraries**. The use of entire external libraries is typically not suggested as this can open up the product to security vulnerabilities. If an external library is absolutely necessary, developers should be thoughtful about the code used and assume ownership as well as of responsibility for it. Try to  only include the strictly necessary part of the library, or use a WordPress-friendly version or opt to build your own version. For example, if needing to use a text editor such as TinyMCE, we recommend using the WordPress-friendly version, TinyMCE Advanced.
14. **Avoid third-party systems**: Loading code from documented services is allowed, but communication must be secure. Executing outside code within a plugin is not allowed. Using third-party CDNs for non-service-related JavaScript and CSS is prohibited. Iframes should not be used to connect admin pages.
15. **Remove unused code**. With version control, there's no reason to leave commented-out code; it's annoying to scroll through and read. Remove it and add it back later if needed.
16. **Use Comments** to describe the functions of your code. If you have a function, what does the function do? There should be comments for most if not all functions in your code. Someone/You may want to modify the plugin, and comments are helpful for that. We recommend using [PHP Doc Blocks](http://en.wikipedia.org/wiki/PHPDoc) similar to [WooCommerce](https://github.com/woocommerce/woocommerce/).
17. **Avoid God Objects**. [God Objects](http://en.wikipedia.org/wiki/God_object) are objects that know or do too much. The point of object-oriented programming is to take a large problem and break it into smaller parts. When functions do too much, it's hard to follow their logic, making bugs harder to fix. Instead of having massive functions, break them down into smaller pieces.
18. **Separate Business Logic & Presentation Logic.** It's a good practice to separate business logic (i.e., how the plugin works) from [presentation logic](http://en.wikipedia.org/wiki/Presentation_logic) (i.e., how it looks). Two separate pieces of logic are more easily maintained and swapped if necessary. An example is to have two different classes - one for displaying the end results, and one for the admin settings page.
19. **Use Transients to Store Offsite Information**. If you provide a service via an API, it's best to store that information so future queries can be done faster and the load on your service is lessened. [WordPress transients](http://codex.wordpress.org/Transients_API) can be used to store data for a certain amount of time.
20. **Log data that can be useful for debugging purposes**, with two conditions: Allow any logging as an 'opt in', and  Use the [WC_Logger](https://woocommerce.com/wc-apidocs/class-WC_Logger.html) class. A user can then view logs on their system status page. Learn [how to add a link to logged data](/docs/code-snippets/link-to-logged-data) in your extension. 
21. **Test Your Code with [WP_DEBUG](http://codex.wordpress.org/Debugging_in_WordPress)** mode on, so you can see all PHP warnings sent to the screen. This will flag things like making sure a variable is set before checking the value.
22. **Integrate the [Quality Insights Toolkit (QIT)](https://qit.woo.com/docs/) into your development workflow**: The QIT allows the ability to test your extensions against new releases of PHP, WooCommerce, and WordPress, as well as other active extensions, at the same time. Additionally, the toolkit includes a [command-line interface (CLI) tool](https://qit.woo.com/docs/installation-setup/cli-installation) that allows you to run and view tests against development builds. This helps to catch errors before releasing a new version.
23. **Never use internal WooCommerce code in your extensions**. Classes in the `Automattic\WooCommerce\Internal` namespace and code marked with `@internal` annotations are for WooCommerce core use only. **Backwards compatibility is not guaranteed** for internal code: it may change, be renamed, or be removed in any future release. Using internal code in your extension may cause it to break when merchants update WooCommerce. See the [Internal namespace documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/README.md) for details.


---

## GDPR compliance guidelines for WooCommerce extensions

*Source: extensions/best-practices-extensions/gdpr-compliance.md*

# GDPR compliance guidelines for WooCommerce extensions

## Introduction

The General Data Protection Regulation (GDPR) is in effect, granting EU residents increased rights over their personal data. Developers must ensure that WooCommerce extensions are compliant with these regulations.

## Data sharing and collection

### Third-party data sharing

- Assess and document any third-party data sharing.
- Obtain and manage user consent for data sharing.
- Link to third-party privacy policies in your plugin settings.

### Data collection

- List the personal data your plugin collects.
- Secure consent for data collection and manage user preferences.
- Safeguard data storage and restrict access to authorized personnel.

## Data access and storage

### Accessing personal data

- Specify what personal data your plugin accesses from WooCommerce orders.
- Justify the necessity for accessing each type of data.
- Control access to personal data based on user roles and permissions.

### Storing personal data

- Explain your data storage mechanisms and locations.
- Apply encryption to protect stored personal data.
- Perform regular security audits.

## Personal data handling

### Data Exporter and erasure hooks

- Integrate data exporter and erasure hooks to comply with user requests.
- Create a user-friendly interface for data management requests.

### Refusal of data erasure

- Define clear protocols for instances where data erasure is refused.
- Communicate these protocols transparently to users.

## Frontend and backend data exposure

### Data on the frontend

- Minimize personal data displayed on the site's frontend.
- Provide configurable settings for data visibility based on user status.

### Data in REST API rndpoints

- Ensure REST API endpoints are secure and disclose personal data only as necessary.
- Establish clear permissions for accessing personal data via the API.

## Privacy documentation and data management

### Privacy policy documentation

- Maintain an up-to-date privacy policy detailing your plugin's data handling.
- Include browser storage methods and third-party data sharing in your documentation.

### Data cleanup

- Implement data cleanup protocols for plugin uninstallation and deletion of orders/users.
- Automate personal data removal processes where appropriate.

## Conclusion

- Keep a record of GDPR compliance measures and make them accessible to users.
- Update your privacy policy regularly to align with any changes in data processing activities.


---

## Privacy Standards for WooCommerce extensions

*Source: extensions/best-practices-extensions/privacy-standards.md*

# Privacy Standards for WooCommerce extensions

Privacy and data protection are becoming increasingly important online, and WooCommerce extensions are no exception. This document outlines the key markers of quality regarding privacy for WooCommerce extensions, the current methods for testing compliance, and the standards developers should adhere to ensure user trust and legal compliance.

## Standards for privacy

To maintain high privacy standards, developers of WooCommerce extensions should adhere to the following:

### Presence of privacy policy page

- A privacy policy should be readily available and easy to understand. It must clearly describe the types of data collected by the extension, the purpose of data collection, how data is processed and stored, and the users' rights concerning their data.

### No unauthorized external requests

- All resources required by the extension should be hosted within the plugin folder/zip file unless there's a clear, justified reason for external requests, which should then be disclosed in the privacy policy.
- Unauthorized or undisclosed external requests, especially those that could expose user data to third-party services without consent, are strictly against privacy standards.

### GDPR compliance

For guidance on ensuring your WooCommerce extension complies with the General Data Protection Regulation (GDPR), please refer to our detailed documentation on [GDPR compliance](./gdpr-compliance.md).

## Conclusion

Adhering to privacy standards is essential for WooCommerce extension developers to build trust with users and ensure compliance with legal requirements. By establishing a clear privacy policy and avoiding unauthorized external requests, developers can demonstrate their commitment to privacy and data protection. Regular testing and compliance checks will help maintain these standards and protect user data effectively.


---

## Support and documentation for WooCommerce extensions

*Source: extensions/best-practices-extensions/support-and-documentation.md*

# Support and documentation for WooCommerce extensions

Effective support and comprehensive documentation are fundamental to the success of any WooCommerce extension. They not only enhance the user experience but also facilitate easier maintenance and development. This document outlines the best practices for creating documentation, providing support, and establishing feedback mechanisms.

## Creating effective documentation

Good documentation serves as a guide, helping users understand and utilize your extension to its full potential. It can significantly reduce the volume of support requests by answering common questions and troubleshooting typical issues.

### Importance of good documentation

- **User Autonomy**: Allows users to solve problems independently.
- **Reduced Support Load**: Comprehensive documentation can answer many user questions, reducing the need for direct support.
- **Improved User Satisfaction**: Users are more satisfied with the product when they can easily find information.

### How to create effective documentation

- **User-friendly language**: Write in clear, simple language accessible to users of all skill levels.
- **Comprehensive coverage**: Cover all features of your extension, including setup, configuration, troubleshooting, and FAQs.
- **Accessibility**: Ensure documentation is easy to navigate with a clear structure and search functionality.
- **Regular updates**: Keep the documentation up to date with the latest version of the extension.

### Standards for documentation

- **Presence of public documentation**: Ensure that users have access to basic documentation that covers essential information about the extension.
- **Quality of public documentation**: Documentation should be clear, concise, and free of technical jargon.
- **Developer-oriented documentation**: Provide detailed documentation aimed at developers who wish to extend or integrate with your extension.
- **Advanced internal documentation**: Maintain in-depth documentation for internal use, covering complex features and developer notes.

## Providing support

Offering timely and effective support is crucial for resolving user issues and maintaining a positive reputation.

### Best practices for offering support

- **Service level agreements (SLA)**: Establish clear SLAs for response times to manage user expectations.
- **Knowledgeable staff**: Ensure your team is well-trained and familiar with the extension and common issues.
- **Proactive support**: Monitor for common issues and reach out to users who might be affected.

### Standards for support

- **Support - SLA**: Define an SLA for how quickly support requests will be acknowledged and resolved.
- **Support quality**: Regularly review support interactions to ensure quality, accuracy, and helpfulness.

## Feedback mechanisms

Feedback is invaluable for continuous improvement of your extension and support services.

### How to establish and utilize feedback channels

- **Surveys and feedback forms**: Implement post-support surveys and feedback forms on your documentation pages.
- **Community forums**: Engage with users on community forums where they can share feedback, ask questions, and offer suggestions.
- **Social media and email**: Encourage feedback through social media channels and support emails.

### Utilizing feedback to improve

- **Act on feedback**: Regularly review feedback to identify areas for improvement in your extension and support services.
- **Update documentation**: Use feedback to fill gaps in your documentation and clarify existing content.
- **Train support staff**: Use common questions and feedback to train your support staff and improve their knowledge base.

## Conclusion

Support and documentation are critical components of the overall user experience for WooCommerce extensions. By investing in high-quality documentation, providing excellent support, and actively seeking and utilizing user feedback, developers can enhance user satisfaction, reduce support workload, and continuously improve their extensions.


---

## Core concepts

*Source: extensions/core-concepts/README.md*

# Core concepts

This section covers the fundamental principles, best practices, and essential knowledge you need to develop robust, maintainable WooCommerce extensions.

Learn about everything from basic setup and architecture to advanced development patterns. Whether you're building your first WooCommerce extension or maintaining existing ones, these guides will help you follow best practices and create high-quality code.

## Getting started

[Check if WooCommerce is active](./check-if-woo-is-active.md) to learn the proper way to ensure WooCommerce is installed and active before your code runs. This prevents errors and ensures your extension works reliably. You'll also want to understand the [core WooCommerce classes](./class-reference.md) and how to work with them, from the main `WooCommerce` class to `WC_Product`, `WC_Customer`, and `WC_Cart`.

## Internal code boundaries

WooCommerce contains both public APIs intended for extension use and internal infrastructure code. **Extensions must not use internal code**, as backwards compatibility between WooCommerce releases is not guaranteed:

- **Internal namespace**: All classes under `Automattic\WooCommerce\Internal` are internal infrastructure.
- **@internal annotations**: Code entities (classes, methods, hooks) marked with `@internal` in their docblocks.

Using internal code may cause your extension to break when merchants update WooCommerce. See the [extension development best practices](../best-practices-extensions/extension-development-best-practices.md) and the [Internal namespace documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/README.md) for details.

## Development patterns

[Adding actions and filters](./adding-actions-and-filters.md) to master the art of extending WooCommerce through hooks. Learn when and how to add actions and filters, following WordPress and WooCommerce standards. For long-term success, discover strategies for [writing maintainable code](./maintainability.md) and establishing update processes that keep your extensions current and secure. You'll also need to [manage deactivation and uninstallation](./handling-deactivation-and-uninstallation.md) to ensure your extension cleans up properly when deactivated or uninstalled, including scheduled actions, admin notes, and tasks.

## Plugin structure and standards

See the [example header plugin comment](./example-header-plugin-comment.md) format for your extension's main plugin file header, including all required metadata. You'll also want to learn the standard [changelog format](./changelog-txt.md) for documenting changes in your extension's changelog file, and understand the [WooCommerce plugin API callback](./woocommerce-plugin-api-callback.md) for proper integration with WooCommerce's plugin API for seamless functionality.



---

## How to add actions and filters

*Source: extensions/core-concepts/adding-actions-and-filters.md*

# How to add actions and filters

Like many WordPress plugins, WooCommerce provides a range of actions and filters through which developers can extend and modify the platform.

Often, when writing new code or revising existing code, there is a desire to add new hooks-but this should always be done with thoughtfulness and care. This document aims to provide high-level guidance on the matter.

Practices we generally allow, support and encourage include:

* [Using existing hooks (or other alternatives) in preference to adding new hooks](#prefer-existing-hooks-or-other-alternatives)
* [Adding lifecycle hooks](#adding-lifecycle-hooks)
* [Optional escape hooks](#escape-hooks)
* [Modifying the inputs and outputs of global rendering functions](#modifying-function-input-and-output-global-rendering-functions)
* [Preferring the passing of objects over IDs](#prefer-passing-objects-over-ids)

On the flip side, there are several practices we discourage:

* [Tying lifecycle hooks to methods of execution](#tying-lifecycle-hooks-to-methods-of-execution)
* [Using filters as feature flags](#using-filters-as-feature-flags)
* [Placing filter hooks inside templates and data stores](#placement-of-filter-hooks)
* [Enumeration values within hook names](#enumeration-values-inside-hook-names)

Beyond those items, we generally otherwise adhere to WordPress coding standards. In regards to hooks, that specifically means following the:

* [Documentation standards for hooks](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#4-hooks-actions-and-filters)
* [Guidance on Dynamic hook names](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#interpolation-for-naming-dynamic-hooks)

Please note that we provide example code throughout this guide to help illustrate some of the principles. However, to keep things concise, we usually omit unnecessary detail, including doc blocks (in practice, though, hooks should always be accompanied by doc blocks!).

## Prefer existing hooks (or other alternatives)

Hooks come with a long-term obligation: the last thing we want is to add a new hook that developers come to depend on, only to strip it away again. However, this can lead to difficulties when the time comes to refactor a piece of code that contains hooks, sometimes delaying meaningful change or limiting how easily we can implement a change without compromising on backward compatibility commitments.

For those reasons, we always prefer that-wherever reasonable-an existing hook or alternative approach in preference to adding a new hook.

## Adding lifecycle hooks

Lifecycle hooks can be used to communicate that a lifecycle event is about to start, or that it has concluded. Examples of such events include:

* Main product loop
* Dispatching emails
* Rendering a template
* Product or order status changes

In general, lifecycle hooks:

* Come in pairs ('before' and 'after')
* Are always actions, never filters
* The 'before' hook will generally always provide callbacks with the arguments array, if there is one
* The 'after' hook will generally also provide callbacks with the function's return value, if there is one

Note that lifecycle hooks primarily exist to let other systems observe, rather than to modify the result. Of course, this does not stop the function author from additionally providing a filter hook that serves this function.

For example, noting that it is the process of fetching the promotions which we view as the "lifecycle event", and not the function itself:

```php
function woocommerce_get_current_promotions( ...$args ) {
    /* Any initial prep, then first lifecycle hook... */
    do_action( 'woocommerce_before_get_current_promotions', $args );
    /* ...Do actual work, then final lifecycle hook... */
    do_action( 'woocommerce_after_get_current_promotions', $result, $args );
    /* ...Return the result, optionally via a filter... */
    return apply_filters( 'woocommerce_get_current_promotions', $result, $args );
}
```

## Escape hooks

In some cases, it may be appropriate to support short-circuiting of functions or methods. This is what we call an escape hook, and can be useful as a means of overriding code when a better way of doing so is not available.

* Escape hooks are always filters
* They should always supply null as the initial filterable value
* If the value is changed to a non-null value, then the function should exit early by returning that new value

For type safety, care should be taken to ensure that, if a function is short-circuited, the return type matches the function signature and/or return type stated in the function doc block.

Example:

```php
function get_product_metrics( $args ): array {
    $pre = apply_filters( 'pre_woocommerce_get_product_metrics', null, $args );

    if ( $pre !== null ) {
        return (array) $pre;
    }

    /* ...Default logic... */
    return $metrics;
}
```

## Modifying function input and output (global rendering functions)

In the case of global rendering or formatting functions (so-called "template tags"), where it is not readily possible to implement better alternatives, it is permissible to add filters for both the function arguments and the function's return value.

This should be done sparingly, and only where necessary. Remember that while providing opportunities for other components to perform extensive customization, it can potentially derail other components which expect unmodified output.

Example:

```php
function woocommerce_format_sale_price( ...$args ): string {
    /* Prep to fill in any missing $args values... */
    $args = (array) apply_filters( 'woocommerce_format_sale_price_args', $args );
    /* ...Actual work to determine the $price string... */
    return (string) apply_filters( 'woocommerce_format_sale_price', $price, $args );
}
```

## Prefer passing objects over IDs

Some actions or filters provide an object ID (such as a product ID) as their primary value, while others will provide the actual object itself (such as a product object). For consistency, it is preferred that objects be passed.

Example:

```php
function get_featured_product_for_current_customer( ) {
    /* ...Logic to find the featured product for this customer... */

    return apply_filters( 
        'woocommerce_featured_product_for_current_customer', 
        $product, /* WC_Product */
        $customer 
    );
}
```

## Tying lifecycle hooks to methods of execution

There can sometimes be multiple paths leading to the same action. For instance, an order can be updated via the REST API, through the admin environment, or on the front end. It may additionally happen via ajax, or via a regular request.

It is important however not to tie hooks for high-level processes to specific execution paths. For example, an action that fires when an order is created must not only be fired when this happens in the admin environment via an ajax request.

Instead, prefer a more generic hook that passes context about the method of execution to the callback.

Example of what we wish to avoid:

```php
/**
 * Pretend this function is only called following an ajax request
 * (perhaps it is itself hooked in using a `wp_ajax_*` action).
 */
function on_ajax_order_creation() {
    /* Avoid this! */
    do_action( 'woocommerce_on_order_creation' );
}
```

## Using filters as feature flags

It is sometimes tempting to use a filter as a sort of feature flag, that enables or disables a piece of functionality. This should be avoided! Prefer using an option:

* Options persist in the database.
* Options are already filterable (ideal for a temporary override).

Example of what we wish to avoid:

```php
/* Avoid this */
$super_products_enabled = (bool) apply_filters( 'woocommerce_super_products_are_enabled', true );

/* Prefer this */
$super_products_enabled = get_option( 'woocommerce_super_products_are_enabled', 'no' ) === 'yes';
```

## Placement of filter hooks

Filters should not be placed inside templates-only actions. If it is important that a value used within a template be filterable, then the relevant logic should be moved to whichever function or method decides to load the template-the result being passed in as a template variable.

It is also preferred that filter hooks not be placed inside data-store classes, as this can reduce the integrity of those components: since, by design, they are replaceable by custom implementations-the risk of accidentally breaking those custom stores is higher.

## Enumeration values inside hook names

Though there is a case for dynamic hook names (where part of the hook name is created using a variable), a good rule of thumb is to avoid this if the variable contains what might be considered an enumeration value.

This might for instance include a case where an error code forms part of the hook name.

Example (of what we wish to avoid):

```php
if ( is_wp_error( $result ) ) {
    /* Avoid this */
    $error_code = $result->get_error_code();
    do_action( "woocommerce_foo_bar_{$error_code}_problem", $intermediate_result );
    
    /* Prefer this */
    do_action( 'woocommerce_foo_bar_problem', $result );
}
```

The primary reason for avoiding this is that the more values there are in the enumeration set, the more filters developers have to include in their code.

## Summary

This document is a high-level guide to the inclusion and placement of hooks, not an exhaustive list. There will occasionally be exceptions, and there may be good rules and methodologies we are missing: if you have suggestions or ideas for improvement, please reach out!


---

## Formatting for Changelog.txt

*Source: extensions/core-concepts/changelog-txt.md*

# Formatting for Changelog.txt

## The changelog.txt file

WooCommerce extensions use a standard changelog format. A changelog.txt file is required for extensions on the WooCommerce Marketplace.

Your `changelog.txt` file should look like this:

```php
*** WooCommerce Extension Name Changelog ***

YYYY-MM-DD - version 1.1.0
* Added - Useful new feature
    * A second new feature
    * A third new feature
* Fixed - Important bug fix
* Update - Compatibility with latest version

YYYY-MM-DD - version 1.0.1
* Fixed a bug

YYYY-MM-DD - version 1.0.0
* Initial release
```

## Changelog entry types

To showcase the different types of work done in a product update, use any of the following words to denote what type of change each line is:

- add
- added
- feature
- new
- developer
- dev
- tweak
- changed
- update
- delete
- remove
- fixed
- fix

## Changelog nesting

Items indented under a specific entry type can nest additional changes of the same type in a single-level list. 

## Example changelog.txt

This is how a parsed changelog appears in a modal on WooCommerce.com, with each entry type replaced by an icon. Changelog entries without a type are displayed with the Other icon, while nested entries have no icon. 

![Example changelog as shown on WooCommerce.com](https://woocommerce.com/wp-content/uploads/2025/11/changelog-formatting.png)


---

## How to check if WooCommerce is active

*Source: extensions/core-concepts/check-if-woo-is-active.md*

# How to check if WooCommerce is active

When developing for WooCommerce, ensuring that WooCommerce is installed and active before your code runs is crucial. This prevents errors related to missing WooCommerce functions or classes.

There are a few methods to achieve this. The first is to execute your code on the `woocommerce_loaded` action. This approach guarantees that WooCommerce and its functionalities are fully loaded and available for use. This is fired around the same time as the core `plugins_loaded` action. 

```php
add_action( 'woocommerce_loaded', 'prefix_woocommerce_loaded' );

function prefix_woocommerce_loaded() {
	// Custom code here. WooCommerce is active and all plugins have been loaded...
}
```

**Note**: At this stage, WordPress has not yet initialized the current user data.

Another method is to execute your code on the `woocommerce_init` action. This is executed right _after_ WooCommerce is active and initialized. This action (and the `before_woocommerce_init` action) fires in the context of the WordPress `init` action so at this point current user data has been initialized.

```php
add_action( 'woocommerce_init', 'prefix_woocommerce_init' );

function prefix_woocommerce_init() {
	// Custom code here. WooCommerce is active and initialized...
}
```

**Note**: The `before_woocommerce_init` hook is also an option, running just _before_ WooCommerce's initialization

Using the above hooks grants access to WooCommerce functions, enabling further condition checks. For instance, you might want to verify WooCommerce's version to ensure compatibility with your code:

```php
add_action( 'woocommerce_init', 'prefix_woocommerce_init' );

function prefix_woocommerce_init() {
	// Only continue if we have access to version 8.7.0 or higher.
	if ( version_compare( wc()->version, '8.7.0', '<' ) ) {
		return;
	}

	// Custom code here. WooCommerce is active and initialized...
}
```

Choosing the right hook based on your development needs ensures your WooCommerce extensions or customizations work seamlessly and efficiently.


---

## Classes in WooCommerce

*Source: extensions/core-concepts/class-reference.md*

# Classes in WooCommerce

## List of Classes in WooCommerce

For a list of Classes in WooCommerce, please see the [WooCommerce Code Reference](https://woocommerce.github.io/code-reference/packages/WooCommerce-Classes.html).

## Common Classes

### WooCommerce

The main class is `woocommerce` which is available globally via the `$woocommerce` variable. This handles the main functions of WooCommerce and init's other classes, stores site-wide variables, and handles error/success messages. The woocommerce class initializes the following classes when constructed:

-   `WC_Query` - stored in `$woocommerce->query`
-   `WC_Customer` - stored in `$woocommerce->customer`
-   `WC_Shipping` - stored in `$woocommerce->shipping`
-   `WC_Payment_Gateways` - stored in `$woocommerce->payment_gateways`
-   `WC_Countries` - stored in `$woocommerce->countries`

Other classes are auto-loaded on demand.

View the [WooCommerce Class Code Reference](https://woocommerce.github.io/code-reference/classes/WooCommerce.html) for a full list of methods contained in this class.

### WC_Product

WooCommerce has several product classes responsible for loading and outputting product data. This can be loaded through PHP using:

`$product = wc_get_product( $post->ID );`

In the loop this is not always necessary since calling  `the_post()` will automatically populate the global  `$product` variable if the post is a product.

View the [WC_Product Code Reference](https://woocommerce.github.io/code-reference/classes/WC-Product.html) for a full list of methods contained in this class.

### WC_Customer

The customer class allows you to get data about the current customer, for example:

```php
global $woocommerce;
$customer_country = $woocommerce->customer->get_country();
```

View the [WC_Customer Code Reference](https://woocommerce.github.io/code-reference/classes/WC-Customer.html) for a full list of methods contained in this class.

### WC_Cart

The cart class loads and stores the users cart data in a session. For example, to get the cart subtotal you could use:

```php
global $woocommerce;
$cart_subtotal = $woocommerce->cart->get_cart_subtotal();
```

View the [WC_Cart Code Reference](https://woocommerce.github.io/code-reference/classes/WC-Cart.html) for a full list of methods contained in this class.

## Internal Classes (Do Not Use)

WooCommerce contains internal infrastructure code that's **not intended for use by extensions**:

- **`Automattic\WooCommerce\Internal\*`**: All classes in this namespace are internal. Backwards compatibility is not guaranteed: these classes may change, be renamed, or be removed in future releases of WooCommerce.
- **Classes with `@internal` annotations**: Equivalently, any class, method or hook marked with `@internal` in its docblock should not be used by extensions.

Using internal code may cause your extension to break when WooCommerce is updated. Any code that's not internal per the above definition is public and generally safe to use.

For more details, see the [Internal namespace documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/README.md).


---

## Example WordPress plugin header comment for WooCommerce extensions

*Source: extensions/core-concepts/example-header-plugin-comment.md*

# Example WordPress plugin header comment for WooCommerce extensions

This is a WordPress plugin header comment. It's used to provide WordPress with metadata about a plugin. 

```php
/**
* Plugin Name: WooCommerce Extension
* Plugin URI: https://woocommerce.com/products/woocommerce-extension/
* Description: Your extension's description text.
* Version: 1.0.0
* Author: Your Name
* Author URI: http://yourdomain.com/
* Developer: Your Name
* Developer URI: http://yourdomain.com/
* Text Domain: woocommerce-extension
* Domain Path: /languages
*
* WC requires at least: 8.0
* WC tested up to: 8.3
*
* License: GNU General Public License v3.0
* License URI: http://www.gnu.org/licenses/gpl-3.0.html
* Woo: 12345:342928dfsfhsf8429842374wdf4234sfd
*/
```

Here's what each line should contain:

* Plugin Name: The name of your plugin.
* Plugin URI: The home page of the plugin or the product page on WooCommerce.com.
* Description: A short description of the plugin.
* Version: The current version number of the plugin.
* Author: The name of the plugin author.
* Author URI: The author's website or profile page.
* Developer: The name of the developer if different from the author.
* Developer URI: The developer's website or profile page.
* Text Domain: The text domain is used for internationalization.
* Domain Path: The domain path is used to show where the MO files are located.
* WC requires at least: The minimum version of WooCommerce required for the plugin to work.
* WC tested up to: The latest version of WooCommerce that the plugin has been tested with.
* License: The license of the plugin.
* License URI: The URL where the license is explained in detail.
* Woo: A unique identifier for a plugin sold on WooCommerce.com. When submitting your extension or adding a new version, **we will automatically add this to the header of your main file**. You are not required to add it manually, but you can opt to include it before uploading. 

This header comment is placed at the top of the main plugin file, so WordPress can read it.


---

## Managing extension deactivation and uninstallation

*Source: extensions/core-concepts/handling-deactivation-and-uninstallation.md*

# Managing extension deactivation and uninstallation

## Introduction

There are a number of cleanup tasks you'll need to handle when a merchant deactivates or uninstalls your extension. This guide provides a brief overview of WooCommerce-specific items you'll want to make sure you account for when defining your extension's deactivation and uninstallation logic.

## Removing Scheduled Actions

If your extension uses Action Scheduler to queue any background jobs, it's important to unschedule those actions when your extension is uninstalled or deactivated.

`as_unschedule_all_actions( $hook, $args, $group );`

You can read more about using Action Scheduler for managing background processing in the [Action Scheduler API Reference](https://actionscheduler.org/api/).

## Removing Admin Notes

If you have created any Notes for merchants, you should delete those notes when your extension is deactivated or, at the very least, when it is uninstalled.

```php
function my_great_extension_deactivate() {
    ExampleNote::possibly_delete_note();
}
register_deactivation_hook( __FILE__, 'my_great_extension_deactivate' );

```

The example above assumes that you have followed the pattern this guide recommends for creating Notes as dedicated classes that include the `NoteTraits` trait included with WooCommerce Admin. This approach provides your Note with some baked in functionality that streamlines note operations such as creation and deletion.

## Removing Admin Tasks

When your extension is deactivated or uninstalled, you should take care to unregister any tasks that your extension created for merchants.

```php
// Unregister task.
function my_extension_deactivate_task() {
    remove_filter( 'woocommerce_get_registered_extended_tasks', 'my_extension_register_the_task', 10, 1 );
}
 
register_deactivation_hook( __FILE__, 'my_extension_deactivate_task' );
```

Keep in mind that merchant tasks are managed via a hybrid approach that involves both PHP and JavaScript, so the client-side registration only happens when your extension's JavaScript runs.

## Unregistering navigation

When your extension deactivates and uninstalls, any registration you've done with the WooCommerce Navigation will be handled automatically.

## WordPress cleanup tasks

There are additional measures you may need to consider when your extension is deactivated or uninstalled, depending on the types of modifications it makes to the underlying WordPress environment when it activates and runs. You can read more about handling deactivation and uninstallation in the [WordPress Plugin Developer Handbook](https://developer.wordpress.org/plugins/intro/).


---

## Maintaining and updating WooCommerce extensions

*Source: extensions/core-concepts/maintainability.md*

# Maintaining and updating WooCommerce extensions

Maintaining and updating WooCommerce extensions is crucial for ensuring they remain compatible, secure, and functional within the ever-evolving WordPress ecosystem. This document outlines best practices for ensuring easy maintainability, adhering to update frequency and process, and conducting manual update checks.

## Ensuring easy maintainability

Maintainable code is essential for the long-term success of any WooCommerce extension. It ensures that your extension can be easily updated, debugged, and extended, both by you and others in the future.

### Importance of writing maintainable code

- **Future-proofing**: Maintainable code helps in adapting to future WooCommerce and WordPress updates.
- **Collaboration**: Makes it easier for teams to work together on the extension.
- **Cost-effective**: Reduces the time and resources required for adding new features or fixing issues.

### Strategies to achieve maintainability

- **Modular code**: Break down your extension into smaller, focused modules or components.
- **Coding standards**: Follow the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) to ensure consistency.
- **Documentation**: Document your code extensively to explain "why" behind the code, not just "how" to use it.
- **Refactoring**: Regularly refactor your code to improve its structure without altering the external behavior.

## Update frequency and process

Keeping your extension up-to-date is vital for security, compatibility, and performance. Regular updates also signal to users that the extension is actively maintained.

### Best practices for regular updates

- **Scheduled updates**: Plan regular updates (e.g., monthly) to incorporate bug fixes, security patches, and new features.
- **Version control**: Use version control systems like Git to manage changes and collaborate efficiently.
- **Compatibility checks**: Before releasing an update, thoroughly test your extension with the latest versions of WordPress and WooCommerce to ensure compatibility.
- **Changelogs**: Maintain clear changelogs for each update to inform users about new features, fixes, and changes.

### Recommended update frequency

- We recommend that extensions receive an update **at least once every 30 days**. This frequency ensures that extensions can quickly adapt to changes in WooCommerce, WordPress, or PHP, and address any security vulnerabilities or bugs.

## Manual update checks

While automated update systems like the WordPress Plugin Repository offer a way to distribute updates, developers should also have a process for manually tracking and managing updates.

### How developers can manually track and manage updates

- **User feedback**: Monitor forums, support tickets, and user feedback for issues that may require updates.
- **Security monitoring**: Stay informed about the latest security vulnerabilities and ensure your extension is not affected.
- **Performance testing**: Regularly test your extension for performance and optimize it in updates.
- **Compatibility testing**: Manually test your extension with beta releases of WordPress and WooCommerce to anticipate compatibility issues before they arise.

## Conclusion

Maintainability and regular updates are key to the success and longevity of WooCommerce extensions. By writing maintainable code, adhering to a consistent update process, and actively monitoring the extension's performance and compatibility, developers can ensure their products remain valuable and functional for users over time.


---

## WooCommerce Plugin API callbacks

*Source: extensions/core-concepts/woocommerce-plugin-api-callback.md*

# WooCommerce Plugin API callbacks

## Overview

This document provides a guide on how to use the WooCommerce Plugin API to initiate callbacks for plugin actions, especially for gateways and classes not initialized by default.

## Callback URL Structure

Before WooCommerce 2.0, use:

`https://example.com/?wc-api=CALLBACK`

In WooCommerce 2.0 or later, use the endpoint:

`https://example.com/wc-api/CALLBACK/`

## Behavior

When the callback URL is accessed, WooCommerce will:

- Initialize the `CALLBACK` class, if available
- Trigger the `woocommerce_api_callback` action
- Exit WordPress

## Hooking into the API Callback

To hook into the callback, add an action in your plugin:

```php
add_action( 'woocommerce_api_callback', 'your_callback_handler_function' );
```

## Redirecting After Callback

It's possible to redirect users after the action has been executed using your custom handler function.


---

## How to add custom product types to Add Products onboarding list

*Source: extensions/extension-onboarding/adding-custom-products-to-add-products-onboarding-list.md*

# How to add custom product types to Add Products onboarding list

## Introduction

WooCommerce allows developers to extend the product type onboarding list, offering a more customizable and engaging experience during the Add Products onboarding task. This tutorial will guide you through adding custom product types to your WooCommerce store using the `experimental_woocommerce_tasklist_product_types` JavaScript filter.

## Prerequisites

- A basic understanding of JavaScript and PHP.
- WooCommerce 8.8 or later installed on your WordPress site.

## Step 1: Adding a JavaScript Filter

To add a new product type to the onboarding list, we'll utilize the `@wordpress/hooks` package, specifically the addFilter function. If you're not already familiar, `@wordpress/hooks` allows you to modify or extend features within the WordPress and WooCommerce ecosystem without altering the core code.

First, ensure you have the `@wordpress/hooks` package installed. If not, you can add it to your project using `npm` or `yarn`:

`npm install @wordpress/hooks`

or:

`yarn add @wordpress/hooks`

Next, add the following JavaScript code to your project. This code snippet demonstrates how to add a "custom product" type to the onboarding list:

```javascript
/**
* External dependencies
*/
import { addFilter } from '@wordpress/hooks';
import { Icon, chevronRight } from '@wordpress/icons';
import { __ } from '@wordpress/i18n';
import FolderMultipleIcon from 'gridicons/dist/folder-multiple';

addFilter(
   'experimental_woocommerce_tasklist_product_types',
   'custom-product',
   (productTypes) => [
       ...productTypes,
       {
           key: 'custom-product',
           title: __('Custom product', 'custom-product'),
           content: __('Create an awesome custom product.', 'custom-product'),
           before: <FolderMultipleIcon />,
           after: <Icon icon={chevronRight} />,
           onClick: () => {
           }
       },
   ]
);
```

This filter adds a new product type called "Custom Product" with a brief description and icons before and after the title for a visually appealing presentation.

## Step 2: Optional - Customizing the onClick Handler

By default, if no onClick handler is supplied, the onboarding task will utilize the default CSV template handler. To customize this behavior, you can specify your own onClick handler within the product type object.

## Step 3: Modifying the CSV Template Path (Optional)

If you wish to use a different CSV template for your custom product type, you can modify the template path using the woocommerce_product_template_csv_file_path filter in PHP. Here's an example of how to change the template path:

```php
add_filter('woocommerce_product_template_csv_file_path', function($path) {
   // Specify your custom template path here
   return $newPath;
});
```

## Conclusion

With WooCommerce, extending the product type onboarding list is straightforward and offers significant flexibility for customizing the onboarding experience. By following the steps outlined in this tutorial, you can enhance your WooCommerce store and make the Add Products task more relevant and helpful to your specific needs.


---

## How to create custom product tours

*Source: extensions/extension-onboarding/creating-custom-product-tours.md*

# How to create custom product tours

## Introduction

WooCommerce allows developers to extend or replace the product tour, offering a more customizable and engaging experience during product creation. This tutorial will guide you through adding a custom product tour to your WooCommerce store using the `experimental_woocommerce_admin_product_tour_steps` JavaScript filter.

This works in conjunction with the ability to customize the product type onboarding list.

## Prerequisites

- A basic understanding of JavaScript and PHP.
- WooCommerce 8.8 or later installed on your WordPress site.

## Adding a JavaScript Filter

To alter or create a product tour, we'll utilize the `@wordpress/hooks` package, specifically the `addFilter` function. If you're not already familiar, `@wordpress/hooks` allows you to modify or extend features within the WordPress and WooCommerce ecosystem without altering the core code.

First, ensure you have the `@wordpress/hooks` package installed. If not, you can add it to your project using `npm` or `yarn`:

`npm install @wordpress/hooks`

or:

`yarn add @wordpress/hooks`

Next, add the following JavaScript code to your project. This code snippet demonstrates how to replace the product tour with an entire custom one:

```javascript
/**
* External dependencies
*/
import { addFilter } from '@wordpress/hooks';
import { __ } from '@wordpress/i18n';

addFilter(
   experimental_woocommerce_admin_product_tour_steps,
   'custom-product',
   (tourSteps, tourType) => {
	if ('custom-product' !== tourType) {
   		return tourSteps;
}

	return [
		{
		   referenceElements: {
		      desktop: '#title',// The element to highlight
		   },
		   focusElement: {
		      desktop: '#title',// A form element to be focused
		   },
		   meta: {
		      name: 'product-name', // Step name
		      heading: __( 'Product name', 'custom-product' ),
  		      descriptions: {
		         desktop: __(
		            'Start typing your new product name here. This will be what your customers will see in your store.',
		            'custom-product'
		         ),
		      },
		   },
		},
	];
   }
);
```

This filter replaces the entire product tour for a `custom-product` product type. Using built-in JavaScript array manipulation functions, you can also customize the default tour (by altering, adding, or removing steps).

The `tourType` is set by the `tutorial_type` GET parameter.

## Conclusion

With WooCommerce, extending and customizing the product tour is straightforward and offers significant flexibility for customizing the onboarding experience. By following the steps outlined in this tutorial, you can enhance your WooCommerce store and make the Add Products tour more relevant and helpful to your specific needs.


---

## How to implement merchant onboarding

*Source: extensions/extension-onboarding/handling-merchant-onboarding.md*

# How to implement merchant onboarding

## Introduction

Onboarding is a critical part of the merchant's user experience. It helps set them up for success and ensures they're not only using your extension correctly but also getting the most out of it. There are a few especially useful features that you can take advantage of as a developer to help onboard merchants who are using your extension:

- Setup tasks
- Store management links
- Admin notes

---

## Getting started

We'll be using `@woocommerce/create-woo-extension` to scaffold a modern WordPress JavaScript environment for plugins. This tool creates a fully functional development environment for integrating with WooCommerce.

In this example, we'll be using the `add-task` variant to create a basic onboarding extension that we can build upon.

In your `wp-content/plugins` directory, run the following command to create your extension:

```sh
npx @wordpress/create-block -t @woocommerce/create-woo-extension --variant=add-task my-extension-name
```

Navigate to the newly created folder and start development:

```sh
cd my-extension-name
npm run start
```

Optionally, you can use `wp-env` for a local WordPress environment:

```sh
npm -g i @wordpress/env
wp-env start
```

Don't forget to head over to `/wp-admin/plugins.php` and activate your plugin.

## Using setup tasks

Setup tasks appear on the WooCommerce Admin home screen and prompt a merchant to complete certain steps in order to set up your extension. Adding tasks is a two-step process that requires:

- Registering the task (and its JavaScript) using PHP
- Using JavaScript to build the task, set its configuration, and add it to the task list

### Registering the task with PHP

To register your task as an extended task list item, you'll need to start by creating a new PHP class that extends the Task class. This class will define the properties and behavior of your custom task.

```php
<?php
/**
 * Custom task example.
 *
 */
use Automattic\WooCommerce\Admin\Features\OnboardingTasks\Task;

/**
 * Custom task class.
 */
class MyTask extends Task {
	/**
	 * Get the task ID.
	 *
	 * @return string
	 */
	public function get_id() {
		return 'my-task';
	}

	/**
	 * Title.
	 *
	 * @return string
	 */
	public function get_title() {
		return __( 'My task', 'woocommerce' );
	}

	/**
	 * Content.
	 *
	 * @return string
	 */
	public function get_content() {
		return __( 'Add your task description here for display in the task list.', 'woocommerce' );
	}

	/**
	 * Time.
	 *
	 * @return string
	 */
	public function get_time() {
		return __( '2 minutes', 'woocommerce' );
	}
}
```

After defining your custom task class, add it to the task list by calling the `add_task` method on the `TaskLists` class. Please note that you need to call the add_task method before or in the `init` hook because onboarding tasks are registered in the `init` hook.

```php
# Register the task.
function register_custom_task() {
    // Register the task.
    use Automattic\WooCommerce\Admin\Features\OnboardingTasks\TaskLists;

    TaskLists::add_task(
        'extended', // The task list ID (e.g., 'extended' for "Things to do next").
        new MyCustomTask(
            TaskLists::get_list( 'extended' ) // Retrieve the task list object.
        )
    );
}

// Hook the registration function to the 'init' action.
add_action('init', 'register_custom_task');
```

The `TaskList` class represents a task list. It contains properties and methods for managing task list. We currently have three predefined task lists

- `setup`: The default task list
- `extended`: The "Things to do next" task list
- `secret_tasklist`: The "Secret" task list that is used for having tasks that are accessed by other means.

### Adding the task using JavaScript

In addition to registering the task in PHP, You need to build the task component with JavaScript, set its configuration, and add it to the task list. For example, the JavaScript file for a simple task might look something like this:

```js
import { createElement } from '@wordpress/element';
import {
	WooOnboardingTask,
	WooOnboardingTaskListItem,
} from '@woocommerce/onboarding';
import { registerPlugin } from '@wordpress/plugins';

const Task = ( { onComplete, task, query } ) => {
	// Implement your task UI/feature here.
	return <div></div>;
};

registerPlugin( 'add-task-content', {
	render: () => (
		<WooOnboardingTask id="my-task">
			{ ( { onComplete, query, task } ) => (
				<Task onComplete={ onComplete } task={ task } query={ query } />
			) }
		</WooOnboardingTask>
	),
} );

registerPlugin( 'add-task-list-item', {
	scope: 'woocommerce-tasks',
	render: () => (
		<WooOnboardingTaskListItem id="my-task">
			{ ( { defaultTaskItem: DefaultTaskItem } ) => (
				// Add a custom wrapper around the default task item.
				<div
					className="woocommerce-custom-tasklist-item"
					style={ {
						border: '1px solid red',
					} }
				>
					<DefaultTaskItem />
				</div>
			) }
		</WooOnboardingTaskListItem>
	),
} );
```

In the example above, the extension does a few different things. Let's break it down:

#### Handle imports

First, import any functions, components, or other utilities from external dependencies.

```js
import { createElement } from '@wordpress/element';
import {
	WooOnboardingTask,
	WooOnboardingTaskListItem,
} from '@woocommerce/onboarding';
import { registerPlugin } from '@wordpress/plugins';
```

#### Construct the component

Next, we create a [functional component](https://reactjs.org/docs/components-and-props.html) that returns our task card. The intermixed JavaScript/HTML syntax we're using here is called JSX. If you're unfamiliar with it, you can [read more about it in the React docs](https://reactjs.org/docs/introducing-jsx.html).

```js
import { onboardingStore } from '@woocommerce/data';
import { useDispatch } from '@wordpress/data';

const Task = ( { onComplete, task } ) => {
	const { actionTask } = useDispatch( onboardingStore );
	const { isActioned } = task;

	return (
		<Card className="woocommerce-task-card">
			<CardBody>
				{ __(
					"This task's completion status is dependent on being actioned. The action button below will action this task, while the complete button will optimistically complete the task in the task list and redirect back to the task list. Note that in this example, the task must be actioned for completion to persist.",
					'plugin-domain'
				) }{ ' ' }
				<br />
				<br />
				{ __( 'Task actioned status: ', 'plugin-domain' ) }{ ' ' }
				{ isActioned ? 'actioned' : 'not actioned' }
				<br />
				<br />
				<div>
					<button
						onClick={ () => {
							actionTask( 'my-task' );
						} }
					>
						{ __( 'Action task', 'plugin-domain' ) }
					</button>
					<button onClick={ onComplete }>
						{ __( 'Complete', 'plugin-domain' ) }
					</button>
				</div>
			</CardBody>
		</Card>
	);
};
```

In the example above, we're using the `Card` and `CardBody` components to construct our task's component. The `div` inside the `CardBody` uses a [JavaScript expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Expressions) (`{}`) to embed a ternary operator that uses the component's state to determine whether to display the task as complete or incomplete.

#### Register the Plugin for Task Content

Next, we register the Task component as a plugin named "add-task-content" using [SlotFills](https://developer.wordpress.org/block-editor/reference-guides/slotfills/). This plugin nests the Task component within a WooOnboardingTask component and passes the necessary properties. We also specify the scope of the plugin as "woocommerce-tasks" to make it effective only within WooCommerce's task list.

```js
registerPlugin( 'add-task-content', {
	render: () => (
		
			{ ( {
				onComplete,
				// eslint-disable-next-line @typescript-eslint/no-unused-vars
				query,
				task,
			} ) =>  }
		
	),
	scope: 'woocommerce-tasks',
} );
```

#### Register the Plugin for Task List Item Customization

Finally, we register another plugin named "my-task-list-item-plugin." This plugin is used to customize the appearance of task list items. It also targets WooCommerce's task list and wraps the DefaultTaskItem component within a custom wrapper with additional styling.

```js
registerPlugin( 'my-task-list-item-plugin', {
  scope: 'woocommerce-tasks',
  render: () => (
    <WooOnboardingTaskListItem id="my-task">
      { ( { defaultTaskItem: DefaultTaskItem } ) => (
        // Add a custom wrapper around the default task item.
        <div
          className="woocommerce-custom-tasklist-item"
          style={ {
            border: '1px solid red',
          } }
        >
          <DefaultTaskItem />
        </div>
      ) }
    </WooOnboardingTaskListItem>
  ),
} );
```

In summary, the JavaScript file for a simple task extends and customizes the functionality of WooCommerce's task list, allowing users to better manage tasks and personalize the appearance of task list items.

### Registering the task with JavaScript

In addition to registering the task in php, you'll also need to register and enqueue the transpiled JavaScript file containing your task component and its configuration. A common way to do this is to create a dedicated registration function that hooks into the `admin_enqueue_scripts` action in WordPress. Below is an annotated example of how this registration might look:

```php
/**
 * Register the scripts to fill the task content on the frontend.
 */
function add_task_register_script() {
	if (
		! class_exists( 'Automattic\WooCommerce\Internal\Admin\Loader' ) ||
		! \Automattic\WooCommerce\Admin\PageController::is_admin_or_embed_page()
	) {
		return;
	}

	$asset_file = require __DIR__ . '/dist/index.asset.php';
	wp_register_script(
		'add-task',
		plugins_url( '/dist/index.js', __FILE__ ), // task registration JS
		$asset_file['dependencies'],
		$asset_file['version'],
		true
	);

	wp_enqueue_script( 'add-task' );
}

add_action( 'admin_enqueue_scripts', 'add_task_register_script' );
```

By following these steps, your custom task should appear in the WooCommerce onboarding tasklist.

For a complete example of adding a custom task as a WordPress plugin, you can check out the [add-task examples directory](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/client/admin/docs/examples/extensions/add-task).

To learn more about the tasklist, you can refer to the [tasklist documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/admin/docs/features/onboarding-tasks.md).


---

## Using Store Management Links

When a merchant completes all of the items on the onboarding task list, WooCommerce replaces it with a section containing a list of handy store management links. Discoverability can be a challenge for extensions, so this section is a great way to bring more attention to key features of your extension and help merchants navigate to them.

The store management section has a relatively narrow purpose, so this section does not currently support external links. Instead, it is meant for navigating quickly within WooCommerce.

Adding your own store management links is a simple process that involves:

- Installing dependencies for icon support
- Enqueuing an admin script in your PHP
- Hooking in via a JavaScript filter to provide your link object

### Installing the Icons package

Store management links use the `@wordpress/icons` package. If your extension isn't already using it, you'll need to add it to your extension's list of dependencies.

`npm` `install` ` @wordpress``/icons ` `--save`

### Enqueuing the JavaScript

The logic that adds your custom link to the store management section will live in a JavaScript file. We'll register and enqueue that file with WordPress in our PHP file:

```js
function custom_store_management_link() {
    wp_enqueue_script(
        'add-my-custom-link',
        plugins_url( '/dist/add-my-custom-link.js', __FILE__ ),
        array( 'wp-hooks' ),
        10
    );
}
add_action( 'admin_enqueue_scripts', 'custom_store_management_link' );

```

The first argument of this call is a handle, the name by which WordPress will refer to the script we're enqueuing. The second argument is the URL where the script is located.

The third argument is an array of script dependencies. By supplying the `wp-hooks` handle in that array, we're ensuring that our script will have access to the `addFilter` function we'll be using to add our link to WooCommerce's list.

The fourth argument is a priority, which determines the order in which JavaScripts are loaded in WordPress. We're setting a priority of 10 in our example. It's important that your script runs before the store management section is rendered. With that in mind, make sure your priority value is lower than 15 to ensure your link is rendered properly.

### Supply your link via JavaScript

Finally, in the JavaScript file you enqueued above, hook in to the `woocommerce_admin_homescreen_quicklinks` filter and supply your task as a simple JavaScript object.

```js
import { megaphone } from '@wordpress/icons';
import { addFilter } from '@wordpress/hooks';
 
addFilter(
    'woocommerce_admin_homescreen_quicklinks',
    'my-extension',
    ( quickLinks ) => {
        return [
            ...quickLinks,
            {
                title: 'My link',
                href: 'link/to/something',
                icon: megaphone,
            },
        ];
    }
);
```

---

## Using Admin Notes

Admin Notes are meant for displaying insightful information about your WooCommerce store, extensions, activity, and achievements. They're also useful for displaying information that can help with the day-to-day tasks of managing and optimizing a store. A good general rule is to use Admin Notes for information that is:

1.  Timely
2.  Relevant
3.  Useful

With that in mind, you might consider using Admin Notes to celebrate a particular milestone that a merchant has passed, or to provide additional guidance about using a specific feature or flow. Conversely, you shouldn't use Admin Notes to send repeated messages about the same topic or target all users with a note that is only relevant to a subset of merchants. It's okay to use Admin Notes for specific promotions, but you shouldn't abuse the system. Use your best judgement and remember the home screen is meant to highlight a store's most important actionable tasks.

Despite being a part of the new React-powered admin experience in WooCommerce, Admin Notes are available to developers via a standard PHP interface.

The recommended approach for using Admin Notes is to encapsulate your note within its own class that uses the [NoteTraits](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Admin/Notes/NoteTraits.php) trait included with WooCommerce Admin. Below is a simple example of what this might look like:

```php
<?php
/**
 * Simple note provider
 *
 * Adds a note with a timestamp showing when the note was added.
 */
 
namespace My\Wonderfully\Namespaced\Extension\Area;
 
// Exit if this code is accessed outside of WordPress.
defined ( 'ABSPATH' ) || exit;
 
// Check for Admin Note support
if ( ! class_exists( 'Automattic\WooCommerce\Admin\Notes\Notes' ) ||
     ! class_exists( 'Automattic\WooCommerce\Admin\Notes\NoteTraits' )) {
    return;
}
 
// Make sure the WooCommerce Data Store is available
if ( ! class_exists( 'WC_Data_Store' ) ) {
    return;
}
 
 
/**
 * Example note class.
 */
class ExampleNote {
 
    // Use the Note class to create Admin Note objects
    use Automatic\WooCommerce\Admin\Notes\Note;
 
    // Use the NoteTraits trait, which handles common note operations.
    use Automatic\WooCommerce\Admin\Notes\NoteTraits;
 
    // Provide a note name.
    const NOTE_NAME = 'my-prefix-example-note';
 
    public static function get_note() {
    // Our welcome note will include information about when the extension
    // was activated.  This is just for demonstration. You might include
    // other logic here depending on what data your note should contain.
        $activated_time = current_time( 'timestamp', 0 );
        $activated_time_formatted = date( 'F jS', $activated_time );
 
        // Instantiate a new Note object
        $note = new Automattic\WooCommerce\Admin\Notes\Note();
 
        // Set our note's title.
        $note->set_title( 'Getting Started' );
 
        // Set our note's content.
        $note->set_content(
            sprintf(
                'Extension activated on %s.', $activated_time_formatted
            )
        );
 
        // In addition to content, notes also support structured content.
        // You can use this property to re-localize notes on the fly, but
        // that is just one use. You can store other data here too. This
        // is backed by a longtext column in the database.
        $note->set_content_data( (object) array(
            'getting_started'       => true,
            'activated'             => $activated_time,
            'activated_formatted'   => $activated_time_formatted
        ) );
 
        // Set the type of the note. Note types are defined as enum-style
        // constants in the Note class. Available note types are:
        // error, warning, update, info, marketing.
        $note->set_type( Note::E_WC_ADMIN_NOTE_INFORMATIONAL );
 
        // Set the type of layout the note uses. Supported layout types are:
        // 'plain', 'thumbnail'
        $note->set_layout( 'plain' );
 
        // Set the image for the note. This property renders as the src
        // attribute for an img tag, so use a string here.
        $note->set_image( '' );
 
 
        // Set the note name and source.  You should store your extension's
        //   name (slug) in the source property of the note.  You can use
        //   the name property of the note to support multiple sub-types of
        //   notes.  This also gives you a handy way of namespacing your notes.
        $note->set_source( 'inbox-note-example');
        $note->set_name( self::NOTE_NAME );
 
        // Add action buttons to the note.  A note can support 0, 1, or 2 actions.
        //   The first parameter is the action name, which can be used for event handling.
        //   The second parameter renders as the label for the button.
        //   The third parameter is an optional URL for actions that require navigation.
        $note->add_action(
            'settings', 'Open Settings', '?page=wc-settings&tab=general'
        );
        $note->add_action(
            'learn_more', 'Learn More', 'https://example.com'
        );
 
        return $note;
    }
}
 
function my_great_extension_activate() {
    // This uses the functionality from the NoteTraits trait to conditionally add your note if it passes all of the appropriate checks.
    ExampleNote::possibly_add_note();
}
register_activation_hook( __FILE__, 'my_great_extension_activate' );
 
function my_great_extension_deactivate() {
    // This uses the functionality from the NoteTraits trait to conditionally remove your note if it passes all of the appropriate checks.
    ExampleNote::possibly_delete_note();
}
register_deactivation_hook( __FILE__, 'my_great_extension_deactivate' );
```


### Breaking it down

Let's break down the example above to examine what each section does.

#### Namespacing and feature availability checks

First, we're doing some basic namespacing and feature availability checks, along with a safeguard to make sure this file only executes within the WordPress application space.

```php
namespace My\Wonderfully\Namespaced\Extension\Area;
 
defined ( 'ABSPATH' ) || exit;
 
if ( ! class_exists( 'Automattic\WooCommerce\Admin\Notes\Notes') ||
     ! class_exists( 'Automattic\WooCommerce\Admin\Notes\NoteTraits') ) {
    return;
}
 
if ( ! class_exists( 'WC_Data_Store' ) ) {
    return;
}
```

#### Using Note and NoteTraits objects

Next, we define a simple class that will serve as a note provider for our note. To create and manage note objects, we'll import the `Note` and `NotesTraits` classes from WooCommerce Admin.

```php
class ExampleNote {
 
    use Automatic\WooCommerce\Admin\Notes\Note;
    use Automatic\WooCommerce\Admin\Notes\NoteTraits;
 
}
```

#### Provide a unique note name

Before proceeding, create a constant called `NOTE_NAME` and assign a unique note name to it. The `NoteTraits` class uses this constant for queries and note operations.

`const NOTE_NAME = 'my-prefix-example-note';`

#### Configure the note's details

Once you've set your note's name, you can define and configure your note. The `NoteTraits` class will call `self::get_note()` when performing operations, so you should encapsulate your note's instantiation and configuration in a static function called `get_note()` that returns a `Note` object.

```php
public static function get_note() {
    // We'll fill this in with logic that instantiates a Note object
    //   and sets its properties.
}
```

Inside our `get_note()` function, we'll handle any logic for collecting data our Note may need to display. Our example note will include information about when the extension was activated, so this bit of code is just for demonstration. You might include other logic here depending on what data your note should contain.

```php
$activated_time = current_time( 'timestamp', 0);
$activated_time_formatted = date( 'F jS', $activated_time );

```

Next, we'll instantiate a new `Note` object.

`$note = new Note();`

Once we have an instance of the Note class, we can work with its API to set its properties, starting with its title.

`$note->set_title( 'Getting Started' );`

Then we'll use some of the timestamp data we collected above to set the note's content.

```php
$note->set_content(
    sprintf(
        'Extension activated on %s.', $activated_time_formatted
    )
);
```

In addition to regular content, notes also support structured content using the `content_data` property. You can use this property to re-localize notes on the fly, but that is just one use case. You can store other data here too. This is backed by a `longtext` column in the database.

```php
$note->set_content_data( (object) array(
    'getting_started'     => true,
    'activated'           => $activated_time,
    'activated_formatted' => $activated_time_formatted
) );
```

Next, we'll set the note's `type` property. Note types are defined as enum-style class constants in the `Note` class. Available note types are _error_, _warning_, _update_, _info_, and _marketing_. When selecting a note type, be aware that the _error_ and _update_ result in the note being shown as a Store Alert, not in the Inbox. It's best to avoid using these types of notes unless you absolutely need to.

`$note->set_type( Note::E_WC_ADMIN_NOTE_INFORMATIONAL );`

Admin Notes also support a few different layouts. You can specify `banner`, `plain`, or `thumbnail` as the layout. If you're interested in seeing the different layouts in action, take a look at [this simple plugin](https://gist.github.com/octaedro/864315edaf9c6a2a6de71d297be1ed88) that you can install to experiment with them.

We'll choose `plain` as our layout, but it's also the default, so we could leave this property alone and the effect would be the same.

`$note->set_layout( 'plain' );`

If you have an image that you want to add to your Admin Note, you can specify it using the `set_image` function. This property ultimately renders as the `src` attribute on an `img` tag, so use a string here.

`$note->set_image( '' );`

Next, we'll set the values for our Admin Note's `name` and `source` properties. As a best practice, you should store your extension's name (i.e. its slug) in the `source` property of the note. You can use the `name` property to support multiple sub-types of notes. This gives you a handy way of namespacing your notes and managing them at both a high and low level.

```php
$note->set_source( 'inbox-note-example');
$note->set_name( self::NOTE_NAME );
```

Admin Notes can support 0, 1, or 2 actions (buttons). You can use these actions to capture events that trigger asynchronous processes or help the merchant navigate to a particular view to complete a step, or even simply to provide an external link for further information. The `add_action()` function takes up to three arguments. The first is the action name, which can be used for event handling, the second renders as a label for the action's button, and the third is an optional URL for actions that require navigation.

```php
$note->add_action(
    'settings', 'Open Settings', '?page=wc-settings&tab=general'
);
$note->add_action(
    'learn_more', 'Learn More', 'https://example.com'
);
```

Finally, remember to have the `get_note()` function return the configured Note object.

`return $note;`

#### Adding and deleting notes

To add and delete notes, you can use the helper functions that are part of the `NoteTraits` class: `possibly_add_note()` and its counterpart `possibly_delete_note()`. These functions will handle some of the repetitive logic related to note management and will also run checks to help you avoid creating duplicate notes.

Our example extension ties these calls to activation and deactivation hooks for the sake of simplicity. While there are many events for which you may want to add Notes to a merchant's inbox, deleting notes upon deactivation and uninstallation is an important part of managing your extension's lifecycle.

```php
function my_great_extension_activate() {
    ExampleNote::possibly_add_note();
}
register_activation_hook( __FILE__, 'my_great_extension_activate' );
 
function my_great_extension_deactivate() {
    ExampleNote::possibly_delete_note();
}
register_deactivation_hook( __FILE__, 'my_great_extension_deactivate' );

```


---

## Integrating with coming soon mode

*Source: extensions/extension-onboarding/integrating-coming-soon-mode.md*

# Integrating with coming soon mode

This guide provides examples for third-party developers and hosting providers on how to integrate their systems with WooCommerce's coming soon mode. For more details, please read the [developer blog post](https://developer.woocommerce.com/2024/06/18/introducing-coming-soon-mode/). For site visibility settings, please refer to the [admin documentation](https://woocommerce.com/document/configuring-woocommerce-settings/coming-soon-mode/).

## Introduction

WooCommerce's coming soon mode allows you to temporarily make your site invisible to the public while you work on it. This guide will show you how to integrate this feature with your system, clear server cache when site visibility settings change, and sync coming soon mode with other plugins.

## Prerequisites

-   Familiarity with PHP and WordPress development.

## Step-by-step instructions

### Clear server cache on site visibility settings change

When the site's visibility settings change, it may be necessary to clear a server cache to apply the changes and re-cache customer-facing pages. The [`update_option`](https://developer.wordpress.org/reference/hooks/update_option/) hook can be used to achieve this.

```php
add_action( 'update_option_woocommerce_coming_soon', 'clear_server_cache', 10, 3 );
add_action( 'update_option_woocommerce_store_pages_only', 'clear_server_cache', 10, 3 );

function clear_server_cache( $old_value, $new_value, $option ) {
    // Implement your logic to clear the server cache.
    if ( function_exists( 'your_cache_clear_function' ) ) {
        your_cache_clear_function();
    }
}
```

### Clear server cache on template changes

By default, Coming-soon pages are set with `Cache-Control: max-age=60` header. This setting enables CDNs and other caching mechanisms to cache the page for 60 seconds, balancing the need for efficient performance with reasonable update times.

When the user changes the coming soon template, it's recommended that any cache be purged so the changes take effect immediately when the client-side cache expires.

You can use the `save_post_wp_template`, `save_post_wp_template_part`, and `save_post_wp_global_styles` hooks to detect when a template is updated and trigger the cache purge.

```php
add_action( 'save_post_wp_template', 'purge_cache_on_template_change', 10, 3 );
add_action( 'save_post_wp_template_part', 'purge_cache_on_template_change', 10, 3 );
add_action( 'save_post_wp_global_styles', 'purge_cache_on_template_change', 10, 3 );

function purge_cache_on_template_change( $post_id, $post, $update ) {
    // Check if the template is associated with the coming soon mode.
    if ( 'coming-soon' === $post->post_name ) {
        // Implement your logic to clear the server cache.
        if ( function_exists( 'your_cache_clear_function' ) ) {
            your_cache_clear_function();
        }
    }
}
```

### Syncing coming soon mode with other plugins

The coming soon mode can be programmatically synced from a plugin or application. Here are some example use cases:

-   Integrating with a maintenance mode plugin.
-   Integrating with a hosting provider's coming soon mode.

#### Trigger from WooCommerce

You can use the following example to run a code such as setting your plugin's status when coming soon mode option is updated:

```php
add_action( 'update_option_woocommerce_coming_soon', 'sync_coming_soon_to_other_plugins', 10, 3 );

function sync_coming_soon_to_other_plugins( $old_value, $new_value, $option ) {
    $is_enabled = $new_value === 'yes';

    // Implement your logic to sync coming soon status.
    if ( function_exists( 'your_plugin_set_coming_soon' ) ) {
        your_plugin_set_coming_soon( $is_enabled );
    }
}
```

#### Trigger from other plugins

You can use the following example to enable or disable WooCommerce coming soon mode from another plugin by directly updating `woocommerce_coming_soon` option:

```php
function sync_coming_soon_from_other_plugins( $is_enabled ) {
    // Check user capability.
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( 'You do not have sufficient permissions to access this page.' );
    }

    // Set coming soon mode.
    if ( isset( $is_enabled ) ) {
        update_option( 'woocommerce_coming_soon', $is_enabled ? 'yes' : 'no' );
    }
}
```

#### 2-way sync with plugins

If 2-way sync is needed, use the following example where `update_option` will not recursively call `sync_coming_soon_from_other_plugins`:

```php
add_action( 'update_option_woocommerce_coming_soon', 'sync_coming_soon_to_other_plugins', 10, 3 );

function sync_coming_soon_to_other_plugins( $old_value, $new_value, $option ) {
    $is_enabled = $new_value === 'yes';

    // Implement your logic to sync coming soon status.
    if ( function_exists( 'your_plugin_set_coming_soon' ) ) {
        your_plugin_set_coming_soon( $is_enabled );
    }
}

function sync_coming_soon_from_other_plugins( $is_enabled ) {
    // Check user capability.
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( 'You do not have sufficient permissions to access this page.' );
    }

    if ( isset( $is_enabled ) ) {
        // Temporarily remove the action to prevent a recursive call.
        remove_action( 'update_option_woocommerce_coming_soon', 'sync_coming_soon_to_other_plugins', 10, 3 );

        // Set coming soon mode.
        update_option( 'woocommerce_coming_soon', $is_enabled ? 'yes' : 'no' );

        // Re-add the action.
        add_action( 'update_option_woocommerce_coming_soon', 'sync_coming_soon_to_other_plugins', 10, 3 );
    }
}
```

#### One-way binding with option override

We could also programmatically bind the coming soon option from another plugin by overriding the `woocommerce_coming_soon` option. This is advantageous since it simplifies state management and prevents possible out-of-sync issues.

In the following example, we're binding the coming soon option from another plugin by overriding the `woocommerce_coming_soon` option.

```php
add_filter( 'pre_option_woocommerce_coming_soon', 'override_option_woocommerce_coming_soon' );

function override_option_woocommerce_coming_soon( $current_value ) {
    // Implement your logic to sync coming soon status.
    if ( function_exists( 'your_plugin_is_coming_soon' ) ) {
        return your_plugin_is_coming_soon() ? 'yes' : 'no';
    }
    return $current_value;
}

add_filter( 'pre_update_option_woocommerce_coming_soon', 'override_update_woocommerce_coming_soon', 10, 2 );

function override_update_woocommerce_coming_soon( $new_value, $old_value ) {
    // Check user capability.
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( 'You do not have sufficient permissions to access this page.' );
    }

    // Implement your logic to sync coming soon status.
    if ( function_exists( 'your_plugin_set_coming_soon' ) ) {
        your_plugin_set_coming_soon( $new_value === 'yes' );
    }
}
```

### Custom exclusions filter

It is possible for developers to add custom exclusions that bypass the coming soon protection. This is useful for exclusions like always bypassing the screen on a specific IP address, or making a specific landing page available.

#### Disabling coming soon in all pages

If there is another feature that behaves similarly to WooCommerce's coming soon mode, it can cause unintended conflicts. The coming soon mode can be disabled by excluding all customer-facing pages. The following is an example:

```php
add_filter( 'woocommerce_coming_soon_exclude', function() {
    return true;
}, 10 );
```

#### Disabling coming soon except for a specific page

Use the following example to exclude a certain page based on the page's ID. Replace `<page-id>` with your page identifier:

```php
add_filter( 'woocommerce_coming_soon_exclude', function( $is_excluded ) {
    if ( get_the_ID() === <page-id> ) {
        return true;
    }
    return $is_excluded;
}, 10 );
```

#### Custom share links

The following example shows how to integrate with a custom share code. We recommend using cookies or other storage to persist the access when users navigate across the site:

```php
add_filter( 'woocommerce_coming_soon_exclude', function( $exclude ) {
    // Implement your logic to get and validate share code.
    if ( function_exists( 'your_plugin_get_share_code' ) && function_exists( 'your_plugin_is_valid_share_code' ) ) {
        $share_code = your_plugin_get_share_code();
        if ( your_plugin_is_valid_share_code( $share_code ) ) {
            return true;
        }
    }

    return $exclude;
} );
```

### Extend "Apply to store pages only" setting

When using the `Apply to store pages only` setting, you may want to add a custom page to the list of store pages which will be restricted by coming soon mode. You can use the following example to add a custom page:

```php
add_filter( 'woocommerce_store_pages', function( $pages ) {
    $page = get_page_by_path( 'your-page-slug' );
    if ( $page ) {
        $pages[] = $page->ID;
    }
    return $pages;
} );
```


---

## Get started building extensions

*Source: extensions/getting-started-extensions/README.md*

# Get started building extensions

This section provides guides and resources for building, testing, and distributing WooCommerce extensions.

## Important: Internal vs public code

Not all WooCommerce code is intended for use by extensions. Classes in the `Automattic\WooCommerce\Internal` namespace and code marked with `@internal` are for WooCommerce core use only: backwards compatibility between WooCommerce releases is not guaranteed and your extension may break if you use them. See the [extension development best practices](../best-practices-extensions/extension-development-best-practices.md) and the [Internal namespace documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/README.md).

## Getting started

- [Design a simple extension](/extensions/getting-started-extensions/how-to-design-a-simple-extension) - Learn extension architecture and best practices
- [Build your first extension](/extensions/getting-started-extensions/building-your-first-extension) - Create your first WooCommerce extension
- [Core concepts](/extensions/core-concepts/) - Master fundamental concepts like plugin headers, lifecycle management, and security

## Submit to the WooCommerce Marketplace

Join the WooCommerce Marketplace and get your extension in front of 3.6M+ active stores worldwide.

Learn more about [why extension developers are choosing the WooCommerce Marketplace](https://woocommerce.com/partners/) and [submit your extension](https://woocommerce.com/document/submitting-your-product-to-the-woo-marketplace/)


### Quality Insights Toolkit (QIT)

#### Available to all developers with a WooCommerce.com vendor profile

QIT (Quality Insights Toolkit) is a testing platform developed by WooCommerce for plugins and themes. It allows developers to quickly run a variety of managed tests out-of-the-box, as well as integrate their own custom E2E tests to ensure their extensions are reliable, secure, and compatible.

#### Key features

- **Managed test suites:** Run pre-configured end-to-end tests, activation tests, security scans, PHPStan analysis, API tests, and more
- **Custom E2E testing:** Write and run your own Playwright-based E2E tests directly through QIT
- **Continuous quality checks:** Seamlessly integrate QIT into your development workflows via CLI, GitHub Actions, and more
- **Marketplace integration:** Currently in closed beta for extensions listed on the WooCommerce Marketplace

[Learn more about QIT](https://qit.woo.com/docs/)

## Development tools

- [Extension scaffolds](/getting-started/scaffolding/#extension-scaffolds) - Learn how to scaffold new extensions with our [create-woo-extension](https://www.npmjs.com/package/@woocommerce/create-woo-extension) package.
- [WooCommerce CLI](/wc-cli/cli-overview) - Command-line tools for WooCommerce development


---

## How to build your first extension

*Source: extensions/getting-started-extensions/building-your-first-extension.md*

# How to build your first extension

This guide will teach you how to use [create-woo-extension](https://www.npmjs.com/package/@woocommerce/create-woo-extension) to scaffold a WooCommerce extension. There are various benefits to using create-woo-extension over manually creating one from scratch, including:

There is less boilerplate code to write, and fewer dependencies to manually setup.

Modern features such as Blocks are automatically supported, and unit testing, linting, and Prettier IDE configuration are ready to use.

Once your extension is set up, we will show you how to instantly spin up a development environment using [wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/).

## Requirements

Before getting started, you will need the following tools installed on your device:

- [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) with NPM
- [Docker](https://docs.docker.com/engine/install/) (must be running to use wp-env)
- [Composer](https://getcomposer.org/doc/00-intro.md)

This guide also presumes that you are familiar with working with the command line.

## Bootstrapping Your Extension

Open your terminal and run

```sh
 npx @wordpress/create-block -t @woocommerce/create-woo-extension my-extension-name
```

If you would like to set a custom extension name, you can replace `my-extension-name` with any slug. Please note that your slug must not have any spaces.

If you see a prompt similar to `Need to install the following packages`: `@wordpress/create-block@4.34.0. Ok to proceed?`, press `Y`.

Once the package finishes generating your extension, navigate into the extension folder using 

```sh
 cd my-extension-name
```

You should then install the extension dependencies using `npm install`  and build it using `npm run build`.

Congratulations! You just spun up a WooCommerce extension! Your extension will have the following file structure:

- `my-extension-name`
    - `block.json` - contains metadata used to register your custom blocks with WordPress. Learn more.
    - `build` - the built version of your extension which is generated using npm run build. You shouldn't directly modify any of the files in this folder.
    - `composer.json` - contains a list of your PHP dependencies which is referenced by Composer.
    - `composer.lock` - this file allows you to control when and how to update these dependencies
    - `includes` - The primary purpose of an "includes" folder in PHP development is to store reusable code or files that need to be included or required in multiple parts of a project. This is a PHP developer convention.
    - `languages` - contains POT files that are used to localize your plugin.
    - `my-extension-name.php` - your plugin entry point that registers your plugin with WordPress.
    - `node-modules` - help you form the building blocks of your application and write more structured code
    - `package.json` - is considered the heart of a Node project. It records metadata, and installs functional dependencies, runs scripts, and defines the entry point of your application.
    - `README.md` - An introduction and instructional overview of your application. Any special instructions, updates from the author, and details about the application can be written in text here.
    - `src` - keeps the root directory clean and provides a clear separation between the source code and other assets
    - `tests` - can hold unit tests for your application, keeps them separate from source files
    - `vendor` - holds project dependencies, and 3rd party code that you did not write
    - `webpack.config.js` - webpack is a module bundler. Its main purpose is to bundle JavaScript files for usage in a browser


## Setting Up a Developer Environment

We recommend using `wp-env` to spin up local development environments. You can [learn more about wp-env here](https://make.wordpress.org/core/2020/03/03/wp-env-simple-local-environments-for-wordpress/). If you do not already have wp-env installed locally, you can install it using 
`npm -g i @wordpress/env`.

Once you have installed `wp-env`, and while still inside your `my-extension-name` folder, run `wp-env` start. After a few seconds, a test WordPress site with your WooCommerce and your extension installed will be running on `localhost:8888`.

If you did not set a custom name for your extension, you can visit `wp-admin/admin.php?page=wc-admin&path=%2Fmy-extension-name` to see the settings page generated by /src/index.js. The default username/password combination for `wp-env` is `admin` / `password`.

## Next Steps

Now that you’ve bootstrapped your extension, you can finally add some features! Here are some simple ones you could include:

[How to add a custom field to simple and variable products](https://developer.woocommerce.com/docs/how-to-add-a-custom-field-to-simple-and-variable-products/)

## Reference

[Visit @woocommerce/create-woo-extension on NPM for package reference](https://www.npmjs.com/package/@woocommerce/create-woo-extension)
[Check out wp-env's command reference to learn more about advanced functionality](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#command-reference)


---

## How to design a simple extension

*Source: extensions/getting-started-extensions/how-to-design-a-simple-extension.md*

# How to design a simple extension

## Introduction

Building a WooCommerce extension that provides a first-class experience for merchants and shoppers requires a hybrid development approach combining PHP and modern JavaScript. The PHP handles the lifecycle and server-side operations of your extension, while the modern JavaScript lets you shape the appearance and behavior of its user interface.

## The main plugin file

Your extension's main PHP file is a bootstrapping file. It contains important metadata about your extension that WordPress and WooCommerce use for a number of ecosystem integration processes, and it serves as the primary entry point for your extension's functionality. While there is not a particular rule enforced around naming this file, using a hyphenated version of the plugin name is a common best practice. (i.e. my-extension.php)

## Declaring extension metadata

Your extension's main plugin file should have a header comment that includes a number of important pieces of metadata about your extension. WordPress has a list of [header requirements](https://developer.wordpress.org/plugins/plugin-basics/header-requirements/) to which all plugins must adhere, but there are additional considerations for WooCommerce extensions:

- The `Author` and `Developer` fields are required and should be set to  
  either your name or your company name.

- The `Developer URI` field should be your official webpage URL.

- The `Plugin URI` field should contain the URL of the extension's product page in the WooCommerce Marketplace or the extension's official landing page on your website.

- The `Requires Plugins` field should list the slugs of any required plugins, separated by commas. WooCommerce extensions should require WooCommerce to activate. 

- The `Woo` field is used for extensions listed in the WooCommerce Marketplace. This code is automatically added upon deployment for products sold on WooCommerce.com to facilitate updates. Please don't add it manually, and refrain from adding it to products offered outside of the WooCommerce Marketplace. Including this header in other versions will prevent updates from working.

Below is an example of what the header content might look like for an extension listed in the WooCommerce Marketplace.

```php
/**
 * Plugin Name: My Great Extension for WooCommerce
 * Plugin URI: https://woocommerce.com/products/my-extension-name/
 * Description: Your extension's description text.
 * Version: 1.0.0
 * Author: Your Name
 * Author URI: http://yourdomain.com/
 * Developer: Your Name
 * Developer URI: http://yourdomain.com/
 * Text Domain: my-extension-name
 * Domain Path: /languages
 * Requires Plugins: woocommerce
 *
 * Woo: 12345:342928dfsfhsf8429842374wdf4234sfd
 *
 * License: GNU General Public License v3.0
 * License URI: http://www.gnu.org/licenses/gpl-3.0.html
 */
```

## Preventing data leaks

As a best practice, your extension's PHP files should contain a conditional statement at the top that checks for WordPress' ABSPATH constant. If this constant is not defined, the script should exit.

`defined( 'ABSPATH' ) || exit;`

This check prevents your PHP files from being executed via direct browser access and instead only allows them to be executed from within the WordPress application environment.

## Managing extension lifecycle

Because your main PHP file is the primary point of coupling between your extension and WordPress, you should use it as a hub for managing your extension's lifecycle. At a very basic level, this means handling:

- Activation
- Execution
- Deactivation

Starting with these three broad lifecycle areas, you can begin to break your extension's functionality down further to help maintain a good separation of concerns.

## Handling activation and deactivation

A common pattern in WooCommerce extensions is to create dedicated functions in your main PHP file to serve as activation and deactivation hooks. You then register these hooks with WordPress using the applicable registration function. This tells WordPress to call the function when the plugin is activated or deactivated. Consider the following examples:

```php
function my_extension_activate() {
    // Your activation logic goes here.
}
register_activation_hook( __FILE__, 'my_extension_activate' );
```

```php
function my_extension_deactivate() {
    // Your deactivation logic goes here.
}
register_deactivation_hook( __FILE__, 'my_extension_deactivate' );
```

## Maintaining a separation of concerns

There are numerous ways to organize the code in your extension. You can find a good overview of best practices in the WordPress Plugin Developer Handbook. Regardless of the approach you use for organizing your code, the nature of WordPress' shared application space makes it imperative that you build with an eye toward interoperability. There are a few common principles that will help you optimize your extension and ensure it is a good neighbor to others:

- Use namespacing and prefixing to avoid conflicts with other extensions.
- Use classes to encapsulate your extension's functionality.
- Check for existing declarations, assignments, and implementations.

## The core extension class

As mentioned above, encapsulating different parts of your extension's functionality using classes is an important measure that not only helps with interoperability, but which also makes your code easier to maintain and debug. Your extension may have many different classes, each shouldering some piece of functionality. At a minimum, your extension should define a central class which can handle the setup, initialization and management of a single instance of itself.

## Implementing a singleton pattern

Unless you have a specific reason to create multiple instances of your main class when your extension runs, you should ensure that only one instance exists in the global scope at any time. A common way of doing this is to use a Singleton pattern. There are several ways to go about setting up a singleton in a PHP class. Below is a basic example of a singleton that also implements some of the best practices mentioned above about namespacing and pre-declaration checks:

```php
if ( ! class_exists( 'My_Extension' ) ) :
    /**
     * My Extension core class
     */
    class My_Extension {
        /**
         * The single instance of the class.
         */
        protected static $_instance = null;

        /**
         * Constructor.
         */
        protected function __construct() {
            // Instantiation logic will go here.
        }

        /**
         * Main Extension Instance.
         * Ensures only one instance of the extension is loaded or can be loaded.
         */
        public static function instance() {
            if ( is_null( self::$_instance ) ) {
                self::$_instance = new self();
            }

            return self::$_instance;
        }

        /**
         * Cloning is forbidden.
         */
        public function __clone() {
            // Override this PHP function to prevent unwanted copies of your instance.
            //   Implement your own error or use `wc_doing_it_wrong()`
        }

        /**
         * Unserializing instances of this class is forbidden.
         */
        public function __wakeup() {
            // Override this PHP function to prevent unwanted copies of your instance.
            //   Implement your own error or use `wc_doing_it_wrong()`
        }
    }
endif;
```

Notice that the example class above is designed to be instantiated by calling the static class method `instance()`, which will either return an existing instance of the class or create one and return it. In order to fully protect against unwanted instantiation, it's also necessary to override the built-in magic methods `__clone()` and `__wakeup()`. You can implement your own error logging here or use something like `_doing_it_wrong()` which handles error logging for you. You can also use WooCommerce's wrapper function `wc_doing_it_wrong()` here. Just be sure your code checks that the function exists first.

## Constructor

The example above includes an empty constructor for demonstration. In a real-world WooCommerce extension, however, this constructor should handle a few important tasks:

- Check for an active installation of WooCommerce & other sibling dependencies.

- Call a setup method that loads other files that your class depends on.
- Call an initialization method that gets your class and its dependencies ready to go.

If we build upon our example above, it might look something like this:

```php
protected function __construct() {
    $this->includes();
    $this->init();
    // You might also include post-setup steps such as showing activation notices here.
}
```

## Loading dependencies

The includes() function above is where you'll load other class dependencies, typically via an include or require constructs. A common way of managing and loading external dependencies is to use Composer's autoload feature, but you can also load specific files individually. You can read more about how to autoload external dependencies in the Composer documentation. A basic example of a setup method that uses both Composer and internal inclusion is below.

```php
public function includes() {
    $loader = include_once dirname( __FILE__ ) . '/' . 'vendor/autoload.php';

    if ( ! $loader ) {
        throw new Exception( 'vendor/autoload.php missing please run `composer install`' );
    }

    require_once dirname( __FILE__ ) . '/' . 'includes/my-extension-functions.php';
}
```

## Initialization

The `init()` function above is where you should handle any setup for the classes you loaded in the includes() method. This step is where you'll often perform any initial registration with relevant actions or filters. It's also where you can register and enqueue your extension's JavaScripts and stylesheets.

Here's an example of what your initialization method might look like:

```php
private function init() {
    // Set up cache management.
    new My_Extension_Cache();

    // Initialize REST API.
    new My_Extension_REST_API();

    // Set up email management.
    new My_Extension_Email_Manager();

    // Register with some-action hook
    add_action( 'some-action', 'my-extension-function' );
}
```

There are many different ways that your core class' initialization method might look, depending on the way that you choose to architect your extension. The important concept here is that this function serves as a central point for handling any initial registration and setup that your extension requires in order to respond to web requests going forward.

## Delaying initialization

The WordPress activation hook we set up above with register_activation_hook() may seem like a great place to instantiate our extension's main class, and in some cases it will work. By virtue of being a plugin for a plugin, however, WooCommerce extensions typically require WooCommerce to be loaded in order to function properly, so it's often best to delay instantiation and initialization until after WordPress has loaded other plugins.

To do that, instead of hooking your instantiation to your extension's activation hook, use the plugins_loaded action in WordPress to instantiate your extension's core class and add its singleton to the $GLOBALS array.

```php
function my_extension_initialize() {
    // This is also a great place to check for the existence of the WooCommerce class
    if ( ! class_exists( 'WooCommerce' ) ) {
    // You can handle this situation in a variety of ways,
    //   but adding a WordPress admin notice is often a good tactic.
        return;
    }

    $GLOBALS['my_extension'] = My_Extension::instance();
}
add_action( 'plugins_loaded', 'my_extension_initialize', 10 );
```

In the example above, WordPress will wait until after all plugins have been loaded before trying to instantiate your core class. The third argument in add_action() represents the priority of the function, which ultimately determines the order of execution for functions that hook into the plugins_loaded action. Using a value of 10 here ensures that other WooCommerce-related functionality will run before our extension is instantiated.

## Handling execution

Once your extension is active and initialized, the possibilities are wide open. This is where the proverbial magic happens in an extension, and it's largely up to you to define. While implementing specific functionality is outside the scope of this guide, there are some best practices to keep in mind as you think about how to build out your extension's functionality.

- Keep an event-driven mindset. Merchants and shoppers who use your extension will be interacting with WooCommerce using web requests, so it can be helpful to anchor your extension to some of the critical flows that users follow in WooCommerce.

- Keep business logic and presentation logic separate. This could be as simple as maintaining separate classes for handling back-end processing and front-end rendering.

- Where possible, break functionality into smaller parts and delegate responsibility to dedicated classes instead of building bloated classes and lengthy functions.

You can find detailed documentation of classes and hooks in the WooCommerce Core Code Reference and additional documentation of the REST API endpoints in the WooCommerce REST API Documentation.

## Handling deactivation

The WordPress deactivation hook we set up earlier in our main PHP file with register_deactivation_hook() is a great place to aggregate functionality for any cleanup that you need to handle when a merchant deactivates your extension. In addition to any WordPress-related deactivation tasks your extension needs to do, you should also account for WooCommerce-related cleanup, including:

- Removing Scheduled Actions
- Removing Notes in the Admin Inbox
- Removing Admin Tasks

## Uninstallation

While it's certainly possible to completely reverse everything your extension has created when a merchant deactivates it, it's not advisable nor practical in most cases. Instead, it's best to reserve that behavior for uninstallation.

For handling uninstallation, it's best to follow the guidelines in the WordPress Plugin Handbook.

## Putting it all together

Below is an example of what a main plugin file might look like for a very simple extension:

```php
/**
 * Plugin Name: My Great Extension for WooCommerce
 * Plugin URI: https://woocommerce.com/products/my-extension-name/
 * Description: Your extension's description text.
 * Version: 1.0.0
 * Author: Your Name
 * Author URI: http://yourdomain.com/
 * Developer: Your Name
 * Developer URI: http://yourdomain.com/
 * Text Domain: my-extension-name
 * Domain Path: /languages
 *
 * Woo: 12345:342928dfsfhsf8429842374wdf4234sfd
 *
 * License: GNU General Public License v3.0
 * License URI: http://www.gnu.org/licenses/gpl-3.0.html
 */

defined( 'ABSPATH' ) || exit;

/**
 * Activation and deactivation hooks for WordPress
 */
function myPrefix_extension_activate() {
    // Your activation logic goes here.
}
register_activation_hook( __FILE__, 'myPrefix_extension_activate' );

function myPrefix_extension_deactivate() {
    // Your deactivation logic goes here.

    // Don't forget to:
    // Remove Scheduled Actions
    // Remove Notes in the Admin Inbox
    // Remove Admin Tasks
}
register_deactivation_hook( __FILE__, 'myPrefix_extension_deactivate' );


if ( ! class_exists( 'My_Extension' ) ) :
    /**
     * My Extension core class
     */
    class My_Extension {

        /**
         * The single instance of the class.
         */
        protected static $_instance = null;

        /**
         * Constructor.
         */
        protected function __construct() {
            $this->includes();
            $this->init();
        }

        /**
         * Main Extension Instance.
         */
        public static function instance() {
            if ( is_null( self::$_instance ) ) {
                self::$_instance = new self();
            }
            return self::$_instance;
        }

        /**
         * Cloning is forbidden.
         */
        public function __clone() {
            // Override this PHP function to prevent unwanted copies of your instance.
            //   Implement your own error or use `wc_doing_it_wrong()`
        }

        /**
         * Unserializing instances of this class is forbidden.
         */
        public function __wakeup() {
            // Override this PHP function to prevent unwanted copies of your instance.
            //   Implement your own error or use `wc_doing_it_wrong()`
        }

        /**
        * Function for loading dependencies.
        */
        private function includes() {
            $loader = include_once dirname( __FILE__ ) . '/' . 'vendor/autoload.php';

            if ( ! $loader ) {
                throw new Exception( 'vendor/autoload.php missing please run `composer install`' );
            }

            require_once dirname( __FILE__ ) . '/' . 'includes/my-extension-functions.php';
        }

        /**
         * Function for getting everything set up and ready to run.
         */
        private function init() {

            // Examples include:

            // Set up cache management.
            // new My_Extension_Cache();

            // Initialize REST API.
            // new My_Extension_REST_API();

            // Set up email management.
            // new My_Extension_Email_Manager();

            // Register with some-action hook
            // add_action('some-action', 'my-extension-function');
        }
    }
endif;

/**
 * Function for delaying initialization of the extension until after WooCommerce is loaded.
 */
function my_extension_initialize() {

    // This is also a great place to check for the existence of the WooCommerce class
    if ( ! class_exists( 'WooCommerce' ) ) {
    // You can handle this situation in a variety of ways,
    //   but adding a WordPress admin notice is often a good tactic.
        return;
    }

    $GLOBALS['my_extension'] = My_Extension::instance();
}

add_action( 'plugins_loaded', 'my_extension_initialize', 10 );
```


---

## Review guidelines

*Source: extensions/review-guidelines/README.md*

# Review guidelines

Reviews are an integral part of the online shopping experience, and people installing software pay attention to them. Prospective users of your extensions will likely consider average ratings when making software choices.

Many of today's most popular online review platforms - from Yelp business reviews, to Amazon product reviews - have a range of opinion that can be polarized, with many extremely positive and/or negative reviews, and fewer moderate opinions. This creates a "J-shaped" distribution of reviews that isn't as accurate or as helpful as could be.

WooCommerce.com and WordPress.org both feature reviews heavily, and competing extensions having a higher rating likely have the edge in user choice. 

## Primary considerations around reviews

Requesting more reviews for a extension with major issues will not generate good reviews, and analyzing existing reviews will help surface areas to address before soliciting reviews.

It is extremely rare for users of WordPress plugins to leave reviews organically (.2% of users for WordPress.org leave reviews), which means that there's an untapped market of 99.8% of users of the average plugin.

These plugins are competing with other plugins on the same search terms in the WordPress.org plugin directory, and ratings are a large factor in the ranking algorithm. This is not usually a factor to the same extent on the WooCommerce Marketplace. For instance, WooCommerce's PayPal extension directly competes on all possible keywords with other PayPal extensions on the WordPress.org repository, while it does not compete with other PayPal payments extensions on the Marketplace.


---

## How to request WooCommerce extension reviews

*Source: extensions/review-guidelines/how-to-request-reviews.md*

# How to request WooCommerce extension reviews

## Methods of requesting reviews

### Admin notices

Admin notices are an industry standard method of requesting reviews, but bombarding the admin dashboard with admin notices is not effective. We recommend using restraint in the design of a notice, as well as limiting to a single notice at a time. It's very easy to overwhelm merchants with too many notices, or too intrusive notices.

#### Recommendations

* A good place for an admin notice to review an extension would be to show on the `Plugins` page and extension's settings pages.
* Include a snooze option (or multiple) on your notices with a clear expectation of when the notice will reappear.
* Admin notices should always be always be completely dismissable. They cannot only have a snooze option.
* The options presented in the notice must be phrased carefully to avoid manipulative language.
* Use consistently designed notices so the request for reviews feels like a part of your extension, and looks consistent with WooCommerce's design.

### Direct contact

#### Recommendations

* The most direct route to requesting reviews with the highest chance of being positive is to contact the customer when they are the happiest with the product.
* This can be milestone or time based, following the timing guidelines below.
* The best method for this is either an email or other direct exchange (support chat, call, etc.). This has the highest conversion rate, especially when timed properly so that the customer is happiest.
* This is also extremely effective when you are able to request feedback from specifically qualified merchants, such as merchants that have processed a certain amount with your platform, or who have shipped their first 100 orders using your fulfillment extension, or similar.
* Direct outreach is most likely to be successful if you have ways of targeting users for review requests (merchant account / usage info, etc.), as well as ways to gather the reviews, like sales or marketing teams able to email/call/chat with merchants.

## Messaging for requesting reviews

One method of requesting feedback that we recommend is using the NPS style of review solicitation. This can allow for an increase positive reviews as well as providing the opportunity to assist merchants that are struggling.

NPS-style reviews first ask the user how they rate the product (out of 5 stars), then route them based on their response:

* If they click 4 or 5 stars, ask them to leave a review.
* If they click 1, 2 or 3, tell them we're here to help & ask them to submit a support ticket.

Merchants are significantly more likely to leave a review after a positive support interaction with a support rep who explicitly asked for a review. The language "the best way to thank me is to leave a 5 star review that mentions me in it" or similar tends to work very well - people are more willing to help a person than a produc or company.


---

## Miscellaneous guidelines and advice

*Source: extensions/review-guidelines/misc-guidelines.md*

# Miscellaneous guidelines and advice

Contributors' names matching search terms directly will rank extremely highly on the WordPress.org plugin repo, which means that having a WordPress.org user named after your business (if that's a search term for your plugin) could tilt the scales over a competing plugin.

Constant nags and overwhelming the admin dashboard with unnecessary alerts detract from your user experience.

You can request to have reviews that are not actually feedback removed. Where this might be applicable is if the request is a simple support request, where it's obviously in the wrong spot. 1 star reviews, even if aggressive or angry, are not usually removed.

Reply to reviews! Thank the giver for offering feedback, acknowledge the issue if needed, ask for more specific feedback, or provide an update when that feedback is addressed! Your reviews are a great window into what your extension's users are actually thinking.

Having folks close to the extension's development (think developers and project managers) looking at reviews on a regular basis is a good way to ensure the customers voice is heard. 1 star reviews are among the most useful, as long as the issue is understood and addressed (if needed).


---

## Notifying users about bug fixes and feature requests

*Source: extensions/review-guidelines/notifying-users-about-important-events.md*

# Notifying users about bug fixes and feature requests

A bug or a missing feature can be a showstopper for merchants. Bugs that pile up or popular features that are not implemented can lead to negative reviews and/or merchants churning and looking at a competitive solution.

Bugs are usually reported via support or GitHub, or you can discover them yourselves in testing.

When a critical bug is found, resolve it within a couple of days (most critical bugs should be resolved within 24 hours) and release a new plugin version promptly. Part of your release process should be to notify all stakeholders (the support team and the merchant affected) about the upcoming release.

Even though a critical bug is a great source of stress for merchants, a quick resolution makes merchants feel heard and supported - having a reliable business partner, who is keen to help in the most difficult situation, helps build a stronger relationship. Therefore, we usually ask merchants for a 5* review when we deliver a fast solution.

When you implement a new feature request and ship a new plugin version, you can follow a similar approach to bugs:

* Notify all stakeholders.
* Update the relevant request in the Feature Requests board, by sharing a public update and marking it as 'Completed'.
* For breaking releases: communicating with your marketing/relations teams to publish updates/newsletters before the release.


---

## How to respond to negative WooCommerce extension reviews

*Source: extensions/review-guidelines/responding-to-negative-reviews.md*

# How to respond to negative WooCommerce extension reviews

An unpleasant event in the merchant's journey can lead them to leave a public, negative review. These events usually are:

* a problem with the product,
* a missing product feature,
* an unhelpful reply,
* long wait times to receive a reply, or;
* combinations of the above.

When receiving a negative review, your goal should always be to turn this review around - this sounds tough, but it is really rewarding.

In the majority of cases, merchants who leave a negative review have first tried contacting support for help. This is useful knowledge, as we can read through the conversation history, understand the issue the merchant experienced and share more details with them when we reach out, even from our first reply.

The process we have seen work well is:

* Create a new response (via email, or on a public review) with subject: Regarding your recent review for xxx.
* Start by introducing yourself, for example: "Hey there, This is Andrew from the team that develops xxx".
* Use empathetic language and make it clear that this negative review had an impact on you. For example, "I read your recent review for xxx and I am worried to hear that an issue is preventing you from using this plugin as you had in mind. I'd be happy to help you resolve this!".

Compare the above sentence with: "I am sorry to hear that you experienced an issue with xxx". "I am sorry to" indicates that you are saddened by an event, but don't necessarily plan to do something about it. In comparison, in "I am worried to hear", worry indicates action. Additionally, "That you experienced an issue" can be interpreted as if the problem is mainly the merchant's fault, whereas language like "an issue is preventing you from using this plugin as you had in mind. I'd be happy to help you resolve this!" implies you and the merchant are on the same team.

* Share more details, a solution, an idea, a suggestion or an explanation.
* Urge the merchant to update the review, by highlighting how important reviews are for our team and for other merchants. Example language to do this is "We would appreciate it if you could take a couple of minutes to update your review and describe your experience with our product and support. Honest reviews are extremely helpful for other merchants who try to decide if a plugin is a right fit for them. Thank you for your contribution!".
* Include a direct link to the reviews section, so merchants can easily navigate there and change their review.
* On a follow-up communication, if the merchant has changed the review, consider saying something like: "I shared this with the rest of the team and it made everyone's day".

If the above things are true, sharing some of your procedures with merchants (highlighting how your team emphasizes and thrives on feedback) helps ensure merchants feel like you are part of their team and builds a strong relationship with them. 

Even a merchant that doesn't change their review can offer a mutually beneficial discussion by learning more about their setup and offering some suggestions. These conversations help grow merchants' trust.


---

## Utilizing WooCommerce extension feature requests

*Source: extensions/review-guidelines/utilizing-feature-requests.md*

# Utilizing WooCommerce extension feature requests

It is important to keep track of all feature requests, and have some sort of system of record where anyone can see what kind of feedback the product is receiving over time. 

We recommend a daily or bi-daily check-in, where you:

* triage new feature requests,
* celebrate positive reviews and;
* act upon negative reviews.

Carefully maintaining feature request boards (or similar system) is key, as the average board contains a lot of duplicate/spam content, requests about features that have been implemented and requests about features that will likely never be implemented. Poorly maintained boards make merchants feel unheard/neglected.

This results in more negative reviews on the premise that the product teams were not reading/listening to their feedback.

We've seen good results with the following procedures:

Starting with the most affected products, go through all open requests, reply to most/all of them and categorize them as:

* "Open", for requests that we still want more feedback,
* "Planned", for requests that we plan to implement,
* "Completed", for requests that have already been implemented and;
* "Closed", for requests that we do not plan to implement, as they are not a good fit for the product, for duplicate/spam requests and for requests that were actually support questions.

Replying to all "Open" requests is the goal, but if that's not attainable currently, make sure to reply to 100% of the requests that are closed.

For new open requests that arrive as a feature request, discuss/triage them, reply promptly, and assign a status to avoid having the board become unmanaged, and ensure merchants feel (and are) heard. 

In addition to the effect a tidy board has on merchants, it also helps product teams better understand which requests are most wanted and most impactful and then plan work accordingly.


---

## Utilizing your support team to respond to feedback

*Source: extensions/review-guidelines/utilizing-your-support-team.md*

# Utilizing your support team to respond to feedback

Your support team is usually the primary contact point of merchants when they contact you. Tickets and chats are the best tools we have to converse with merchants, understand pain-points about our software, listen to their feedback and analyze their feature requests. Collectively, support teams have a great understanding of the products and how people use them. This information is essential to be transferred over to product and engineering teams.

We recommend that you take the following steps to best utilize your support team:

* Create a strict internal SLA where support team requests are answered by product or engineering teams.
* Ensure you have a way for your support team to effectively report bugs to your product and engineering teams.
* When responding to your support team, avoid super-short answers, and try to explain the answer simply and concisely. This will allow the support agent to copy/paste your answer to the merchant.
* Avoid replying with statements like "no, this is not possible" or "no, this feature will not be implemented" without providing additional context about technical or product limitations.
* Regularly dedicate additional time to implement a short custom code snippets or to provide in-depth technical details about how a custom project would be implemented so that merchants can reach a solution faster if they decide to hire a dedicated WooCommerce developer. A small effort can go a long way to amaze merchants and reveal an opportunity to request a 5 star review.
* Keep support in the loop when they report a bug or request a new feature. When you release a new product version, we always consider the impact it can have on support.  
* Work closely with your support team. For example, consider having a feedback hangout call every month where you can discuss product feedback and planned improvements.

With these kinds of practices in place, support teams are more willing to share feedback, issues, concerns, and questions with us. This helps maintain a closer relationship with merchants and identify pain-points early, before they become a reason for them to churn.


---

## When to request WooCommerce extension reviews

*Source: extensions/review-guidelines/when-to-request-reviews.md*

# When to request WooCommerce extension reviews

The best approach to increasing our top-star reviews is to identify key moments in the merchant's journey, when they are more likely to leave a review and actively request for it.

The most distinct moments for most of our use cases are: 

* When merchants feel helpless, lost, frustrated and we are able to help,
* When merchants find a bug in our code and we quickly ship a fix,
* When merchants need a feature and we notify them when it is shipped,
* When merchants feel alone and we make them feel heard and;
* When merchants contact with a question and we go out of our way to provide them with top-notch support, even if this means slightly stepping outside the official boundaries of a support policy.

Think about who is seeing the review request, and what they are doing at that time. Showing a request to a fulfillment worker just trying to ship an order isn't likely going to work well.

Outreach after a milestone works really well. Some language we've used before is "Congratulations on your xxth sale! We're delighted that WooPayments facilitated this milestone. Would you consider sharing your experience and encouraging others by reviewing our extension?".

Another way to optimally time a review request would be to setup a prompt that aligns with use patterns. For instance, if you know that most of your merchants use your extension daily, you would likely send a review request sooner than a extension that most merchants interact very sparingly with.

SaaS/Connector extensions need to be particularly careful about requesting ratings correctly, as they are the most likely to be overlooked unless there is an issue, leading to skewed ratings not representative of the actual extension.

Consider requesting feedback at the end of every single support interaction, especially in the WordPress.org support forums. One of the largest barriers to leaving a review is the requirement of a user being logged into WooCommerce.com (or WordPress.org), and the WordPress.org support forums present a good opportunity to gather these reviews. By being highly responsive in the public support forum and solving issues there, users are already logged in and able to immediately leave a review (after being requested to!).


---

## Settings APIs and admin pages

*Source: extensions/settings-and-config/README.md*

# Settings APIs and admin pages

Managing your settings, admin pages, and more is possible through the Settings APIs. The docs in this section cover what the Settings APIs and admin pages system offers in general. This guide goes further to map all of the various approaches you have available, some of the scenarios they cover, and the trade-offs of each approach.

There are also code examples for your reference before you commit to an implementation path. However, reading through the approach you're interested in will give you greater scope to understand and apply the principles of each.

## Approaches at a glance

The Settings API and admin pages section has six approaches, outlined in the table. The four core concepts (Settings API, settings pages, settings tab sections, and admin pages) cover most settings and admin placement decisions, while the remaining approaches cover specialized integrations and navigation shortcuts.

| Approach | Use when | Requires |
| :---- | :---- | :---- |
| [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 |
| [Integration settings](/docs/extensions/settings-and-config/implementing-settings/) | Your extension connects to a third-party service and needs a page under the Integrations tab | PHP |
| [Store management links](/docs/extensions/settings-and-config/how-to-add-your-own-store-management-links/) | Surfacing quick-access links on the WooCommerce home screen | JavaScript |

## Settings API

`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.

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

Use `WC_Settings_Page` when your extension needs a full tab under **WooCommerce > Settings**. A settings page class registers the tab, renders one or more sections, defines fields with WooCommerce's settings array format, and lets WooCommerce handle saving through the existing settings form.

The main trade-off is navigation weight. If your extension only needs a few settings that clearly belong under an existing WooCommerce settings tab, add a section to that tab instead of creating a new top-level tab. If the extension needs an interface outside WooCommerce settings entirely, use admin page registration.

```php
final class My_Plugin_Settings_Page extends WC_Settings_Page {
	public function __construct() {
		$this->id    = 'my_plugin';
		$this->label = __( 'My plugin', 'my-plugin' );

		parent::__construct();
	}

	protected function get_settings_for_default_section() {
		return array(
			array(
				'title' => __( 'My plugin settings', 'my-plugin' ),
				'type'  => 'title',
				'id'    => 'my_plugin_options',
			),
			array(
				'title'   => __( 'Enable feature', 'my-plugin' ),
				'id'      => 'my_plugin_enabled',
				'type'    => 'checkbox',
				'default' => 'no',
			),
			array(
				'type' => 'sectionend',
				'id'   => 'my_plugin_options',
			),
		);
	}
}

add_filter(
	'woocommerce_get_settings_pages',
	function( $settings_pages ) {
		$settings_pages[] = new My_Plugin_Settings_Page();
		return $settings_pages;
	}
);
```

## Settings tab sections

Rather than creating a whole new page, you can add a section beneath an existing WooCommerce settings tab using two filters:

- `woocommerce_get_sections_{tab}` registers the section.
- `woocommerce_get_settings_{tab}` supplies its fields.

The `{tab}` portion of each filter corresponds to the settings page ID for the tab you want to extend. For instance, `products` targets the **Products** tab, while `account` targets **Accounts & Privacy**.

Placing settings under an existing tab keeps the admin area organized and means merchants find your extension's options in an understandable context. The limit is that linking to your section from documentation or onboarding flows requires a URL with both a tab and a section parameter rather than a page URL you control.

```php
add_filter(
	'woocommerce_get_sections_products',
	function( $sections ) {
		$sections['my_extension'] = __( 'My Extension', 'my-extension' );
		return $sections;
	}
);

add_filter(
	'woocommerce_get_settings_products',
	function( $settings, $current_section ) {
		if ( 'my_extension' === $current_section ) {
			return array(
				array(
					'title' => __( 'My Extension', 'my-extension' ),
					'type'  => 'title',
					'id'    => 'my_extension',
				),
				array(
					'title' => __( 'Enable feature', 'my-extension' ),
					'type'  => 'checkbox',
					'id'    => 'my_extension_enabled',
				),
				array(
					'type' => 'sectionend',
					'id'   => 'my_extension',
				),
			);
		}

		return $settings;
	},
	10,
	2
);
```

## Admin page registration

When your extension needs a page outside WooCommerce's settings structure, you register it with the `PageController`. This attaches the WooCommerce Admin header and activity panel to the page and WooCommerce provides two registration paths:

- `wc_admin_connect_page()` for PHP-powered pages.
- `wc_admin_register_page()` for React-powered pages.

PHP registration connects an existing admin page to the WooCommerce Admin shell. This will suit extensions that already render an interface with PHP. React registration creates a menu entry and renders a component you supply, which gives you a component-driven interface but requires a JavaScript build step.

Both paths are for extensions with an interface that's too distinct to fit within WooCommerce's settings tabs. For example, this could be a reporting dashboard, a product import tool, or any page with its own layout.

```php
// PHP-powered page.
wc_admin_connect_page(
	array(
		'id'        => 'my-extension-page',
		'screen_id' => 'my-extension-page',
		'title'     => array( 'My Extension', 'Settings' ),
		'path'      => add_query_arg( 'page', 'my-extension', 'admin.php' ),
	)
);
```

```jsx
// React-powered page.
import { addFilter } from '@wordpress/hooks';

const MyPage = () => <h1>My Extension</h1>;

addFilter( 'woocommerce_admin_pages_list', 'my-extension', ( pages ) => {
	pages.push( {
		container: MyPage,
		path: '/my-extension',
		breadcrumbs: [ 'My Extension' ],
	} );

	return pages;
} );
```

## Integration settings

`WC_Integration` extends `WC_Settings_API` and creates a settings page under **WooCommerce > Settings > Integrations**. It also handles data saving and sanitization for you. You should use it when your extension connects to an external service and a dedicated page under the **Integrations** tab is the right home for its settings.

The main trade-off is placement: if your settings belong under an existing WooCommerce tab or on a standalone page, this is not the path. `WC_Integration` is great for fields such as API keys or toggle switches because you get saving and sanitization without writing that logic yourself.

```php
class My_Integration extends WC_Integration {
	public function __construct() {
		$this->id                 = 'my-integration';
		$this->method_title       = __( 'My Integration', 'my-integration' );
		$this->method_description = __( 'Connect to My Service.', 'my-integration' );
		$this->init_form_fields();
		$this->init_settings();
		add_action(
			'woocommerce_update_options_integration_' . $this->id,
			array( $this, 'process_admin_options' )
		);
	}

	public function init_form_fields() {
		$this->form_fields = array(
			'api_key' => array(
				'title' => __( 'API Key', 'my-integration' ),
				'type'  => 'text',
			),
		);
	}
}

add_filter(
	'woocommerce_integrations',
	function( $integrations ) {
		$integrations[] = 'My_Integration';
		return $integrations;
	}
);
```

## Store management links

The WooCommerce home screen includes a store management dashboard that displays quick-access links and statistics for merchants. You can add your own link there using the `woocommerce_admin_homescreen_quicklinks` JavaScript filter.

However, two constraints apply:

- Links must point to pages within WooCommerce as external URLs are not supported.
- All extension-added links appear under a fixed **Extensions** category and custom categories are not available.

You enqueue your script using `admin_enqueue_scripts`, with a dependency on `wp-hooks` and a priority higher than 15 to ensure it runs before the section renders.

Note that this approach doesn't *configure* settings as its purpose is discoverability for merchants who use the WooCommerce home screen as a starting point for day-to-day tasks.

```js
import { megaphone } from '@wordpress/icons';
import { addFilter } from '@wordpress/hooks';

addFilter( 'woocommerce_admin_homescreen_quicklinks', 'my-extension', ( quickLinks ) => {
	return [
		...quickLinks,
		{
			title: 'My Extension',
			href: 'link/to/my-extension',
			icon: megaphone,
		},
	];
} );
```

## Next steps

With the trade-offs and code examples for each approach as a reference, you can work through the full documentation for the one your extension needs.

1. [Settings API](/docs/extensions/settings-and-config/settings-api/). Core reference for the `WC_Settings_API` class.
2. [Adding a settings page](/docs/extensions/settings-and-config/extend-wc-settings-page/). Creating a full tab under **WooCommerce > Settings**.
3. [Adding a section to a settings tab](/docs/extensions/settings-and-config/adding-a-section-to-a-settings-tab/). Adding a section beneath an existing WooCommerce tab.
4. [Working with WooCommerce admin pages](/docs/extensions/settings-and-config/working-with-woocommerce-admin-pages/). Registering PHP and React admin pages.
5. [Implementing settings with `WC_Integration`](/docs/extensions/settings-and-config/implementing-settings/). How to use the `WC_Integration` class for third-party service connections.
6. [Adding store management links](/docs/extensions/settings-and-config/how-to-add-your-own-store-management-links/). Navigation shortcuts on the WooCommerce home screen.


---

## How to add a section to a settings tab

*Source: extensions/settings-and-config/adding-a-section-to-a-settings-tab.md*

# How to add a section to a settings tab

When you're building an extension for WooCommerce that requires settings of some kind, it's important to ask yourself:  **Where do they belong?**  If your extension just has a couple of simple settings, do you really need to create a new tab specifically for it? Most likely the answer is no.

## When to Create a Section

Let's say we had an extension that adds a slider to a single product page. This extension only has a few options:

-   Auto-insert into single product page (checkbox)
-   Slider Title (text field)

That's only two options, specifically related to  **Products**. We could quite easily just append them onto the core WooCommerce Products Settings (**WooCommerce > Settings > Products**), but that wouldn't be very user friendly. Users wouldn't know where to look initially so they'd have to scan all of the Products options and it would be difficult / impossible to link the options directly. Fortunately, as of WooCommerce 2.2.2, there is a new filter in place that allows you add a new  **section**, beneath one of the core settings' tabs.

## How to Create a Section

We'll go over doing this through individual functions, but you should probably create a Class that stores all of your settings methods.

The first thing you need to is add the section, which can be done like this by hooking into the  `woocommerce_get_sections_products`  filter:

```php
/**

* Create the section beneath the products tab

**/

add_filter( 'woocommerce_get_sections_products', 'wcslider_add_section' );

function wcslider_add_section( $sections ) {

    $sections['wcslider'] = __( 'WC Slider', 'text-domain' );

    return $sections;

}
```

_[wc-create-section-beneath-products.php](https://gist.github.com/woogists/2964ec01c8bea50fcce62adf2f5c1232/raw/da5348343cf3664c0bc8b6b132d8105bfcf9ca51/wc-create-section-beneath-products.php)_

Make sure you change the  **wcslider**  parts to suit your extension's name / text-domain. The important thing about the  `woocommerce_get_sections_products`  filter, is that the last part  **products**, is the tab you'd like to add a section to. So if you want to add a new tab to accounts section, you would hook into the  `woocommerce_get_sections_accounts`  filter.

## How to Add Settings to a Section

Now that you've got the tab, you need to filter the output of  `woocommerce_get_sections_products`  (or similar). You would add the settings like usual using the  [**WooCommerce Settings API**](/docs/extensions/settings-and-config/settings-api/), but check for the current section before adding the settings to the tab's settings array. For example, let's add the sample settings we discussed above to the new  **wcslider**  section we just created:

```php
/**

* Add settings to the specific section we created before

*/

add_filter( 'woocommerce_get_settings_products', 'wcslider_all_settings', 10, 2 );

function wcslider_all_settings( $settings, $current_section ) {

/**

* Check the current section is what we want

**/

  if ( $current_section == 'wcslider' ) {
  
      $settings_slider = array();
    
      // Add Title to the Settings
      
      $settings_slider[] = array( 'name' => __( 'WC Slider Settings', 'text-domain' ), 'type' => 'title', 'desc' => __( 'The following options are used to configure WC Slider', 'text-domain' ), 'id' => 'wcslider' );
      
      // Add first checkbox option
      
      $settings_slider[] = array(
      
          'name' => __( 'Auto-insert into single product page', 'text-domain' ),
          
          'desc_tip' => __( 'This will automatically insert your slider into the single product page', 'text-domain' ),
          
          'id' => 'wcslider_auto_insert',
          
          'type' => 'checkbox',
          
          'css' => 'min-width:300px;',
          
          'desc' => __( 'Enable Auto-Insert', 'text-domain' ),
      
      );
      
      // Add second text field option
      
      $settings_slider[] = array(
      
          'name' => __( 'Slider Title', 'text-domain' ),
          
          'desc_tip' => __( 'This will add a title to your slider', 'text-domain' ),
          
          'id' => 'wcslider_title',
          
          'type' => 'text',
          
          'desc' => __( 'Any title you want can be added to your slider with this option!', 'text-domain' ),
      
      );
      
      $settings_slider[] = array( 'type' => 'sectionend', 'id' => 'wcslider' );
      
      return $settings_slider;
    
    /**
    
    * If not, return the standard settings
    
    **/
    
    } else {
    
        return $settings;
  
    }

}

```

_[wc-add-settings-section.php](https://gist.github.com/woogists/4038b83900508806c57a193a2534b845#file-wc-add-settings-section-php)_

We're hooking into the same  `woocommerce_get_sections_products`  filter, but this time doing a check that the  `$current_section`  matches our earlier defined custom section (wcslider), before adding in our new settings.

## Using the New Settings

You would now just use your newly created settings like you would any other WordPress / WooCommerce setting, through the  [**get_option**](http://codex.wordpress.org/Function_Reference/get_option)  function and the defined ID of the setting. For example, to use the previously created  **wcslider_auto_insert**  option, simply use the following code:  `get_option( 'wcslider_auto_insert' )`

## Conclusion

When creating an extension for WooCommerce, think about where your settings belong before you create them. The key to building a useful product is making it easy to use for the end user, so appropriate setting placement is crucially important. For more specific information on adding settings to WooCommerce, check out the  [**Settings API documentation**](/docs/extensions/settings-and-config/settings-api/).


---

## How to add a settings page

*Source: extensions/settings-and-config/extend-wc-settings-page.md*

# How to add a settings page

Use `WC_Settings_Page` when your extension needs a full tab under **WooCommerce > Settings**. A settings page class registers the tab, renders one or more sections, defines fields with WooCommerce's settings array format, and lets WooCommerce handle saving through the existing settings form.

If your extension only needs a few settings that clearly belong under an existing WooCommerce settings tab, add a section to that tab instead of creating a new top-level tab. See [How to add a section to a settings tab](./adding-a-section-to-a-settings-tab.md). If your settings belong to a payment gateway, shipping method, or integration, also check whether `WC_Payment_Gateway`, `WC_Shipping_Method`, `WC_Integration`, or `WC_Settings_API` is the better fit.

## How settings pages are loaded

WooCommerce loads settings page objects from `WC_Admin_Settings::get_settings_pages()`. Core pages are loaded first, then extensions can add their own page objects through the `woocommerce_get_settings_pages` filter.

A `WC_Settings_Page` subclass must set its `$id` and `$label` before calling `parent::__construct()`. The parent constructor uses the page ID to register these hooks:

- `woocommerce_settings_tabs_array` adds the settings tab.
- `woocommerce_sections_{$page_id}` outputs section navigation.
- `woocommerce_settings_{$page_id}` outputs the fields.
- `woocommerce_settings_save_{$page_id}` saves the fields.

## Create a settings page class

Load your class only after `WC_Settings_Page` is available. WooCommerce includes the base class before it applies `woocommerce_get_settings_pages`, so a common pattern is to require your settings page class from that filter callback.

The example below defines a full **My plugin** tab with two sections. Place the class in a file such as `includes/class-my-plugin-settings-page.php`, and load that file from the registration callback shown after the class.

```php
<?php
defined( 'ABSPATH' ) || exit;

final class My_Plugin_Settings_Page extends WC_Settings_Page {
	public function __construct() {
		$this->id    = 'my_plugin';
		$this->label = __( 'My plugin', 'my-plugin' );

		parent::__construct();
	}

	protected function get_own_sections() {
		return array(
			''         => __( 'General', 'my-plugin' ),
			'advanced' => __( 'Advanced', 'my-plugin' ),
		);
	}

	protected function get_settings_for_default_section() {
		return array(
			array(
				'title' => __( 'My plugin settings', 'my-plugin' ),
				'type'  => 'title',
				'desc'  => __( 'Configure the default behavior for My plugin.', 'my-plugin' ),
				'id'    => 'my_plugin_options',
			),
			array(
				'title'    => __( 'Enable feature', 'my-plugin' ),
				'desc'     => __( 'Turn on the main plugin feature.', 'my-plugin' ),
				'id'       => 'my_plugin_enabled',
				'type'     => 'checkbox',
				'default'  => 'no',
			),
			array(
				'title'    => __( 'Display title', 'my-plugin' ),
				'id'       => 'my_plugin_display_title',
				'type'     => 'text',
				'default'  => __( 'Featured products', 'my-plugin' ),
				'desc'     => __( 'Shown to customers when the feature appears on the storefront.', 'my-plugin' ),
				'desc_tip' => true,
			),
			array(
				'type' => 'sectionend',
				'id'   => 'my_plugin_options',
			),
		);
	}

	protected function get_settings_for_advanced_section() {
		return array(
			array(
				'title' => __( 'Advanced settings', 'my-plugin' ),
				'type'  => 'title',
				'id'    => 'my_plugin_advanced_options',
			),
			array(
				'title'    => __( 'Mode', 'my-plugin' ),
				'id'       => 'my_plugin_mode',
				'type'     => 'select',
				'default'  => 'automatic',
				'options'  => array(
					'automatic' => __( 'Automatic', 'my-plugin' ),
					'manual'    => __( 'Manual', 'my-plugin' ),
				),
				'desc_tip' => __( 'Choose how My plugin should choose products.', 'my-plugin' ),
			),
			array(
				'type' => 'sectionend',
				'id'   => 'my_plugin_advanced_options',
			),
		);
	}
}
```

Register the settings page from your main plugin file:

```php
add_filter(
	'woocommerce_get_settings_pages',
	function ( array $settings_pages ): array {
		require_once __DIR__ . '/includes/class-my-plugin-settings-page.php';

		$settings_pages[] = new My_Plugin_Settings_Page();
		return $settings_pages;
	}
);
```

The page is available at:

```text
wp-admin/admin.php?page=wc-settings&tab=my_plugin
```

The `advanced` section is available at:

```text
wp-admin/admin.php?page=wc-settings&tab=my_plugin&section=advanced
```

## Define sections

Override `get_own_sections()` when your page has more than one section. Return an associative array where each key is a section ID and each value is the translated section label.

The default section uses an empty string as its key:

```php
protected function get_own_sections() {
	return array(
		''         => __( 'General', 'my-plugin' ),
		'advanced' => __( 'Advanced', 'my-plugin' ),
	);
}
```

If the page has only one section, you can omit `get_own_sections()` and WooCommerce will use a single **General** section. Section IDs appear in URLs, so keep them stable and use lowercase values. If you rely on the `get_settings_for_{$section_id}_section()` method-name convention, use section IDs that are valid in PHP method names, such as `advanced` or `my_plugin_section`.

## Define settings for each section

For new settings pages, define fields with section-specific methods:

- `get_settings_for_default_section()` returns fields for the default section.
- `get_settings_for_{$section_id}_section()` returns fields for a named section, such as `get_settings_for_advanced_section()`. This convention requires the section ID to work in a PHP method name.
- `get_settings_for_section_core( $section_id )` can be overridden when the page needs one generic method for many dynamic sections.

Do not override `get_settings()` for new code. WooCommerce still calls it internally for backward compatibility with older extensions, but it is deprecated. New code should use the section-specific methods above.

Each method returns a WooCommerce settings array. A section usually starts with a `title` field and ends with a matching `sectionend` field.

```php
protected function get_settings_for_default_section() {
	return array(
		array(
			'title' => __( 'My plugin settings', 'my-plugin' ),
			'type'  => 'title',
			'id'    => 'my_plugin_options',
		),
		array(
			'title'   => __( 'Items per page', 'my-plugin' ),
			'id'      => 'my_plugin_items_per_page',
			'type'    => 'number',
			'default' => '12',
			'custom_attributes' => array(
				'min'  => '1',
				'step' => '1',
			),
		),
		array(
			'type' => 'sectionend',
			'id'   => 'my_plugin_options',
		),
	);
}
```

## Field array reference

WooCommerce renders and saves fields based on each field array.

| Key | Purpose |
| --- | ------- |
| `id` | Option name and HTML field ID. Required for fields that save an option. |
| `type` | Field type, such as `text`, `checkbox`, `select`, `textarea`, or `title`. |
| `title` | Label shown in the left column. Older examples may use `name`; prefer `title` for new code. |
| `desc` | Description text shown near the field. |
| `desc_tip` | `true` to use `desc` as a tooltip, or a string to use as tooltip text. |
| `default` | Default value used when the option is not set. |
| `options` | Key/value choices for `select`, `multiselect`, and `radio` fields. |
| `class` | CSS class for the input. |
| `css` | Inline CSS for the input. Use sparingly. |
| `placeholder` | Placeholder text for supported input types. |
| `custom_attributes` | Extra HTML attributes such as `min`, `max`, `step`, or `required`. |
| `autoload` | Whether the saved option should autoload. Defaults to `true`. Use `false` for rarely used options. |
| `field_name` | Input name when it must differ from `id`, including array-style names. |
| `is_option` | Set to `false` for rendered fields that should not be saved as options. |

Common field types include:

- `title`
- `sectionend`
- `text`
- `password`
- `number`
- `email`
- `url`
- `textarea`
- `select`
- `multiselect`
- `radio`
- `checkbox`
- `single_select_page`
- `single_select_page_with_search`
- `single_select_country`
- `multi_select_countries`
- `relative_date_selector`

Custom field types can be rendered with the `woocommerce_admin_field_{$type}` action.

## Saving settings

When the merchant saves a settings page, WooCommerce verifies the `manage_woocommerce` capability and the settings nonce, then fires the page-specific save hooks. For a `WC_Settings_Page` subclass, the registered `save()` method saves the current section's fields with `WC_Admin_Settings::save_fields()`.

The save routine:

1. Reads submitted values from `$_POST`.
2. Sanitizes values according to field type.
3. Applies `woocommerce_admin_settings_sanitize_option`.
4. Applies `woocommerce_admin_settings_sanitize_option_{$option_name}`.
5. Updates the WordPress option named by `field_name` or `id`.

Checkboxes are saved as `yes` or `no`. Select fields are constrained to the keys in `options`. Password fields are trimmed but otherwise preserved so special characters are not corrupted.

Use `get_option( 'my_plugin_enabled', 'no' )` or `WC_Admin_Settings::get_option( 'my_plugin_enabled', 'no' )` to read saved values.

## Add custom sanitization

Use the option-specific sanitize filter when a field needs validation beyond the built-in field type handling.

```php
add_filter(
	'woocommerce_admin_settings_sanitize_option_my_plugin_items_per_page',
	function ( $value, array $option, $raw_value ) {
		return (string) max( 1, absint( $raw_value ) );
	},
	10,
	3
);
```

Return `null` to skip updating the option.

## Run extra work after saving

Use the section-specific update action when saving a section needs side effects, such as clearing caches or scheduling work.

```php
add_action(
	'woocommerce_update_options_my_plugin_advanced',
	function (): void {
		delete_transient( 'my_plugin_expensive_data' );
	}
);
```

The default section does not fire a section-specific `woocommerce_update_options_{$page_id}_{$section_id}` action because its section ID is empty. If you need custom behavior for every save on the tab, use `woocommerce_update_options_{$page_id}`:

```php
add_action(
	'woocommerce_update_options_my_plugin',
	function (): void {
		delete_transient( 'my_plugin_expensive_data' );
	}
);
```

Override `save()` only when the page must change the order of operations or save non-option data. If you override it, call `save_settings_for_current_section()` when the normal fields should still be persisted.

## Add a section to an existing settings page

Many extensions should not create a new settings tab. If the settings belong under an existing tab, register a section under that tab instead.

For WooCommerce versions that support the settings section registry, create a `SettingsSection` and register it on `woocommerce_settings_sections_registration`. This keeps section metadata, fields, Settings UI scripts, and save behavior together.

```php
<?php
use Automattic\WooCommerce\Admin\Settings\SettingsSection;
use Automattic\WooCommerce\Admin\Settings\SettingsSectionRegistry;

final class My_Plugin_Products_Settings_Section extends SettingsSection {
	public function get_parent_page_id(): string {
		return 'products';
	}

	public function get_id(): string {
		return 'my_plugin';
	}

	public function get_label(): string {
		return __( 'My plugin', 'my-plugin' );
	}

	public function get_settings( WC_Settings_Page $parent_page ): array {
		return array(
			array(
				'title' => __( 'My plugin', 'my-plugin' ),
				'type'  => 'title',
				'id'    => 'my_plugin_products_options',
			),
			array(
				'title'   => __( 'Enable product display', 'my-plugin' ),
				'desc'    => __( 'Show My plugin content on product pages.', 'my-plugin' ),
				'id'      => 'my_plugin_product_display_enabled',
				'type'    => 'checkbox',
				'default' => 'no',
			),
			array(
				'type' => 'sectionend',
				'id'   => 'my_plugin_products_options',
			),
		);
	}
}

add_action(
	'woocommerce_settings_sections_registration',
	function ( SettingsSectionRegistry $registry ): void {
		$registry->register( new My_Plugin_Products_Settings_Section() );
	}
);
```

For older WooCommerce versions, use the filter-based approach documented in [How to add a section to a settings tab](./adding-a-section-to-a-settings-tab.md).

## Opt in to the React settings UI

> **The settings UI is experimental** and subject to change. See the [settings UI status](./settings-ui.md#status) for details.

`WC_Settings_Page` still owns registration, permissions, schema, and persistence when a page opts in to the React settings UI. To render a page with the React settings UI when the feature flag is enabled, return a settings UI adapter from `get_settings_ui_page()`.

```php
use Automattic\WooCommerce\Admin\Settings\LegacySettingsPageAdapter;
use Automattic\WooCommerce\Admin\Settings\SettingsUIPageInterface;

public function get_settings_ui_page(): ?SettingsUIPageInterface {
	return new LegacySettingsPageAdapter( $this );
}
```

This is optional. If the feature flag is disabled, or the page does not return an adapter, WooCommerce renders the classic PHP settings table. See [Settings UI](./settings-ui.md) for custom React components, script handles, save adapters, and migration details.

## Further reading

- [WooCommerce Settings API](./settings-api.md)
- [How to add a section to a settings tab](./adding-a-section-to-a-settings-tab.md)
- [Settings UI](./settings-ui.md)
- [WC_Settings_Page code reference](https://woocommerce.github.io/code-reference/classes/WC-Settings-Page.html)
- [WC_Admin_Settings code reference](https://woocommerce.github.io/code-reference/classes/WC-Admin-Settings.html)


---

## How to add store management links

*Source: extensions/settings-and-config/how-to-add-your-own-store-management-links.md*

# How to add store management links

## Introduction

In the new and improved WooCommerce home screen, there are two points of extensibility for plugin developers that have recently had some attention. The first is the setup task list, allowing you to remind the user of tasks they need to complete and keeping track of their progress for them.

The second is the store management links section. Once the user has completed the setup tasks this will display for them. This section consolidates a list of handy navigation links that merchants can use to quickly find features in WooCommerce.

Discoverability can be hard for users so this can be a great place to bring attention to the features of your plugin and allow users to easily find their way to the key functionality your plugin provides.

Adding your own store management links is a simple process.

## Add your own store management link

Before we start, let's outline a couple of restrictions on this feature.

Right now these links are designed to keep the user within WooCommerce, so it does not support external links.

All the links you add will fall under a special category in the list called "Extensions". There is not currently any support for custom categories.

With those things in mind, let's start.

## Step 1 - Enqueue JavaScript

Adding a store management link will all be done in JavaScript, so the first step is enqueuing your script that will add the store management link. The most important thing here is ensuring that your script runs before the store management link section is rendered.

To ensure that your script runs before ours you'll need to enqueue it with a priority higher than 15. You'll also need to depend on `wp-hooks` to get access to `addFilter`.

Example:

```php
function enqueue_management_link_script() {
    wp_enqueue_script( $script_name, $script_url, array( 'wp-hooks' ), 10 );
}

add_action( 'admin_enqueue_scripts', 'enqueue_management_link_script' );
```

## Step 2 - Install @wordpress/icons

To provide an icon of your choice for your store management link, you'll need to install `@wordpress/icons` in your JavaScript project:

```sh
npm install @wordpress/icons --save
```

## Step 3 - Add your filter

Your script will need to use `addFilter` to provide your custom link to the store management link section. And you'll need to import your icon of choice from `@wordpress/icons`. Here's an example:

```js
import { megaphone } from "@wordpress/icons";
import { addFilter } from "@wordpress/hooks";

addFilter(
  "woocommerce_admin_homescreen_quicklinks",
  "my-extension",
  (quickLinks) => {
    return [
      ...quickLinks,
      {
        title: "My link",
        href: "link/to/something",
        icon: megaphone,
      },
    ];
  }
);
```

Here's a screen shot using our new custom store management link:

![screen shot of custom store management link in wp-admin](https://developer.woocommerce.com/wp-content/uploads/2023/12/yvXeSya.png)


---

## Creating custom settings for WooCommerce integrations

*Source: extensions/settings-and-config/implementing-settings.md*

# Creating custom settings for WooCommerce integrations

If you're customizing WooCommerce or adding your own functionality to it you'll probably need a settings page of some sort. One of the easiest ways to create a settings page is by taking advantage of the [`WC_Integration` class](https://woocommerce.github.io/code-reference/classes/WC-Integration.html 'WC_Integration Class'). Using the Integration class will automatically create a new settings page under **WooCommerce > Settings > Integrations** and it will automatically save, and sanitize your data for you. We've created this tutorial so you can see how to create a new integration.

## Setting up the Integration

You'll need at least two files to create an integration so you'll need to create a directory.

### Creating the Main Plugin File

Create your main plugin file to [hook](https://developer.wordpress.org/reference/functions/add_action/ 'WordPress add_action()') into the `plugins_loaded` hook and check if the `WC_Integration` [class exists](https://www.php.net/manual/en/language.oop5.basic.php#language.oop5.basic.extends 'PHP Class Exists'). If it doesn't then the user most likely doesn't have WooCommerce activated. After you do that you need to register the integration. Load the integration file (we'll get to this file in a minute). Use the `woocommerce_integrations` filter to add a new integration to the [array](http://php.net/manual/en/language.types.array.php 'PHP Array').

### Creating the Integration Class

Now that we have the framework setup let's actually implement this Integration class. There already is a `WC_Integration` class so we want to make a [child class](https://www.php.net/manual/en/language.oop5.inheritance.php). This way it inherits all of the existing methods and data. You'll need to set an id, a description, and a title for your integration. These will show up on the integration page. You'll also need to load the settings by calling: `$this->init_form_fields();` & `$this->init_settings();` You'll also need to save your options by calling the `woocommerce_update_options_integration_{your method id}` hook. Lastly you have to input some settings to save! We've included two dummy fields below but we'll go more into fields in the next section.

> Added to a file named `class-wc-integration-demo-integration.php`

```php
<?php
/**
 * Integration Demo Integration.
 *
 * @package  WC_Integration_Demo_Integration
 * @category Integration
 * @author   Patrick Rauland
 */
if ( ! class_exists( 'WC_Integration_Demo_Integration' ) ) :
    /**
     * Demo Integration class.
     */
    class WC_Integration_Demo_Integration extends WC_Integration {
        /**
         * Init and hook in the integration.
         */
        public function __construct() {
            global $woocommerce;

            $this->id                 = 'integration-demo';
            $this->method_title       = __( 'Integration Demo', 'woocommerce-integration-demo' );
            $this->method_description = __( 'An integration demo to show you how easy it is to extend WooCommerce.', 'woocommerce-integration-demo' );

            // Load the settings.
            $this->init_form_fields();
            $this->init_settings();

            // Define user set variables.
            $this->api_key = $this->get_option( 'api_key' );
            $this->debug   = $this->get_option( 'debug' );

            // Actions.
            add_action( 'woocommerce_update_options_integration_' .  $this->id, array( $this, 'process_admin_options' ) );
        }

        /**
         * Initialize integration settings form fields.
         */
        public function init_form_fields() {
            $this->form_fields = array(
                'api_key' => array(
                    'title'       => __( 'API Key', 'woocommerce-integration-demo' ),
                    'type'        => 'text',
                    'description' => __( 'Enter with your API Key. You can find this in "User Profile" drop-down (top right corner) > API Keys.', 'woocommerce-integration-demo' ),
                    'desc_tip'    => true,
                    'default'     => '',
                ),
                'debug' => array(
                    'title'       => __( 'Debug Log', 'woocommerce-integration-demo' ),
                    'type'        => 'checkbox',
                    'label'       => __( 'Enable logging', 'woocommerce-integration-demo' ),
                    'default'     => 'no',
                    'description' => __( 'Log events such as API requests', 'woocommerce-integration-demo' ),
                ),
            );
        }
    }
endif;
```

> Added to a file named `wc-integration-demo.php`

```php
<?php
/**
 * Plugin Name: WooCommerce Integration Demo
 * Plugin URI: https://gist.github.com/BFTrick/091d55feaaef0c5341d8
 * Description: A plugin demonstrating how to add a new WooCommerce integration.
 * Author: Patrick Rauland
 * Author URI: http://speakinginbytes.com/
 * Version: 1.0
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 *
 */
if ( ! class_exists( 'WC_Integration_Demo' ) ) :
    /**
     * Integration demo class.
     */
    class WC_Integration_Demo {
        /**
         * Construct the plugin.
         */
        public function __construct() {
            add_action( 'plugins_loaded', array( $this, 'init' ) );
        }

        /**
         * Initialize the plugin.
         */
        public function init() {
            // Checks if WooCommerce is installed.
            if ( class_exists( 'WC_Integration' ) ) {
                // Include our integration class.
                include_once 'class-wc-integration-demo-integration.php';
                // Register the integration.
                add_filter( 'woocommerce_integrations', array( $this, 'add_integration' ) );
            } else {
                // throw an admin error if you like
            }
        }

        /**
         * Add a new integration to WooCommerce.
         *
         * @param array Array of integrations.
         */
        public function add_integration( $integrations ) {
            $integrations[] = 'WC_Integration_Demo_Integration';
            return $integrations;
        }
    }
endif;

$WC_Integration_Demo = new WC_Integration_Demo( __FILE__ );

```

## Creating Settings

If you took a look through the last section you'll see that we added two dummy settings using the `init_form_fields()` method.

### Types of Settings

WooCommerce includes support for 8 types of settings.

-   text
-   price
-   decimal
-   password
-   textarea
-   checkbox
-   select
-   multiselect

And these settings have attributes which you can use. These affect the way the setting looks and behaves on the settings page. It doesn't affect the setting itself. The attributes will manifest slightly differently depending on the setting type. A placeholder for example doesn't work with checkboxes. To see exactly how they work you should look through the [source code](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/abstracts/abstract-wc-settings-api.php 'WC Settings API on GitHub'). Ex.

-   title
-   class
-   css
-   placeholder
-   description
-   default
-   desc_tip

### Creating Your Own Settings

The built-in settings are great but you may need extra controls to create your settings page. That's why we included some methods to do this for you. First, define a setting by adding it to the `$this->form_fields` array, entering the kind of form control you want under `type`. You can override the default HTML for your form inputs by creating a method with a name of the format `generate_{ type }_html` which outputs HTML markup. To specify how buttons are rendered, you'd add a method called `generate_button_html`. For textareas, you'd add a `generate_textarea_html` method, and so on. (Check out the `generate_settings_html` method of the `WC_Settings_API` class in the WooCommerce source code to see how WooCommerce uses this.) The below example creates a button that goes to WooCommerce.com.

```php
/**
 * Initialize integration settings form fields.
 *
 * @return void
 */
public function init_form_fields() {
	$this->form_fields = array(
		// don't forget to put your other settings here
		'customize_button' => array(
			'title'             => __( 'Customize!', 'woocommerce-integration-demo' ),
			'type'              => 'button',
			'custom_attributes' => array(
				'onclick' => "location.href='https://woocommerce.com'",
			),
			'description'       => __( 'Customize your settings by going to the integration site directly.', 'woocommerce-integration-demo' ),
			'desc_tip'          => true,
		)
	);
}


/**
 * Generate Button HTML.
 *
 * @access public
 * @param mixed $key
 * @param mixed $data
 * @since 1.0.0
 * @return string
 */
public function generate_button_html( $key, $data ) {
	$field    = $this->plugin_id . $this->id . '_' . $key;
	$defaults = array(
		'class'             => 'button-secondary',
		'css'               => '',
		'custom_attributes' => array(),
		'desc_tip'          => false,
		'description'       => '',
		'title'             => '',
	);

	$data = wp_parse_args( $data, $defaults );

	ob_start();
	?>
	<tr valign="top">
		<th scope="row" class="titledesc">
			<label for="<?php echo esc_attr( $field ); ?>"><?php echo wp_kses_post( $data['title'] ); ?></label>
			<?php echo $this->get_tooltip_html( $data ); ?>
		</th>
		<td class="forminp">
			<fieldset<
				<legend class="screen-reader-text"><span><?php echo wp_kses_post( $data['title'] ); ?></span></legend>
				<button class="<?php echo esc_attr( $data['class'] ); ?>" type="button" name="<?php echo esc_attr( $field ); ?>" id="<?php echo esc_attr( $field ); ?>" style="<?php echo esc_attr( $data['css'] ); ?>" <?php echo $this->get_custom_attribute_html( $data ); ?>><?php echo wp_kses_post( $data['title'] ); ?></button>
				<?php echo $this->get_description_html( $data ); ?>
			</fieldset>
		</td>
	</tr>
	<?php
	return ob_get_clean();
}
```

## Validating & Sanitizing Data

To create the best user experience you'll most likely want to validate and sanitize your data. The integration class already performs basic sanitization so that there's no malicious code present but you could further sanitize by removing unused data. An example of sanitizing data would be integrating with a 3rd party service where all API keys are upper case. You could convert the API key to upper case which will make it a bit more clear for the user.

### Sanitize

We'll demonstrate how to sanitize data first because it's a bit easier to understand. But the one thing you should keep in mind is that sanitizing happens _after_ validation. So if something isn't validated it won't get to the sanitization step.

```php
/**
 * Init and hook in the integration.
 */
public function __construct() {

    // do other constructor stuff first

	// Filters.
	add_filter( 'woocommerce_settings_api_sanitized_fields_' . $this->id, array( $this, 'sanitize_settings' ) );

}

/**
 * Sanitize our settings
 */
public function sanitize_settings( $settings ) {
	// We're just going to make the api key all upper case characters since that's how our imaginary API works
	if ( isset( $settings ) &&
	     isset( $settings['api_key'] ) ) {
		$settings['api_key'] = strtoupper( $settings['api_key'] );
	}
	return $settings;
}
```

### Validation

Validation isn't always necessary but it's nice to do. If your API keys are always 10 characters long and someone enters one that's not 10 then you can print out an error message and prevent the user a lot of headache when they assumed they put it in correctly. First set up a `validate_{setting key}_field` method for each field you want to validate. For example, with the `api_key` field you need a `validate_api_key_field()` method.

```php
public function validate_api_key_field( $key, $value ) {
    if ( isset( $value ) && 20 < strlen( $value ) ) {
        WC_Admin_Settings::add_error( esc_html__( 'Looks like you made a mistake with the API Key field. Make sure it isn&apos;t longer than 20 characters', 'woocommerce-integration-demo' ) );
    }

    return $value;
}
```

## A complete example

If you've been following along you should have a complete integration example. If you have any problems see our [full integration demo](https://github.com/woogists/woocommerce-integration-demo 'Integration Demo').


---

## Registering settings UI components

*Source: extensions/settings-and-config/registering-settings-ui-components.md*

# Registering settings UI components

> **The settings UI is experimental** and subject to change. See the [settings UI status](./settings-ui.md#status) for details.

Use custom components when a WooCommerce settings field needs plugin-specific React UI that cannot be represented by a built-in DataForm field type.

For most fields, prefer DataForm's built-in controls. Custom components are best for specialized selectors, previews, or validation flows.

## PHP field metadata

Declare a stable component name on the field:

```php
array(
	'id'        => 'my_plugin_payment_methods',
	'title'     => __( 'Payment methods', 'my-plugin' ),
	'type'      => 'multiselect',
	'component' => 'my-plugin/payment-method-picker',
	'options'   => array(
		'card' => __( 'Card', 'my-plugin' ),
		'bnpl' => __( 'Buy now, pay later', 'my-plugin' ),
	),
)
```

The `component` value is a name, not a script handle. It lets the PHP schema say which renderer a field intends to use while JavaScript supplies the implementation.

## Register JavaScript components

Register components with `registerSettingsExtension()` from `@woocommerce/settings-ui`:

```ts
import { registerSettingsExtension } from '@woocommerce/settings-ui';
import { PaymentMethodPicker } from './payment-method-picker';

registerSettingsExtension( {
	scope: {
		page: 'my_plugin',
		section: 'payments',
	},
	components: {
		'my-plugin/payment-method-picker': PaymentMethodPicker,
	},
} );
```

Registrations are scoped by settings page and, optionally, by section. This prevents one plugin from accidentally replacing another plugin's field behavior. Omit `section` for a page-wide registration, use `section: ''` for the default section only, or pass a section id such as `section: 'payments'` for one named section.

## Component props

Custom components receive a stable subset of the DataForm edit-control props:

```ts
type SettingsEditControlProps = {
	data: Record< string, string | number | boolean | string[] | null >;
	field: {
		id: string;
		label?: string;
		description?: string | JSX.Element;
		placeholder?: string;
		elements?: Array< { label: string; value: string } >;
		getValue: ( args: {
			item: Record< string, string | number | boolean | string[] | null >;
		} ) => string | number | boolean | string[] | null;
		isDisabled: ( args: {
			item: Record< string, string | number | boolean | string[] | null >;
		} ) => boolean;
	};
	onChange: (
		value: Partial<
			Record< string, string | number | boolean | string[] | null >
		>
	) => void;
	hideLabelFromVision?: boolean;
};
```

Read the current value with `field.getValue( { item: data } )`. Call
`onChange()` with an object containing the changed field value. The settings UI
handles hidden input serialization for the field's save adapter.

Check `field.isDisabled( { item: data } )` and render the control disabled when
it returns `true`. DataForm applies the disabled state to its own controls only,
so a registered component has to honor it itself.

## Example component

```tsx
import type { SettingsEditControlProps } from '@woocommerce/settings-ui';

export const PaymentMethodPicker = ( {
	data,
	field,
	onChange,
}: SettingsEditControlProps ) => {
	const value = field.getValue( { item: data } );
	const selectedValues = Array.isArray( value ) ? value : [];

	return (
		<fieldset>
			<legend>{ field.label }</legend>
			{ field.elements?.map( ( option ) => {
				const checked = selectedValues.includes( option.value );

				return (
					<label key={ option.value }>
						<input
							type="checkbox"
							checked={ checked }
							onChange={ () => {
								onChange( {
									[ field.id ]: checked
										? selectedValues.filter(
												( item ) =>
													item !== option.value
										  )
										: [ ...selectedValues, option.value ],
								} );
							} }
						/>
						{ option.label }
					</label>
				);
			} ) }
		</fieldset>
	);
};
```

## Field-specific overrides

If a legacy field cannot add `component` metadata directly, register a field override by field id:

```ts
registerSettingsExtension( {
	scope: {
		page: 'my_plugin',
	},
	fieldOverrides: {
		my_plugin_payment_methods: PaymentMethodPicker,
	},
} );
```

Field overrides are useful during migration, but component metadata is preferred because the intended renderer stays close to the PHP field schema.

## Type renderers

Use `typeRenderers` when every field of a type should share the same renderer within a page scope:

```ts
registerSettingsExtension( {
	scope: {
		page: 'my_plugin',
	},
	typeRenderers: {
		my_plugin_color: ColorField,
	},
} );
```

The PHP schema validator accepts extension-defined field types when their values use the Settings UI value contract. The extension script must register the matching renderer before the page mounts.

Resolution order is:

1. `field.component`
2. `fieldOverrides[ field.id ]`
3. `typeRenderers[ field.type ]`
4. DataForm's built-in control

If one registry entry is missing, resolution continues to the next registry entry. When a field declares `field.component`, that metadata states that a custom control is required. If no named component, field override, or type renderer resolves it, the page fails closed instead of silently replacing the required control with a built-in one.

For a field without `field.component`, DataForm's built-in control for the field type is the final fallback after field overrides and type renderers. A field type with no registered renderer and no built-in control fails closed.

## Enqueue the component script

Register your script in WordPress and return its handle from the settings integration that owns the fields.

For a section registered under an existing tab, return the handle from the section object:

```php
<?php
use Automattic\WooCommerce\Admin\Settings\SettingsSection;

final class My_Plugin_Settings_Section extends SettingsSection {
	// Other settings section methods omitted for brevity.

	public function get_script_handles( WC_Settings_Page $parent_page ): array {
		return array( 'my-plugin-settings-ui' );
	}
}
```

For a full settings tab that opts in through a `WC_Settings_Page` adapter, return the handle from the adapter:

```php
<?php
use Automattic\WooCommerce\Admin\Settings\LegacySettingsPageAdapter;

final class My_Plugin_Settings_UI_Page extends LegacySettingsPageAdapter {
	public function get_script_handles( string $section ): array {
		return array( 'my-plugin-settings-ui' );
	}
}
```

WooCommerce loads the settings UI package first, then your script, then mounts the settings app.

## Failure and fallback behavior

WooCommerce validates server-observable schema metadata and declared script handles before rendering the Settings UI mount. An invalid schema or a script handle that is not registered and enqueued renders the complete classic settings page in the same response.

PHP cannot inspect the component registry in the browser. The Settings UI fails closed when an explicitly required component has no registry fallback, when a field without an explicit component has no registered or built-in control, or when a component throws while rendering. It renders no editable fallback control and no Save action. The error notice offers a **Use classic settings** action that reloads the same page and section with `wc_settings_ui=classic` for that request. The action does not disable the feature flag, persist a preference, or reload automatically.


---

## Settings API

*Source: extensions/settings-and-config/settings-api.md*

# Settings API

The WooCommerce Settings API is used by extensions to display, save, and load settings. The best way to make use of the API in your extension is to create a class that extends the `WC_Settings_API` class:

```php
class My_Extension_Settings extends WC_Settings_API {
	//
}
```

## Defining form fields

You can define your fields using a method called `init_form_fields` in your class constructor:

```php
$this->init_form_fields();
```

You must have your settings defined before you can load them. Setting definitions go in the `form_fields` array:

```php
/**
 * Initialise gateway settings form fields.
 */
function init_form_fields() {
	$this->form_fields = array(
		'title'       => array(
			'title'       => __( 'Title', 'your-text-domain' ),
			'type'        => 'text',
			'description' => __( 'This controls the title which the user sees during checkout.', 'your-text-domain' ),
			'default'     => __( 'PayPal', 'your-text-domain' )
		),
		'description' => array(
			'title'       => __( 'Description', 'your-text-domain' ),
			'type'        => 'textarea',
			'description' => __( 'This controls the description which the user sees during checkout.', 'your-text-domain' ),
			'default'     => __( "Pay via PayPal; you can pay with your credit card if you don't have a PayPal account", 'your-text-domain' )
		)
	);
} // End init_form_fields()
```

(Make sure your class initializes the `form_fields` property so that the "Creation of dynamic property" error is not thrown in PHP 8.2+)

In the above example we define two settings, Title and Description. Title is a text box, whereas Description is a textarea. Notice how you can define a default value and a description for the setting itself.

Setting definitions use the following format:

```php
'setting_name' => array(
	'title'       => 'Title for your setting shown on the settings page',
	'description' => 'Description for your setting shown on the settings page',
	'type'        => 'text|password|textarea|checkbox|select|multiselect',
	'default'     => 'Default value for the setting',
	'class'       => 'Class for the input element',
	'css'         => 'CSS rules added inline on the input element',
	'label'       => 'Label', // For checkbox inputs only.
	'options'     => array( // Array of options for select/multiselect inputs only.
		'key' => 'value'
	),
)
```

## Displaying your settings

Create a method called `admin_options` containing the following:

```php
function admin_options() {
	?>
	<h2><?php esc_html_e( 'Your plugin name', 'your-text-domain' ); ?></h2>
	<table class="form-table">
		<?php $this->generate_settings_html(); ?>
	</table>
	<?php
}
```

This will output your settings in the correct format.

## Saving your settings

`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' ) );
```

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:

```php
// Load the settings.
$this->init_settings();
```

After that you can load your settings from the settings API. The `init_settings` method above populates the settings variable for you:

```php
// Define user set variables
$this->title       = $this->settings['title'];
$this->description = $this->settings['description'];
```


---

## Settings UI

*Source: extensions/settings-and-config/settings-ui.md*

# Settings UI

The settings UI is an experimental, opt-in path for rendering WooCommerce settings pages with React while keeping the existing `WC_Settings_Page` registration and save flow.

It is designed for extension authors who want to migrate incrementally. PHP still owns page registration, settings schema, permissions, script dependencies, and persistence. React owns field rendering and client-side interaction.

## Status

> **The settings UI is experimental.** Until it is marked as stable, the PHP API under `Automattic\WooCommerce\Admin\Settings`, the schema format, and the `@woocommerce/settings-ui` package can change in backwards-incompatible ways in any release. Expect to update integrations between WooCommerce versions.

-   The settings UI is behind the `settings-ui` feature flag.
-   With the flag disabled, settings pages keep the legacy PHP renderer.
-   With the flag enabled, a settings page still has to opt in explicitly.
-   Saves use the existing WooCommerce settings form POST flow by default.
-   The public PHP API is available under `Automattic\WooCommerce\Admin\Settings`.

## Build a settings UI integration

A complete integration has the same pieces whether it is a full settings tab or a section inside an existing tab:

1. Choose the location: a new `WC_Settings_Page` tab, or a registered section under an existing tab.
2. Define fields in PHP using the WooCommerce settings array. This remains the source of truth for labels, descriptions, defaults, option ids, and fallback rendering.
3. Add Settings UI metadata to fields that need custom React rendering, such as a stable `component` name.
4. Return any script handles that register those custom components before the settings UI mounts.
5. Use the default `form_post` save adapter unless the field is display-only or manages persistence separately.

## Enable the feature flag

For local testing, enable the feature with a small mu-plugin:

```php
<?php
add_filter(
	'woocommerce_admin_features',
	static function ( array $features ): array {
		$features[] = 'settings-ui';
		return array_values( array_unique( $features ) );
	}
);
```

## Opt in a settings page

A `WC_Settings_Page` subclass opts in by returning a settings UI adapter from `get_settings_ui_page()`.

For pages that only need built-in fields, use `LegacySettingsPageAdapter`:

```php
<?php
use Automattic\WooCommerce\Admin\Settings\LegacySettingsPageAdapter;
use Automattic\WooCommerce\Admin\Settings\SettingsUIPageInterface;

class My_Plugin_Settings_Page extends WC_Settings_Page {
	public function __construct() {
		$this->id    = 'my_plugin';
		$this->label = __( 'My plugin', 'my-plugin' );

		parent::__construct();
	}

	public function get_settings_ui_page(): ?SettingsUIPageInterface {
		return new LegacySettingsPageAdapter( $this );
	}
}
```

WooCommerce only uses the adapter when the `settings-ui` feature flag is enabled. Returning an adapter does not change the page while the feature flag is disabled.

## Register a section under an existing settings tab

Extensions can register a complete settings section under an existing WooCommerce settings tab. The section object defines where the section lives, how it is labelled, which fields it renders, which scripts power custom React components, and how fields are saved.

This is useful for payment providers or integrations that should live inside a Core-owned tab such as **WooCommerce > Settings > Payments**.

```php
<?php
use Automattic\WooCommerce\Admin\Settings\SettingsSection;
use Automattic\WooCommerce\Admin\Settings\SettingsSectionRegistry;

final class My_Plugin_Settings_Section extends SettingsSection {
	public function get_parent_page_id(): string {
		return 'checkout';
	}

	public function get_id(): string {
		return 'my_plugin';
	}

	public function get_label(): string {
		return __( 'My plugin', 'my-plugin' );
	}

	public function get_settings( WC_Settings_Page $parent_page ): array {
		return array(
			array(
				'title' => __( 'My plugin', 'my-plugin' ),
				'type'  => 'title',
				'id'    => 'my_plugin_options',
			),
			array(
				'title'     => __( 'Payment methods', 'my-plugin' ),
				'id'        => 'my_plugin_payment_methods',
				'type'      => 'multiselect',
				'component' => 'my-plugin/payment-method-picker',
				'options'   => array(
					'card' => __( 'Card', 'my-plugin' ),
					'bnpl' => __( 'Buy now, pay later', 'my-plugin' ),
				),
			),
			array(
				'type' => 'sectionend',
				'id'   => 'my_plugin_options',
			),
		);
	}

	public function get_script_handles( WC_Settings_Page $parent_page ): array {
		return array( 'my-plugin-settings-ui' );
	}

	// The inherited save adapter is `form_post` by default.
}

add_action(
	'woocommerce_settings_sections_registration',
	function ( SettingsSectionRegistry $registry ): void {
		$registry->register( new My_Plugin_Settings_Section() );
	}
);
```

WooCommerce creates the settings UI adapter for registered sections internally. When the settings UI feature flag is disabled, WooCommerce falls back to the legacy settings returned by `get_settings()`. Saves continue through the existing WooCommerce settings form flow and section-specific hooks such as `woocommerce_update_options_checkout_my_plugin`.

Use a section id that does not conflict with an existing section on the same settings tab. For the `checkout` tab, ids that match existing payment gateway sections are reserved.

### Provide a custom Settings UI page for a registered section

Sections with custom navigation, save handlers, or custom Settings UI schemas can provide their own Settings UI page instead of using the legacy settings adapter.

```php
<?php
use Automattic\WooCommerce\Admin\Settings\SettingsSection;
use Automattic\WooCommerce\Admin\Settings\SettingsUIPageInterface;

final class My_Plugin_Settings_Section extends SettingsSection {
	// Other settings section methods omitted for brevity.

	public function get_settings_ui_page( WC_Settings_Page $parent_page ): ?SettingsUIPageInterface {
		return new My_Plugin_Settings_UI_Page( $parent_page );
	}
}
```

When `get_settings_ui_page()` returns a `SettingsUIPageInterface`, WooCommerce uses it directly for the registered section. Returning `null` keeps the default behavior: WooCommerce converts the section's legacy `get_settings()` array into a Settings UI schema.

### Section navigation on custom pages

The Settings UI shell renders sibling-section navigation from the `shell.sectionNavigation` schema key. How it applies depends on where the page is registered:

-   **Top-level pages** never render shell section navigation. The classic section links render with the settings header instead, and any schema-provided value is cleared.
-   **Drill-down pages** default to no section navigation, since the header breadcrumbs replace it. Setting a custom array renders it as tabs under the header; each entry needs `id`, `label`, `href`, and `active` keys.

```php
// Custom navigation entry shape.
$schema['shell']['sectionNavigation'] = array(
	array(
		'id'     => 'my_section',
		'label'  => __( 'My section', 'my-plugin' ),
		'href'   => admin_url( 'admin.php?page=wc-settings&tab=checkout&section=my_section' ),
		'active' => true,
	),
);
```

## DataForm field migration

The legacy adapter converts the existing `get_settings()` array into a canonical schema for React. It supports common settings fields:

-   `text`
-   `password`
-   `email`
-   `url`
-   `tel`
-   `number`
-   `textarea`
-   `checkbox`
-   `select`
-   `radio`
-   `multiselect`
-   `multi_select_countries`
-   `single_select_country`
-   `single_select_page`
-   `info`

Fields before the first `title` marker are placed into a default group automatically.

For legacy country and page selectors, the adapter creates the same option list that the classic renderer creates at render time. Other select, radio, and multiselect fields can omit `options` or use an empty array. The Settings UI then renders the same empty choice set that the classic settings API accepts. When a field supplies options, WooCommerce validates their structure before rendering.

The default save adapter is `form_post`, which serializes hidden inputs so `WC_Admin_Settings::save_fields()` continues to save the submitted values.

## Extension registration and saving

Repeated extension registrations replace only matching entries. Registering a replacement control preserves unrelated controls, visibility predicates, save handlers, and regions in the same scope.

Use `form_post` for the existing PHP settings save flow. Integrations with separate persistence requirements can continue using the experimental `custom` save adapter and registered save handlers. The settings page owns the Save button, busy and error states, dirty-state reset, and navigation protection; the handler supplies the persistence operation. Both paths use DataForm for field rendering and editing.

## Custom component migration

If a field needs a custom React UI, declare a component name in the PHP field schema:

```php
array(
	'id'        => 'my_plugin_payment_methods',
	'title'     => __( 'Payment methods', 'my-plugin' ),
	'type'      => 'multiselect',
	'component' => 'my-plugin/payment-method-picker',
	'options'   => array(
		'card' => __( 'Card', 'my-plugin' ),
		'bnpl' => __( 'Buy now, pay later', 'my-plugin' ),
	),
)
```

Then register that component from JavaScript:

```ts
import { registerSettingsExtension } from '@woocommerce/settings-ui';
import { PaymentMethodPicker } from './payment-method-picker';

registerSettingsExtension( {
	scope: {
		page: 'my_plugin',
	},
	components: {
		'my-plugin/payment-method-picker': PaymentMethodPicker,
	},
} );
```

Omit `scope.section` for a page-wide registration. Use `section: ''` for the default section only, or pass a section id such as `section: 'payments'` for one named section.

See [Registering settings UI components](./registering-settings-ui-components.md) for the full component contract.

## Load extension scripts before mount

Custom component scripts must load before the settings app mounts. Return their registered WordPress script handles from the adapter:

```php
<?php
use Automattic\WooCommerce\Admin\Settings\LegacySettingsPageAdapter;

final class My_Plugin_Settings_UI_Page extends LegacySettingsPageAdapter {
	public function get_script_handles( string $section ): array {
		return array( 'my-plugin-settings-ui' );
	}
}
```

The settings embed script depends on the settings UI package and these handles only for the opted-in page. Other settings pages do not load it.

WooCommerce validates the schema structure and declared script handles on the server. Structural checks cover identifiers, references, list and map shapes, values that cross the PHP-to-JavaScript boundary, and renderer metadata. PHP does not keep a list of supported field types or decide whether an HTML attribute such as `min`, `max`, or `step` applies to a field. The registered component and the browser own those rendering rules. The existing `WC_Admin_Settings` flow remains responsible for validating, sanitizing, and saving submitted values.

Each declared script handle must be a non-empty string, and the script must be registered and enqueued before the Settings UI renders. WooCommerce trims surrounding whitespace and removes duplicate handles before loading them; whitespace-only handles are invalid. If the schema or a declared handle is invalid, WooCommerce renders the complete classic settings page in that response. PHP cannot inspect the JavaScript component registry. Extension-defined field types remain valid when their values use the Settings UI value contract and a matching `typeRenderers` entry renders them in the browser.

The component registry exists only in the browser, after PHP has selected the Settings UI mount. The browser resolves a named component, a field override, and then a type renderer. A field without an explicit `component` can then use a built-in DataForm control. When a field declares `component`, that custom control is required: if no registry entry resolves it, the page fails closed instead of silently replacing it with a built-in control. A field without an explicit component also fails closed when it has no registered or built-in control. Component render errors use the same fail-closed state.

The fail-closed state has no editable fallback and no Save action. Its error notice provides a **Use classic settings** link that preserves the current page and section and adds `wc_settings_ui=classic`. This is a user-initiated, request-only reload: it does not change the feature flag or automatically reload the page.

## Save adapters

The settings UI supports two save adapters:

| Adapter     | Behavior                                                             |
| ----------- | -------------------------------------------------------------------- |
| `form_post` | Serializes hidden inputs for the existing WooCommerce settings form. |
| `none`      | Does not submit a value. Use for display-only fields.                |

The legacy adapter uses `form_post` by default. A field can override its save behavior:

```php
array(
	'id'   => 'my_plugin_read_only_notice',
	'type' => 'info',
	'text' => __( 'This field is display only.', 'my-plugin' ),
	'save' => array(
		'adapter' => 'none',
	),
)
```

## Group descriptions

Group title rows can include a plain-text description. Use it for short context
that applies to the whole group.

```php
array(
	'id'    => 'my_plugin_checkout',
	'type'  => 'title',
	'title' => __( 'Checkout experience', 'my-plugin' ),
	'desc'  => __( 'Choose where customers can use express payment methods.', 'my-plugin' ),
)
```

Group descriptions render as plain text. Put links and other sanitized HTML in
a field description instead.

## Page header

The shell header (the page title, badges, breadcrumbs, and the top save button) is reserved for drill-down pages. WooCommerce decides this from the page registration, so a page cannot change it through its schema:

- Pages registered at the top level of settings, whether a `WC_Settings_Page` tab or a registered section, render without the header. The top-level settings tabs stay visible, pages with sections keep the classic section links, and the save button appears at the bottom of the page.
- Sections of the Payments tab render as drill-down pages. The header replaces the top-level settings tabs, and its breadcrumbs default to a link back to the Payments tab when the schema does not provide any. The save button renders in the header.

A settings UI page that supplies its own schema (via `SettingsUIPageInterface::get_schema()`) can set header content through the `shell` key for drill-down pages. Alongside `title` and `breadcrumbs`, the header supports a `subtitle` and `badges`:

```php
$schema['shell']['subtitle'] = __( 'Manage your store payment settings.', 'my-plugin' );
$schema['shell']['badges']   = array(
	array(
		'label'  => __( 'Active', 'my-plugin' ),
		'intent' => 'success', // default | info | success | warning | error
	),
);
```

`subtitle` renders under the page title. Each badge renders as a pill next to the title; `intent` selects its color. Both are plain text and are escaped on render.

`intent` is decorative styling only — it conveys meaning through color. The badge `label` must be self-descriptive so screen-reader and color-blind users get the same information (e.g. prefer `"Active"` or `"Beta"` over generic text). Unknown `intent` values fall back to `default`.

## Reference migration in WooCommerce core

The Products settings page is the Core reference migration. With `settings-ui` enabled, the Products tab renders through the settings UI. With the flag disabled, it renders through the existing legacy settings UI.

Use this page to verify the DataForm migration path before testing a plugin-specific page such as WooPayments.

## Testing an extension integration

1. Enable the `settings-ui` feature flag.
2. Return a settings UI adapter from your `WC_Settings_Page` subclass.
3. Start with built-in fields and confirm the page renders and saves.
4. Add `component` metadata only for fields that need custom UI.
5. Register scoped JavaScript components with `registerSettingsExtension()`.
6. Return custom script handles from `get_script_handles()` so they load before mount.
7. Disable the feature flag and confirm the legacy page still renders unchanged.

## Diagnostics

In development, the settings UI logs warnings for common integration issues:

-   The settings payload is missing.
-   The `wc-settings-ui` script is missing for a settings UI mount.
-   A field declares an unknown save adapter.

A field that declares an unregistered component, or whose type has no registered or built-in control, does not log a warning. The page fails closed instead, as described under [Load extension scripts before mount](#load-extension-scripts-before-mount).


---

## Integrating admin pages into WooCommerce extensions

*Source: extensions/settings-and-config/working-with-woocommerce-admin-pages.md*

# Integrating admin pages into WooCommerce extensions

## Introduction

There are a number of ways to manage admin-area pages for your WooCommerce extension. You can use existing PHP pages or create new React-powered pages. Regardless of the approach you choose, you'll need to register your page with the [`PageController`](https://woocommerce.github.io/code-reference/classes/Automattic-WooCommerce-Admin-PageController.html) in order to display the WooCommerce Admin header and activity panel on your page.

## Connecting a PHP-powered page to WooCommerce Admin

To register an existing PHP-powered admin page with the [`PageController`](https://woocommerce.github.io/code-reference/classes/Automattic-WooCommerce-Admin-PageController.html), use the [`wc_admin_connect_page()`](https://woocommerce.github.io/code-reference/namespaces/default.html#function_wc_admin_connect_page) function. For example:

```php
wc_admin_connect_page(
    array(
        'id'        => 'woocommerce-settings',
        'screen_id' => 'woocommerce_page_wc-settings-general',
        'title'     => array( 'Settings', 'General' ),
        'path'      => add_query_arg( 'page', 'wc-settings', 'admin.php' ),
    )
);
```

The [`wc_admin_connect_page()`](https://woocommerce.github.io/code-reference/namespaces/default.html#function_wc_admin_connect_page) function accepts an array of arguments, two of which are optional:

-   `id` (**required**) - This identifies the page with the controller.
-   `parent` (_optional_) - This value denotes the page as a child of a parent (using the parent's ID) and is used for generating breadcrumbs.
-   `screen_id` (**required**) - This corresponds to [`PageController::get_current_screen_id()`](https://woocommerce.github.io/code-reference/classes/Automattic-WooCommerce-Admin-PageController.html#method_get_current_screen_id). It is used to determine the current page. (see note below)
-   `title` (**required**) - This corresponds to the page's title and is used to build breadcrumbs. You can supply a string or an array of breadcrumb pieces here.
-   `path` (_optional_) - This is the page's relative path. Used for linking breadcrumb pieces when this page is a parent.

In the example above, you can see how to use an array to construct breadcrumbs for your extension. WooCommerce will attach a link leading to the `path` value to the first piece in the title array. All subsequent pieces are rendered as text and not linked.

### A note about determining the screen ID

WooCommerce Admin uses its own version of [`get_current_screen()`](https://developer.wordpress.org/reference/functions/get_current_screen/) to allow for more precise identification of admin pages, which may have various tabs and subsections.

The format of this ID may vary depending on the structural elements present on the page. Some formats that the function will generate are:

-   `{$current_screen->action}-{$current_screen->action}-tab-section`
-   `{$current_screen->action}-{$current_screen->action}-tab`
-   `{$current_screen->action}-{$current_screen->action}` if no tab is present
-   `{$current_screen->action}` if no action or tab is present

If your extension adds new pages with tabs or subsections, be sure to use the `wc_admin_pages_with_tabs` and `wc_admin_page_tab_sections` filters to have WooCommerce generate accurate screen IDs for them.

You can also use the `wc_admin_current_screen_id` filter to make any changes necessary to the screen ID generation behavior.

## Registering a React-powered page

To register a React-powered page, use the [`wc_admin_register_page()`](https://woocommerce.github.io/code-reference/namespaces/default.html#function_wc_admin_register_page) function. It accepts an array of arguments:

-   `id` (**required**) - This identifies the page with the controller.
-   `parent` (_optional_) - This denotes the page as a child of `parent` (using the parent's ID) and is used for generating breadcrumbs.
-   `title` (**required**) - This corresponds to the page's title and is used to build breadcrumbs. You can supply a String or an Array of breadcrumb pieces here.
-   `path` (**required**) - This is the page's path (relative to `#wc-admin`). It is used for identifying this page and for linking breadcrumb pieces when this page is a parent.
-   `capability` (_optional_) - User capability needed to access this page. The default value is `manage_options`.
-   `icon` (_optional_) - Use this to apply a Dashicons helper class or base64-encoded SVG. Include the entire dashicon class name, ie `dashicons-*`. Note that this won't be included in WooCommerce Admin Navigation.
-   `position` (_optional_) - Menu item position. See: [`add_menu_page()`](https://developer.wordpress.org/reference/functions/add_menu_page/) and [`add_submenu_page()`](https://developer.wordpress.org/reference/functions/add_submenu_page/).

Registering a React-powered page is similar to connecting a PHP page, but with some key differences. Registering pages will automatically create WordPress menu items for them, with the appropriate hierarchy based on the value of `parent`.

### Example: Adding a new WooCommerce Admin page

```php
if ( ! function_exists( 'YOUR_PREFIX_add_extension_register_page' ) ) {
  function YOUR_PREFIX_add_extension_register_page() {
    if ( ! function_exists( 'wc_admin_register_page' ) ) {
        return;
    }

    wc_admin_register_page( array(
        'id'       => 'my-example-page',
        'title'    => __( 'My Example Page', 'YOUR-TEXTDOMAIN' ),
        'parent'   => 'woocommerce',
        'path'     => '/example',
    ) );
  }
}
add_action( 'admin_menu', 'YOUR_PREFIX_add_extension_register_page' );
```

In the example above, we encapsulated our call to [`wc_admin_register_page()`](https://woocommerce.github.io/code-reference/namespaces/default.html#function_wc_admin_register_page) in a function that we have hooked to the [`admin_menu`](https://developer.wordpress.org/reference/hooks/admin_menu/) action. Once you have registered a page with the controller, you can supply a React component on the client side.

```js
import { addFilter } from '@wordpress/hooks';
import { __ } from '@wordpress/i18n';

const MyExamplePage = () => <h1>My Example Extension</h1>;

addFilter( 'woocommerce_admin_pages_list', 'my-namespace', ( pages ) => {
	pages.push( {
		container: MyExamplePage,
		path: '/example',
		breadcrumbs: [ __( 'My Example Page', 'YOUR-TEXTDOMAIN' ) ],
	} );

	return pages;
} );
```

Above, we're creating a simple [functional React component](https://reactjs.org/docs/components-and-props.html#function-and-class-components) for the sake of demonstration, but a real-world extension would likely have a more complex nesting of components.

## Further reading

You can learn more about how page registration works by checking out the [`PageController`](https://woocommerce.github.io/code-reference/classes/Automattic-WooCommerce-Admin-PageController.html) class in the WooCommerce Core Code Reference.

You can see real-world examples of the two page registration methods in WooCommerce Core by taking a look at:

-   [How WooCommerce Admin registers existing core pages](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/react-admin/connect-existing-pages.php) - registering PHP-powered pages
-   [How WooCommerce registers React-powered Analytics report pages](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/Admin/Analytics.php) - registering React-powered pages


---

## Extension Guidelines

*Source: extensions/ux-guidelines-extensions/README.md*

# Extension Guidelines

This section covers general guidelines, and best practices to follow in order to ensure your product experience aligns with WooCommerce for ease of use, seamless integration, and strong adoption.

We strongly recommend you review the current [WooCommerce setup experience](https://woocommerce.com/documentation/plugins/woocommerce/getting-started/) to get familiar with the user experience and taxonomy.

We also recommend you review the [WordPress core guidelines](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/) to ensure your product isn't breaking any rules, and review [this helpful resource](https://woocommerce.com/document/grammar-punctuation-style-guide/) on content style.

## General

Use existing WordPress/WooCommerce UI, built in components (text fields, checkboxes, etc) and existing menu structures.

Plugins which draw on WordPress' core design aesthetic will benefit from future updates to this design as WordPress continues to evolve. If you need to make an exception for your product, be prepared to provide a valid use case.

-   [WordPress Components library](https://wordpress.github.io/gutenberg/?path=/story/docs-introduction--page)
-   [Figma for WordPress](https://make.wordpress.org/design/2018/11/19/figma-for-wordpress/) | ([WordPress Design Library Figma](https://www.figma.com/file/e4tLacmlPuZV47l7901FEs/WordPress-Design-Library))
-   [WooCommerce Component Library](https://woocommerce.github.io/woocommerce/)

## Component Library - Storybook

> Storybook is an open source tool for developing UI components in isolation for React, React Native and more. It makes building stunning UIs organized and efficient.

The WooCommerce repository also includes [Storybook](https://storybook.js.org/) integration that allows testing and developing in a WooCommerce-agnostic context. This is very helpful for developing reusable components and trying generic JavaScript modules without any backend dependency.

You can launch Storybook by running `pnpm --filter=@woocommerce/storybook watch:build` locally. It will open in your browser automatically.

You can also test Storybook for the current `trunk` branch on GitHub Pages: [https://woocommerce.github.io/woocommerce](https://woocommerce.github.io/woocommerce)


---

## Accessibility

*Source: extensions/ux-guidelines-extensions/accessibility.md*

# Accessibility

Your extensions must meet the [WordPress Accessibility Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/) 

For more information on accessibility, check out the [WordPress accessibility quick start guide](https://make.wordpress.org/accessibility/handbook/best-practices/quick-start-guide/).


---

## Best Practices

*Source: extensions/ux-guidelines-extensions/best-practices.md*

# Best Practices

- **Plugin name should simply state the feature of the plugin and not use an existing core feature or extension in its' title**. The plugin name should appear at all times in the UI as a functional and original name. e.g "Appointments" instead of "VendorXYZ Bookings Plugin for WooCommerce."

- **Avoid creating new UI**. Before considering a new UI, review the WordPress interface to see if a component can be repurposed. Follow existing UI navigation patterns so merchants have context on where they are when navigating to a new experience.

- **Be considerate of mobile for the merchant (and shopper-facing if applicable) experience**. Stores operate 24/7. Merchants shouldn't be limited to checking their store on a desktop. Extensions need to be built responsively so they work on all device sizes.

- **It's all about the merchant**. Don't distract with unrelated content. Keep the product experience front and center to help the user achieve the tasks they purchased your product for.

- **Present a review request at the right time**. Presenting users with a request for review is a great way to get feedback on your extension. Think about best placement and timing to show these prompts.
    - Avoid showing the user a review request upon first launching the extension. Once the user has had a chance to set up, connect, and use the plugin they'll have a better idea of how to rate it.
    - Try to present the review request at a time that's least disruptive, such as after successful completion of a task or event.

- **Don't alter the core interface**. Don't express your brand by changing the shape of containers in the Woo admin.

- **Focus on the experience**. After the customer installs your product, the experience should be the primary focus. Keep things simple and guide the user to successful setup. Do not convolute the experience or distract the user with branding, self promotion, large banners, or anything obtrusive.

- **Keep copy short and simple**. Limit instructions within the interface to 120-140 characters. Anything longer should be placed in the product documentation.

- **Maintain a consistent tone when communicating with a user**. Maintain the same communication style and terminology across an extension, and avoid abbreviations and acronyms.

    - In extensions:
        - Use sentences for descriptions, feedback, and headlines. Avoid all-caps text.
        - Use standard punctuation and avoid excessive exclamation marks.
        - Use American English.
        - For more, read our [Grammar, Punctuation, and Capitalization guide](https://woocommerce.com/document/grammar-punctuation-style-guide/).


---

## Colors

*Source: extensions/ux-guidelines-extensions/colors.md*

# Colors

When creating extensions for the WordPress wp-admin, use the core colors, respect the user's WordPress admin color scheme selection, and ensure your designs pass AA level guidelines.

When using components with text, such as buttons, cards, or navigation, the background-to-text contrast ratio should be at least 4.5:1 to be [WCAG AA compliant](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html). Be sure to [test your color contrast ratios](https://webaim.org/resources/contrastchecker/) to abide by WCAG standards.

- [Accessibility handbook on uses of color and contrast](https://make.wordpress.org/accessibility/handbook/current-projects/use-of-color/)
- [Color contrast ratio checker](http://webaim.org/resources/contrastchecker/)
- [More resources regarding accessibility and color testing](http://webaim.org/resources/contrastchecker/)

For WooCommerce-specific color use, review our [Style Guide](https://woocommerce.com/brand-and-logo-guidelines/).


---

## Navigation

*Source: extensions/ux-guidelines-extensions/navigation.md*

# Navigation

Place your product navigation elements within the existing WooCommerce menu structure.

## Extension with its own menu item

The two options to extend the WooCommerce menu structure are within the category menu or within the relevant settings areas.

![Category Subnavigation Image](/img/doc_images/Category-Subnavigation.png)

## Category sub-navigation

If your plugin is extending an area of WooCommerce, it should live directly within that category’s section.

For example, TikTok lives in Marketing and Product Add-Ons lives in Products.

![Category Setting Image](/img/doc_images/Category-Settings.png)

## Settings

If your plugin adds a settings screen to set up the plugin, settings should be under an appropriate tab on the WooCommerce > Settings screen.

For example, shipping and payments extensions will appear in their relevant Settings area. Only if necessary, create a top-level settings tab if your extension has settings that don’t fit under existing tabs and creating a sub-tab isn’t appropriate.

### Don’t: Add top-level navigation

If your product is extending WooCommerce, there’s a 99.9% chance your product navigation and settings should live within the WooCommerce nav structure—see the menu structure examples above.

### Don’t: No iframes, only APIs

To create a cohesive experience, application data should be loaded via API instead of an iframe.

### Do: Keep menu structure simple

Keep menu structure simple. Use existing WooCommerce menu structures as much as possible to reduce redundancies.

If your plugin must introduce multiple pages or areas, consider grouping them in tabs using existing components to remain consistent with WooCommerce structure.

## Extension with no menu item

Some extensions don’t require a menu item because they extend specific features within an existing product area.

Integrated features include extensions that don't live in the navigation and simply add functionality to an existing system. For example, the Product Bundles plugin is limited to the product form.

In this case, there’s no navigation item or extension home screen. The Plugins page can be used to share updates with your users.

## Plugin name

The plugin name represents a way for merchants to identify your plugin across multiple touchpoints in the WooCommerce admin.

### Don’t: Use an existing feature or extension in the plugin title

The plugin name should appear at all times in the UI as a functional and original name. e.g “Appointments” instead of “VendorXYZ Bookings Plugin for WooCommerce.”

### Do: One-line navigation label

Keep extension names short, ideally within 20 characters, to make it easier for merchants to read and understand.

Keep all navigation labels on one line. Do not introduce a second line in any of the menu items.


---

## Notices

*Source: extensions/ux-guidelines-extensions/notices.md*

# Notices

Use notices primarily to provide user feedback in response to an action. Avoid using notices to communicate offers or announcements. Don't apply brand colors, fonts, or illustrations to your notices.

If a post-activation notice is required, keep it within the WordPress plugin area-do not display it on the dashboard, or any other parts of the platform.

Use the standard WordPress notice format and WooCommerce admin notices API.

## Language

Providing timely feedback like success and error messages is essential for ensuring that the user understands whether changes have been made.

Use short but meaningful messages that communicate what is happening. Ensure that the message provides instructions on what the user needs to do to continue. Proper punctuation should be used if the message contains multiple sentences. Avoid abbreviations.

## Design

The placement of feedback is vital so the user notices it. For example, when validation messages are needed to prompt the user to enter data, get the user's attention by displaying a message close to the inputs where data needs to be revised.

![visualization of four different notice designs next to one another](https://developer.woocommerce.com/wp-content/uploads/2023/12/notices1.png)

**Success** message: When the user performs an action that is executed successfully.

**Error Message**: When the user performs an action that could not be completed. (This can include validation messages.) When requiring the user to input data, make sure you verify whether each field meets the requirements, such as format, ranges, and if the field is required. Provide validation messages that are adjacent to each field so that the user can act on each in context. Avoid technical jargon.

**Warning Message**: When the user performs an action that may have completed successfully, but the user should review it and proceed with caution.

**Informational Message**: When it's necessary to provide information before the user executes any action on the screen. Examples can be limitations within a time period or when a global setting limits actions on the current screen.

### Examples

![an example of an informational message as a notice](https://developer.woocommerce.com/wp-content/uploads/2023/12/informational-notice.png)


---

## Onboarding

*Source: extensions/ux-guidelines-extensions/onboarding.md*

# Onboarding

The first experience your users have with your extension is crucial. A user activating your extension for the first time provides an opportunity to onboard new and reorient returning users the right way. Is it clear to the user how to get started? Keep in mind that the more difficult the setup, the more likely a user will abandon the product altogether so keep it simple and direct.

**Use primary buttons as calls to action and keep secondary information deprioritized for clarity**. Guide merchants towards successful setup with a clear next step and/or step-by-step process with progress indicator if the extension isn't configured or if setup is not complete.

**If necessary, provide a dismissible notification in the plugin area**. Add a notification to communicate next steps if setup or connection is required to successfully enable the plugin.

- Use the standard WordPress notice format and WooCommerce admin notices API.
- Notices should be dismissible. Users should always have a clear way to close the notice.
- Keep the post-activation notice with the WordPress plugin area in context of the plugin listing-do not display it on the dashboard, or any other parts of the platform.
- Don't display more than one notice.
- Try to keep the notice copy between 125 to 200 characters.

If no action is required for setup it's best to rely on other onboarding aids such as the Task List (link to component) and Inbox (link to component) to help users discover features and use your plugin.

**Get to the point and keep it instructional**. This is not a time to promote your brand or pitch the product. The user has bought your product and is ready to use it. Keep the information instructional and precise and avoid the use of branded colors, fonts, and illustrations in empty states and other onboarding aids. Help users with context on next steps.

**Show helpful empty states**. Rely on the existing plugin UI, if any, to guide users towards successful setup and use of the plugin. Avoid onboarding emails, push notifications, and welcome tours.

**Plugins should not redirect on activation from WordPress plugins area**. This can break bulk activation of plugins. Following the [dotorg plugin guideline 11](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/#11-plugins-should-not-hijack-the-admin-dashboard), the extension shouldn't hijack the dashboard or hide functionality of core or other extensions.

**Avoid dead end links and pages**. There should always be a way forward or back.

**Error Handling and Messaging**. If users encounter an error during setup, provide a clear and useful notification with clear and easily understood information on what went wrong and how to fix it.


---

## Settings

*Source: extensions/ux-guidelines-extensions/settings.md*

# Settings

**Make extension settings easy to understand.** Only include settings options that are crucial to the overall functionality of the product.

**Use smart defaults wherever possible**, rather than asking the merchant to configure.

**Group your settings intuitively.** Prioritize frequently-used settings at the top of each section, and place destructive or infrequently-used settings at the bottom.

**Group relevant settings together**, either by frequency of use (eg. Quick Settings), or by description (eg. Account Settings). Use section titles and sub-section titles to create clear hierarchy.

**Avoid long, tedious lists of many different types of settings.** This overwhelms the user with so many options that the product feels unusable to them. Consider using separate pages or sections for different types of settings, or progressive disclosure that surfaces the most used settings and hides everything else.

**Use impersonal titles and text**, eg. "Reports" instead of "My reports." Exception: If referring to the user is necessary for understanding the setting, use the second person ("you") rather than the first person ("I").

**Include helper text** for settings or sections that are not easily understandable.

**Use clear and consistent language.** Avoid technical jargon.


---

## Task List and Inbox

*Source: extensions/ux-guidelines-extensions/task-list-and-inbox.md*

# Task List and Inbox

Plugins should choose between implementing a Task or Inbox note based on the following guidelines. Avoid implementing both Task and Inbox note for the same message, which adds clutter and reduces the impact of the message.

Use the Task List and Inbox sparingly. Messages should be clear, concise, and maintain a consistent tone. Follow the [Grammar, Punctuation, and Capitalization guide](https://woocommerce.com/document/grammar-punctuation-style-guide/).

## Task List

![an example of a task in the task list](https://developer.woocommerce.com/wp-content/uploads/2023/12/task-list1.png)

Anything that **requires** action should go in the task list.

- *What appears in the Things to Do Task List:*

    - Tasks that will enable, connect, or configure an extension.
    - Tasks that are critical to the business, such as capturing payment or responding to disputes.

- *What doesn't appear in the Things to do Task List:*

    - Any critical update that would impact or prevent the functioning of the store should appear as a top level notice using the standard WordPress component.
    - Informational notices such as feature announcements or tips for using the plugin should appear in the Inbox as they are not critical and do not require action.
    - Notifications from user activity should result in regular feedback notices (success, info, error, warning).

Examples:

![three tasks in the task list under the heading "Things to do next" with the option to expand at the bottom to "show 3 more tasks" ](https://developer.woocommerce.com/wp-content/uploads/2023/12/task-list-example.png)

## Inbox

The Inbox provides informational, useful, and supplemental content to the user, while important notices and setup tasks have their separate and relevant locations.

![an example of an inbox notification](https://developer.woocommerce.com/wp-content/uploads/2023/12/inbox1.png)

- *What appears in the Inbox*:
    - Informational notices such as non-critical reminders.
    - Requests for plugin reviews and feedback.
    - Tips for using the plugin and introducing features.
    - Insights such as inspirational messages or milestones.

- *What doesn't appear in the Inbox*:

    - Notices that require action, extension setup tasks, or regular feedback notices.

Examples:

![an example of two inbox notifications listed under the "Inbox" section of the admin](https://developer.woocommerce.com/wp-content/uploads/2023/12/inbox-examples.png)


---

## Testing

*Source: extensions/ux-guidelines-extensions/testing.md*

# Testing

Users must be able to perform all actions of the functionality provided. This can be achieved by running user tests.

To run an effective user test, list as many scenarios your extension supports. An example of a scenario: "I am a store owner who wants to create a customizable product that includes letting customers add custom text and select from 5 different color options for the custom text." Give this scenario to testers, and watch them attempt/perform the task with your extension.

Different ways to do quick user testing:

- Recruit potential customers to test your product.
- Use online services that allow you to expose your extension to new users such as UserTesting.com.
- Ask enthusiasts in the [WooCommerce Community Slack](https://woocommerce.com/community-slack/) for feedback.


---

## Address Autocomplete Provider Implementation

*Source: features/address-autocomplete.md*

# Address Autocomplete Provider Implementation

## Overview

The WooCommerce Address Autocomplete system allows third-party services to provide address suggestions as customers type in their billing and shipping addresses during checkout. This guide explains how to create and register custom address providers to integrate with any address validation service.

Please note, this implementation will register the provider for both the shortcode and block-based checkouts.

## Architecture

The address autocomplete system consists of three main components:

1. **Server-side Provider (PHP)** - Handles provider registration and configuration
2. **Client-side Provider (JavaScript)** - Implements the search and selection logic
3. **UI Components** - Displays suggestions and handles user interactions (this is implemented by WooCommerce, plugins do not have to provide this)

## Registering the server-side provider

### Step 1: Create a WC_Address_Provider subclass

Create a PHP class that extends `WC_Address_Provider`:

```php
<?php
/**
 * Custom Address Provider Implementation
 *
 * @package YourPlugin
 */

namespace YourPlugin\Providers;

use WC_Address_Provider;

/**
 * Custom Address Provider
 */
class Custom_Address_Provider extends WC_Address_Provider {
    
    /**
     * Provider unique identifier.
     *
     * @var string
     */
    public $id = 'custom-provider';
    
    /**
     * Provider display name.
     *
     * @var string
     */
    public $name = 'Custom Address Provider';
    
    /**
     * Optional branding HTML to display with suggestions.
     *
     * @var string
     */
    public $branding_html = '<div class="custom-branding">Powered by Custom Provider</div>';
    
    /**
     * Constructor
     */
    public function __construct() {
        // Initialize any API clients or configurations.
    }
}
```

### Step 2: Register the provider

Register your provider with WooCommerce using the `woocommerce_address_providers` filter:

```php
/**
 * Register the custom address provider
 *
 * @param array $providers Existing providers.
 * @return array Modified providers list.
 */
function register_custom_address_provider( $providers ) {
    // Only register if the provider class exists
    if ( class_exists( 'YourPlugin\Providers\Custom_Address_Provider' ) ) {
        $providers[] = new \YourPlugin\Providers\Custom_Address_Provider();
    }
    
    return $providers;
}
add_filter( 'woocommerce_address_providers', 'register_custom_address_provider', 10, 1 );
```

## Registering the client-side provider

### Step 3: Implement JavaScript functions

Create a JavaScript file that implements the client-side provider logic.

#### Provider Object API

### Parameters

- _id_ `string` - Unique identifier that must match the server-side provider ID.
- _canSearch_ `function` - Function to determine if the provider supports searching in a given country.
    - Parameters:
        - _country_ `string` - Two-letter country code (e.g., 'US', 'GB').
    - Returns: `boolean` - Whether the provider supports this country.
- _search_ `function` - Asynchronous function to search for address suggestions.
    - Parameters:
        - _query_ `string` - The text entered by the user (minimum 3 characters).
        - _country_ `string` - Two-letter country code of the selected country.
        - _type_ `string` - Address type, either 'billing' or 'shipping'.
    - Returns: `Promise<Array>` - Promise resolving to an array of suggestion objects.
- _select_ `function` - Asynchronous function to retrieve complete address details.
    - Parameters:
        - _addressId_ `string` - The ID of the selected suggestion.
    - Returns: `Promise<Object|null>` - Promise resolving to an address object or null on error.

### Suggestion Object Format

The `search` function must return suggestion objects with the following structure:

- _id_ `string` - Unique identifier for this suggestion.
- _label_ `string` - Display text shown to the user.
- _matchedSubstrings_ `array` (optional) - Array of text ranges to highlight in the label.
    - _offset_ `number` - Starting position of matched text.
    - _length_ `number` - Length of matched text.

### Address Object Format

The `select` function must return address objects with these WooCommerce field names:

- _address_1_ `string` - Primary address line.
- _address_2_ `string` - Secondary address line (optional, can be empty string).
- _city_ `string` - City or town name.
- _state_ `string` - State or province code.
- _postcode_ `string` - ZIP or postal code.
- _country_ `string` - Two-letter country code.

### Example Implementation

```javascript
/**
 * Custom Address Provider Client Implementation
 */
// Define the provider
const customProvider = {
    // Must match the PHP provider's ID.
    id: 'custom-provider',

    /**
     * Check if provider can search in given country
     *
     * @param {string} country - Two-letter country code (e.g., 'US', 'GB')
     * @return {boolean} Whether the provider supports this country
     */
    canSearch: function ( country ) {
      // Define supported countries.
      const supportedCountries = [ 'US', 'CA', 'GB', 'AU' ];
      return supportedCountries.includes( country );
    },

    /**
     * Search for address suggestions
     *
     * @param {string} query - The search query entered by the user
     * @param {string} country - The selected country code
     * @param {string} type - Address type ('billing' or 'shipping')
     * @return {Promise<Array>} Array of suggestion objects
     */
    search: async function ( query, country, type ) {
      // Return search results.  Your function may call an endpoint to get this data.
      const data = [
        {
          id: '1',
          label: '123 Main Street, City, US',
          matchedSubstrings: [ { offset: 0, length: 3 } ],
        },
        {
          id: '2',
          label: '456 Oak Avenue, Town, US',
          matchedSubstrings: [ { offset: 0, length: 3 } ],
        },
        {
          id: '3',
          label: '789 Pine Road, Village, US',
          matchedSubstrings: [ { offset: 0, length: 3 } ],
        },
        {
          id: '4',
          label: '101 Pine Road, Village, US',
          matchedSubstrings: [ { offset: 0, length: 3 } ],
        },
        {
          id: '5',
          label: '101 Pine Road, Village, US',
          matchedSubstrings: [ { offset: 0, length: 3 } ],
        },
      ];
      return data;
    },

    /**
     * Get full address details for a selected suggestion
     *
     * @param {string} addressId - The ID of the selected suggestion
     * @return {Promise<Object>} Address details object
     */
    select: async function ( addressId ) {
      // Return address components in correct format. Your function may call an endpoint to get this data.
      return {
        // Required fields
        address_1: 'Test address 1',
        city: 'Test City',
        state: 'CA',
        postcode: '92010',
        country: 'US',
      };
    },
  };

// Register the provider.
if (
  window.wc &&
  window.wc.addressAutocomplete &&
  window.wc.addressAutocomplete.registerAddressAutocompleteProvider
) {
  window.wc.addressAutocomplete.registerAddressAutocompleteProvider(
    customProvider
  );
}
```

### Step 4: Enqueue the JavaScript

Enqueue your JavaScript file on checkout pages.

This JavaScript file should be enqueued even if the provider is not chosen as the preferred provider. This is because your provider could be used as a fallback if the preferred provider is unable to search for results.

```php
/**
 * Enqueue custom provider scripts
 */
function enqueue_custom_provider_scripts() {
    // Only load on checkout pages
    if ( is_checkout() ) {
        // Check if address autocomplete is enabled
        $is_enabled = get_option( 'woocommerce_address_autocomplete_enabled' ) === 'yes';
        
        if ( $is_enabled ) {
            wp_enqueue_script(
                'custom-address-provider',
                plugin_dir_url( __FILE__ ) . 'assets/js/custom-address-provider.js',
                array( 'wc-address-autocomplete' ),
                '1.0.0',
                true
            );
            
            // Pass data to JavaScript
            wp_localize_script(
                'custom-address-provider',
                'yourPlugin',
                array(
                    'nonce' => wp_create_nonce( 'wp_rest' ),
                    'apiUrl' => rest_url( 'your-plugin/v1/' )
                )
            );
        }
    }
}
add_action( 'wp_enqueue_scripts', 'enqueue_custom_provider_scripts' );
```

## REST API Implementation

The JavaScript provider communicates with your server via REST API endpoints. You'll need to create two endpoints:

1. **Address Search Endpoint** (`/wp-json/your-plugin/v1/address-search`)
   - Accepts: query string, country code, address type
   - Returns: Array of suggestions with IDs and labels

2. **Address Details Endpoint** (`/wp-json/your-plugin/v1/address-details`)
   - Accepts: Address/place ID
   - Returns: Complete address components

For implementation details, refer to the [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/).


## Troubleshooting

### Common Issues

1. **Provider not appearing in checkout**
   - Verify the provider is registered on the server
   - Check that JavaScript file is loading
   - Ensure provider ID matches between PHP and JavaScript

2. **Suggestions not showing**
   - Check browser console for JavaScript errors
   - Verify API endpoints are accessible
   - Check that country is supported by provider
   - Ensure search query is at least 3 characters

3. **Fields not populating on selection**
   - Verify `select` method returns correct field names
   - Check that address data matches WooCommerce field structure


---

## How to add columns to analytics reports and CSV downloads

*Source: features/analytics/adding-columns-to-analytics-reports-and-csv-downloads.md*

# How to add columns to analytics reports and CSV downloads

Adding columns to analytics reports are a really interesting way to add functionality to WooCommerce. New data can be consumed in the table view of the user interface and in your user's favourite spreadsheet or third party application by generating a CSV.

These instructions assume that you have a test plugin for WooCommerce installed and activated. You can follow the ["Getting started" instructions](extending-woocommerce-admin-reports.md) to get a test plugin set up. That post also includes instructions to further modify the query that is executed to get the data in an advanced fashion - it isn't required to just add a simple column.

In WooCommerce, analytics CSVs are generated in two different ways: in the web browser using data already downloaded, or on the server using a new query. It uses the size of the data set to determine the method - if there is more than one page worth of results it generates the data on the server and emails a link to the user, but if the results fit on one page the data is generated and downloaded straight away in the browser.

We'll look at the on-server method for adding a column first, because this is also where the data sent to the browser is generated.

This example extends the Downloads analytics report. To get some data in your system for this report, create a downloadable product with a download expiry value, create an order purchasing the product, then download the product several times. In testing I created 26 downloads, which is enough that the report is spread over two pages when showing 25 items per page, and on a single page when showing 50 items per page. This let me test CSVs generated both on the server and in browser.

In the PHP for your plugin, add three filter handlers:

```php
// This adds the SELECT fragment to the report SQL
function add_access_expires_select( $report_columns, $context, $table_name ) {
	if ( $context !== 'downloads' ) {
		return $report_columns;
	}
	$report_columns['access_expires'] =
		'product_permissions.access_expires AS access_expires';
	return $report_columns;
}
add_filter( 'woocommerce_admin_report_columns', 'add_access_expires_select', 10, 3 );

// This adds the column header to the CSV
function add_column_header( $export_columns ) {
	$export_columns['access_expires'] = 'Access expires';
	return $export_columns;
}
add_filter( 'woocommerce_filter_downloads_export_columns', 'add_column_header' );

// This maps the queried item to the export item
function map_access_expires( $export_item, $item ) {
	$export_item['access_expires'] = $item['access_expires'];
	return $export_item;
}
add_filter( 'woocommerce_report_downloads_prepare_export_item', 'map_access_expires', 10, 2 );
```

This adds the access expiry timestamp to the Downloads table/CSV (when the CSV is generated on the server).

These three filters together add the new column to the database query, adds the new header to the CSV, and maps the data returned from the database to the CSV. The first filter `woocommerce_admin_report_columns` adds a SQL fragment to the `SELECT` statement generated for the data query. The second filter `woocommerce_filter_downloads_export_columns` adds the column header to the CSV generated on the server. The third filter `woocommerce_report_downloads_prepare_export_item` maps the value in the data returned from the database query `$item` to the export item for the CSV.

To finish this off by adding support for columns generated in browser, another filter needs to be added to your plugin's JavaScript:

```js
import { addFilter } from "@wordpress/hooks";
function addAccessExpiresToDownloadsReport(reportTableData) {
  const { endpoint, items } = reportTableData;
  if ("downloads" !== endpoint) {
    return reportTableData;
  }

  reportTableData.headers = [
    ...reportTableData.headers,
    {
      label: "Access expires",
      key: "access_expires",
    },
  ];
  reportTableData.rows = reportTableData.rows.map((row, index) => {
    const item = items.data[index];
    const newRow = [
      ...row,
      {
        display: item.access_expires,
        value: item.access_expires,
      },
    ];
    return newRow;
  });

  return reportTableData;
}
addFilter(
  "woocommerce_admin_report_table",
  "dev-blog-example",
  addAccessExpiresToDownloadsReport
);
```

This filter first adds the header to the CSV, then maps the data.

With the plugin you've created, you should now be able to add data to the analytics table, the CSV generated on the server, and the CSV generated on the browser.


---

## How to extend WooCommerce analytics reports

*Source: features/analytics/extending-woocommerce-admin-reports.md*

# How to extend WooCommerce analytics reports

## Introduction

This document serves as a guide to extending WC-Admin Reports with a basic UI dropdown, added query parameters, and modification of SQL queries and resulting report data. This example will create a currency selector for viewing the Orders Report based on a specific currency.

## Getting started

We'll be using `@woocommerce/create-woo-extension` to scaffold a modern WordPress JavaScript environment for plugins. This tool creates a fully functional development environment for integrating with WooCommerce.

In this example, we'll be using the `sql-modification` variant to create a basic report extension that we can build upon.

In your `wp-content/plugins` directory, run the following command to create your extension:

```sh
npx @wordpress/create-block -t @woocommerce/create-woo-extension --variant=sql-modification my-extension-name
```

Navigate to the newly created folder and start development:

```sh
cd my-extension-name
npm run start
```

Optionally, you can use `wp-env` for a local WordPress environment:

```sh
npm -g i @wordpress/env
wp-env start
```

Don't forget to head over to `/wp-admin/plugins.php` and activate your plugin.

## Populating test data

Next, set up some orders to have sample data. Using WooCommerce > Settings > Currency, I added three test orders in Mexican Peso, US Dollar, and New Zealand Dollar.

After doing so, check out WC-Admin to make sure the orders are showing up by going to `/wp-admin/admin.php?page=wc-admin&period=today&path=%2Fanalytics%2Forders&compare=previous_year`. Note that without any modification currency figures show according to what I have currently in WooCommerce settings, which is New Zealand Dollar in this case.

![screenshot of wp-admin showing processing orders](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-02-19-at-12.11.34-pm.png?w=851)

We can confirm each order's currency by running the following query on the `wp_posts` table and joining `wp_postmeta` to gather currency meta values. Results show an order in NZD, USD, and MXN. This query is similar to the one we'll implement later in the guide to gather and display currency values.

```sql
SELECT
    ID,
    post_name,
    post_type,
    currency_postmeta.meta_value AS currency
FROM `wp_posts`
JOIN wp_postmeta currency_postmeta ON wp_posts.ID = currency_postmeta.post_id
WHERE currency_postmeta.meta_key = '_order_currency'
ORDER BY wp_posts.post_date DESC
LIMIT 3
```

![screenshot of resulting query](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-02-19-at-12.33.45-pm.png?w=756)

## Add a UI dropdown

In order to view reports in differing currencies, a filter or dropdown will be needed. We can add a basic filter to reports by adding a configuration object similar to [this one from the Orders Report](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/admin/client/analytics/report/orders/config.js#L50-L62).

First, we need to populate the client with data to render the dropdown. The best way to do this is to add data to the `wcSettings` global. This global can be useful for transferring static configuration data from PHP to the client. In the main PHP file, add currency settings to the Data Registry to populate `window.wcSettings.multiCurrency`.

```php
function add_currency_settings() {
	$currencies = array(
		array(
			'label' => __( 'United States Dollar', 'dev-blog-example' ),
			'value' => 'USD',
		),
		array(
			'label' => __( 'New Zealand Dollar', 'dev-blog-example' ),
			'value' => 'NZD',
		),
		array(
			'label' => __( 'Mexican Peso', 'dev-blog-example' ),
			'value' => 'MXN',
		),
	);

	$data_registry = Automattic\WooCommerce\Blocks\Package::container()->get(
		Automattic\WooCommerce\Blocks\Assets\AssetDataRegistry::class
	);

	$data_registry->add( 'multiCurrency', $currencies );
}

add_action( 'init', 'add_currency_settings' );
```

In the console, you can confirm the data has safely made its way to the client.

![screenshot of console](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-02-19-at-1.11.50-pm.png?w=476)

In `index.js` create the custom currency filter and add it the Orders Report.

```js
import { addFilter } from "@wordpress/hooks";
import { __ } from "@wordpress/i18n";

const addCurrencyFilters = (filters) => {
  return [
    {
      label: __("Currency", "dev-blog-example"),
      staticParams: [],
      param: "currency",
      showFilters: () => true,
      defaultValue: "USD",
      filters: [...(wcSettings.multiCurrency || [])],
    },
    ...filters,
  ];
};

addFilter(
  "woocommerce_admin_orders_report_filters",
  "dev-blog-example",
  addCurrencyFilters
);
```

If we check out the Orders Report, we can see our new dropdown. Play around with it and you'll notice the currency query parameter gets added to the url. If you check out the Network tab, you'll also see this value included in requests for data used to populate the report. For example, see the requests to orders stats endpoint, `/wp-json/wc-analytics/reports/orders/stats`. Next we'll use that query parameter to adjust report results.

![screenshot showing UI dropdown in wp-admin](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-02-19-at-1.16.44-pm.png?w=512)

## Handle currency parameters on the server

Now that our dropdown adds a `currency` query parameter to requests for data, the first thing we'll need to do is add the parameter as a query argument to the Orders Data Store and Orders Stats Data Store. Those data stores use query arguments for caching purposes, so by adding our parameter we can be sure a new database query will be performed when the parameter changes. Add the query argument in your main PHP file.

```php
function apply_currency_arg( $args ) {
	$currency = 'USD';

	if ( isset( $_GET['currency'] ) ) {
		$currency = sanitize_text_field( wp_unslash( $_GET['currency'] ) );
	}

	$args['currency'] = $currency;

	return $args;
}

add_filter( 'woocommerce_analytics_orders_query_args', 'apply_currency_arg' );
add_filter( 'woocommerce_analytics_orders_stats_query_args', 'apply_currency_arg' );
```

Now that we're sure a new database query is performed on mutations of the `currency` query parameter, we can start adding SQL statements to the queries that gather data.

Lets start by adding a JOIN for the orders table, orders stats, and orders chart.

```php
function add_join_subquery( $clauses ) {
	global $wpdb;

	$clauses[] = "JOIN {$wpdb->postmeta} currency_postmeta ON {$wpdb->prefix}wc_order_stats.order_id = currency_postmeta.post_id";

	return $clauses;
}

add_filter( 'woocommerce_analytics_clauses_join_orders_subquery', 'add_join_subquery' );
add_filter( 'woocommerce_analytics_clauses_join_orders_stats_total', 'add_join_subquery' );
add_filter( 'woocommerce_analytics_clauses_join_orders_stats_interval', 'add_join_subquery' );
```

Next, add a WHERE clause

```php
function add_where_subquery( $clauses ) {
  global $wpdb;

	$currency = 'USD';

	if ( isset( $_GET['currency'] ) ) {
		$currency = sanitize_text_field( wp_unslash( $_GET['currency'] ) );
	}

  // Use $wpdb->prepare to safely escape the currency value for SQL.
  $prepared_clause = $wpdb->prepare(
      'AND currency_postmeta.meta_key = %s AND currency_postmeta.meta_value = %s',
      '_order_currency',
      $currency
  );
  
  $clauses[] = $prepared_clause;

	return $clauses;
}

add_filter( 'woocommerce_analytics_clauses_where_orders_subquery', 'add_where_subquery' );
add_filter( 'woocommerce_analytics_clauses_where_orders_stats_total', 'add_where_subquery' );
add_filter( 'woocommerce_analytics_clauses_where_orders_stats_interval', 'add_where_subquery' );
```

And finally, a SELECT clause.

```php
function add_select_subquery( $clauses ) {
	$clauses[] = ', currency_postmeta.meta_value AS currency';

	return $clauses;
}

add_filter( 'woocommerce_analytics_clauses_select_orders_subquery', 'add_select_subquery' );
add_filter( 'woocommerce_analytics_clauses_select_orders_stats_total', 'add_select_subquery' );
add_filter( 'woocommerce_analytics_clauses_select_orders_stats_interval', 'add_select_subquery' );
```

Lets head back to the Orders Report and see if it works. You can manipulate the dropdown and see the relevant order reflected in the table.

![screenshot of WooCommerce Orders tab in wp-admin showing the relevant order reflected in the table.](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-02-19-at-1.38.54-pm.png?w=585)

## Finishing touches

The orders table could use some customisation to reflect the selected currency. We can add a column to display the currency in `index.js`. The `reportTableData` argument is an object of headers, rows, and items, which are arrays of data. We'll need to add a new header and append the currency to each row's data array.

```js
const addTableColumn = (reportTableData) => {
  if ("orders" !== reportTableData.endpoint) {
    return reportTableData;
  }

  const newHeaders = [
    {
      label: "Currency",
      key: "currency",
    },
    ...reportTableData.headers,
  ];
  const newRows = reportTableData.rows.map((row, index) => {
    const item = reportTableData.items.data[index];
    const newRow = [
      {
        display: item.currency,
        value: item.currency,
      },
      ...row,
    ];
    return newRow;
  });

  reportTableData.headers = newHeaders;
  reportTableData.rows = newRows;

  return reportTableData;
};

addFilter("woocommerce_admin_report_table", "dev-blog-example", addTableColumn);
```

![screenshot of customized table](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-02-19-at-4.02.15-pm.png?w=861)

While adding a column is certainly helpful, currency figures in the table and chart only reflect the store currency.

![screenshot of report](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-02-19-at-4.03.42-pm.png?w=865)

In order to change a Report's currency and number formatting, we can make use of the `woocommerce_admin_report_currency` JS hook. You can see the store's default sent to the client in `wcSettings.currency`, but we'll need to change these depending on the currency being viewed and designated by the query parameter `?currency=NZD`.

![screenshot of currency settings](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-04-03-at-11.18.42-am.png?w=238)

First, lets create some configs in index.js.

```js
const currencies = {
  MXN: {
    code: "MXN",
    symbol: "$MXN", // For the sake of the example.
    symbolPosition: "left",
    thousandSeparator: ",",
    decimalSeparator: ".",
    precision: 2,
  },
  NZD: {
    code: "NZD",
    symbol: "$NZ",
    symbolPosition: "left",
    thousandSeparator: ",",
    decimalSeparator: ".",
    precision: 2,
  },
};
```

Finally, add our function to the hook which applies a config based on the currency query parameter.

```js
const updateReportCurrencies = (config, { currency }) => {
  if (currency && currencies[currency]) {
    return currencies[currency];
  }
  return config;
};

addFilter(
  "woocommerce_admin_report_currency",
  "dev-blog-example",
  updateReportCurrencies
);
```

🎉 We can now view our Orders Report and see the currency reflected in monetary values throughout the report.

![Screenshot of customized order report](https://developer.woocommerce.com/wp-content/uploads/2023/12/screen-shot-2020-04-03-at-11.29.05-am.png?w=912)

## Conclusion

In this guide, we added a UI element to manipulate query parameters sent to the server and used those values to modify SQL statements which gather report data. In doing so, we established a way to highly customise WC-Admin reports. Hopefully this example illustrates how the platform can be tailored by extensions to bring a powerful experience to users.


---

## WooCommerce email editor integration guide

*Source: features/email/email-editor-integration.md*

# WooCommerce email editor integration guide

This guide shows how extensions can add custom email notifications that integrate with the WooCommerce Email Editor.  
**Note:** The WooCommerce Email Editor is currently in alpha. To enable it, go to **WooCommerce > Settings > Advanced > Features** and enable **Block Email Editor (alpha)**.

## Quick start

1. **Extend `WC_Email`** – Create a custom email class for your notification by extending the core WooCommerce email class.
2. **Register with `woocommerce_email_classes`** – Add your new email class to WooCommerce so it appears in the admin email settings.
3. **Register the email with the block editor** – Register your email ID with the `woocommerce_transactional_emails_for_block_editor` filter to enable block editor support.
4. **Create a block template** – Design a block-based template to ensure your email works seamlessly with the WooCommerce Email Editor.
5. **Set up triggers** – Define when and under what conditions your custom email should be sent (for example, after a specific user action or event).

## 1. Create email class

Extend `WC_Email` and implement the required methods:

```php
class YourPlugin_Custom_Email extends WC_Email {

    public function __construct() {
        $this->id             = 'your_plugin_custom_email';
        $this->title          = __( 'Custom Email', 'your-plugin' );
        $this->customer_email = true;
        $this->email_group    = 'your-plugin';

        $this->template_html  = 'emails/your-custom-email.php';
        $this->template_plain = 'emails/plain/your-custom-email.php';
        $this->template_base  = plugin_dir_path( __FILE__ ) . 'templates/';

        parent::__construct();
    }

    public function get_default_subject() {
        return __( 'Your custom email subject', 'your-plugin' );
    }

    public function get_default_heading() {
        return __( 'Your custom email heading', 'your-plugin' );
    }

    public function trigger( $order_id ) {
        $this->setup_locale();

        if ( $order_id ) {
            $order = wc_get_order( $order_id );
            $this->object = $order;
            $this->recipient = $order->get_billing_email();
        }

        if ( $this->is_enabled() && $this->get_recipient() ) {
            $this->send( $this->get_recipient(), $this->get_subject(), $this->get_content(), $this->get_headers(), $this->get_attachments() );
        }

        $this->restore_locale();
    }

    public function get_content_html() {
        return wc_get_template_html( $this->template_html, array(
            'order'         => $this->object,
            'email_heading' => $this->get_heading(),
            'sent_to_admin' => false,
            'plain_text'    => false,
            'email'         => $this,
        ) );
    }

    public function get_content_plain() {
        return wc_get_template_html( $this->template_plain, array(
            'order'         => $this->object,
            'email_heading' => $this->get_heading(),
            'sent_to_admin' => false,
            'plain_text'    => true,
            'email'         => $this,
        ) );
    }
}
```

## 2. Register email

Add your email to WooCommerce:

```php
// Add the custom email class to the WooCommerce Emails.
function your_plugin_add_email_class( $email_classes ) {
    $email_classes['YourPlugin_Custom_Email'] = new YourPlugin_Custom_Email();
    return $email_classes;
}
add_filter( 'woocommerce_email_classes', 'your_plugin_add_email_class' );

// Add the custom email group. This is only necessary if email_group is not set on the WC_Email class.
function your_plugin_add_email_group( $email_groups ) {
    $email_groups['your-plugin'] = __( 'Your Plugin', 'your-plugin' );
    return $email_groups;
}
add_filter( 'woocommerce_email_groups', 'your_plugin_add_email_group' );
```

## 3. Register the email with the block editor

Third-party extensions need to explicitly opt their emails into block editor support. This is done by registering your email ID with the `woocommerce_transactional_emails_for_block_editor` filter:

```php
/**
 * Register custom transactional emails for the block editor.
 *
 * @param array $emails Array of email IDs.
 * @return array Modified array of email IDs.
 */
function your_plugin_register_transactional_emails_for_block_editor( $emails ) {
    $emails[] = 'your_plugin_custom_email';
    return $emails;
}
add_filter( 'woocommerce_transactional_emails_for_block_editor', 'your_plugin_register_transactional_emails_for_block_editor' );
```

**Important:** Without this step, your email may still appear in the email list, but it will not use the email editor, as explicit opt-in is required from third-party developers.

**Note:** For third-party extensions, WooCommerce will not create an email post unless you opt-in using the `woocommerce_transactional_emails_for_block_editor` filter. Email posts are created lazily. A draft post is created only when the user opens the email in the editor. Until that draft is published, it is not the rendering source: the email renders directly from the file template, regardless of the draft's content.

### Customizing email template post creation

You can modify the email post data before it's created using the `woocommerce_email_content_post_data` filter. This allows you to customize the post title, content, meta, or any other post data when the post is created (that is, when the user first opens the email in the editor). The filtered content is also what renders when no saved post exists yet. Note that `post_status` is system-owned and a value returned by the filter is ignored: posts are created as `draft` and only become the rendering source when published.

**Filter details:**

| Property   | Value                                                                   |
| ---------- | ----------------------------------------------------------------------- |
| Hook name  | `woocommerce_email_content_post_data`                                   |
| Since      | 10.5.0                                                                  |
| Parameters | `$post_data` (array), `$email_type` (string), `$email_data` (\WC_Email) |
| Returns    | array                                                                   |

**Parameters:**

-   `$post_data` _(array)_ – The post data array that will be passed to `wp_insert_post()`. Contains keys like `post_type`, `post_status`, `post_title`, `post_content`, `post_excerpt`, `post_name`, and `meta_input`.
-   `$email_type` _(string)_ – The email type identifier (e.g., 'customer_processing_order').
-   `$email_data` _(\WC_Email)_ – The WooCommerce email object.

**Return value:**

Return the modified post data array. This array will be used to create the email template post.

#### Example: Modifying email template post data

```php
/**
 * Customize email template post data during generation.
 *
 * @param array     $post_data  The post data array.
 * @param string    $email_type The email type identifier.
 * @param \WC_Email $email_data The WooCommerce email object.
 * @return array Modified post data.
 */
function your_plugin_customize_email_template_post( $post_data, $email_type, $email_data ) {
    // Modify the post title for specific email types.
    if ( 'customer_processing_order' === $email_type ) {
        $post_data['post_title'] = __( 'Custom Processing Order Email', 'your-plugin' );
    }

    // Modify the post content (block template HTML).
    $post_data['post_content'] = str_replace(
        'default content',
        'custom content',
        $post_data['post_content']
    );

    // Add custom meta data.
    $post_data['meta_input']['custom_meta_key'] = 'custom_value';

    return $post_data;
}
add_filter( 'woocommerce_email_content_post_data', 'your_plugin_customize_email_template_post', 10, 3 );
```

**Important notes:**

-   You can modify any valid `wp_insert_post()` parameter (`post_title`, `post_content`, `post_excerpt`, `post_name`, `meta_input`, etc.) — except `post_status`, which is system-owned and ignored.
-   Always return the modified `$post_data` array.
-   When modifying `post_content`, ensure valid block markup is maintained.
-   The filter runs for all email types; check `$email_type` to target specific emails.

## 4. Create the initial block template

Create `templates/emails/block/your-custom-email.php`:

**Template base property:** Make sure to set the `$template_base` property in your email class constructor to point to your plugin's template directory. This allows WooCommerce to properly locate and load your block template files. The block template filename is expected to match the plain template, but using the `block` directory instead of `plain`.

```php
<?php
use Automattic\WooCommerce\Internal\EmailEditor\BlockEmailRenderer;
defined( 'ABSPATH' ) || exit;
?>

<!-- wp:heading -->
<h2 class="wp-block-heading"><?php printf( esc_html__( 'Hello %s!', 'your-plugin' ), '<!--[woocommerce/customer-first-name]-->' ); ?></h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p><?php printf( esc_html__( 'Thank you for your order #%s.', 'your-plugin' ), '<!--[woocommerce/order-number]-->' ); ?></p>
<!-- /wp:paragraph -->

<!-- wp:woocommerce/email-content {"lock":{"move":false,"remove":true}} -->
<div class="wp-block-woocommerce-email-content"><?php echo esc_html( BlockEmailRenderer::WOO_EMAIL_CONTENT_PLACEHOLDER ); ?></div>
<!-- /wp:woocommerce/email-content -->
```

Pro tip: If you use a custom path for your email templates, set the block template path using the `template_block` property on the email class.

**Email content placeholder:**

The `BlockEmailRenderer::WOO_EMAIL_CONTENT_PLACEHOLDER` is a special placeholder that gets replaced with the main email content when the email is rendered. This placeholder is essential for integrating with WooCommerce's email system and allows the email editor to inject the core email content (like order details, customer information, etc.) into your custom template.

By default, WooCommerce uses the [general block email template](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/templates/emails/block/general-block-email.php) to generate the content that replaces this placeholder. When WooCommerce processes your email template, it replaces this placeholder with the appropriate email content based on the email type and context.

If your email needs to use different content, you have two options:

**Using custom block content template:**

1. **Set a custom template**: Set the `$template_block_content` property in your email class constructor to point to a custom template for the block content:

    ```php
    $this->template_block_content = 'emails/block/custom-content.php';
    ```

2. **Implement custom logic**: Implement the `get_block_editor_email_template_content` method in your email class to provide custom logic for generating the content:

    ```php
    public function get_block_editor_email_template_content() {
        return '<!-- wp:paragraph -->
    <p>Your custom block template content here</p>
    <!-- /wp:paragraph -->';
    }
    ```

**Using action hook:**
You can use the action hook `woocommerce_email_general_block_email` to execute additional actions within the content template.

## 5. Set Up Triggers

**Set up when your email should be sent** by hooking into WordPress actions. You can trigger emails on WooCommerce events or your own custom actions:

```php
function your_plugin_trigger_custom_email( $order_id ) {
    $emails = WC()->mailer()->get_emails();
    $email  = $emails['YourPlugin_Custom_Email'];

    $email->trigger( $order_id );
}

// Trigger on WooCommerce order completion
add_action( 'woocommerce_order_status_completed', 'your_plugin_trigger_custom_email' );

// Trigger on your custom plugin action
add_action( 'your_plugin_custom_action', 'your_plugin_trigger_custom_email' );
```

**Common WooCommerce hooks you can use:**

-   `woocommerce_order_status_completed` - When order is completed
-   `woocommerce_order_status_processing` - When order is processing
-   `woocommerce_new_order` - When new order is created
-   `woocommerce_customer_created` - When new customer registers

## Personalization tags

**Personalization tags** allow you to insert dynamic content into your emails. They appear as `<!--[tag-name]-->` in your templates and get replaced with actual values when the email is sent.

### Built-in tags

WooCommerce provides many built-in personalization tags organized by category:

#### Customer tags

-   `<!--[woocommerce/customer-email]-->` - Customer's email address
-   `<!--[woocommerce/customer-first-name]-->` - Customer's first name
-   `<!--[woocommerce/customer-last-name]-->` - Customer's last name
-   `<!--[woocommerce/customer-full-name]-->` - Customer's full name
-   `<!--[woocommerce/customer-username]-->` - Customer's username
-   `<!--[woocommerce/customer-country]-->` - Customer's country

#### Order tags

-   `<!--[woocommerce/order-number]-->` - Order number
-   `<!--[woocommerce/order-date]-->` - Order date (supports format parameter)
-   `<!--[woocommerce/order-items]-->` - List of order items
-   `<!--[woocommerce/order-subtotal]-->` - Order subtotal
-   `<!--[woocommerce/order-tax]-->` - Order tax amount
-   `<!--[woocommerce/order-discount]-->` - Order discount amount
-   `<!--[woocommerce/order-shipping]-->` - Order shipping cost
-   `<!--[woocommerce/order-total]-->` - Order total amount
-   `<!--[woocommerce/order-payment-method]-->` - Payment method used
-   `<!--[woocommerce/order-payment-url]-->` - Payment URL for order
-   `<!--[woocommerce/order-transaction-id]-->` - Transaction ID
-   `<!--[woocommerce/order-shipping-method]-->` - Shipping method used
-   `<!--[woocommerce/order-shipping-address]-->` - Formatted shipping address
-   `<!--[woocommerce/order-billing-address]-->` - Formatted billing address
-   `<!--[woocommerce/order-view-url]-->` - Customer order view URL
-   `<!--[woocommerce/order-admin-url]-->` - Admin order edit URL
-   `<!--[woocommerce/order-custom-field]-->` - Custom order field (requires key parameter)

#### Site tags

-   `<!--[woocommerce/site-title]-->` - Site title
-   `<!--[woocommerce/site-homepage-url]-->` - Homepage URL

#### Store tags

-   `<!--[woocommerce/store-email]-->` - Store email address
-   `<!--[woocommerce/store-url]-->` - Store URL
-   `<!--[woocommerce/store-name]-->` - Store name
-   `<!--[woocommerce/store-address]-->` - Store address
-   `<!--[woocommerce/my-account-url]-->` - My Account page URL
-   `<!--[woocommerce/admin-order-note]-->` - Admin order note

### Custom personalization tags

**Create your own tags** for plugin-specific data using the proper WooCommerce hook:

```php
/**
 * Register custom personalization tags for the email editor.
 *
 * @param \Automattic\WooCommerce\EmailEditor\Engine\PersonalizationTags\Personalization_Tags_Registry $registry The registry.
 * @return \Automattic\WooCommerce\EmailEditor\Engine\PersonalizationTags\Personalization_Tags_Registry
 */
function your_plugin_register_personalization_tags( $registry ) {
    // Register custom field tag
    $custom_field_tag = new \Automattic\WooCommerce\EmailEditor\Engine\PersonalizationTags\Personalization_Tag(
        // Display name in editor
        __( 'Custom Field', 'your-plugin' ),
        // Token (unique identifier)
        'your-plugin/custom-field',
        // Category for grouping
        __( 'Your Plugin Group', 'your-plugin' ),
        // Callback function
        'your_plugin_get_custom_field_value',
        // Attributes (optional)
        array(),
        // Value to insert (optional - defaults to token)
        null,
        // Post types this tag works with
        array( 'woo_email' )
    );
    $registry->register( $custom_field_tag );

    return $registry;
}

// Callback function that returns the custom field value
function your_plugin_get_custom_field_value( $context, $args = array() ) {
    $order_id = $context['order']->get_id() ?? 0;
    return get_post_meta( $order_id, '_custom_field', true );
}

// Register with the proper WooCommerce hook
add_filter( 'woocommerce_email_editor_register_personalization_tags', 'your_plugin_register_personalization_tags' );
```

**Usage in templates:** Use `<!--[your-plugin/custom-field]-->` in your block template, and it will be replaced with the value returned by your callback function.

To learn more about personalization tags, please see the [personalization tags documentation](https://github.com/woocommerce/woocommerce/blob/trunk/packages/php/email-editor/docs/personalization-tags.md) in the `woocommerce/email-editor` package.

### Providing custom context for personalization tags

Use the `woocommerce_email_editor_integration_personalizer_context_data` filter to provide custom context data to your personalization tags. This is useful when your extension needs to pass additional data (such as subscription details, loyalty points, or custom order metadata) that your personalization tag callbacks can access.

**Filter details:**

| Property   | Value                                                            |
| ---------- | ---------------------------------------------------------------- |
| Hook name  | `woocommerce_email_editor_integration_personalizer_context_data` |
| Since      | 10.5.0                                                           |
| Parameters | `$context` (array), `$email` (\WC_Email)                         |
| Returns    | array                                                            |

**Parameters:**

-   `$context` _(array)_ – The existing context data array. This may already contain data from WooCommerce core or other extensions.
-   `$email` _(\WC_Email)_ – The WooCommerce email object being processed. You can use this to access the email ID, recipient, and the object associated with the email (such as an order or customer).

**Return value:**

Return an array of custom context data along with Woo core context data. This array will be accessible to all personalization tag callbacks through the `$context` parameter.

#### Example: Adding subscription data to context

```php
/**
 * Add subscription-related context data for personalization tags.
 *
 * @param array     $context The existing context data.
 * @param \WC_Email $email   The WooCommerce email object.
 * @return array Modified context data.
 */
function your_plugin_add_subscription_context( $context, $email ) {
    // Only add context for subscription-related emails.
    if ( strpos( $email->id, 'subscription' ) === false ) {
        return $context;
    }

    // Get the order from the email object.
    $order = $email->object instanceof WC_Order ? $email->object : null;

    if ( ! $order ) {
        return $context;
    }

    // Add your custom subscription data to context.
    $context['subscription_id']       = $order->get_meta( '_subscription_id' );
    $context['subscription_end_date'] = $order->get_meta( '_subscription_end_date' );
    $context['renewal_count']         = (int) $order->get_meta( '_renewal_count' );

    return $context;
}
add_filter( 'woocommerce_email_editor_integration_personalizer_context_data', 'your_plugin_add_subscription_context', 10, 2 );
```

#### Example: Using custom context in a personalization tag callback

Once you've added custom data to the context, your personalization tag callbacks can access it:

```php
/**
 * Personalization tag callback that uses custom context data.
 *
 * @param array $context The context data (includes your custom data).
 * @param array $args    Optional attributes passed to the tag.
 * @return string The personalized value.
 */
function your_plugin_get_subscription_end_date( $context, $args = array() ) {
    // Access the custom context data you added via the filter.
    $end_date = $context['subscription_end_date'] ?? '';

    if ( empty( $end_date ) ) {
        return __( 'N/A', 'your-plugin' );
    }

    // Format the date according to site settings.
    return date_i18n( get_option( 'date_format' ), strtotime( $end_date ) );
}
```

**Important notes:**

-   The filter is called during email personalization, so your context data is available when personalization tags are processed.
-   Always check if the email type is relevant before adding context data to avoid unnecessary processing.
-   Use unique keys for your context data to prevent conflicts with WooCommerce core or other extensions.
-   The `$email->object` property typically contains the main object associated with the email (e.g., `WC_Order` for order emails, `WP_User` for user-related emails).
-   When using context data in personalization tags, ensure proper escaping based on the output context (e.g., `esc_html()`, `esc_attr()`, `esc_url()`).

## Complete example

Below is an example of a loyalty program welcome email implementation:

**Email Class:**

```php
class YourPlugin_Loyalty_Welcome_Email extends WC_Email {
    public function __construct() {
        $this->id             = 'loyalty_welcome_email';
        $this->title          = __( 'Loyalty Welcome Email', 'your-plugin' );
        $this->customer_email = true;
        $this->email_group    = 'loyalty';

        $this->template_html  = 'emails/loyalty-welcome.php';
        $this->template_plain = 'emails/plain/loyalty-welcome.php';
        $this->template_block = 'emails/block/loyalty-welcome.php';
        $this->template_base  = plugin_dir_path( __FILE__ ) . 'templates/';

        parent::__construct();
    }

    public function get_default_subject() {
        return __( 'Welcome to our Loyalty Program!', 'your-plugin' );
    }

    public function trigger( $customer_id, $points_earned = 0 ) {
        $this->setup_locale();
        $customer = new WC_Customer( $customer_id );
        $this->object = $customer;
        $this->recipient = $customer->get_email();

        if ( $this->is_enabled() && $this->get_recipient() ) {
            $this->send( $this->get_recipient(), $this->get_subject(), $this->get_content(), $this->get_headers(), $this->get_attachments() );
        }
        $this->restore_locale();
    }

    public function get_content_html() {
        return wc_get_template_html( $this->template_html, array(
            'customer'       => $this->object,
            'email_heading'  => $this->get_heading(),
            'sent_to_admin'  => false,
            'plain_text'     => false,
            'email'          => $this,
        ) );
    }

    public function get_content_plain() {
        return wc_get_template_html( $this->template_plain, array(
            'customer'       => $this->object,
            'email_heading'  => $this->get_heading(),
            'sent_to_admin'  => false,
            'plain_text'     => true,
            'email'          => $this,
        ) );
    }
}
```

**Block Email:**

```php
<!-- wp:heading -->
<h2 class="wp-block-heading"><?php printf( esc_html__( 'Welcome %s!', 'your-plugin' ), '<!--[woocommerce/customer-first-name]-->' ); ?></h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p><?php esc_html_e( 'Thank you for joining our loyalty program!', 'your-plugin' ); ?></p>
<!-- /wp:paragraph -->

<!-- wp:woocommerce/email-content {"lock":{"move":false,"remove":true}} -->
<div class="wp-block-woocommerce-email-content"><?php echo esc_html( BlockEmailRenderer::WOO_EMAIL_CONTENT_PLACEHOLDER ); ?></div>
<!-- /wp:woocommerce/email-content -->
```

**Registration and Setup:**

This code ties everything together - registering the email class, template, and trigger:

```php
// Add the custom email class to the WooCommerce Emails.
add_filter( 'woocommerce_email_classes', function( $classes ) {
    $classes['YourPlugin_Loyalty_Welcome_Email'] = new YourPlugin_Loyalty_Welcome_Email();
    return $classes;
} );

// Add the custom email group.
add_filter( 'woocommerce_email_groups', function( $email_groups ) {
    $email_groups['loyalty'] = __( 'Loyalty Program', 'your-plugin' );
    return $email_groups;
} );

// Register the email with the block editor.
add_filter( 'woocommerce_transactional_emails_for_block_editor', function( $emails ) {
    $emails[] = 'loyalty_welcome_email';
    return $emails;
} );

// Set up trigger - when to send the email
add_action( 'your_plugin_customer_joined_loyalty', function( $customer_id, $points_earned ) {
    $emails = WC()->mailer()->get_emails();
    $email  = $emails['YourPlugin_Loyalty_Welcome_Email'];

    $email->trigger( $customer_id, $points_earned );
}, 10, 2 );
```

**How it works:**

1. **Email registration** makes your email appear in **WooCommerce > Settings > Emails**
2. **Block editor registration** enables your email to work with the WooCommerce Email Editor
3. **Template registration** allows you to register additional email templates for use and editing in the block editor
4. **Trigger setup** automatically sends the email when a customer joins your loyalty program

## Best practices

-   **Sanitize inputs and escape outputs:** Always validate and sanitize any data used in your email logic, and escape outputs in your templates to prevent security issues and display problems.
-   **Test across email clients:** Email layouts can look different in various clients. Tools like Litmus or Email on Acid can help with testing your emails in popular clients (such as Gmail, Outlook, and Apple Mail) to ensure they look as intended.
-   **Use efficient queries and cache data:** When fetching data for your emails, use optimized queries and cache results if possible to avoid slowing down your site.
-   **Follow WordPress coding standards:** Write your code according to WordPress standards for better readability and compatibility.
-   **Include proper error handling:** Add checks and error handling so that issues (like missing data or failed sends) are caught and can be debugged easily.

## Troubleshooting

-   **Email not in admin?**
    Double-check that your email class is registered with the `woocommerce_email_classes` filter and that the class name is correct.
-   **Email not using the block template or email editor?**
    Ensure you have registered your email ID with the `woocommerce_transactional_emails_for_block_editor` filter.
-   **Template not loading?**
    Make sure the template file path is correct and that you have registered it with the email editor.
-   **Tags not working?**
    Confirm that your personalization tag callbacks are registered and returning the expected values.
-   **Email not sending?**
    Check that the email is enabled in WooCommerce settings and that your trigger action is firing as expected.

---

Your custom email will now be available in **WooCommerce > Settings > Emails** and can be edited using the block editor.


---

## Email Editor Logging

*Source: features/email/email-editor-logging.md*

# Email Editor Logging

Email editor logging uses a severity threshold to reduce noise during normal operation. By default, only warnings and above are logged. To change the logging level, use the `woocommerce_email_editor_logging_threshold` filter:

```php
add_filter( 'woocommerce_email_editor_logging_threshold', function() {
    return WC_Log_Levels::DEBUG;
} );
```

This will enable logging for all email editor operations, such as email editor initialization, personalization tag registration, etc.

For available log levels and their priority, see the [Logging in WooCommerce](/docs/best-practices/data-management/logging/#level) documentation.


---

## Email HTML - Best Practices

*Source: features/email/email-html-best-practices.md*

# Email HTML - Best Practices

## Overview

Email design and development require a different approach than traditional web development. This guide outlines best practices for ensuring your HTML emails render correctly across all major email clients.

### Key principles

- **Width**: Keep your email width between 600-640px - This ensures your email displays properly across all devices without horizontal scrolling on smaller screens.
- **File size**: Keep total email size under 100KB - Large emails may be clipped by Gmail and other providers, and take longer to load on mobile devices.
- **Tables**: Use tables for layout (despite being deprecated for the web) - Email clients have inconsistent CSS support but reliable table rendering.
- **Testing**: Test across multiple email clients and devices - Email clients render HTML differently, and testing helps identify and fix rendering issues.

## HTML

### Use older, simpler HTML standards

- Use HTML 4.01 or XHTML 1.0 - Many email clients use outdated rendering engines and don't support modern HTML5 features.
- Avoid HTML5 elements in the main structure - Elements like `<section>`, `<article>`, and `<aside>` aren't supported in all email clients.
- Always use lowercase for tags and attributes - This ensures maximum compatibility and prevents rendering issues in strict clients.
- Always use quotes for attribute values - Unquoted attributes can cause parsing errors in some email clients.
- Close all tags, even self-closing ones with a trailing slash (`<br />`) - This prevents rendering issues in clients that expect XHTML-style syntax.

### Tables as the foundation

- Use nested tables for layout instead of div-based layouts - Tables provide consistent structure across email clients with poor CSS support.
- Set explicit cell padding, spacing, and dimensions - This prevents inconsistent spacing and layout across different email clients.
- Declare width on table elements and on cells - Double-declaring widths improves rendering consistency, especially in Outlook.
- Use `align` and `valign` attributes instead of CSS equivalents - These HTML attributes have better support than CSS positioning in email clients.

```html
<table border="0" cellpadding="0" cellspacing="0" width="100%">
    <tr>
        <td align="center" valign="top">
            <!-- Content here -->
        </td>
    </tr>
</table>
```

### Avoid problematic elements

- No JavaScript - Most email clients strip JavaScript for security reasons, so any functionality depending on it will fail.
- No forms (though some clients support them) - Form support is extremely inconsistent; many clients disable or strip form elements.
- No iframes - These are stripped by most email clients for security reasons.
- No background images (use with fallbacks if necessary) - Many email clients disable background images by default.
- No embedded audio/video (link to hosted content instead) - Direct embedding is poorly supported; linking to external content is more reliable.

## CSS

### CSS Support Limitations

- Use inline CSS for everything critical - Many email clients strip `<style>` tags or ignore them entirely.
- Avoid CSS shorthand properties (use `margin-top` instead of `margin`) - Some email clients only recognize individual properties, not shorthand.
- Avoid CSS positioning properties (`position`, `float`, `clear`) - These are poorly supported and can cause layout issues.
- Avoid advanced selectors (stick to element, class, and ID selectors) - Complex selectors often fail in email clients with limited CSS support.

### Always use inline styles

```html
<p style="font-family: Arial, sans-serif; font-size: 16px; line-height: 24px; color: #333333;">
    Your content here
</p>
```

### Limited use of style tags

- Use for email client-specific hacks only
- Be careful with media queries (support varies)
- Always include the type attribute: `<style type="text/css">`

### Supported vs unsupported CSS

**Well-supported:**

- `font-family`, `font-size`, `color` - Basic text styling has consistent support across email clients.
- `text-align`, `line-height` - Text alignment and spacing properties work reliably in most clients.
- `width`, `height`, `padding`, `margin` (with caution) - Basic box model properties work when used conservatively. Margin doesn't work properly in Outlook.
- `border`, `background-color` - These visual properties have good support in most email clients.

**Poorly supported or inconsistent:**

- Flexbox, Grid - Modern layout systems are not supported in many email clients, particularly Outlook.
- Positioning properties (`position`, `display`) - These can cause emails to render differently or break layouts in some clients.
- CSS transitions, animations - These are stripped or ignored by most email clients.
- Many pseudo-classes and pseudo-elements - Support is inconsistent; Outlook and some webmail clients ignore them completely.

## Layout Techniques

### Single column design

- Most reliable across all clients - Simple layouts have fewer points of failure.
- Recommended width: 600px - This fits within most preview panes and mobile screens.
- Works well on mobile without responsiveness - Single column naturally adapts to narrow screens with minimal issues.

### Multi-column layouts with tables

```html
<table border="0" cellpadding="0" cellspacing="0" width="600">
    <tr>
        <td width="300" valign="top">
            <!-- Column 1 content -->
        </td>
        <td width="300" valign="top">
            <!-- Column 2 content -->
        </td>
    </tr>
</table>
```

### Column stacking techniques

- Use media queries where supported - Media queries allow columns to stack on mobile devices in clients that support them.
- Use MSO conditional comments for Outlook - These target Outlook specifically, which needs special handling for responsive layouts.
- Consider hybrid/spongy approach for clients without media query support - This technique creates layouts that adapt reasonably even without media query support.

```html
<!--[if mso]>
<table border="0" cellpadding="0" cellspacing="0" width="600">
<tr><td width="300" valign="top"><![endif]-->
<div style="display: inline-block; width: 300px; vertical-align: top;">
    <!-- Column 1 content -->
</div>
<!--[if mso]></td><td width="300" valign="top"><![endif]-->
<div style="display: inline-block; width: 300px; vertical-align: top;">
    <!-- Column 2 content -->
</div>
<!--[if mso]></td></tr></table><![endif]-->
```

## Responsiveness

### Mobile-first approach

- Design for small screens first - Mobile email opens often exceed desktop, making mobile optimization critical.
- Use proportional widths where possible - This allows content to adapt to different screen sizes automatically.
- Use appropriate font sizes (minimum 14px) - Smaller fonts are difficult to read on mobile devices and may require zooming.
- Ensure touch targets are at least 44x44px - This follows accessibility guidelines and makes interaction easier on touchscreens.

### Media queries

Limited but important support:

```html
<style type="text/css">
    @media screen and (max-width: 480px) {
        .mobile-full-width {
            width: 100% !important;
            height: auto !important;
        }
        
        .mobile-font {
            font-size: 16px !important;
        }
    }
</style>
```

### Fluid hybrid approach

Uses max-width and MSO conditionals to work across clients with or without media query support:

```html
<!--[if mso]>
<table width="600" cellpadding="0" cellspacing="0" border="0"><tr><td>
<![endif]-->
<div style="width:100%; max-width:600px; margin:0 auto;">
    <!-- Content -->
</div>
<!--[if mso]>
</td></tr></table>
<![endif]-->
```

## Typography

### Email-safe fonts

Always use a font stack with widely supported fonts:

```css
font-family: Arial, Helvetica, sans-serif;
font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
font-family: 'Times New Roman', Times, serif;
font-family: Verdana, Geneva, sans-serif;
font-family: Georgia, Times, 'Times New Roman', serif;
font-family: 'Courier New', Courier, monospace;
```

### Web fonts

- Limited support - use only with proper fallbacks - Many email clients don't support web fonts, so fallbacks are essential.
- Most reliable support: Google Fonts in Apple Mail, iOS Mail, and Android - These clients render web fonts consistently.
- Outlook, Gmail, and Yahoo! often don't support web fonts - These popular clients will display your fallback fonts instead.

```html
<style>
    @import url('https://fonts.googleapis.com/css2?family=Open+Sans&display=swap');
</style>

<p style="font-family: 'Open Sans', Arial, sans-serif;">Your text</p>
```

### Text formatting best practices

- Set a base font size of 14-16px - Smaller fonts can be difficult to read, especially on mobile devices.
- Line height should be 1.4-1.6 times the font size - Proper spacing improves readability and prevents text from appearing cramped.
- Break up large blocks of text - Chunking content improves scanability and engagement with your email.
- Left-align text for better readability - This creates a consistent reading experience and prevents ragged edges on both sides.
- Ensure sufficient contrast between text and background - This improves readability and accessibility for all users.

## Images

### Image guidelines

- Always include the `alt` attribute - This provides text alternatives when images are blocked and improves accessibility.
- Set explicit width and height on all images - This prevents layout shifts when images load and maintains structure when images are blocked.
- Keep image file sizes small (optimize for web) - Large images increase loading time and may exceed file size limits.
- Consider what happens when images are blocked - Many email clients block images by default, so your email should still make sense without them.

```html
<img src="https://example.com/image.jpg" alt="Description of image" width="600" height="400" style="display: block; width: 100%; max-width: 600px; height: auto;" border="0">
```

### Background images

Limited support; always provide a fallback bgcolor:

```html
<table background="https://example.com/bg.jpg" bgcolor="#f7f7f7" width="600" cellpadding="0" cellspacing="0" border="0">
    <tr>
        <td>
            Content
        </td>
    </tr>
</table>
```

## Email Client Specifics

### Outlook (Windows)

- Uses Word rendering engine (MSO) - This explains Outlook's unique rendering quirks and limited CSS support.
- Requires VML for background images and rounded corners - Standard CSS methods for these effects don't work in Outlook.
- Use MSO conditional comments for Outlook-specific code - These allow you to target Outlook versions specifically.

```html
<!--[if mso]>
    Outlook-specific content here
<![endif]-->
```

### Gmail

- Strips style tags and head section - Inline styles must be used for all critical styling.
- Removes class and ID attributes in some cases - Don't rely on these for critical styling or functionality.
- Use inline styles for everything - This is the only reliable way to style content in Gmail.
- Limits email size (clipping if too large) - Emails over 102KB get clipped with a "View entire message" link.

### Apple Mail/iOS

- Best rendering capabilities - These clients support modern CSS and HTML standards.
- Supports most modern CSS - Features like flexbox and grid can be used if you're targeting primarily Apple users.
- Good support for media queries - Responsive design works reliably on these platforms.

## Accessibility

### Semantic structure

- Use semantic HTML where possible (`p`, `h1`, `h2`, etc.) - This improves screen reader interpretation and overall accessibility.
- Add `role="presentation"` to layout tables - This tells screen readers the table is for layout only, not data presentation.
- Include proper heading structure - This creates a logical document outline that helps screen reader users navigate.
- Use `aria-hidden="true"` for decorative elements - This prevents screen readers from announcing purely visual elements.

```html
<table role="presentation" border="0" cellpadding="0" cellspacing="0">
```

### Text alternatives

- Always use descriptive alt text for images - This ensures people using screen readers understand the content and purpose of images.
- Set empty alt text for decorative images - This prevents screen readers from announcing images that don't add information.
- Consider what the email looks like with images off - Many users and email clients block images, so content should work without them.

### Color and contrast

- Maintain a minimum contrast ratio of 4.5:1 for normal text - This meets WCAG accessibility standards and improves readability for all users.
- Use actual text instead of text in images - Text in images isn't accessible to screen readers and doesn't scale well on different devices.
- Don't rely on color alone to convey information - This accommodates users with color vision deficiencies.

### Navigation and links

- Make links easily identifiable - Distinct styling helps users recognize clickable elements.
- Use descriptive link text (avoid "click here") - Descriptive links provide context and are more accessible to screen reader users.
- Ensure adequate spacing between touch targets - This prevents accidental taps on mobile devices and helps users with motor impairments.

## Testing tools and services

- Use professional email testing services like [Litmus](https://www.litmus.com/) and [Email on Acid](https://www.emailonacid.com/) - These platforms provide comprehensive testing across multiple email clients and devices.
- Test in real email clients when possible - While testing services are valuable, real-world testing can catch issues that automated testing might miss.
- Check rendering in both desktop and mobile clients - Mobile email opens often exceed desktop, making mobile testing essential.
- Test with images disabled - Many email clients block images by default, so ensure your email is readable and functional without them.
- Check spam filter scores - Use tools like [Mail-Tester](https://www.mail-tester.com/) to identify potential spam triggers in your email content.
- Validate HTML - Use email-specific validators to catch potential rendering issues before sending.


---

## Email Preview Integration

*Source: features/email/email-preview.md*

# Email Preview Integration

## Overview

WooCommerce's Email Preview feature allows you to preview email templates using dummy data (i.e., it doesn't use the actual data from the database). This means that extensions registering new email types need to integrate with the email preview system to properly showcase their emails. 

## Integration Hooks

The following hooks allow extensions to take full control of email preview:

### Style and Content Settings

These hooks allow extensions to add new style and content settings that the email preview listens for changes, and updates the preview when changes are made.

#### `woocommerce_email_preview_email_style_setting_ids`

Add new email style settings that the email preview listens for changes.

```php
add_filter( 'woocommerce_email_preview_email_style_setting_ids', function( $setting_ids ) {
    $setting_ids[] = 'my_extension_email_style';
    return $setting_ids;
} );
```

#### `woocommerce_email_preview_email_content_setting_ids`

Add new email content settings that the email preview listens for changes.

```php
add_filter( 'woocommerce_email_preview_email_content_setting_ids', function( $setting_ids ) {
    $setting_ids[] = 'my_extension_email_content';
    return $setting_ids;
} );
```

### Dummy Data Modification

#### `woocommerce_email_preview_dummy_order`

Modify the dummy `WC_Order` object used in preview.

```php
add_filter( 'woocommerce_email_preview_dummy_order', function( $order ) {
    // Modify the dummy order object
    $order->set_currency( 'EUR' );
    return $order;
} );
```

#### `woocommerce_email_preview_dummy_product`

Modify the dummy product used in preview.

```php
add_filter( 'woocommerce_email_preview_dummy_product', function( $product ) {
    // Modify the dummy product object
    $product->set_name( 'My Product' );
    return $product;
} );
```

#### `woocommerce_email_preview_dummy_product_variation`

Modify the dummy product variation used in preview.

```php
add_filter( 'woocommerce_email_preview_dummy_product_variation', function( $variation ) {
    // Modify the dummy variation object
    $variation->set_name( 'My Variation' );
    return $variation;
} );
```

#### `woocommerce_email_preview_dummy_address`

Modify the dummy address used in preview.

```php
add_filter( 'woocommerce_email_preview_dummy_address', function( $address ) {
    // Modify the dummy address array
    $address['first_name'] = 'Preview';
    $address['last_name'] = 'Customer';
    return $address;
} );
```

### Placeholders and Email Object

#### `woocommerce_email_preview_placeholders`

Modify placeholders to be replaced in the email.

```php
add_filter( 'woocommerce_email_preview_placeholders', function( $placeholders ) {
    // Add custom placeholders
    $placeholders['{custom_placeholder}'] = 'Custom Value';
    return $placeholders;
} );
```

#### `woocommerce_prepare_email_for_preview`

Modify the `WC_Email` object used in preview.

```php
add_filter( 'woocommerce_prepare_email_for_preview', function( $email ) {
    // Modify the email object, e.g. to replace WC_Order
    $email->set_object( $custom_object );
    return $email;
} );
```

## Best Practices

When integrating with email preview:

1. **Use Appropriate Object Types**
   - Use the correct object type for your extension (e.g., `WC_Subscription` instead of `WC_Order` for WooCommerce Subscriptions)
   - Ensure all required properties are set on dummy objects

2. **Handle Placeholders**
   - Add all custom placeholders your extension uses
   - Provide realistic preview values for placeholders

3. **Style and Content Settings**
   - Register all custom settings that affect email appearance or content

4. **Testing**
   - Test preview with different email types
   - Verify all custom content appears correctly
   - Check responsive design

## Troubleshooting

Common issues and solutions:

1. **I see "There was an error rendering an email preview." error**
   - There is a PHP error in your code that is causing the email preview to fail. Check your error log for more details.
   - Alternatively, you can modify [`class-wc-admin.php`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/admin/class-wc-admin.php) and remove [`try/catch` block](https://github.com/woocommerce/woocommerce/blob/f5310a33fbb160a73ea2de95efe4759c3aa791ea/plugins/woocommerce/includes/admin/class-wc-admin.php#L212-L218) around rendering the email preview to see the error message.

2. **Style or Content Settings Changes Not Reflecting**
   - Ensure the style settings are registered using the `woocommerce_email_preview_email_style_setting_ids` filter
   - Ensure the content settings are registered using the `woocommerce_email_preview_email_content_setting_ids` filter
3. **I don't see my extension's emails**
   - Ensure the email is registered using the `woocommerce_email_classes` filter


---

## Model Context Protocol (MCP) Integration

*Source: features/mcp/README.md*

# Model Context Protocol (MCP) Integration

## Introduction

WooCommerce includes native support for the Model Context Protocol (MCP), enabling AI assistants and tools to interact directly with WooCommerce stores through a standardized protocol. This integration exposes WooCommerce functionality as discoverable tools that AI clients can use to perform store operations with proper authentication and permissions.

:::info

**Developer Preview Notice**
The MCP implementation in WooCommerce is currently in developer preview. Implementation details, APIs, and integration patterns may change in future releases as the feature matures.

:::

## Background

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. WooCommerce's MCP integration builds on two core technologies:

- **[WordPress Abilities API](https://github.com/WordPress/abilities-api)** - A standardized system for registering capabilities in WordPress
- **[WordPress MCP Adapter](https://github.com/WordPress/mcp-adapter)** - The core MCP protocol implementation

This architecture allows WooCommerce to expose operations as MCP tools through the flexible WordPress Abilities system while maintaining existing security and permission models.

## What's Available

WooCommerce registers purpose-built abilities for core store operations. These abilities are available through the WordPress Abilities API and can be surfaced through the shared WordPress MCP adapter.

### Purpose-Built WooCommerce Abilities

#### Product Management

- Query products with filtering and pagination
- Create new products
- Update existing products
- Delete products

#### Order Management

- Query orders with filtering and pagination
- Update order status
- Add order notes

### Deprecated WooCommerce MCP Endpoint

The deprecated WooCommerce MCP endpoint also exposes REST-derived compatibility abilities for products and orders. These abilities map to existing REST API operations and currently include product list, retrieve, create, update, and delete operations, plus order list, retrieve, create, and update operations.

All operations respect WooCommerce's existing permission system. The deprecated WooCommerce MCP endpoint authenticates using WooCommerce REST API keys; clients using the shared WordPress MCP adapter should follow the adapter's authentication requirements.

:::warning

**Data Privacy Notice**
Order and customer operations may expose personally identifiable information (PII) including names, email addresses, physical addresses, and payment details. You are responsible for ensuring compliance with applicable data protection regulations. Use least-privilege API scopes, rotate and revoke REST API keys regularly, and follow your organization's data retention and handling policies.

:::

## Architecture

### Data Flow Overview

The MCP integration uses a multi-layered architecture to bridge between MCP clients and WordPress:

```text
AI Client (Claude, etc.)
    ↓ (MCP protocol over stdio/JSON-RPC)
Local MCP Proxy (mcp-wordpress-remote)
    ↓ (HTTP/HTTPS requests with authentication)
Remote WordPress MCP Server (mcp-adapter)
    ↓ (WordPress Abilities API)
WooCommerce Abilities
    ↓ (REST API calls or direct operations)
WooCommerce Core
```

### Architecture Components

**Local MCP Proxy** (`mcp-wordpress-remote`)

- Runs locally on the developer's machine as a Node.js process
- Converts MCP protocol messages to HTTP requests
- Handles authentication header injection
- Bridges the protocol gap between MCP clients and WordPress REST endpoints

**Remote WordPress MCP Server** (`mcp-adapter`)

- Is provided by the bundled WordPress MCP Adapter package
- Powers MCP tool discovery and execution for WordPress abilities
- Creates the deprecated `/wp-json/woocommerce/mcp` endpoint for WooCommerce compatibility

#### WordPress Abilities System

- Provides a standardized way to register and execute capabilities
- Acts as an abstraction layer between MCP tools and actual operations
- Enables flexible implementation approaches (REST bridging, direct DB operations, etc.)

### Core Components

**MCP Adapter Provider** ([`MCPAdapterProvider.php`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/MCP/MCPAdapterProvider.php))

- Initializes the bundled MCP adapter when the `mcp_integration` feature flag is enabled
- Creates the deprecated WooCommerce MCP endpoint
- Handles feature flag checking (`mcp_integration`)
- Provides deprecated endpoint exposure filtering

**Abilities Registry** ([`AbilitiesRegistry.php`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/Abilities/AbilitiesRegistry.php))

- Initializes WooCommerce ability categories and loaders
- Bridges WordPress Abilities API with WooCommerce operations
- Enables ability discovery for MCP servers and other Abilities API consumers

**Purpose-Built Domain Abilities** ([`Domain`](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/src/Internal/Abilities/Domain))

- Provide WooCommerce product and order abilities backed by domain APIs
- Use shared WordPress MCP adapter metadata (`mcp.public` and `mcp.type`) for MCP exposure
- Keep the ability contract focused on agent-friendly store operations

**REST Bridge Implementation** ([`AbilitiesRestBridge.php`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/Abilities/AbilitiesRestBridge.php))

- Registers REST-derived compatibility abilities only while handling requests to the deprecated WooCommerce MCP endpoint
- Provides explicit ability definitions with schemas for REST product and order operations
- Marks those abilities with `expose_in_deprecated_woocommerce_mcp` metadata

**WooCommerce Transport** ([`WooCommerceRestTransport.php`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/MCP/Transport/WooCommerceRestTransport.php))

- Handles WooCommerce API key authentication
- Enforces HTTPS requirements
- Validates permissions based on API key scope

### Implementation Approach

WooCommerce's preferred implementation path is purpose-built domain abilities. These abilities use schemas and response shapes designed for agent workflows instead of automatically projecting every REST-shaped operation into MCP.

REST-derived abilities remain available as a compatibility layer for the deprecated WooCommerce MCP endpoint. This keeps existing clients working while allowing new abilities to use the shared WordPress MCP adapter without expanding the deprecated endpoint by namespace alone.

## Enabling MCP Integration

The MCP feature is controlled by the `mcp_integration` feature flag. You can enable it programmatically:

```php
add_filter( 'woocommerce_features', function( $features ) {
    $features['mcp_integration'] = true;
    return $features;
});
```

Alternatively, you can enable it via WooCommerce CLI:

```bash
wp option update woocommerce_feature_mcp_integration_enabled yes
```

## Authentication and Security

### WordPress Application Password Requirements

Remote HTTP connections authenticate using a WordPress username and an [Application Password](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/#basic-authentication-with-application-passwords). Do not use your account password or a WooCommerce REST API key.

To create an Application Password:

1. In the WordPress dashboard, navigate to **Users → Profile**.
2. Under **Application Passwords**, enter a name for the MCP client.
3. Click **Add New Application Password**.
4. Copy the generated password and store it securely. WordPress only displays it once.

Use the WordPress username and generated password as `WP_API_USERNAME` and `WP_API_PASSWORD` in the remote proxy configuration. Application Passwords can be revoked independently from the user's profile.

### HTTPS Enforcement

Use HTTPS for remote HTTP connections so credentials are encrypted in transit. Local STDIO connections authenticate through WP-CLI using the configured `--user` and do not require an Application Password.

### Permission Validation

The MCP Adapter authenticates requests as the WordPress user associated with the Application Password. The default server requires an authenticated user with the `read` capability, and each WooCommerce ability also enforces its own permission callback. Use a dedicated WordPress user with only the capabilities the MCP client needs.

## Server Endpoint

WooCommerce abilities are available through the WordPress MCP Adapter's default server:

```text
https://yourstore.com/wp-json/mcp/mcp-adapter-default-server
```

The WooCommerce-specific `/wp-json/woocommerce/mcp` endpoint is deprecated and should not be used for new integrations.

## Connecting to the MCP Server

Choose a connection method based on where the WordPress site is running. For a detailed overview and application-specific instructions, see [Connecting AI applications](https://developer.wordpress.org/news/2026/02/from-abilities-to-ai-agents-introducing-the-wordpress-mcp-adapter/#connecting-ai-applications) and the [wordpress/mcp-adaptor repository](https://github.com/wordpress/mcp-adapter).

### Local Sites Using STDIO

For a local WordPress installation, MCP clients can connect directly through the MCP Adapter's WP-CLI command. The client needs access to the WordPress files and a working WP-CLI installation.

#### JSON Configuration

Add the following server to your MCP client configuration. Replace the WordPress path and user with values from your local environment:

```json
{
  "mcpServers": {
    "woocommerce_store": {
      "command": "wp",
      "args": [
        "--path=/path/to/your/wordpress/site",
        "mcp-adapter",
        "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    }
  }
}
```

Claude Desktop, Claude Code, and Cursor use the `mcpServers` property shown above. For VS Code, use `servers` instead.

#### Command-Line Configuration

Claude Code users can add the same server from the command line:

```bash
claude mcp add woocommerce_store -- \
  wp --path=/path/to/your/wordpress/site \
  mcp-adapter serve \
  --server=mcp-adapter-default-server \
  --user=admin
```

You can verify the server directly with WP-CLI:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  wp --path=/path/to/your/wordpress/site \
  mcp-adapter serve \
  --server=mcp-adapter-default-server \
  --user=admin
```

### Remote Sites Using HTTP

For a remote WordPress installation, use the `@automattic/mcp-wordpress-remote` proxy. The proxy translates the MCP client's local STDIO messages into HTTP requests to the WordPress MCP Adapter.

Before connecting:

1. Create or select a dedicated WordPress user with the minimum required capabilities.
2. Open the user's **Profile** screen and create a WordPress Application Password.
3. Confirm the site uses HTTPS and non-Plain permalinks.

#### JSON Configuration

Add the following server to your MCP client configuration. Replace the example URL, username, and Application Password:

```json
{
  "mcpServers": {
    "woocommerce_store": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/mcp-wordpress-remote@latest"
      ],
      "env": {
        "WP_API_URL": "https://yourstore.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "your-application-password"
      }
    }
  }
}
```

Claude Desktop, Claude Code, and Cursor use the `mcpServers` property shown above. For VS Code, use `servers` instead. Do not commit a configuration containing an Application Password to version control.

#### Command-Line Configuration

Claude Code users can add the remote server from the command line:

```bash
claude mcp add \
  --env WP_API_URL=https://yourstore.com/wp-json/mcp/mcp-adapter-default-server \
  --env WP_API_USERNAME=your-username \
  --env WP_API_PASSWORD='your-application-password' \
  woocommerce_store \
  -- npx -y @automattic/mcp-wordpress-remote@latest
```

**Troubleshooting**: For common setup issues with npx versions or SSL in local environments, see the [mcp-wordpress-remote troubleshooting guide](https://github.com/Automattic/mcp-wordpress-remote/blob/trunk/Docs/troubleshooting.md).

## Extending MCP Capabilities

Third-party plugins can register additional abilities using the WordPress Abilities API. Abilities can be implemented in various ways, including direct operations, custom logic, REST endpoint bridging, or external integrations.

### Adding Custom Abilities

Register an ability category first, then register the ability during the WordPress Abilities API init hook:

```php
add_action( 'wp_abilities_api_categories_init', function() {
    if ( ! function_exists( 'wp_register_ability_category' ) ) {
        return;
    }

    if ( function_exists( 'wp_has_ability_category' ) && wp_has_ability_category( 'your-plugin' ) ) {
        return;
    }

    wp_register_ability_category(
        'your-plugin',
        array(
            'label'       => __( 'Your Plugin', 'your-plugin' ),
            'description' => __( 'Abilities provided by Your Plugin.', 'your-plugin' ),
        )
    );
});

add_action( 'wp_abilities_api_init', function() {
    if ( ! function_exists( 'wp_register_ability' ) ) {
        return;
    }

    wp_register_ability(
        'your-plugin/custom-operation',
        array(
            'label'               => __( 'Custom Store Operation', 'your-plugin' ),
            'description'         => __( 'Performs a custom store operation.', 'your-plugin' ),
            'category'            => 'your-plugin',
            'execute_callback'    => 'your_custom_ability_handler',
            'permission_callback' => function () {
                return current_user_can( 'manage_woocommerce' );
            },
            'input_schema'        => array(
                'type'       => 'object',
                'properties' => array(
                    'store_id' => array(
                        'type'        => 'integer',
                        'description' => 'Store identifier',
                    ),
                ),
                'required' => array( 'store_id' ),
            ),
            'output_schema' => array(
                'type'       => 'object',
                'properties' => array(
                    'success' => array(
                        'type'        => 'boolean',
                        'description' => 'Operation result',
                    ),
                ),
            ),
            'meta'                => array(
                'show_in_rest' => true,
                'mcp'          => array(
                    'public' => true,
                    'type'   => 'tool',
                ),
            ),
        )
    );
});
```

The `mcp.public` and `mcp.type` metadata tells the shared WordPress MCP adapter that the ability can be exposed as an MCP tool. The `show_in_rest` metadata exposes the ability through the Abilities API REST routes.

### Including Custom Abilities in the Deprecated WooCommerce MCP Server

REST-derived WooCommerce abilities include `expose_in_deprecated_woocommerce_mcp` metadata automatically. Custom abilities are not included by namespace alone; set this metadata to boolean `true` when registering the ability to include it in the deprecated WooCommerce MCP server by default:

```php
'meta' => array(
    'show_in_rest' => true,
    'mcp'          => array(
        'public' => true,
        'type'   => 'tool',
    ),
    'expose_in_deprecated_woocommerce_mcp' => true,
),
```

To override the default metadata decision at runtime, use the `woocommerce_mcp_include_ability` filter:

```php
add_filter( 'woocommerce_mcp_include_ability', function( $include, $ability_id ) {
    if ( str_starts_with( $ability_id, 'your-plugin/' ) ) {
        return true;
    }
    return $include;
}, 10, 2 );
```

## Development Example

For a complete working example, see the [WooCommerce MCP Ability Demo Plugin](https://github.com/woocommerce/wc-mcp-ability). This demonstration plugin shows how third-party developers can:

- Register custom abilities using the WordPress Abilities API
- Define comprehensive input and output schemas
- Implement proper permission handling
- Integrate with MCP through the shared WordPress MCP adapter or the deprecated WooCommerce MCP endpoint

The demo plugin creates a `woocommerce-demo/store-info` ability that retrieves store information and statistics, demonstrating the integration patterns for extending WooCommerce MCP capabilities while using a direct implementation approach rather than REST endpoint bridging.

## Troubleshooting

### Common Issues

## MCP Server Not Available

- Verify the `mcp_integration` feature flag is enabled
- Check that the MCP adapter is properly loaded
- Review WooCommerce logs for initialization errors

## Authentication Failures

- Confirm `WP_API_USERNAME` matches the WordPress user that created the Application Password
- Confirm `WP_API_PASSWORD` contains an active Application Password, not the user's account password or a WooCommerce REST API key
- Verify the WordPress user has the capabilities required by the ability
- Ensure HTTPS is used for remote HTTP connections

## Ability Not Found

- Confirm the ability category is registered during `wp_abilities_api_categories_init`
- Confirm abilities are registered during `wp_abilities_api_init`
- For the deprecated WooCommerce MCP endpoint, check the ability's `expose_in_deprecated_woocommerce_mcp` metadata or override inclusion using the `woocommerce_mcp_include_ability` filter
- Verify ability callbacks are accessible

Check **WooCommerce → Status → Logs** for entries with source `woocommerce-mcp`.

## Important Considerations

- **Developer Preview**: This feature is in preview status and may change
- **Implementation Approach**: WooCommerce uses purpose-built domain abilities and retains REST-derived compatibility abilities for the deprecated WooCommerce MCP endpoint
- **Breaking Changes**: Future updates may introduce breaking changes
- **Production Testing**: Thoroughly test before deploying to production
- **API Stability**: The WordPress Abilities API and MCP adapter are evolving

## Related Resources

- [WordPress Abilities API Repository](https://github.com/WordPress/abilities-api)
- [WordPress MCP Adapter Repository](https://github.com/WordPress/mcp-adapter)
- [WooCommerce MCP Demo Plugin](https://github.com/woocommerce/wc-mcp-ability)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [WooCommerce REST API Documentation](/docs/apis/rest-api/)


---

## High Performance Order Storage (HPOS)

*Source: features/orders/high-performance-order-storage/README.md*

# High Performance Order Storage (HPOS)

WooCommerce has traditionally stored store orders and related order information (like refunds) as custom WordPress post types or post meta records. This comes with performance issues.

[High-Performance Order Storage (HPOS)](https://developer.woocommerce.com/2022/09/14/high-performance-order-storage-progress-report/) also previously known as "Custom Order Tables" is a solution that provides an easy-to-understand and solid database structure - specifically designed for eCommerce needs. It uses the WooCommerce CRUD design to store order data in custom tables - optimized for WooCommerce queries with minimal impact on the store's performance.

In January 2022, we published the [initial plan for the Custom Order Tables feature](https://developer.woocommerce.com/2022/01/17/the-plan-for-the-woocommerce-custom-order-table/) and since then, we've been working hard to bring the High-Performance Order Storage (HPOS) to WooCommerce Core. In May 2022, we invited you to [test the order migration process](https://developer.woocommerce.com/2022/05/16/call-for-early-testing-custom-order-table-migrations/) and provide feedback on how our initial work performs on real stores of varied configurations.

From WooCommerce 8.2, released on October 2023, [High-Performance Order Storage (HPOS)](https://developer.woocommerce.com/2022/09/14/high-performance-order-storage-progress-report/)  is officially released under the stable flag and will be enabled by default for new installations.

## What's New with High-Performance Order Storage?

Bringing High-Performance Order Storage (HPOS) to WooCommerce improves these three essential properties for eCommerce stores.

### Scalability

The rise in the number of customers and customer orders increases the load on your store's database - making it difficult to handle customer order requests and deliver a seamless user experience.

With High-Performance Order Storage, you get dedicated tables for data like orders and order addresses and thus dedicated indexes which results in fewer read/write operations and fewer busy tables. This feature enables eCommerce stores of all shapes and sizes to scale their business to their maximum potential - without expert intervention.

### Reliability

High-Performance Order Storage makes implementing and restoring targeted data backup easier. You'll no longer need to worry about losing orders, inventory numbers, or client information with reliable backup in these custom order tables. It'll also facilitate implementing read/write locks and prevent race conditions.

### Simplicity

You no longer have to go through a single huge database to locate underlying data and WooCommerce entries.

With High-Performance Order Storage, you can easily browse through the separate tables and easy-to-handle entries, independent of the table  `_posts`, to find data or understand the table structure. It also lets you easily develop new plugins, implement designs for shops and products, and modify WooCommerce with more flexibility.

## Background

Before the release of version 8.2, WooCommerce relied on the `_post` and `_postmeta` table structures to store order information, which has served well over the years.

However, High-Performance Order Storage introduces dedicated tables for data like orders and order addresses and thus dedicated indexes which results in fewer read/write operations and fewer busy tables. This feature enables eCommerce stores of all shapes and sizes to scale their business to their maximum potential - without expert intervention.

The order data is synced from `_posts` and `_postmeta` table to four custom order tables:

1. `_wc_orders`
2. `_wc_order_addresses`
3. `_wc_order_operational_data`
4. `_wc_orders_meta`


## Enabling the feature

From WooCommerce 8.2, released on October 2023, HPOS is enabled by default for new installations. Existing stores can check [How to enable HPOS](https://developer.woocommerce.com/docs/how-to-enable-high-performance-order-storage/)

## Database tables

A number of database tables are used to store order data by HPOS. The `get_all_table_names` method in [the OrdersTableDataStore class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/DataStores/Orders/OrdersTableDataStore.php) will return the names of all the tables.

## Authoritative tables

At any given time, while the HPOS feature is enabled, there are two roles for the involved database tables: _authoritative_ and _backup_. The authoritative tables are the working tables, where order data will be stored to and retrieved from during normal operation of the store. The _backup_ tables will receive a copy of the authoritative data whenever [synchronization](#synchronization) happens.

If the `woocommerce_custom_orders_table_enabled` options is set to true, HPOS is active and [the new tables](#database-tables) are authoritative, while the posts and post meta tables act as the backup tables. If the option is set to false, it's the other way around. The option can be changed via admin UI (WooCommerce - Settings - Advanced - Custom data stores).

[The CustomOrdersTableController class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/DataStores/Orders/CustomOrdersTableController.php) hooks on the `woocommerce_order_data_store` filter so that `WC_Data_Store::load( 'order' );` will return either an instance of [OrdersTableDataStore](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/DataStores/Orders/OrdersTableDataStore.php) or an instance of [WC_Order_Data_Store_CPT](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/data-stores/class-wc-order-data-store-cpt.php), depending on which are the authoritative tables.

In order to preserve data integrity, switching the authoritative tables (from the new tables to the posts table or the other way around) isn't allowed while there are orders pending synchronization.

## Synchronization

_Synchronization_ is the process of applying all the pending changes in the authoritative tables to the backup tables. _Orders pending synchronization_ are orders that have been modified in the authoritative tables but the changes haven't been applied to the backup tables yet.

This can happen in a number of ways:


### Immediate synchronization

If the `woocommerce_custom_orders_table_data_sync_enabled` setting is set to true, synchronization happens automatically and immediately as soon as the orders are changed in the authoritative tables.


### Manual synchronization

When immediate synchronization is disabled, it can be triggered manually via command line as follows: `wp wc cot sync`. It can also be triggered programmatically as follows:

```php
$synchronizer = wc_get_container()->get(Automattic\WooCommerce\Internal\DataStores\Orders\DataSynchronizer::class);
$order_ids = $synchronizer->get_next_batch_to_process( $batch_size );
if ( count( $order_ids ) ) {
	$synchronizer->process_batch( $order_ids );
}
```

where `$batch_size` is the maximum count of orders to process.


### Scheduled synchronization

If immediate synchronization gets activated (`woocommerce_custom_orders_table_data_sync_enabled` is set to true) while there are orders pending synchronization, an instance of [DataSynchronizer](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/DataStores/Orders/DataSynchronizer.php) will be enqueued using [BatchProcessingController](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/BatchProcessing/BatchProcessingController.php) so that the synchronization of created/modified/deleted orders will happen in batches via scheduled actions. This scheduling happens inside [CustomOrdersTableController](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/DataStores/Orders/CustomOrdersTableController.php), by means of hooking into `woocommerce_update_options_advanced_custom_data_stores`.

If for some reason immediate synchronization is already active but synchronization is not scheduled, a trick to restart it is to go to the settings page (WooCommerce - Settings - Advanced - Custom data stores) and hit "Save" even without making any changes. As long as "Keep the posts table and the orders tables synchronized" is checked the synchronization scheduling will happen, even if it was checked before.

If the `woocommerce_auto_flip_authoritative_table_roles` option is set to true (there's a checkbox for it in the settings page), the authoritative tables will be switched automatically once all the orders have been synchronized. This is handled by [the CustomOrdersTableController class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/DataStores/Orders/CustomOrdersTableController.php).


### Deletion synchronization

Synchronization of order deletions is tricky: if an order exists in one set of tables (new tables or posts) but not in the other, it's not clear if the missing orders need to be created or if the existing orders need to be deleted. Theoretically, the orders missing from the backup tables imply the former and the orders missing from the authoritative tables imply the latter; but that's dangerous as a bug in the involved code could easily lead to the deletion of legitimate orders.

To achieve a robust order deletion synchronization mechanism the following is done. Whenever an order is deleted and immediate synchronization is disabled, a record is created in the `wp_wc_orders_meta` table that has `deleted_from` as the key and the name of the authoritative table the order was deleted from (`wp_wc_orders` or the posts table). Then at synchronization time these records are processed (the corresponding orders are deleted from the corresponding tables) and deleted afterwards.

An exception to the above are the [placeholder records](#placeholder-records): these are deleted immediately when the corresponding order is deleted from `wp_wc_orders`, even if immediate synchronization is disabled.

When the "**High-Performance Order Storage**" and "**Compatibility mode**" are enabled, WooCommerce populates the HPOS tables with data from posts & postmeta tables. The synchronization between the tables is [explained in detail in this document](https://developer.woocommerce.com/2022/09/29/high-performance-order-storage-backward-compatibility-and-synchronization/#synchronization).


> You can find a deeper explanation about the synchronization between the tables in [this document about high-performance-order-storage-backward-compatibility-and-synchronization](https://developer.woocommerce.com/2022/09/29/high-performance-order-storage-backward-compatibility-and-synchronization/#synchronization).

## Placeholder records

Order IDs must match in both the authoritative tables and the backup tables, otherwise synchronization wouldn't be possible. The order IDs that are compared for order identification and synchronization purposes are the ones from the `id` field in both the `wp_wc_orders` table and the posts table.

If the posts table is authoritative, achieving an order ID match is easy: the record in `wp_wc_orders` is created with the same ID and that's it. However, when the new orders tables are authoritative there's a problem: the posts table is used to store multiple types of data, not only orders; and by the time synchronization needs to happen, a non-order post could already exist having the same ID as the order to synchronize.

To solve this, _placeholder records_ are used. Whenever the new orders tables are authoritative and immediate synchronization is disabled, creating a new order will cause a record with post type `shop_order_placehold` and the same ID as the order to be created in the posts table; this effectively "reserves" the order ID in the posts table. Then, at synchronization time, the record is filled appropriately and its post type is changed to `shop_order`.


## Order Data Storage

You can switch between data stores freely to sync the data between the tables.

-   If you select  **"WordPress Post Tables"**, the system will save the order data within  `_post`  and  `_postmeta`  tables. The order tables are not utilized in this scenario.

![Select WordPress Post Tables](https://woocommerce.com/wp-content/uploads/2023/10/image-18.png?w=650)

-   If you select  **"High-Performance Order Storage"**, the system will save the order data within the new WooCommerce order tables

![Select High-Performance Order Storage](https://woocommerce.com/wp-content/uploads/2023/10/image-19.png?w=650)

-   If you select  **"WordPress Post Tables"** and **"Enable compatibility mode"**, the system will sync the order data between the posts/postmeta and the WooCommerce order tables.

![Select WordPress Post Tables and Enable compatibility mode](https://woocommerce.com/wp-content/uploads/2023/10/image-20.png?w=650)


## Incompatible Plugins

If you are using a plugin that is not compatible with High-Performance Order Storage, then the HPOS option will be disabled under  **WooCommerce > Settings > Advanced > Features**.

![Incompatible plugin](https://woocommerce.com/wp-content/uploads/2023/10/image-21.png?w=650)

-   You can click on "**View and manage**" to review the list of incompatible plugins
-   Or you can visit  `https://example.com/wp-admin/plugins.php?plugin_status=incompatible_with_feature&feature_id=custom_order_tables`  to review the list of incompatible plugins (please replace  `example.com`  with your site domain)

![Plugins page](https://woocommerce.com/wp-content/uploads/2023/10/image-22.png?w=650)

> **Note:** If you are using a third-party extension that isn't working properly with High-Performance Order Storage then please notify the developers of the extension and ask them to update their extension to add support for HPOS. It's up to the extension developers to add support for HPOS. We have [developer resources and documentation](https://developer.woocommerce.com/2022/09/14/high-performance-order-storage-progress-report/)  available to help with their integration efforts.


## Disabling HPOS

If you encounter problems or if you need to continue working with plugins that are not yet compatible with HPOS, then we recommend temporarily switching back to  **WordPress posts storage**.

To do this, navigate to  **WooCommerce ▸ Settings ▸ Advanced ▸ Features**  and start by making sure that  **compatibility mode** is enabled. If it was not already enabled, you may find you need to wait for some time while order data is synchronized across data-stores.

![WooCommerce ▸ Settings ▸ Advanced ▸ Features Screen](https://woocommerce.com/wp-content/uploads/2023/10/hpos-feature-settings.png?w=650)

Once synchronization has completed, you can select  **WordPress posts storage (legacy)**  as your preferred option. You can also disable compatibility mode at this point. Once you are ready to re-enable HPOS, simply follow the instructions posted at the  [start of this doc](/docs/features/orders/high-performance-order-storage/#enabling-the-feature). Finally, remember to save this page between changes!

As noted earlier, we also strongly recommend reaching out to the support teams of any plugins that are incompatible, so they can take corrective action.


---

## HPOS CLI Tools

*Source: features/orders/high-performance-order-storage/cli-tools.md*

# HPOS CLI Tools

## Overview

We have a number of [WP-CLI commands](https://developer.woocommerce.com/docs/category/wc-cli/) that can be used to manage HPOS-related functionality, all of which live under the `wp wc hpos` namespace (though you may come across blog posts and older documentation referencing the now-deprecated `wp wc cot` namespace).

The following table provides an overview of what each command does, while more details and examples can be found below.

Keep in mind that the commands themselves have documentation and examples that can be accessed via WP-CLI's help by passing the `--help` flag.

|Command|Use this command to...|
|----|-----|
|`wc hpos status`|Get an overview of all HPOS matters on your site.|
|`wc hpos enable`|Enable HPOS (and possibly compatibility mode).|
|`wc hpos disable`|Disable HPOS (and possibly compatibility mode).|
|`wc hpos count_unmigrated`|Get a count of all orders pending sync.|
|`wc hpos sync`|Performantly sync orders from the currently active order storage to the other.|
|`wc hpos verify_data`|Verify data between datastores.|
|`wc hpos diff`|Get an user friendly version of the differences for an order between both order storages.|
|`wc hpos backfill`|Copy over whole orders or specific bits of order data from any order storage to the other.|
|`wc hpos cleanup`|Remove order data from legacy tables.|

## Usage and examples

### `wc hpos status`

Use this to get an overview of HPOS settings and status on your site. The command will output whether HPOS and compatibility mode are enabled or not, and other useful information such as orders pending sync or subject to cleanup.

**Note:** Remember that, if desired, orders pending sync can be synced using [`wc hpos sync`](#wc-hpos-sync) and, similarly, you can perform a cleanup on those subject to cleanup (provided compatibility mode is disabled) by running [`wc hpos cleanup all`](#wc-hpos-cleanup).


#### Example 1 - HPOS status output

```plaintext
$ wp wc hpos status
HPOS enabled?: yes
Compatibility mode enabled?: no
Unsynced orders: 651
Orders subject to cleanup: 348
```

### `wc hpos enable`

Use this command to enable HPOS and compatibility mode (if desired) from the command line.

#### Example 1 - Enable HPOS via CLI

Enables HPOS and compatibility mode too (`--with-sync` flag).

```plaintext
$ wp wc hpos enable --with-sync
Running pre-enable checks...
Success: Sync enabled.
Success: HPOS enabled.
```

### `wc hpos disable`

Similarly to the prior command, this can be used to disable HPOS.

#### Example 1 - Attempt to disable HPOS (with orders pending sync)

If there are any orders pending sync, you won't be allowed to disable HPOS until those orders have been synced (via `wp wc hpos sync`).

```plaintext
$ wp wc hpos disable
Running pre-disable checks...
Error: [Failed] There are orders pending sync. Please run `wp wc hpos sync` to sync pending orders.
```

#### Example 2 - Disable HPOS

```plaintext
$ wp wc hpos disable
Running pre-disable checks...
Success: HPOS disabled.
```

### `wc hpos count_unmigrated`

Prints the number of orders pending sync.

#### Example 1 - Obtain number of orders pending sync

```plaintext
$ wp wc hpos count_unmigrated
There are 651 orders to be synced.
```

### `wc hpos sync`

This command can be used to migrate orders from the posts order storage to HPOS (or viceversa) based on the current settings in WC > Settings > Advanced > Features.
That is, it'll sync orders from your currently selected datastore to the other one.

Note that enabling compatibility mode in the settings will eventually take care of migrating all orders, but this command can be used to do that more performantly.

If you need more control over which datastore to use as source (or destination) regardless of settings, or want to migrate just a few orders or properties, use [`wp wc hpos backfill`](#wc-hpos-backfill) instead.

#### Example 1 - Sync all orders

```plaintext
$ wp wc hpos sync
There are 999 orders to be synced.
Order Data Sync  100% [============================================================================================] 0:08 / 0:08
Sync completed.
Success: 999 orders were synced in 14 seconds.
```

### `wc hpos verify_data`

Use this command to check that order data in both the legacy (posts) datastore and HPOS is in sync. This is only relevant if you have "compatibility mode" enabled and orders might've been modified outside of the usual WooCommerce flows.

This command operates on all orders. For a user friendlier alternative that operates on individual orders, refer to [`wp wc hpos diff`](#wc-hpos-diff).

#### Example 1 - Verify data on a migrated site

All orders are identical between datastores.

```plaintext
$ wp wc hpos verify_data
Order Data Verification  100% [====================================================================================] 0:00 / 0:00
Verification completed.
Success: 999 orders were verified in 0 seconds.
```

#### Example 2 - Verification failures

An order (with ID 100126) fails verification due to differences in order total, tax, modification date and billing information.

```plaintext
$ wp wc hpos verify_data
Order Data Verification  100% [====================================================================================] 0:00 / 0:00
Verification completed.
Error: 999 orders were verified in 0 seconds. 1 error found: {
    "100126": [
        {
            "column": "post_modified_gmt",
            "original_value": "2024-04-04 15:32:27",
            "new_value": "2024-04-05 15:19:56"
        },
        {
            "column": "_order_tax",
            "original_value": "74",
            "new_value": "0"
        },
        {
            "column": "_order_total",
            "original_value": "567.25",
            "new_value": "0"
        },
        {
            "order_id": 100126,
            "meta_key": "_billing_address_index",
            "orig_meta_values": [
                "Hans Howell Moore Ltd 325 Ross Drive  Wilfridhaven WA 23322 NF heidi.koch@example.net +17269674166"
            ],
            "new_meta_values": [
                "Hans X Howell Moore Ltd 325 Ross Drive  Wilfridhaven WA 23322 NF heidi.koch@example.net +17269674166"
            ]
        }
    ]
}. Please review the error above.
```

#### Example 3 - Re-migrate during verification

The verification command also admits a `--re-migrate` flag that will attempt to sync orders that have differences. This could effectively overwrite an order in the database, so use with care.

```plaintext
$ wp wc hpos verify_data --re-migrate
Order Data Verification  100% [====================================================================================] 0:00 / 0:00
Verification completed.
Success: 999 orders were verified in 0 seconds.
```

### `wc hpos diff`

If you have enabled compatibility mode or migrated orders using `wp wc hpos sync`, all of your orders should be in an identical state in both datastores (the legacy one and HPOS), but errors can happen. Also, manually modifying orders in the database or use of HPOS-incompatible plugins can result in orders deviating.

The `wp wc hpos diff`  tool can be used to look into those (possible) differences, which can be useful to determine whether re-migrating to/from either datastore should be done, or a more careful approach needs to be taken.

The tool itself doesn't reconcile the differences. For that you should use [`wp wc hpos backfill`](#wc-hpos-backfill).

#### Example 1 - No difference between orders

Order is the same in both datastores (legacy and HPOS).

```plaintext
$ wp wc hpos diff 100087
Success: No differences found.
```

#### Example 2 - Mismatch in order properties between datastores

This examples shows that order `100126`  differs in various fields between both datastores. For example, its HPOS version has status `completed` while the post is still in `pending` status. Similarly, there are differences in other fields and there's even some metadata (`post_only_meta`) that only exists in the post/legacy version.

Any other order fields or metadata not listed are understood to be equal in both order versions.

```plaintext
$ wp wc hpos diff 100126
Warning: Differences found for order 100126:
+--------------------+---------------------------+---------------------------+
| property           | hpos                      | post                      |
+--------------------+---------------------------+---------------------------+
| status             | completed                 | pending                   |
| total              | 567.25                    | 267.25                    |
| date_modified      | 2024-04-04T15:32:27+00:00 | 2024-04-04T19:00:26+00:00 |
| billing_first_name | Hans                      | Jans                      |
| post_only_meta     |                           | why not?                  |
+--------------------+---------------------------+---------------------------+
```

#### Example 3 - JSON output

You can also get the output in various formats (`json`, `csv` or `list` -the default-), which can be useful for exporting differences from various orders to a file.

```plaintext
$ wp wc hpos diff 100126 --format=json
Warning: Differences found for order 100126:
[{"property":"status","hpos":"completed","post":"pending"},{"property":"total","hpos":"567.25","post":"267.25"},{"property":"date_modified","hpos":"2024-04-04T15:32:27+00:00","post":"2024-04-04T19:00:26+00:00"},{"property":"billing_first_name","hpos":"Hans","post":"Jans"},{"property":"post_only_meta","hpos":"","post":"why not?"}]
```

### `wc hpos backfill`

The backfill command can be used to selectively migrate order data (or whole orders) from either the legacy or HPOS datastore to the other one. It's very useful to reconcile sync or migration mishaps.

The exact syntax for this command is as follows:

```plaintext
wp wc hpos backfill <order_id> --from=<datastore> --to=<datastore> [--meta_keys=<meta_keys>] [--props=<props>]
```

You have to specify which datastore to use as source (either `posts` or `hpos`) and which one to use as destination. The `--meta_keys` and `--props` arguments receive a comma separated list of meta keys and order properties, which can be used to move only certain data from one datastore to the other, instead of the whole order.

Note that `wp wc hpos backfill` differs from `wp wc hpos sync` in various ways:

- You can specify which order to operate on, which gives you more control for one-off operations.
- It lets you move order data between datastores irrespective of what the current order storage is in WC settings. In contrast, `wp wc hpos sync` will only sync data from the current datastore to the other.
- In addition to letting you migrate full orders, it lets you choose which bits of data (order fields or metadata) to migrate.

#### Example 1 - Migrate a full order from HPOS to posts

```plaintext
$ wp wc hpos backfill 99709
Success: Order 99709 backfilled from hpos to posts.
```

#### Example 2 - Migrate metadata

Continuing with example 2 from the previous section, we can see how to migrate just one key of metadata from posts to HPOS.

```plaintext
$ wp wc hpos backfill 100126 --from=posts --to=hpos --meta_keys=post_only_meta
Success: Order 100126 backfilled from posts to hpos.
```

If you now run `wp wc hpos diff` on this order, you can see that the bit of metadata is no longer listed as a difference.

```plaintext
$ wp wc hpos diff 100126
Warning: Differences found for order 100126:
+--------------------+---------------------------+---------------------------+
| property           | hpos                      | post                      |
+--------------------+---------------------------+---------------------------+
| status             | completed                 | pending                   |
| total              | 567.25                    | 267.25                    |
| date_modified      | 2024-04-04T15:32:27+00:00 | 2024-04-04T19:00:26+00:00 |
| billing_first_name | Hans                      | Jans                      |
+--------------------+---------------------------+---------------------------+
```

#### Example 3

Also following the previous example, we can now reconcile all the data as we see fit. For example, we can migrate the status from posts to HPOS and the other bits of info in the other direction.
In the end, the orders will be identical, as can be confirmed through `wp wc hpos diff`.

1. Sync order status from posts to HPOS. This means the order will become "pending" in both datastores.

   ```plaintext
   $ wp wc hpos backfill 100126 --from=posts --to=hpos --props=status
   Success: Order 100126 backfilled from posts to hpos.
   ```

2. Sync the other properties from HPOS to posts.

   ```plaintext
   $ wp wc hpos backfill 100126 --from=hpos --to=posts --props=total,date_modified,billing_first_name
   Success: Order 100126 backfilled from hpos to posts.
   ```

3. Are we all sync'ed yet?

   ```plaintext
   $ wp wc hpos diff 100126
   Success: No differences found.
   ```

### `wc hpos cleanup`

The cleanup command can be used to remove order data from legacy tables when HPOS is enabled and compatibility mode is disabled.

Given this is a destructive operation, the tool won't do anything by default. You'll have to specify an order ID, a range of order IDs or `all` to operate on all orders.

The tool will also verify orders before removal, stopping if the post version seems more recent than the HPOS one. This allows closer inspection of those differences (for example, with `wp wc hpos diff`) and reconciling the data (with [`wp wc hpos backfill`](#wc-hpos-backfill)) before the deletion is executed.

**Note:** This command won't remove placeholder records (posts with type `shop_order_placehold`) from the posts table. We're working on allowing this in the near future, but for now leave placeholders so that datastores can be switched if necessary. Metadata is removed, which is where most data is stored in the legacy order storage, so the remaining placeholder post is very lightweight.

#### Example 1 - Error during cleanup

Cleaning up of an order that seems more recent on the posts datastore is prevented by default.

```plaintext
$ wp wc hpos cleanup 100126
Starting cleanup for 1 order...
Warning: An error occurred while cleaning up order 100126: Data in posts table appears to be more recent than in HPOS tables.
```

You can investigate the differences with `wp wc hpos diff`:

```plaintext
$ wp wc hpos diff 100126
Warning: Differences found for order 100126:
+---------------+---------------------------+---------------------------+
| property      | hpos                      | post                      |
+---------------+---------------------------+---------------------------+
| date_modified | 2024-04-05T15:19:56+00:00 | 2024-04-05T16:39:26+00:00 |
+---------------+---------------------------+---------------------------+
```

If reconciling is not necessary, the `--force` flag can be used to skip the verification checks:

```plaintext
$ wp wc hpos cleanup 100126 --force
Starting cleanup for 1 order...
HPOS cleanup  100% [=====================================================================================================================] 0:00 / 0:00
Success: Cleanup completed for 1 order.
```

#### Example 2 - Cleaning up a range of order IDs

```plaintext
$ wp wc hpos cleanup 90000-100000
Starting cleanup for 865 orders...
HPOS cleanup  100% [=====================================================================================================================] 0:01 / 0:12
Success: Cleanup completed for 865 orders.
```

#### Example 3 -Cleaning up all orders

```plaintext
$ wp wc hpos cleanup all
Starting cleanup for 999 orders...
HPOS cleanup  100% [=====================================================================================================================] 0:01 / 0:05
Success: Cleanup completed for 999 orders.
```


---

## How to enable High Performance Order Storage

*Source: features/orders/high-performance-order-storage/enable-hpos.md*

# How to enable High Performance Order Storage

From WooCommerce 8.2, released on October 2023, HPOS is enabled by default for new installations. Existing stores can switch to the "High-Performance Order Storage" from "WordPress Posts Storage" by following the below steps.

To activate High-Performance Order Storage, existing stores will first need to get both the posts and orders table in sync, which can be done by turning on the setting "**Enable compatibility mode (synchronizes orders to the posts table)**".

1. Navigate to **WooCommerce > Settings > Advanced > Features**
2. Turn on the **"Enable compatibility mode (synchronizes orders to the posts table)"** setting.

    ![Enable HPOS Screen](https://developer.woocommerce.com/wp-content/uploads/2023/12/New-Project-4.jpg)

3. Once this setting is activated, background actions will be scheduled.

    - The action `wc_schedule_pending_batch_process` checks whether there are orders that need to be backfilled.
    - If there are, it schedules another action `wc_run_batch_process` that actually backfills the orders to post storage.
    - You can either wait for these actions to run on their own, which should be quite soon, or you can go to **WooCommerce > Status > Scheduled Actions**, find the actions and click on the run button.
    - The action will backfill 25 orders at a time, if there are more orders to be synced, then more actions will be scheduled as soon as the previous actions are completed.

    ![wc_schedule_pending_batch_process Screen](https://developer.woocommerce.com/wp-content/uploads/2023/12/2.jpg)
    ![wc_run_batch_process Screen](https://developer.woocommerce.com/wp-content/uploads/2023/12/New-Project-5.jpg)

4. After both tables are successfully synchronized, you'll be able to select the option to switch to High-Performance Order Storage (HPOS).
  
    - It is advisable to maintain compatibility mode for some time to ensure a seamless transition. In case of any issues, reverting to the post table can be done instantly.


---

## A large store's guide to enable HPOS on WooCommerce

*Source: features/orders/high-performance-order-storage/guide-large-store.md*

# A large store's guide to enable HPOS on WooCommerce

Do you run a high-volume WooCommerce store? Are you about to embark on the task to enable High Performance Order Storage (HPOS) on said store? As we move more and more high-volume store to HPOS, we decided to document the guidelines for those of you who may be faced with this task.

## Before you begin

1. [Intro to High-Performance Order Storage](/docs/features/orders/high-performance-order-storage/)
2. [High-Performance Order Storage Upgrade Recipe Book](/docs/features/orders/high-performance-order-storage/recipe-book/)
3. [High-Performance Order Storage: Backward Compatibility and Synchronization](https://developer.woocommerce.com/2022/09/29/high-performance-order-storage-backward-compatibility-and-synchronization/)
4. [Intro to High-Performance Order Storage for non-devs](https://woocommerce.com/document/high-performance-order-storage/)

## Phase 1: Test out HPOS on a local development system

If you have a local development setup for your site, you can try out HPOS on your development setup. Make sure that you have all plugins and any custom code enabled on this test site and that you're running their latest versions. The test environment should mimic your production site as much as possible.

At the very least, we suggest you focus on the following tests:

1. Test checkout with every payment method.
2. Test refunds for those checkouts.
3. If you are using WooCommerce Subscriptions, check that subscriptions can be purchased and renewals come through.
4. Any critical flows you've defined for your site.

You can repeat the tests with both synchronization enabled and disabled.

Remember that you can [toggle synchronization](https://woocommerce.com/document/high-performance-order-storage/#section-5) by going to **WooCommerce > Settings > Advanced > Features**, and toggling the "**Enable compatibility mode**" checkbox.

![Toggle synchronization](https://woocommerce.com/wp-content/uploads/2023/10/image-18.png)

### Review: Phase 1 Checklist

- [ ] Make sure code on your test site is up to date by installing the latest versions of all WooCommerce-related plugins you're running.
- [ ] Test checkout functionality for every payment method.
- [ ] Verify refund process for test checkouts.
- [ ] If WooCommerce Subscriptions is installed, test subscription purchases and renewal.
- [ ] Test critical site flows with synchronization both enabled and disabled.

## Phase 2: Migrations and testing on a staging site

When you're happy with how things are working in your local environment, it is time to copy over your production database to the staging site and test out HPOS migrations. For large sites, we recommend setting synchronization to on but, instead of relying on the scheduled jobs to perform the migration, you can speed things up by using the CLI: specifically, the command **wp wc hpos sync**.

To get a sense of how much the final migration (on production) is going to take, make sure to time how much it takes for this command to run. For example, for our test store of 9 million orders, this took about a week to complete.

For extra peace of mind, you can run `wp wc hpos verify_cot_data --verbose` to check that the data has migrated successfully.
Once migration is complete on your staging site, and still with synchronization enabled, re-run the tests defined in Phase 1. **Disable the sync, and go through all testing again.**

### Test out 3rd party and external systems

You may have non-PHP systems directly connected to DB that would escape a normal code audit. Verify that if you have systems such as data warehouses, shipping tracking systems, accounting systems, etc., they are not reading the posts tables directly. If they are, then they would need to be updated before you can proceed with the next steps.

### Review: Phase 2 Checklist

1. [ ] Make sure the code on your staging site is up to date by installing the latest versions of all WooCommerce-related plugins you're running.
2. [ ] Migrate production database to staging site using CLI.
3. [ ] Monitor migration time for insights into production migration duration.
4. [ ] Test Phase 1 flows on the staging site with synchronization on.
5. [ ] Optionally, verify data migration integrity using `wp wc hpos verify_cot_data --verbose`.
6. [ ] Test Phase 1 flows on the staging site with synchronization off.
7. [ ] Audit third-party systems to ensure they do not directly access posts tables.

## Phase 3: Enabling HPOS on production

If you are happy with testing on your local setup and staging site, it's time to start working on enabling HPOS in production.

### Enable synchronization, keeping posts authoritative

Just like in the previous phases, you'll want to enable synchronization while still using the WordPress posts storage as order storage. As usual, do this by going to **WooCommerce > Settings > Advanced > Features** and making sure that **Use the WordPress posts tables** is selected as the order data storage.


This will make sure that orders will start appearing in the HPOS tables, and that existing orders will stay up to date.

### Migrate and verify data

Now, start the migration by enabling synchronization by toggling on the "**Enable compatibility mode**" checkbox.

Right after enabling synchronization, you can start migrating past orders from the post tables to the new HPOS tables via CLI using the `wp wc hpos sync` command.

In case you see any errors, turning off the sync, or interrupting the sync CLI job is considered safe. You can resume once you have resolved the error (or if the error was unrelated to the sync process).

Optionally, you can also run the verify command (`wp wc hpos verify_cot_data --verbose`) to check that data migrated is as expected.

Important: Even if the CLI job has completed, don't turn off synchronization just yet. For a production site, we recommend disabling sync progressively: disabling sync on read and then fully disabling sync.

Also, we didn't see a noticeable negative performance impact when keeping synchronization enabled (with posts authoritative) during our recent high-volume store migration.

### Switch to HPOS as authoritative

It's time to switch to HPOS. Go to **WooCommerce > Settings > Advanced > Features** and set HPOS to be authoritative (select "**Use the WooCommerce orders tables**").

As mentioned above, don't turn off synchronization yet. If there are any issues, the system can be instantaneously reverted to the posts table, resulting in no downtime.

Revisit all your critical flows from the previous phases and run some tests. Make sure to test checkout with various payment methods and your critical flows. On a high-volume store you should probably see some orders coming in naturally too, so open a few of those orders and verify that all the order data is being populated as expected. Keep an eye on your support or contact channels as well.

**Tip**: If your store has a natural low volume period then we'd recommend making the switch then, but you should plan to be online for some time after. Both switching to HPOS or reverting to posts (if needed) are hot migrations, and do not require any planned downtime.

### Switch off sync on the read

In the previous steps you have enabled HPOS with sync on, now it's time to disable synchronization progressively in order to start seeing most of the benefits from HPOS. The first step in this process would be to disable sync on read, which you can do via the following snippet:

```php
add_filter( 'woocommerce_hpos_enable_sync_on_read', '__return_false' );
```

We disable sync on read first because it demands more resources. If your site is running as expected, and you see some orders coming in, you can disable sync on read. We disabled this on our high-volume store migration after just 6 hours of setting HPOS to authoritative.

### Switch off sync on write

If everything is working as expected, you can disable sync on write as well. Given sync on read was already disabled, you can disable sync altogether from the settings. As usual, go to **WooCommerce > Settings > Advanced > Features**, and uncheck **"Enable compatibility mode"**.

On our high-volume site, we fully disabled sync after 1 week. We still run some manual synchronization (via `wp wc hpos sync`) periodically so that we have the opportunity to fall back to posts immediately should anything happen.

Keep in mind that disabling synchronization does not remove the ability to revert to the posts datastore, but you'd have to wait for the migration jobs to backfill the posts table with any data in the HPOS tables that they are missing. As always, `wp wc hpos sync` can also be used for this purpose.

Now with synchronization fully disabled, test out various critical flows, check that orders are coming in naturally as expected, and keep an eye on your support and contact channels.

### Review: Phase 3 Checklist

1. [ ] Plan to be online and monitoring your live site for a period of time.
2. [ ] Enable synchronization with posts set as authoritative: in **WooCommerce > Settings > Advanced > Features** > select "**Use the WordPress posts tables**".
3. [ ] Start migration via CLI using the `wp wc hpos sync` command.
4. [ ] Monitor for errors during migration; halt or resume as necessary.
5. [ ] Verify migrated data integrity using the verify command `wp wc hpos verify_cot_data`.
6. [ ] Enable synchronization with HPOS set as authoritative: in **WooCommerce > Settings > Advanced > Features** > select "Use the **WooCommerce orders tables**".
7. [ ] Test all critical flows, perform checkouts with multiple payment methods, and verify order data accuracy.
8. [ ] Monitor support tickets for any issues.
9. [ ] Disable synchronization on read using the provided snippet: `add_filter( 'woocommerce_hpos_enable_sync_on_read', '__return_false' );`
10. [ ] Monitor site performance.
11. [ ] After one week of stable operation, fully disable sync.
12. [ ] Continuously monitor site performance, order processing, and support tickets.

### General guidelines

1. [ ] Keep test environments as close to the production setup as possible.
2. [ ] Document any issues encountered during testing and migration.
3. [ ] Regularly communicate with stakeholders regarding testing progress and outcomes.
4. [ ] Plan for potential fallback scenarios, ensuring the ability to revert to posts if issues arise.


---

## HPOS extension recipe book

*Source: features/orders/high-performance-order-storage/recipe-book.md*

# HPOS extension recipe book

## What is High-Performance Order Storage (HPOS)?

Up until recently, WooCommerce stored order-related data in the post and postmeta tables in the database as a custom WordPress post type, which allowed everyone working in the ecosystem to take advantage of extensive APIs provided by the WordPress core in managing orders as custom post types.

However, in early 2022, [we announced the plans to migrate to dedicated tables for orders](https://developer.woocommerce.com/2022/01/17/the-plan-for-the-woocommerce-custom-order-table/). Orders in their own tables will allow the shops to scale more easily, make the data storage simpler and increase reliability. For further details, please check out our [deep dive on the database structure on our dev blog](https://developer.woocommerce.com/2022/09/15/high-performance-order-storage-database-schema/).

Generally, WooCommerce has tried to be fully backward compatible with the older versions, but, as a result of this project, extension developers will be required to make some changes to their plugins to take advantage of the HPOS. This is because the underlying data structure has changed fundamentally.

More specifically, instead of using WordPress-provided APIs to access order data, developers will need to use WooCommerce-specific APIs. We [introduced these APIs in WooCommerce version 3.0](https://developer.woocommerce.com/2017/04/04/say-hello-to-woocommerce-3-0-bionic-butterfly/) to make the transition to HPOS easier.

In this guide, we will focus on the changes required to make an extension, or any snippet of custom code, compatible with HPOS.

For details on how to take enable or disable HPOS, as well as details on how orders are synced between datastores please refer to the [HPOS documentation](https://woocommerce.com/document/high-performance-order-storage/).

## Backward compatibility

To make the transition easier for shops and developers alike, we have tried to be as backward compatible as possible. One of the major compatibility issues with this project is that since the underlying data structure was `wp_posts` and `wp_postmeta` tables, circumventing the WC-specific CRUD classes and accessing the data directly using WordPress APIs worked fine.

Now that this has changed, directly reading from these WordPress tables may mean reading an outdated order, and directly writing to these tables may mean updating an order that will not be read. Since this is a pretty significant issue, we have added a few mitigations for the transitory period.

### Switching data source

Additionally, you can switch from using HPOS to posts tables manually if you see an issue with the new tables. To switch back, change the "Order data storage" setting in the WC > Settings > Advanced > Features.

## Supporting High-Performance Order Storage in your extension

While the backward compatibility policies make it easier for merchants to use the project, for extension developers this means that you have to support both Posts and HPOS for a while.

To help with this, we have provided a few guidelines for extension developers to follow.

**Note:** We recommend you use the development version of WooCommerce while working on your extension, in order to get all of the latest HPOS fixes and APIs. Refer to our [development guide](https://github.com/woocommerce/woocommerce/blob/trunk/DEVELOPMENT.md) to understand how the WooCommerce repo is structured and how to build the plugin from source.

### Detecting whether HPOS tables are being used in the store

While the WooCommerce CRUD API will let you support both posts and custom tables without additional effort most of the time, in some cases (like when you are writing a SQL query for better performance) you would want to know whether the store is using HPOS tables or not. In this case, you can use the following pattern:

```php
use Automattic\WooCommerce\Utilities\OrderUtil;

if ( OrderUtil::custom_orders_table_usage_is_enabled() ) {
	// HPOS usage is enabled.
} else {
	// Traditional CPT-based orders are in use.
}
```

### Auditing the code base for direct DB access usage

To support HPOS tables, a good place to start is to audit your code base for direct DB access and usage of WordPress APIs that shouldn't be used to work with orders anymore. You can search using the following regexp to perform this audit:

```regexp
wpdb|get_post|get_post_field|get_post_status|get_post_type|get_post_type_object|get_posts|metadata_exists|get_post_meta|get_metadata|get_metadata_raw|get_metadata_default|get_metadata_by_mid|wp_insert_post|add_metadata|add_post_meta|wp_update_post|update_post_meta|update_metadata|update_metadata_by_mid|delete_metadata|delete_post_meta|delete_metadata_by_mid|delete_post_meta_by_key|wp_delete_post|wp_trash_post|wp_untrash_post|wp_transition_post_status|clean_post_cache|update_post_caches|update_postmeta_cache|post_exists|wp_count_post|shop_order
```

Please note that you will find lots of false positives, but this regular expression is quite thorough and should catch most of the true positives.

Search for the above regular expression in your source code, and:

1. Go through the matches one by one and check whether the occurrence relates to an order. Most of the matches will probably be false positives i.e. they won't be related to orders.
2. If you see one of the matches are directly accessing or modifying order data, you will need to change it to use WooCommerce's CRUD API instead.

### APIs for getting/setting posts and postmeta

Any code getting posts directly can be converted to a `wc_get_order` call instead:

```php
// Instead of
$post = get_post( $post_id ); // returns WP_Post object.
// use
$order = wc_get_order( $post_id ); // returns WC_Order object.
```

For interacting with metadata, use the `update_`/`add_`/`delete_metadata` methods on the order object, followed by a `save` call. WooCommerce will take care of figuring out which tables are active, and saving data in appropriate locations.

```php
// Instead of following update/add/delete methods, use:
update_post_meta( $post_id, $meta_key_1, $meta_value_1 );
add_post_meta( $post_id, $meta_key_2, $meta_value_2 );
delete_post_meta( $post_id, $meta_key_3, $meta_value_3 );

// use
$order = wc_get_order( $post_id );
$order->update_meta_data( $meta_key_1, $meta_value_1 );
$order->add_meta_data( $meta_key_2, $meta_value_2 );
$order->delete_meta_data( $meta_key_3, $meta_value_3 );
$order->save();
```

**Note:** Calling the `save()` method is a relatively expensive operation, so you may wish to avoid calling it more times than necessary (for example, if you know it will be called later in the same flow, you may wish to avoid additional earlier calls when operating on the same object).

When getting exact type of an order, or checking if given ID is an order, you can use methods from `OrderUtil` class.

```php
// Pattern to check when an ID is an order
'shop_order' === get_post_type( $post_id ); // or
in_array( get_post_type( $post_type ), wc_get_order_types() );

// replace with:
use Automattic\WooCommerce\Utilities\OrderUtil;
'shop_order' === OrderUtil::get_order_type( $post_id ); // or
OrderUtil::is_order( $post_id, wc_get_order_types() );
```

### Audit for order administration screen functions

As WC can't use the WordPress-provided post list and post edit screens, we have also added new screens for order administration. These screens are very similar to the one you see in the WooCommerce admin currently (except for the fact that they are using HPOS tables). You can use the following regular expression to perform this audit:

```regexp
post_updated_messages|do_meta_boxes|enter_title_here|edit_form_before_permalink|edit_form_after_title|edit_form_after_editor|submitpage_box|submitpost_box|edit_form_advanced|dbx_post_sidebar|manage_shop_order_posts_columns|manage_shop_order_posts_custom_column
```

You will see a lot of false positives here as well. However, if you do encounter a usage where these methods are called for the order screen then to upgrade them to HPOS, the following changes have to be done:

Instead of a `$post` object of the `WP_Post` class, you will need to use an `$order` object of the `WC_Order` class. If it's a filter or an action, then we will implement a similar filter in the new WooCommerce screen as well and instead of passing the post object, it will accept a WC_Order object instead.

The following snippet shows a way to add meta boxes to the legacy order editor screen when legacy orders are in effect, and to the new HPOS-powered editor screen otherwise:

```php
use Automattic\WooCommerce\Internal\DataStores\Orders\CustomOrdersTableController;

add_action( 'add_meta_boxes', 'add_xyz_metabox' );

function add_xyz_metabox() {
	$screen = class_exists( '\Automattic\WooCommerce\Internal\DataStores\Orders\CustomOrdersTableController' ) && wc_get_container()->get( CustomOrdersTableController::class )->custom_orders_table_usage_is_enabled()
		? wc_get_page_screen_id( 'shop-order' )
		: 'shop_order';

	add_meta_box(
		'xyz',
		'Custom Meta Box',
		'render_xyz_metabox',
		$screen,
		'side',
		'high'
	);
}
```

The above will also change the parameter passed to the metabox to order. So in your metaboxes, you would have to account for both a post or order object that may be passed. We recommend fetching the order object and working with it completely instead of the passed parameter.

```php
function render_xyz_metabox( $post_or_order_object ) {
    $order = ( $post_or_order_object instanceof WP_Post ) ? wc_get_order( $post_or_order_object->ID ) : $post_or_order_object;

    // ... rest of the code. $post_or_order_object should not be used directly below this point.
}
```

### Declaring extension (in)compatibility

Once you examined the extension's code, you can declare whether it's compatible with HPOS or not. We've prepared an API to make this easy. To **declare your extension compatible**, place the following code into your **main plugin file**:

```php
add_action( 'before_woocommerce_init', function() {
	if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
	}
} );
```

If you know your code doesn't support HPOS, you should declare **incompatibility** in the following way. Place the following code into your **main plugin file**:

```php
add_action( 'before_woocommerce_init', function() {
	if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, false );
	}
} );
```

If you prefer to include the compatibility declaration outside of your main plugin file, please pass 'my-plugin-slug/my-plugin.php' instead of the `__FILE__` parameter in the snippets above.

To prevent problems, WooCommerce will warn users if they try to enable HPOS while any of the incompatible plugins are active. It will also display a warning in the Plugins screen to make sure people would know if extension is incompatible.
As many WordPress extensions aren't WooCommerce related, WC will only display this information for extensions that declare `WC tested up to` in the header of the main plugin file.

### New order querying APIs

HPOS, through `WC_Order_Query`, introduces new query types that allow for more complex order queries involving dates, metadata and order fields. Head over to [HPOS: new order querying APIs](https://developer.woocommerce.com/docs/hpos-order-querying-apis/) for details and examples.


---

## HPOS order querying APIs

*Source: features/orders/high-performance-order-storage/wc-order-query-improvements.md*

# HPOS order querying APIs

With the introduction of HPOS, we've enhanced the querying functionality in WC. Now, in addition to the well-known [existing APIs](/docs/features/orders/wc-get-orders), we're adding a few features that would make it easier to create complex queries on orders or their properties, including the ability to query custom order metadata.

All the new query types are implemented as additional query arguments that can be passed to `wc_get_orders()` and are heavily inspired by similar functionality in WordPress' own `WP_Query`. As regular query arguments, they can be combined with other arguments to produce complex queries that, until now, would have required writing custom code and SQL.

## The new query types

### Metadata queries (`meta_query`)

With the introduction of HPOS, order fields that were previously stored as post metadata have been moved to their own tables, but the remaining metadata (custom, or from other extensions) can now be queried through the `meta_query `argument.

At its core, `meta_query` is an array that can contain one or more arrays with keys:
`key` (the meta key name),
`value` (the meta value)
`compare` (optional) an operator to use for comparison purposes such as LIKE, RLIKE, NOT BETWEEN, BETWEEN, etc.
`type` to cast the meta value to a specific SQL type in the query

The different arrays can also be combined using `relation` (which admits 'AND' or 'OR' values) to produce more complex queries. The syntax for this new argument is exactly the same as for WP_Query's `meta_query`. As such, you can refer to the [`meta_query` docs](https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters) for more details.

```php
// Example: obtain all orders which have metadata with the "color" key (any value) and have metadata
// with key "size" containing "small" (so it'd match "extra-small" as well as "small", for example).
$orders = wc_get_orders(
    array(
        'meta_query' => array(
            array(
                'key' => 'color',
            ),
            array(
                'key'        => 'size',
                'value'      => 'small',
                'compare'    => 'LIKE'
            ),
        ),
    )
);
```

### Order field queries (`field_query`)

This query type has a syntax similar to that of meta queries (`meta_query`) but instead of `key` you'd use `field` inside the different clauses. Here, `field` refers to any order property (such as `billing_first_name`, `total` or `order_key`, etc.) which are also accessible as top-level keys in the query arguments as usual. The difference between directly querying those properties and using a `field_query` is that you can create more complex queries by implementing comparison operators and combining or nesting.

```php
// Example. For a simple query, you'd be better off by using the order properties directly, even though there's a `field_query` equivalent.
$orders = wc_get_orders(
    array(
        'billing_first_name' => 'Lauren',
        'order_key'          => 'my_order_key',
    )
);

$orders = wc_get_orders(
    array(
        'field_query' => array(
            array(
                'field' => 'billing_first_name',
                'value' => 'Lauren'
            ),
            array(
                'field' => 'order_key',
                'value' => 'my_order_key',
            )
        )
    )
);
```

The true power of `field_query` is revealed when you want to perform more interesting queries, that were not possible before...

```php
// Example. Obtain all orders where either the total or shipping total is less than 5.0.

$orders = wc_get_orders(
    array(
        'field_query' => array(
            'relation' => 'OR',
            array(
                'field'   => 'total',
                'value'   => '5.0',
                'compare' => '<',
            ),
            array(
                'field'   => 'shipping_total',
                'value'   => '5.0',
                'compare' => '<',
            ),
        )
    )
);
```

### Date queries (`date_query`)

Date queries allow you to fetch orders by querying their associated dates (`date_completed`, `date_created`, `date_updated`, `date_paid`) in various ways.
The syntax for `date_query` is fully compatible with that of `date_query` in `WP_Query`. As such, a good source of examples and details is [the `meta_query` docs](https://developer.wordpress.org/reference/classes/wp_query/#date-parameters) in the WP codex.

```php
// Example. Obtain all orders paid in the last month that were created before noon (on any date).

$orders = wc_get_orders(
    array(
        'date_query' => array(
            'relation' => 'AND',
            array(
                'column'  => 'date_created_gmt',
                'hour'    => 12,
                'compare' => '<'
            ),
            array(
                'column'  => 'date_paid_gmt',
                'after'   => '1 month ago',
            ),
        ),
    )
);
```

## Advanced Examples

```php
// Obtain orders either "on-hold" or "pending" that have metadata `weight` >= 50 and metadata `color` or `size` is set.

$query_args = array(
    'status' => array( \Automattic\WooCommerce\Enums\OrderStatus::PENDING, \Automattic\WooCommerce\Enums\OrderStatus::ON_HOLD ),
    'meta_query' => array(
        array(
            'key'     => 'weight',
            'value'   => '50',
            'compare' => '>=',
        ),
        array(
            'relation' => 'OR',
            array(
                'key'     => 'color',
                'compare' => 'EXISTS',
            ),
            array(
                'key'     => 'size',
                'compare' => 'EXISTS',
            )
        ),
    )
);

$orders = wc_get_orders( $query_args );
```

```php
// Obtain orders where the first name in the billing details contains "laur" (so it'd both match "lauren" and "laura", for example), and where the order's total is less than 10.0 and the total discount is >= 5.0.

$orders = wc_get_orders(
    array(
        'field_query' => array(
            array(
                'field'   => 'billing_first_name',
                'value'   => 'laur',
                'compare' => 'LIKE',
            ),
            array(
                'relation' => 'AND',
                array(
                    'field'   => 'total',
                    'value'   => '10.0',
                    'compare' => '<',
                    'type'    => 'NUMERIC',
                ),
                array(
                    'field'   => 'discount_total',
                    'value'   => '5.0',
                    'compare' => '>=',
                    'type'    => 'NUMERIC',
                )
            )
        ),
    )
);
```


---

## `wc_get_orders()` and order queries

*Source: features/orders/wc-get-orders.md*

# `wc_get_orders()` and order queries

`wc_get_orders()` and `WC_Order_Query` provide a standard way of retrieving orders from the database, similar to WordPress' [`get_posts()` and `WP_Query`](https://codex.wordpress.org/Class_Reference/WP_Query) but specifically for orders.

Plugin and theme developers are discouraged from writing custom WordPress queries or direct SQL as changes in the WordPress or WooCommerce database can result in breakage. These APIs provide the best-practices and future-proof way to fetch orders in WooCommerce.

## Basic usage

### Examples

Here are a few examples:

```php
// Get orders from people named John paid in 2016.
$orders = wc_get_orders(
    array(
        'billing_first_name' => 'John',
        'date_paid'          => '2016-01-01...2016-12-31',
    )
);
```

```php
// Get 10 most recent order IDs.
$query = new WC_Order_Query(
    array(
        'limit'   => 10,
        'orderby' => 'date',
        'order'   => 'DESC',
        'return'  => 'ids',
    )
);
$orders = $query->get_orders();
```

```php
// Get orders from the customer with email 'woocommerce@woocommerce.com'.
$query = new WC_Order_Query();
$query->set( 'customer', 'woocommerce@woocommerce.com' );
$orders = $query->get_orders();
```

Note that `wc_get_orders()` is mostly a shortcut to `WC_Order_Query::get_orders()`.

### Best practices

- Avoid direct base queries and rely on `wc_get_orders()` instead.
- If your code needs to support legacy setups, test thoroughly with HPOS enabled and disabled.
- Use specific parameters to limit results and improve performance.
- Consider pagination for large result sets using `limit` and `offset`.
- Cache results when appropriate.
- For complex filtering requirements, leverage the new query arguments `meta_query`, `field_query` and `date_query` available since 8.2 on sites running HPOS.


## API reference

| Method | Description |
| --- | --- |
| `wc_get_orders ( $args )` | Retrieve orders matching query `$args`. |
| `WC_Order_Query::get_query_vars()` | Get an array of all of the current query variables set on the query object. |
| `WC_Order_Query::get( string $key, mixed $default = '' )` | Get the value of a query variable or the default if the query variable is not set. |
| `WC_Order_Query::set( string $key, mixed $value )` | Set a query variable. |
| `WC_Order_Query::get_orders()` | Get all orders matching the current query variables. |

Query parameters/arguments that can be used with these functions are described below.

## Query parameters reference

### General

| Parameter | Description |
| --- | --- |
| **status** | Accepts an array of strings: by default is set to the keys of `wc_get_order_statuses()`. Both `wc-`-prefixed (`'wc-processing'`) and unprefixed (`'processing'`) values are accepted. See the [OrderInternalStatus](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Enums/OrderInternalStatus.php) and [OrderStatus](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Enums/OrderStatus.php) constant classes. |
| **type** | Accepts a string: `'shop_order'`, `'shop_order_refund'`, or a custom order type. |
| **version** | Accepts a string: WooCommerce version number the order was created in. |
| **created_via** | Accepts a string: 'checkout', 'rest-api', or a custom creation method slug. |
| **parent** | Accepts an integer: post ID of the order parent. |
| **parent_exclude** | Accepts an array of integers: Excludes orders with parent ids in the array. |
| **exclude** | Accepts an array of integers: excludes orders that have the ids. |
| **order** | Accepts a string: 'DESC' or 'ASC'. Use with 'orderby'. Default: 'DESC'. |
| **orderby** | Accepts a string: 'none', 'ID', 'name', 'type', 'rand', 'date', 'modified'. Default: 'date'. |
| **return** | Return type. Accepts a string: 'ids' or 'objects'. Default: 'objects'. |

#### Examples

```php
// Get most recently modified orders.
$args = array(
    'orderby' => 'modified',
    'order' => 'DESC',
);
$orders = wc_get_orders( $args );
```

```php
// Get some random orders.
$orders = wc_get_orders( array( 'orderby' => 'rand' ) );
```

```php
// Return only order ids.
$orders = wc_get_orders( array( 'return' => 'ids' ) );
```

```php
// Get orders processing and on-hold.
$args = array(
    'status' => array( 'wc-processing', 'wc-on-hold' ),
);
$orders = wc_get_orders( $args );
```

```php
// Using constant classes for status.
$args = array(
    'status' => array(
        \Automattic\WooCommerce\Enums\OrderInternalStatus::PROCESSING,
        \Automattic\WooCommerce\Enums\OrderInternalStatus::ON_HOLD,
    ),
);
$orders = wc_get_orders( $args );
```

```php
// Get refunds in the last 24 hours.
$args = array(
    'type'         => 'shop_order_refund',
    'date_created' => '>' . ( time() - DAY_IN_SECONDS ),
);
$orders = wc_get_orders( $args );
```

```php
// Get orders created during WooCommerce 2.6.14 and through site checkout.
$args = array(
    'version'     => '2.6.14',
    'created_via' => 'checkout',
);
$orders = wc_get_orders( $args );
```

```php
// Get orders with post parent ID of 20 that aren't order 12.
$args = array(
    'parent'  => 20,
    'exclude' => array( 12 ),
);
$orders = wc_get_orders( $args );
```

### Pagination

| Parameter | Description |
| --- | --- |
| **limit** | Accepts an integer: Maximum number of results to retrieve or `-1` for unlimited. Default: Site 'posts_per_page' setting. |
| **paged** | Accepts an integer: Page of results to retrieve. Does nothing if 'offset' is used. |
| **offset** | Accepts an integer: Amount to offset order results. |
| **paginate** | Accepts a boolean: True for pagination, or false for not (default: false). If enabled, modifies the return results to give an object with fields: `orders` (array of found orders), `total` (number of found orders) and `max_num_pages` (total number of pages). |

#### Examples

```php
// Get latest 3 orders.
$orders = wc_get_orders( array( 'limit' => 3 ) );
```

```php
// First 3 orders.
$args = array(
    'limit' => 3,
    'paged' => 1,
);
$page_1_orders = wc_get_orders( $args );

// Second 3 orders.
$args = array(
    'limit' => 3,
    'paged' => 2,
);
$page_2_orders = wc_get_orders( $args );
```

```php
// Get orders with extra info about the results.
$results = wc_get_orders( array( 'paginate' => true ) );
echo $results->total . " orders found\n";
echo 'Page 1 of ' . $results->max_num_pages . "\n";
echo 'First order id is: ' . $results->orders[0]->get_id() . "\n";
```

### Payment & amounts

|Parameter|Description|
|-|-|
|**currency**|Accepts a string: Currency used in order.|
|**prices_include_tax**|Accepts a string: 'yes' or 'no'.|
|**payment_method**|Accepts a string: Slug of payment method used.|
|**payment_method_title**|Accepts a string: Full title of payment method used.|
|**discount_total**|Accepts a float: unrounded amount to match on.|
|**discount_tax**|Accepts a float: unrounded amount to match on.|
|**shipping_total**|Accepts a float: unrounded amount to match on.|
|**shipping_tax**|Accepts a float: unrounded amount to match on.|
|**cart_tax**|Accepts a float: unrounded amount to match on.|
|**total**|Accepts a float: unrounded amount to match on.|

#### Examples

```php
// Get orders paid in USD.
$orders = wc_get_orders( array( 'currency' => 'USD' ) );
```

```php
// Get orders paid by check.
$orders = wc_get_orders( array( 'payment_method' => 'cheque' ) );
```

```php
// Get orders with 20.00 discount total.
$orders = wc_get_orders( array( 'discount_total' => 20.00 ) );
```

### Customer

|Parameter|Description|
|-|-|
|**customer**|Accepts a string or an integer: The order's billing email or customer id.|
|**customer_id**|Accepts an integer: Customer ID.|
|**customer_ip_address**|Accepts string: Value to match on.|

#### Examples

```php
// Get orders by customer with email 'woocommerce@woocommerce.com'.
$orders = wc_get_orders( array( 'customer' => 'woocommerce@woocommerce.com' ) );
```

```php
// Get orders by customer with ID 12.
$orders = wc_get_orders( array( 'customer_id' => 12 ) );
```

### Billing & shipping

|Parameter|Description|
|-|-|
|**billing_first_name**|Accepts string: value to match on.|
|**billing_last_name**|Accepts string: value to match on.|
|**billing_company**|Accepts string: value to match on.|
|**billing_address_1**|Accepts string: value to match on.|
|**billing_address_2**|Accepts string: value to match on.|
|**billing_city**|Accepts string: value to match on.|
|**billing_state**|Accepts string: value to match on.|
|**billing_postcode**|Accepts string: value to match on.|
|**billing_country**|Accepts string: value to match on.|
|**billing_email**|Accepts string: value to match on.|
|**billing_phone**|Accepts string: value to match on.|
|**shipping_first_name**|Accepts string: value to match on.|
|**shipping_last_name**|Accepts string: value to match on.|
|**shipping_company**|Accepts string: value to match on.|
|**shipping_address_1**|Accepts string: value to match on.|
|**shipping_address_2**|Accepts string: value to match on.|
|**shipping_city**|Accepts string: value to match on.|
|**shipping_state**|Accepts string: value to match on.|
|**shipping_postcode**|Accepts string: value to match on.|
|**shipping_country**|Accepts string: value to match on.|

#### Examples

```php
// Get orders from the US.
$orders = wc_get_orders( array( 'billing_country' => 'US' ) );
```

```php
// Get orders from people named Bill Evans.
$args = array(
    'billing_first_name' => 'Bill',
    'billing_last_name'  => 'Evans',
);
$orders = wc_get_orders( $args );
```

### Date

Date arguments receive values following the standard format described below, allowing for more flexible queries.

|Parameter|Description|
|-|-|
|**date_created**|Matches order creation date. Accepts a string in standard format.|
|**date_modified**|Matches order modification date. Accepts a string in standard format.|
|**date_completed**|Matches order completed date. Accepts a string in standard format.|
|**date_paid**|Matches order payment date. Accepts a string in standard format.|

#### Standard format

- `YYYY-MM-DD` - Matches on orders during that one day in site timezone.
- `>YYYY-MM-DD` - Matches on orders after that one day in site timezone.
- `>=YYYY-MM-DD` - Matches on orders during or after that one day in site timezone.
- `<YYYY-MM-DD` - Matches on orders before that one day in site timezone.
- `<=YYYY-MM-DD` - Matches on orders during or before that one day in site timezone.
- `YYYY-MM-DD...YYYY-MM-DD` - Matches on orders during or in between the days in site timezone.
- `TIMESTAMP` - Matches on orders during that one second in UTC timezone.
- `>TIMESTAMP` - Matches on orders after that one second in UTC timezone.
- `>=TIMESTAMP` - Matches on orders during or after that one second in UTC timezone.
- `<TIMESTAMP` - Matches on orders before that one second in UTC timezone.
- `<=TIMESTAMP` - Matches on orders during or before that one second in UTC timezone.
- `TIMESTAMP...TIMESTAMP` - Matches on orders during or in between the seconds in UTC timezone.

#### Examples

```php
// Get orders paid February 12, 2016.
$orders = wc_get_orders( array( 'date_paid' => '2016-02-12' ) );
```

```php
// Get orders created before the last hour.
$args = array(
    'date_created' => '<' . ( time() - HOUR_IN_SECONDS ),
);
$orders = wc_get_orders( $args );
```

```php
// Get orders completed 16 May 2017 21:46:17 UTC to 17 May 2017 12:46:17 UTC.
$args = array(
    'date_completed' => '1494938777...1494971177',
);
$orders = wc_get_orders( $args );
```

### Metadata

| Parameter | Description |
| --- | --- |
| **meta_query** | One or more arrays with keys `key` (meta key), `value` (optional, string or array) and optionally `type` and `compare`.<br />This parameter is analogous to [WP_Query's `meta_query`](https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters), supporting various comparison operators and levels of queries joined by AND/OR relations. |

For more details and examples, refer to the [HPOS order querying](/docs/features/orders/high-performance-order-storage/wc-order-query-improvements#metadata-queries-meta_query) guide.

:::warning

Support for `meta_query` is only available when HPOS is the configured order data storage (the default since WooCommerce 8.2).

Check if it's enabled with `OrderUtil::custom_orders_table_usage_is_enabled()` before using.
:::


#### Examples

```php
// Orders with metadata 'custom_field' set to 'some_value' and metadata 'weight' higher than '50'.
$orders = wc_get_orders(
    array(
        'meta_query' => array(
            array(
                'key'     => 'custom_field',
                'value'   => 'some_value',
                'compare' => '='
            ),
            array(
                'key'     => 'weight',
                'value'   => '50',
                'compare' => '>='
            ),
            'relation' => 'AND'
        )
    )
);
```

### Order fields

|Parameter|Description|
|-|-|
|**field_query**|One or more arrays with keys `field` (any order property), `value` and optionally `type` and `compare`.<br />This parameter is analogous to those of `meta_query` described in the previous section, supporting various comparison operators and levels of queries joined by AND/OR relations.|

For more details and examples, refer to the [HPOS order querying](/docs/features/orders/high-performance-order-storage/wc-order-query-improvements#order-field-queries-field_query) guide.

:::warning

Support for `field_query` is only available when HPOS is the configured order data storage (the default since WooCommerce 8.2).

Check if it's enabled with `OrderUtil::custom_orders_table_usage_is_enabled()` before using.
:::

#### Examples

```php
// Obtain orders with a total greater than 100 or from New York city.
$orders = wc_get_orders(
    array(
        'field_query' => array(
            array(
                'field' => 'total',
                'value' => 100,
                'compare' => '>'
            ),
            array(
                'field' => 'billing_city',
                'value' => 'New York',
                'compare' => '='
            ),
            'relation' => 'OR'
        )
    )
);
```

### Advanced date queries

| Parameter | Description |
| --- | --- |
| **date_query** | One or more arrays with keys `column` (an order date: `date_completed`, `date_created`, `date_updated` or `date_paid`, optionally followed by `_gmt` for UTC dates), `value` and optionally `type` and `compare`.<br />This parameter is analogous to [WP_Query's `date_query`](https://developer.wordpress.org/reference/classes/wp_query/#date-parameters), supporting various comparison operators and levels of queries joined by AND/OR relations. |

For more details and examples, refer to the [HPOS order querying](/docs/features/orders/high-performance-order-storage/wc-order-query-improvements#date-queries-date_query) guide.

:::warning

Support for `date_query` is only available when HPOS is the configured order data storage (the default since WooCommerce 8.2).

Check if it's enabled with `OrderUtil::custom_orders_table_usage_is_enabled()` before using.
:::

#### Examples

```php
// Example: Orders paid in the last month that were created before noon (on any date).

$orders = wc_get_orders(
    array(
        'date_query' => array(
            'relation' => 'AND',
            array(
                'column'  => 'date_created_gmt',
                'hour'    => 12,
                'compare' => '<'
            ),
            array(
                'column'  => 'date_paid_gmt',
                'after'   => '1 month ago',
            ),
        ),
    )
);
```

## Adding support for custom parameters

Developers can extend the query capabilities by filtering the generated query to add support for custom parameters to both `wc_get_orders()` and `WC_Order_Query`.

WooCommerce currently supports two order storage mechanisms: HPOS (the default) and legacy (which uses WordPress posts and metadata), each with their own hook to filter the generated query:

- (HPOS) `woocommerce_order_query_args` to translate a parameter into an existing one, or `woocommerce_orders_table_query_clauses` to write your own SQL.
- (Legacy) `woocommerce_order_data_store_cpt_get_orders_query` to translate a parameter into a `WP_Query` parameter.

```php
/**
 * Example: Handle a custom 'customvar' query var to get orders with the 'customvar' meta.
 */
use Automattic\WooCommerce\Utilities\OrderUtil;

// HPOS version.
function handle_custom_query_var_hpos( $query_args ) {
    if ( ! empty( $query_args['customvar'] ) ) {
        if ( ! isset( $query_args['meta_query'] ) ) {
            $query_args['meta_query'] = array();
        }

		$query_args['meta_query'][] = array(
			'key'   => 'customvar',
			'value' => esc_attr( $query_args['customvar'] ),
		);

        unset( $query_args['customvar'] );
    }


    return $query_args;
}

// Legacy version.
function handle_custom_query_var_legacy( $query, $query_vars ) {
	if ( ! empty( $query_vars['customvar'] ) ) {
		$query['meta_query'][] = array(
			'key'   => 'customvar',
			'value' => esc_attr( $query_vars['customvar'] ),
		);
	}

	return $query;
}

if ( OrderUtil::custom_orders_table_usage_is_enabled() ) {
    // HPOS.
    add_filter(
        'woocommerce_order_query_args',
        'handle_custom_query_var_hpos'
    );
} else {
    // Legacy support.
    add_filter(
        'woocommerce_order_data_store_cpt_get_orders_query',
        'handle_custom_query_var_legacy',
        10,
        2
    );
}
```

Usage:

```php
$orders = wc_get_orders( array( 'customvar' => 'somevalue' ) );
```


---

## WooCommerce Payment Gateway API

*Source: features/payments/payment-gateway-api.md*

# WooCommerce Payment Gateway API

Payment gateways in WooCommerce are class based and can be added through traditional plugins. This guide provides an intro to gateway development.

## Types of payment gateway

Payment gateways come in several varieties:

1.  **Form based** - This is where the user must click a button on a form that then redirects them to the payment processor on the gateway's own website. _Example_: PayPal standard, Authorize.net DPM
2.  **iFrame based** - This is when the gateway payment system is loaded inside an iframe on your store. _Example_: SagePay Form, PayPal Advanced
3.  **Direct** - This is when the payment fields are shown directly on the checkout page and the payment is made when 'place order' is pressed. _Example_: PayPal Pro, Authorize.net AIM
4.  **Offline** - No online payment is made. _Example_: Cheque, Bank Transfer

Form and iFrame based gateways post data offsite, meaning there are less security issues for you to think about. Direct gateways, however, require server security to be implemented ([SSL certificates](https://woocommerce.com/document/ssl-and-https/), etc.) and may also require a level of [PCI compliance](https://woocommerce.com/document/pci-dss-compliance-and-woocommerce/).

## Creating a basic payment gateway

**Note:** The instructions below are for the default Checkout page. If you're looking to add a custom payment method for the new Checkout block, check out [the payment method integration documentation](/docs/block-development/extensible-blocks/cart-and-checkout-blocks/checkout-payment-methods/payment-method-integration).

Payment gateways should be created as additional plugins that hook into WooCommerce. Inside the plugin, you need to create a class after plugins are loaded. Example:

```php
add_action( 'plugins_loaded', 'init_your_gateway_class' );
```

It is also important that your gateway class extends the WooCommerce base gateway class, so you have access to important methods and the [settings API](https://developer.woocommerce.com/docs/settings-api/):

```php
function init_your_gateway_class() {
    class WC_Gateway_Your_Gateway extends WC_Payment_Gateway {}
}
```

You can view the [WC_Payment_Gateway class in the API Docs](https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html).

As well as defining your class, you need to also tell WooCommerce (WC) that it exists. Do this by filtering _woocommerce_payment_gateways_:

```php
function add_your_gateway_class( $methods ) {
    $methods[] = 'WC_Gateway_Your_Gateway';
    return $methods;
}
```

```php
add_filter( 'woocommerce_payment_gateways', 'add_your_gateway_class' );
```

### Required Methods

Most methods are inherited from the WC_Payment_Gateway class, but some are required in your custom gateway.

#### __construct()

Within your constructor, you should define the following variables:

- `$this->id` - Unique ID for your gateway, e.g., 'your_gateway'
- `$this->icon` - If you want to show an image next to the gateway's name on the frontend, enter a URL to an image.
- `$this->has_fields` - Bool. Can be set to true if you want payment fields to show on the checkout (if doing a direct integration).
- `$this->method_title` - Title of the payment method shown on the admin page.
- `$this->method_description` - Description for the payment method shown on the admin page.

Your constructor should also define and load settings fields:

```php
$this->init_form_fields();
$this->init_settings();
```

We'll cover `init_form_fields()` later, but this basically defines your settings that are then loaded with `init_settings()`.

After `init_settings()` is called, you can get the settings and load them into variables, meaning:

```php
$this->title = $this->get_option( 'title' );
```

Finally, you need to add a save hook for your settings:

```php
add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
```

##### Display in the Payments settings page

The Payments settings page uses the gateway's admin-facing details to build the payment provider list. Set these values in your gateway constructor so merchants can identify your extension before they open its individual settings screen.

| Provider detail | Source | Notes |
| ----------------- | -------- | ------- |
| Icon | `$this->icon` | Must be a valid image URL. Use a square image for the best fit. If the value is empty, invalid, or contains an `<img>` tag instead of a URL, WooCommerce shows the default payments icon. |
| Title | `PaymentsProviders\PaymentGateway::get_title()` | Uses `WC_Payment_Gateway::get_method_title()` as a `$this->method_title` accessor. If it is empty, the provider falls back to the gateway's customer-facing `WC_Payment_Gateway::get_title()`, strips HTML, and truncates the display value to 75 characters. |
| Description | `PaymentsProviders\PaymentGateway::get_description()` | Uses `WC_Payment_Gateway::get_method_description()` as a `$this->method_description` accessor. If it is empty, the provider falls back to the gateway's customer-facing `WC_Payment_Gateway::get_description()`, strips HTML, and truncates the display value to 130 characters. |

Use `$this->method_title` and `$this->method_description` for concise admin copy. Use `$this->title` and `$this->description` for the customer-facing checkout label and payment instructions, often loaded from merchant settings with `$this->get_option()`.

For example:

```php
public function __construct() {
    $this->id                 = 'your_gateway';
    $this->method_title       = __( 'Your Gateway', 'your-text-domain' );
    $this->method_description = __( 'Accept card payments with Your Gateway.', 'your-text-domain' );
    $this->icon               = plugins_url( 'assets/images/your-gateway-icon.svg', __FILE__ );
    $this->has_fields         = true;

    $this->init_form_fields();
    $this->init_settings();

    $this->title       = $this->get_option( 'title' );
    $this->description = $this->get_option( 'description' );
}
```

#### init_form_fields()

Use this method to set `$this->form_fields` - these are options you'll show in admin on your gateway settings page and make use of the [WC Settings API](https://developer.woocommerce.com/docs/settings-api/).

A basic set of settings for your gateway would consist of _enabled_, _title_ and _description_:

```php
$this->form_fields = array(
    'enabled' => array(
        'title' => __( 'Enable/Disable', 'woocommerce' ),
        'type' => 'checkbox',
        'label' => __( 'Enable Cheque Payment', 'woocommerce' ),
        'default' => 'yes'
    ),
    'title' => array(
        'title' => __( 'Title', 'woocommerce' ),
        'type' => 'text',
        'description' => __( 'This controls the title which the user sees during checkout.', 'woocommerce' ),
        'default' => __( 'Cheque Payment', 'woocommerce' ),
        'desc_tip' => true,
    ),
    'description' => array(
        'title' => __( 'Customer Message', 'woocommerce' ),
        'type' => 'textarea',
        'default' => ''
    )
);
```

#### process_payment( $order_id )

Now for the most important part of the gateway - handling payment and processing the order. Process_payment also tells WC where to redirect the user, and this is done with a returned array.

Here is an example of a process_payment function from the Cheque gateway:

```php
function process_payment( $order_id ) {
global $woocommerce;
$order = new WC_Order( $order_id );

    // Mark as on-hold (we're awaiting the cheque)
    $order->update_status(\Automattic\WooCommerce\Enums\OrderStatus::ON_HOLD, __( 'Awaiting cheque payment', 'woocommerce' ));

    // Remove cart
    $woocommerce->cart->empty_cart();

    // Return thankyou redirect
    return array(
        'result' => 'success',
        'redirect' => $this->get_return_url( $order )
    );

}
```

As you can see, its job is to:

- Get and update the order being processed
- Return success and redirect URL (in this case the thanks page)

Cheque gives the order On-Hold status since the payment cannot be verified automatically. If, however, you are building a direct gateway, then you can complete the order here instead. Rather than using update_status when an order is paid, you should use payment_complete:

```php
$order->payment_complete();
```

This ensures stock reductions are made, and the status is changed to the correct value.

If payment fails, you should throw an error and return an array with the failure status:

```php
wc_add_notice( __('Payment error:', 'woothemes') . $error_message, 'error' );
return array(
    'result'   => 'failure'
);
```

WooCommerce will catch this error and show it on the checkout page.

Stock levels are updated via actions (`woocommerce_payment_complete` and in transitions between order statuses), so it's no longer needed to manually call the methods reducing stock levels while processing the payment.

### Updating Order Status and Adding Notes

Updating the order status can be done using functions in the order class. You should only do this if the order status is not processing (in which case you should use payment_complete()). An example of updating to a custom status would be:

```php
$order = new WC_Order( $order_id );
$order->update_status(\Automattic\WooCommerce\Enums\OrderStatus::ON_HOLD, __('Awaiting cheque payment', 'woothemes'));
```

The above example updates the status to On-Hold and adds a note informing the owner that it is awaiting a Cheque. You can add notes without updating the order status; this is used for adding a debug message:

```php
$order->add_order_note( __('IPN payment completed', 'woothemes') );
```

### Order Status Best Practice

- If the order has completed but the admin needs to manually verify payment, use **On-Hold**
- If the order fails and has already been created, set to **Failed**
- If payment is complete, let WooCommerce handle the status and use `$order->payment_complete()`. WooCommerce will use either **Completed** or **Processing** status and handle stock.

## Notes on Direct Gateways

If you are creating an advanced, direct gateway (i.e., one that takes payment on the actual checkout page), there are additional steps involved. First, you need to set has_fields to true in the gateway constructor:

```php
$this->has_fields = true;
```

This tells the checkout to output a 'payment_box' containing your direct payment form that you define next.

Create a method called `payment_fields()` - this contains your form, most likely to have credit card details.

The next but optional method to add is `validate_fields()`. Return true if the form passes validation or false if it fails. You can use the `wc_add_notice()` function if you want to add an error and display it to the user.

Finally, you need to add payment code inside your `process_payment( $order_id )` method. This takes the posted form data and attempts payment directly via the payment provider.

If payment fails, you should output an error and return the failure array:

```php
wc_add_notice( __('Payment error:', 'woothemes') . $error_message, 'error' );
return array(
    'result'   => 'failure',
);
```

If payment is successful, you should set the order as paid and return the success array:

```php
// Payment complete
$order->payment_complete();
```

```php
// Return thank you page redirect
return array(
    'result' => 'success',
    'redirect' => $this->get_return_url( $order )
);
```

## Working with Payment Gateway Callbacks (such as PayPal IPN)

If you are building a gateway that makes a callback to your store to tell you about the status of an order, you need to add code to handle this inside your gateway.

The best way to add a callback and callback handler is to use WC-API hooks. An example would be as PayPal Standard does. It sets the callback/IPN URL as:

```php
str_replace( 'https:', 'http:', add_query_arg( 'wc-api', 'WC_Gateway_Paypal', home_url( '/' ) ) );
```

Then hooks in its handler to the hook:

```php
add_action( 'woocommerce_api_wc_gateway_paypal', array( $this, 'check_ipn_response' ) );
```

WooCommerce will call your gateway and run the action when the URL is called.

For more information, see [WC_API - The WooCommerce API Callback](https://woocommerce.com/document/wc_api-the-woocommerce-api-callback/).

## Hooks in Gateways

It's important to note that adding hooks inside gateway classes may not trigger. Gateways are only loaded when needed, such as during checkout and on the settings page in admin.

You should keep hooks outside of the class or use WC-API if you need to hook into WordPress events from your class.


---

## WooCommerce payment gateway plugin base

*Source: features/payments/payment-gateway-plugin-base.md*

# WooCommerce payment gateway plugin base

This code can be used as a base to create your own simple custom payment gateway for WooCommerce. If not used in a custom plugin, you need to add this code to your child theme's functions.php file or via a plugin that allows custom functions to be added, such as the [Code snippets](https://wordpress.org/plugins/code-snippets/) plugin. Please don't add custom code directly to your parent theme's functions.php file as this will be wiped entirely when you update the theme.


```php
<?php
/*
Plugin Name: WooCommerce <enter name> Gateway
Plugin URI: https://woothemes.com/woocommerce
Description: Extends WooCommerce with an <enter name> gateway.
Version: 1.0
Author: WooThemes
Author URI: https://woothemes.com/
	Copyright: © 2009-2011 WooThemes.
	License: GNU General Public License v3.0
	License URI: http://www.gnu.org/licenses/gpl-3.0.html
*/
add_action('plugins_loaded', 'woocommerce_gateway_name_init', 0);
function woocommerce_gateway_name_init() {
	if ( !class_exists( 'WC_Payment_Gateway' ) ) return;
	/**
 	 * Localisation
	 */
	load_plugin_textdomain('wc-gateway-name', false, dirname( plugin_basename( __FILE__ ) ) . '/languages');
    
	/**
 	 * Gateway class
 	 */
	class WC_Gateway_Name extends WC_Payment_Gateway {
	
		// Go wild in here
	}
	
	/**
 	* Add the Gateway to WooCommerce
 	**/
	function woocommerce_add_gateway_name_gateway($methods) {
		$methods[] = 'WC_Gateway_Name';
		return $methods;
	}
	
	add_filter('woocommerce_payment_gateways', 'woocommerce_add_gateway_name_gateway' );
}
```


---

## WooCommerce Payment Token API

*Source: features/payments/payment-token-api.md*

# WooCommerce Payment Token API

WooCommerce 2.6 introduced an API for storing and managing payment tokens for gateways. Users can also manage these tokens from their account settings and choose from saved payment tokens on checkout.

This guide offers a few useful tutorials for using the new API as well as all the various methods available to you.

## Tutorials

### Adding Payment Token API Support To Your Gateway

We'll use the Simplify Commerce gateway in some of these examples.

#### Step 0: Extending The Correct Gateway Base

WooCommerce ships with two base classes for gateways. These classes were introduced along with the Token API in 2.6. They  are `WC_Payment_Gateway_CC` (for credit card based tokens) and `WC_Payment_Gateway_eCheck` (for eCheck based tokens). They contain some useful code for generating payment forms on checkout and should hopefully cover most cases.

You can also implement your own gateway base by extending the abstract `WC_Payment_Gateway` class, if neither of those classes work for you.

Since Simplify deals with credit cards, we extend the credit card gateway.

`class WC_Gateway_Simplify_Commerce extends WC_Payment_Gateway_CC`

#### Step 1: 'Supports' Array

We need to tell WooCommerce our gateway supports tokenization. Like other gateways features, this is defined in a gateway's `__construct` in an array called `supports`.

Here is the Simplify array:

```php
$this->supports = array(
    'subscriptions',
    'products',
    ...
    'refunds',
    'pre-orders',
);
```

Add `tokenization` to this array.

#### Step 2: Define A Method For Adding/Saving New Payment Methods From "My Account"

The form handler that is run when adding a new payment method from the "my accounts" section will call your gateway's `add_payment_method` method.

Your `add_payment_method` is expected to return an array with two keys, a `result` string and a `redirect` url:

```php
array(
   'result'   => 'success', // or 'failure'
   'redirect' => wc_get_endpoint_url( 'payment-methods' ),
);
```

After any validation (i.e. making sure the token and data you need is present from the payment provider), you can start building a new token by creating an instance of one of the following classes: `WC_Payment_Token_CC` or `WC_Payment_Token_eCheck`. Like gateways, you can also extend the abstract `WC_Payment_Token` class and define your own token type type if necessary. For more information on all three of these classes and their methods, see further down below in this doc.

Since Simplify uses credit cards, we will use the credit card class.

`$token = new WC_Payment_Token_CC();`

We will use various `set_` methods to pass in information about our token. To start with we will pass the token string and the gateway ID so the token can be associated with Simplify.

```php
$token->set_token( $token_string );
$token->set_gateway_id( $this->id ); // `$this->id` references the gateway ID set in `__construct`
```

At this point we can set any other necessary information we want to store with the token. Credit cards require a card type (visa, mastercard, etc), last four digits of the card number, an expiration month, and an expiration year.

```php
$token->set_card_type( 'visa' );
$token->set_last4( '1234' );
$token->set_expiry_month( '12' );
$token->set_expiry_year( '2018' );
```

In most cases, you will also want to associate a token with a specific user:

`$token->set_user_id( get_current_user_id() );`

Finally, we can save our token to the database once the token object is built.

`$token->save();`

Save will return `true` if the token was successfully saved, and `false` if an error occurred (like a missing field).

#### Step 3: Save Methods On Checkout

WooCommerce also allows customers to save a new payment token during the checkout process in addition to "my account". You'll need to add some code to your gateways `process_payment` function to make this work correctly.

To figure out if you need to save a new payment method you can check the following POST field which should return `true` if the "Save to Account" checkbox was selected.

`wc-{$gateway_id}-new-payment-method`

If you have previously saved tokens being offered to the user, you can also look at `wc-{$gateway_id}-payment-token` for the value `new` to make sure the "Use a new card" / "Use new payment method" radio button was selected.

Once you have found out that a token should be saved you can save a token in the same way you did in Step 2, using the `set_` and `save` methods.

#### Step 4: Retrieve The Token When Processing Payments

You will need to retrieve a saved token when processing a payment in your gateway if a user selects one. This should also be done in your `process_payment` method.

You can check if an existing token should be used with a conditional like the following:

`if ( isset( $_POST['wc-simplify_commerce-payment-token'] ) && 'new' !== $_POST['wc-simplify_commerce-payment-token'] ) {`

`wc-{$gateway_id}}-payment-token` will return the ID of the selected token.

You can then load a token from ta ID (more on the WC_Payment_Tokens class later in this doc):

```php
$token_id = wc_clean( $_POST['wc-simplify_commerce-payment-token'] );
$token    = WC_Payment_Tokens::get( $token_id );
```

This does **not** check if the loaded token belongs to the current user. You can do that with a simple check:

```php
// Token user ID does not match the current user... bail out of payment processing.
if ( $token->get_user_id() !== get_current_user_id() ) {
    // Optionally display a notice with `wc_add_notice`
    return;
}
```

Once you have loaded the token and done any necessary checks, you can get the actual token string (to pass to your payment provider) by using
`$token->get_token()`.

### Creating A New Token Type

You can extend the abstract WC_Payment_Token class and create a new token type If the provided eCheck and CC token types do not satisfy your requirements. There are a few things you need to include if you do this.

#### Step 0: Extend WC_Payment_Token And Name Your Type

Start by extending WC_Payment_Token and providing a name for the new type. We'll look at how the eCheck token class is built since it is the most basic token type shipped in WooCommerce core.

A barebones token file should look like this:

```php
class WC_Payment_Token_eCheck extends WC_Payment_Token {

    /** @protected string Token Type String */
    protected $type = 'eCheck';

}
```

The name for this token type is 'eCheck'. The value provided in `$type` needs to match the class name (i.e: `WC_Payment_Token_$type`).

#### Step 1: Provide A Validate Method

Some basic validation is performed on a token before it is saved to the database. `WC_Payment_Token` checks to make sure the actual token value is set, as well as the `$type` defined above. If you want to validate the existence of other data (eChecks require the last 4 digits for example) or length (an expiry month should be 2 characters), you can provide your own `validate()` method.

Validate should return `true` if everything looks OK, and false if something doesn't.

Always make sure to call `WC_Payment_Token`'s validate method before adding in your own logic.

```php
public function validate() {
    if ( false === parent::validate() ) {
	       return false;
	}
```

Now we can add some logic in for the "last 4" digits.

```php
if ( ! $this->get_last4() ) {
    return false;
}
```

Finally, return true if we make it to the end of the `validate()` method.

```php
    return true;
}
```

#### Step 2: Provide `get_` And `set_` Methods For Extra Data

You can now add your own methods for each piece of data you would like to expose. Handy functions are provided to you to make storing and retrieving data easy. All data is stored in a meta table so you do not need to make your own table or add new fields to an existing one.

Provide a `get_` and `set_` method for each piece of data you want to capture. For eChecks, this is "last4" for the last 4 digits of a check.

```php
public function get_last4() {
    return $this->get_meta( 'last4' );
}

public function set_last4( $last4 ) {
    $this->add_meta_data( 'last4', $last4, true );
}
```

That's it! These meta functions are provided by [WC_Data](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/abstracts/abstract-wc-data.php).

#### Step 3: Use Your New Token Type

You can now use your new token type, either directly when building a new token

```php
`$token = new WC_Payment_Token_eCheck();`
// set token properties
$token->save()
```

or it will be returned when using `WC_Payment_Tokens::get( $token_id )`.

## Classes

### WC_Payment_Tokens

This class provides a set of helpful methods for interacting with payment tokens. All methods are static and can be called without creating an instance of the class.

#### get_customer_tokens( $customer_id, $gateway_id = '' )

Returns an array of token objects for the customer specified in `$customer_id`. You can filter by gateway by providing a gateway ID as well.

```php
// Get all tokens for the current user
$tokens = WC_Payment_Tokens::get_customer_tokens( get_current_user_id() );
// Get all tokens for user 42
$tokens = WC_Payment_Tokens::get_customer_tokens( 42 );
// Get all Simplify tokens for the current user
$tokens = WC_Payment_Tokens::get_customer_tokens( get_current_user_id(), 'simplify_commerce' );
```

#### get_customer_default_token( $customer_id )

Returns a token object for the token that is marked as 'default' (the token that will be automatically selected on checkout). If a user does not have a default token/has no tokens, this function will return null.

```php
// Get default token for the current user
$token = WC_Payment_Tokens::get_customer_default_token( get_current_user_id() );
// Get default token for user 520
$token = WC_Payment_Tokens::get_customer_default_token( 520 );
```

#### get_order_tokens( $order_id )

Orders can have payment tokens associated with them (useful for subscription products and renewing, for example). You can get a list of tokens associated with this function. Alternatively you can use `WC_Order`'s '`get_payment_tokens()` function to get the same result.

```php
// Get tokens associated with order 25
$tokens = WC_Payment_Tokens::get_order_tokens( 25 );
// Get tokens associated with order 25, via WC_Order
$order = wc_get_order( 25 );
$tokens =  $order->get_payment_tokens();
```

#### get( $token_id )

Returns a single payment token object for the provided `$token_id`.

```php
// Get payment token 52
$token = WC_Payment_Tokens::get( 52 );
```

#### delete( $token_id )

Deletes the provided token.

```php
// Delete payment token 52
WC_Payment_Tokens::delete( 52 );
```

#### set_users_default( $user_id, $token_id )

Makes the provided token (`$token_id`) the provided user (`$user_id`)'s default token. It makes sure that whatever token is currently set is default is removed and sets the new one.

```php
// Set user 17's default token to token 82
WC_Payment_Tokens::set_users_default( 17, 82 );
```

#### get_token_type_by_id( $token_id )

You can use this function If you have a token's ID but you don't know what type of token it is (credit card, eCheck, ...).

```php
// Find out that payment token 23 is a cc/credit card token
$type = WC_Payment_Tokens::get_token_type_by_id( 23 );
```

### WC_Payment_Token_CC

`set_` methods **do not** update the token in the database. You must call `save()`, `create()` (new tokens only), or `update()` (existing tokens only).

#### validate()

Makes sure the credit card token has the last 4 digits stored, an expiration year in the format YYYY, an expiration month with the format MM, the card type, and the actual token.

```php
$token = new WC_Payment_Token_CC();
$token->set_token( 'token here' );
$token->set_last4( '4124' );
$token->set_expiry_year( '2017' );
$token->set_expiry_month( '1' ); // incorrect length
$token->set_card_type( 'visa' );
var_dump( $token->validate() ); // bool(false)
$token->set_expiry_month( '01' );
var_dump( $token->validate() ); // bool(true)
```

#### get_card_type()

Get the card type (visa, mastercard, etc).

```php
$token = WC_Payment_Tokens::get( 42 );
echo $token->get_card_type();
```

#### set_card_type( $type )

Set the credit card type. This is a freeform text field, but the following values can be used and WooCommerce will show a formatted label New labels can be added with the `woocommerce_credit_card_type_labels` filter.

```php
$token = WC_Payment_Tokens::get( 42 );
$token->set_last4( 'visa' );
echo $token->get_card_type(); // returns visa
```

Supported types/labels:

```php
array(
	'mastercard'       => __( 'Mastercard', 'woocommerce' ),
	'visa'             => __( 'Visa', 'woocommerce' ),
	'discover'         => __( 'Discover', 'woocommerce' ),
	'american express' => __( 'American Express', 'woocommerce' ),
	'diners'           => __( 'Diners', 'woocommerce' ),
	'jcb'              => __( 'JCB', 'woocommerce' ),
) );
```

#### get_expiry_year()

Get the card's expiration year.

```php
$token = WC_Payment_Tokens::get( 42 );
echo $token->get_expiry_year;
```

#### set_expiry_year( $year )

Set the card's expiration year. YYYY format.

```php
$token = WC_Payment_Tokens::get( 42 );
$token->set_expiry_year( '2018' );
echo $token->get_expiry_year(); // returns 2018
```

#### get_expiry_month()

Get the card's expiration month.

```php
$token = WC_Payment_Tokens::get( 42 );
echo $token->get_expiry_month();
```

#### set_expiry_month( $month )

Set the card's expiration month. MM format.

```php
$token = WC_Payment_Tokens::get( 42 );
$token->set_expiry_year( '12' );
echo $token->get_expiry_month(); // returns 12
```

#### get_last4()

Get the last 4 digits of the stored credit card number.

```php
$token = WC_Payment_Tokens::get( 42 );
echo $token->get_last4();
```

#### set_last4( $last4 )

Set the last 4 digits of the stored credit card number.

```php
$token = WC_Payment_Tokens::get( 42 );
$token->set_last4( '2929' );
echo $token->get_last4(); // returns 2929
```

### WC_Payment_Token_eCheck

`set_` methods **do not** update the token in the database. You must call `save()`, `create()` (new tokens only), or `update()` (existing tokens only).

#### validate()

Makes sure the eCheck token has the last 4 digits stored as well as the actual token.

```php
$token = new WC_Payment_Token_eCheck();
$token->set_token( 'token here' );
var_dump( $token->validate() ); // bool(false)
$token->set_last4( '4123' );
var_dump( $token->validate() ); // bool(true)
```

#### get_last4()

Get the last 4 digits of the stored account number.

```php
$token = WC_Payment_Tokens::get( 42 );
echo $token->get_last4();
```

#### set_last4( $last4 )

Set the last 4 digits of the stored credit card number.

```php
$token = WC_Payment_Tokens::get( 42 );
$token->set_last4( '2929' );
echo $token->get_last4(); // returns 2929
```

### WC_Payment_Token

You should not use `WC_Payment_Token` directly. Use one of the bundled token classes (`WC_Payment_Token_CC` for credit cards and `WC_Payment_Token_eCheck`). You can extend this class if neither of those work for you. All the methods defined in this section are available to those classes.

`set_` methods **do not** update the token in the database. You must call `save()`, `create()` (new tokens only), or `update()` (existing tokens only).

#### get_id()

Get the token's ID.

```php
// Get the token ID for user ID 26's default token
$token = WC_Payment_Tokens::get_customer_default_token( 26 );
echo $token->get_id();
```

#### get_token()

Get the actual token string (used to communicate with payment processors).

```php
$token = WC_Payment_Tokens::get( 49 );
echo $token->get_token();
```

#### set_token( $token )

Set the token string.

```php
// $api_token comes from an API request to a payment processor.
$token = WC_Payment_Tokens::get( 42 );
$token->set_token( $api_token );
echo $token->get_token(); // returns our token
```

#### get_type()

Get the type of token. CC or eCheck. This will also return any new types introduced.

```php
$token = WC_Payment_Tokens::get( 49 );
echo $token->get_type();
```

#### get_user_id()

Get the user ID associated with the token.

```php
$token = WC_Payment_Tokens::get( 49 );
if ( $token->get_user_id() === get_current_user_id() ) {
    // This token belongs to the current user.
}
```

#### set_user_id( $user_id )

Associate a token with a user.

```php
$token = WC_Payment_Tokens::get( 42 );
$token->set_user_id( '21' ); // This token now belongs to user 21.
echo $token->get_last4(); // returns 2929
```

#### get_gateway_id

Get the gateway associated with the token.

```php
$token = WC_Payment_Tokens::get( 49 );
$token->get_gateway_id();
```

#### set_gateway_id( $gateway_id )

Set the gateway associated with the token. This should match the "ID" defined in your gateway. For example, 'simplify_commerce' is the ID for core's implementation of Simplify.

```php
$token->set_gateway_id( 'simplify_commerce' );
echo $token->get_gateway_id();
```

#### is_default()

Returns true if the token is marked as a user's default. Default tokens are auto-selected on checkout.

```php
$token = WC_Payment_Tokens::get( 42 ); // Token 42 is a default token for user 3
var_dump( $token->is_default() ); // returns true
$token = WC_Payment_Tokens::get( 43 ); // Token 43 is user 3's token, but not default
var_dump( $token->is_default() ); // returns false
```

#### set_default( $is_default )

Toggle a tokens 'default' flag. Pass true to set it as default, false if its just another token. This **does not** unset any other tokens that may be set as default. You can use `WC_Payment_Tokens::set_users_default()` to handle that instead.

```php
$token = WC_Payment_Tokens::get( 42 ); // Token 42 is a default token for user 3
var_dump( $token->is_default() ); // returns true
$token->set_default( false );
var_dump( $token->is_default() ); // returns false
```

#### validate()

Does a check to make sure both the token and token type (CC, eCheck, ...) are present. See `WC_Payment_Token_CC::validate()` or `WC_Payment_Token_eCheck::validate()` for usage.

#### read( $token_id )

Load an existing token object from the database. See `WC_Payment_Tokens::get()` which is an alias of this function.

```php
// Load a credit card toke, ID 55, user ID 5
$token = WC_Payment_Token_CC();
$token->read( 55 );
echo $token->get_id(); // returns 55
echo $token->get_user_id(); // returns 5
```

#### update()

Update an existing token. This will take any changed fields (`set_` functions) and actually save them to the database. Returns true or false depending on success.

```php
$token = WC_Payment_Tokens::get( 42 ); // credit card token
$token->set_expiry_year( '2020' );
$token->set_expiry_month( '06 ');
$token->update();
```

#### create()

This will create a new token in the database. So once you build it, create() will create a new token in the database with the details. Returns true or false depending on success.

```php
$token = new WC_Payment_Token_CC();
// set last4, expiry year, month, and card type
$token->create(); // save to database
```

#### save()

`save()` can be used in place of `update()` and `create()`. If you are working with an existing token, `save()` will call `update()`. A new token will call `create()`. Returns true or false depending on success.

```php
// calls update
$token = WC_Payment_Tokens::get( 42 ); // credit card token
$token->set_expiry_year( '2020' );
$token->set_expiry_month( '06 ');
$token->save();
// calls create
$token = new WC_Payment_Token_CC();
// set last4, expiry year, month, and card type
$token->save();
```

#### delete()

Deletes a token from the database.

```php
$token = WC_Payment_Tokens::get( 42 );
$token->delete();
```


---

## Payments Guidelines

*Source: features/payments/ux-guidelines/README.md*

# Payments Guidelines

When building payments extensions, you should ensure you follow the [WooCommerce Extension Guidelines](https://developer.woocommerce.com/docs/extensions/ux-guidelines-extensions/).

Payments plugins come in many types: payment processors and gateways, wallets, Buy Now Pay Later, crypto, and more.

The choice between payment plugins depends on the specific needs and preferences of the merchant and their customers. Some merchants may choose to use multiple types of payment plugins to offer their customers a wider range of payment options.

A merchant can discover a payments plugin in the following ways:

- Through direct installation from WordPress plugins.
- Through Woo's public list of payment services on the Marketplace.
- Through the admin onboarding tasks and payments settings. To be added to the list of payment gateways in the Woo admin, the payments plugin must meet the criteria listed in these guidelines.



---

## Payment Button Layout

*Source: features/payments/ux-guidelines/payment-button-layout.md*

# Payment Button Layout

Define the position and alignment of buttons in relationship to their container, with equal hierarchy and consistent spacing between buttons.

## Product pages

Position payment buttons correctly in relation to "Add to Cart" in horizontal or vertical layout, place payment buttons to the right of or below the "Add to Cart" button.

![Product page layout.png](/img/doc_images/Product-page-layout.png)

## Cart

Position payment buttons correctly in relation to "Proceed to checkout" buttons in vertical layout. Place payment buttons above the "Proceed to checkout" button. Do not place payment buttons below the button or in between.

![Cart layout.png](/img/doc_images/Cart-layout.png)

## Express checkout

Position payment buttons correctly in horizontal layout, consistent in size and spacing. If a second row is required, left-align the buttons.

![Express checkout layout.png](/img/doc_images/Express-checkout-layout.png)

## Mobile view

Express payment buttons on mobile should occupy the full width. Don't use the express payment border as it reduces the view area.

![Mobile view.png](/img/doc_images/Mobile-view.png)

## Clear space

Maintain the minimum amount of clear space on all sides of the payment button. The clear space adapts based on the size of the button.

![Clear space.png](/img/doc_images/Clear-space-updated.png)


---

## Payment Button Size and Anatomy

*Source: features/payments/ux-guidelines/payment-button-size.md*

# Payment Button Size and Anatomy

Payment buttons must be consistent in visual appearance to other buttons in the shopper experience.

Height for payment buttons ranges from 40px (Small) to 55px (Large). The default button height is 48px. The following presets can be used for button height.

- Small: Height 40px
- Default: Height 48px
- Large: Height 55px

## Anatomy

Payment buttons consist of up to three elements: a button component, payment logo, and optional label.

![Anatomy of a payment button](/img/doc_images/Anatomy-updated.png)

Don't place any text outside the surface area of the button.

![Cart layout 2](/img/doc_images/Cart-layout-2.png)

## Layout and spacing

The spacing between and around the Label and Payment Logo adapts based on the size of the button.

![Layout and spacing 0.png](/img/doc_images/Layout-and-spacing-Updated.png)

## Adaptive height

The height of the button can adapt based on the needs of the theme.

![Layout and spacing](/img/doc_images/Layout-and-spacing-1-updated.png)

## Button size

Make payment buttons the same size, no bigger or smaller than other payment buttons, including the CTAs "Add to cart" and "Proceed to checkout".

![Same button size.png](/img/doc_images/Button-size.png)

## Button width

Use the same width size for all payment buttons. Don't make the width larger or smaller than other payment buttons.

![button width.png](/img/doc_images/Button-width.png)

## Minimum width

Buttons have a minimum width to ensure readability.

![Layout and spacing-2.png](/img/doc_images/Layout-and-spacing-2-Updated.png)

Follow the minimum width of each payment button size. Don't squeeze payment buttons in a single line.

![Minimum width.png](/img/doc_images/Minimum-width.png)

## Button Shape

Use the same corner radius for all payment buttons. Don't make the corner radius larger or smaller than other payment buttons.

- Default corner radius: 4px
- Maximum corner radius: half of the button height

![Corner radius.png](/img/doc_images/Corner-radius.png)

## Button Label

Provide variant buttons to accommodate merchant needs and payment experiences. 

- Buy
- Pay
- Donate
- Book
- Checkout
- Subscribe
- Continue
- Order
- Icon only

The button label should appear in sentence case, with only the first letter of the first word capitalized.

![Button labels.png](/img/doc_images/Button-Labels.png)


---

## Payment Button Style

*Source: features/payments/ux-guidelines/payment-button-style.md*

# Payment Button Style

Use the appropriate button style depending on the site theme.

![Button styles.png](/img/doc_images/Button-styles.png)

## Dark

Use on white or light-color backgrounds. Don't use on black or dark backgrounds.

![Dark.png](/img/doc_images/Dark.png)

## Light

Use on dark-color backgrounds. Don't use on white or light backgrounds.

![Light.png](/img/doc_images/Light.png)

## Light with outline

Use on white or light-color backgrounds that don't provide sufficient contrast. Don't use on dark or saturated backgrounds.

![Light with outline.png](/img/doc_images/Light-with-outline.png)

## Button style and specifications

Buttons should contain the following states for resting, loading, active, and loading contexts. For additional guidance, follow the general Woo accessibility guidelines.

![Button States and specifications](/img/doc_images/Button-States-and-specifications.png)


---

## Payments Onboarding and Setup

*Source: features/payments/ux-guidelines/payments-onboarding.md*

# Payments Onboarding and Setup

## Payments onboarding

Plugin authors should actively guide merchants through setup of the plugin once installed and activated.

### Third party onboarding

For plugins that use OAuth or a third party experience to obtain permission from the merchant, the merchant clicks on a link to set up your plugin, which redirects to the plugin onboarding.

The merchant is redirected to the payments plugin to complete configuration and completes any required authentication as part of this step.

For example:

- Prompt the merchant to login to or create an account with the payment provider.
- Ask the merchant to complete configuration for billing plans, payouts, or notifications.

### Manual setup

If manual entry of API keys is required, design the setup process to be as simple as possible, ideally with a guided setup wizard.

## Configuration & Settings

Follow the Woo User Experience guidelines for [Settings](/docs/extensions/ux-guidelines-extensions/settings) and [Navigation](/docs/extensions/ux-guidelines-extensions/navigation).

Include sensible default settings to minimize the configuration effort for the user.

After the merchant has completed all the actions that are required for your plugin's onboarding, merchants are redirected back to the Woo admin to select payment methods to offer and configure additional settings for the plugin.

If you're offering multiple payment methods within the plugin, present the choices clearly to the merchant and provide an indication of which payment methods are enabled.

![Payment methods](/img/doc_images/Payment-methods.png)

If a payment method is not available for any reason, provide clear and informative error messages that help users diagnose and resolve issues.

Your plugin needs to inform the merchant that it's ready to process payments. Until then, display an inline warning notice in the plugin settings as a reminder to the merchant. Do not implement a top level banner for the warning notice.

![Inline notice](/img/doc_images/Inline-Notice.png)


---

## How to add a custom field to simple and variable products

*Source: features/products/adding-a-custom-field-to-variable-products.md*

# How to add a custom field to simple and variable products

In this tutorial you will learn how to create a custom field for a product and show it in your store. Together we will set up the skeleton plugin, and learn about WP naming conventions and WooCommerce hooks. In the end, you will have a functioning plugin for adding a custom field.

The [full plugin code](https://github.com/EdithAllison/woo-product-custom-fields) was written based on WordPress 6.2 and WooCommerce 7.6.0

## Prerequisites

To do this tutorial you will need to have a WordPress install with the WooCommerce plugin activated, and you will need at least one [simple product set up](https://woocommerce.com/document/managing-products/), or you can [import the WooCommerce sample product range](https://woocommerce.com/document/importing-woocommerce-sample-data/).

## Setting up the plugin

To get started, let's do the steps to [create a skeleton plugin](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/create-woo-extension).

First, navigate to your wp-content/plugins folder, then run:

```sh
npx @wordpress/create-block -t @woocommerce/create-woo-extension woo-product-fields
```

Then we navigate to our new folder and run the install and build:

```sh
cd woo-product-fields
npm install # Install dependencies
npm run build # Build the javascript
```

WordPress has its own class file naming convention which doesn't work with PSR-4 out of the box. To learn more about Naming Conventions see the [WP Handbook](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#naming-conventions). We will use the standard format of "class-my-classname.php" format, so let's go to the composer.json file and change the autoload to:

```json
"autoload": {
   	 "classmap": ["includes/", "includes/admin/"]
    },
```

After saving run dump-autoload to generate the class map by running in the Terminal:

```sh
composer dump-autoload -o
```

This generates a new vendor/composer/autoload_classmap.php file containing a list of all our classes in the /includes/ and /includes/admin/ folder. We will need to repeat this command when we add, delete or move class files.

## WooCommerce hooks

Our aim is to create a new custom text field for WooCommerce products to save new stock information for display in the store. To do this, we need to modify the section of the Woo data in the admin area which holds the stock info.

WooCommerce allows us to add our code to these sections through [hooks](https://developer.wordpress.org/plugins/hooks/), which are a standard WordPress method to extend code. In the "Inventory" section we have the following action hooks available to us:

For our Woo extension, we'll be appending our field right at the end with `woocommerce_product_options_inventory_product_data`.

## Creating our class

Let's get started with creating a new class which will hold the code for the field. Add a new file with the name `class-product-fields.php` to the `/includes/admin/` folder. Within the class, we add our namespace, an abort if anyone tries to call the file directly and a `__construct` method which calls the `hooks()` method:

```php
<?php

namespace WooProductField\Admin;

defined( 'ABSPATH' ) || exit;

class ProductFields {

    public function __construct() {
		$this->hooks();
    }

    private function hooks() {}
}
```

Then in Terminal we run `composer dump-autoload -o` to regenerate the class map. Once that's done, we add the class to our `setup.php` `__construct()` function like so:

```php
class Setup {
    public function __construct() {
		add_action( 'admin_enqueue_scripts', array( $this, 'register_scripts' ) );

		new ProductFields();
    }
}
```

## Adding the custom field

With the class set up and being called, we can create a function to add the custom field. WooCommerce has its own `woocommerce_wp_text_input( $args )` function which we can use here. `$args` is an array which allows us to set the text input data, and we will be using the global $product_object to access stored metadata.

```php
public function add_field() {
	global $product_object;
	?>
	<div class="inventory_new_stock_information options_group show_if_simple show_if_variable">
		<?php woocommerce_wp_text_input(
			array(
				'id'      	=> '_new_stock_information',
				'label'   	=> __( 'New Stock', 'woo_product_field' ),
				'description' => __( 'Information shown in store', 'woo_product_field' ),
				'desc_tip'	=> true,
				'value' => $product_object->get_meta( '_new_stock_information' )
			)
		); ?>
	</div>
	<?php
}
```

Let's take a look at the arguments in the array. The ID will be used as meta_key in the database. The Label and Description are shown in the data section, and by setting desc_tip to true, it will be shown as a hover over the info icon. The last argument value ensures that if a value is already stored, then it will be shown.

For the div class, the class names `show_if_simple` and `show_if_variable` will control when our section is shown. This is linked to JS code which dynamically hides/reveals sections. If for example, we wanted to hide the section from variable products, then we can simply delete `show_if_variable`.

Now that we have our field, we need to save it. For this, we can hook into woocommerce_process_product_meta which takes two arguments, `$post_id` and `$post`:

```php
public function save_field( $post_id, $post ) {
	if ( isset( $_POST['_new_stock_information'] ) ) {
		$product = wc_get_product( intval( $post_id ) );
		$product->update_meta_data( '_new_stock_information', sanitize_text_field( $_POST['_new_stock_information'] ) );
		$product->save_meta_data();
	}
}
```

This function checks if our new field is in the POST array. If yes, we create the product object, update our metadata and save the metadata. The `update_meta_data` function will either update an existing meta field or add a new one. And as we're inserting into the database, we must [sanitize our field value](https://developer.wordpress.org/apis/security/sanitizing/).

And to make it all work, we add the hooks:

```php
private function hooks() {
	add_action( 'woocommerce_product_options_inventory_product_data', array( $this, 'add_field' ) );
	add_action( 'woocommerce_process_product_meta', array( $this, 'save_field' ), 10, 2 );
}
```

Now if we refresh our product screen, we can see our new field.

If we add data and save the product, then the new meta data is inserted into the database.

At this point you have a working extension that saves a custom field for a product as product meta.
Showing the field in the store
If we want to display the new field in our store, then we can do this with the `get_meta()` method of the Woo product class: `$product->get_meta( '_new_stock_information' )`

Let's get started by creating a new file /includes/class-product.php. You may have noticed that this is outside the `/admin/` folder as this code will run in the front. So when we set up the class, we also adjust the namespace accordingly:

```php
<?php

namespace WooProductField;

defined( 'ABSPATH' ) || exit;

class Product {
    public function __construct() {
		$this->hooks();
    }

    private function hooks() { }
}
```

Again we run `composer dump-autoload -o` to update our class map.

If you took a look at the extension setup you may have noticed that `/admin/setup.php` is only called if we're within WP Admin. So to call our new class we'll add it directly in `/woo-product-field.php`:

```php
public function __construct() {
	if ( is_admin() ) {
		new Setup();
	}
	new WooProductField\Product();
}
```

For adding the field to the front we have several options. We could create a theme template, but if we are working with a WooCommerce-compatible theme and don't need to make any other changes then a quick way is to use hooks. If we look into `/woocommerce/includes/wc-template-hooks.php` we can see all the existing actions for `woocommerce_single_product_summary` which controls the section at the top of the product page:

For our extension, let's add the new stock information after the excerpt by using 21 as the priority:

```php
private function hooks() {
	add_action( 'woocommerce_single_product_summary', array( $this, 'add_stock_info' ), 21 );
}
```

In our function we output the stock information with the [appropriate escape function](https://developer.wordpress.org/apis/security/escaping/), in this case, I'm suggesting to use `esc_html()` to force plain text.

```php
public function add_stock_info() {
	global $product;
	?>
	<p><?php echo esc_html( $product->get_meta( '_new_stock_information' ) ); ?> </p>
	<?php

    }
```

Now if we refresh the product page our stock information will be shown just below the excerpt:

Fantastic! You have completed this tutorial and have a working WooCommerce extension that adds a new custom field and shows it in the store! 🎉I hope it's shown you how easily you can extend WooCommerce through hooks and tailor it to your or your client's shop requirements!

Below is a bonus task if you are interested in variable products. Feel free to come back to this later.

## How to handle variable products?

The above example was done with a simple product. But what if we have variations, for example, a T-Shirt in multiple sizes and we wanted to store different stock information for each variant? WooCommerce lets us do that with the [variable product type](https://woocommerce.com/document/variable-product/).

A variable product type has variations as its children. To add a custom field to a variation, we can use the `woocommerce_variation_options_inventory` hook, and to save `woocommerce_save_product_variation` so let's update our `hooks()` method with the new action hooks like so:

```php
private function hooks() {
	add_action( 'woocommerce_product_options_inventory_product_data', array( $this, 'add_field' ) );
	add_action( 'woocommerce_process_product_meta', array( $this, 'save_field' ), 10, 2 );

	add_action( 'woocommerce_variation_options_inventory', array( $this, 'add_variation_field' ), 10, 3 );
	add_action( 'woocommerce_save_product_variation', array( $this, 'save_variation_field' ), 10, 2 );
}
```

The setup is very similar to simple products, the main difference is that we need to use the $loop id which distinguishes between the variations, and we will be using the `wrapper_class` to show it as a full width text input:

```php
public function add_variation_field( $loop, $variation_data, $variation ) {
	$variation_product = wc_get_product( $variation->ID );

	woocommerce_wp_text_input(
		array(
			'id' => '_new_stock_information' . '[' . $loop . ']',
			'label' => __( 'New Stock Information', 'woo_product_field' ),
			'wrapper_class' => 'form-row form-row-full',
			'value' => $variation_product->get_meta( '_new_stock_information' )
		)
	);
}
```

For saving we use:

```php
public function save_variation_field( $variation_id, $i  ) {
	if ( isset( $_POST['_new_stock_information'][$i] ) ) {
		$variation_product = wc_get_product( $variation_id );
		$variation_product->update_meta_data( '_new_stock_information', sanitize_text_field( $_POST['_new_stock_information'][$i] ) );
		$variation_product->save_meta_data();
	}
}
```

And we now have a new variation field that stores our new stock information. If you cannot see the new field, please make sure to enable "Manage Stock" for the variation by ticking the checkbox in the variation details.

Displaying the variation in the front store works a bit differently for variable products as only some content on the page is updated when the customer makes a selection. This exceeds the scope of this tutorial, but if you are interested have a look at `/woocommerce/assets/js/frontend/add-to-cart-variation.js` to see how WooCommerce does it.

## How to find hooks?

Everyone will have their own preferred way, but for me, the quickest way is to look in the WooCommerce plugin code. The code for each data section can be found in `/woocommerce/includes/admin/meta-boxes/views`. To view how the inventory section is handled check the `html-product-data-inventory.php` file, and for variations take a look at `html-variation-admin.php`.


---

## `wc_get_products` and product queries

*Source: features/products/wc-get-products.md*

# `wc_get_products` and product queries

`wc_get_products` and `WC_Product_Query` provide a standard way of retrieving products that is safe to use and will not break due to database changes in future WooCommerce versions. Building custom WP_Queries or database queries is likely to break your code in future versions of WooCommerce as data moves towards custom tables for better performance. This is the best-practices way for plugin and theme developers to retrieve multiple products. `wc_get_products` and `WC_Product_Query` are similar to WordPress [`get_posts` and `WP_Query`](https://developer.wordpress.org/reference/classes/wp_query/). Just like those, you pass in an array of arguments defining the criteria for the search.

## Basic usage

### Examples

Here are a few examples:

```php
// Get downloadable products created in the year 2016.
$products = wc_get_products( array(
    'downloadable' => true,
    'date_created' => '2016-01-01...2016-12-31',
) );
```

```php
// Get 10 most recent product IDs in date descending order.
$query = new WC_Product_Query( array(
    'limit' => 10,
    'orderby' => 'date',
    'order' => 'DESC',
    'return' => 'ids',
) );
$products = $query->get_products();
```

```php
// Get products containing a specific SKU.
// Does partial matching, so this will get products with SKUs "PRDCT-1", "PRDCT-2", etc.
$query = new WC_Product_Query();
$query->set( 'sku', 'PRDCT' );
$products = $query->get_products();
```

Note that `wc_get_products()` is mostly a shortcut to `WC_Product_Query::get_products()`.

## API reference

| Method | Description |
| ------ | ----------- |
| `wc_get_products( $args )` | Retrieve products matching query `$args`. |
| `WC_Product_Query::get_query_vars()` | Get an array of all of the current query variables set on the query object. |
| `WC_Product_Query::get( string $key, mixed $default = '' )` | Get the value of a query variable or the default if the query variable is not set. |
| `WC_Product_Query::set( string $key, mixed $value )` | Set a query variable to a value. |
| `WC_Product_Query::get_products()` | Get all products matching the current query variables. |

Query parameters/arguments that can be used with these functions are described below.

## Query parameters reference

### General

| Parameter | Description |
| --------- | ----------- |
| **status** | Accepts a string or array of strings: one or more of `'draft'`, `'pending'`, `'private'`, `'publish'`, or a custom status. See [ProductStatus constant class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Enums/ProductStatus.php). |
| **type** | Accepts a string or array of strings: one or more of `'external'`, `'grouped'`, `'simple'`, `'variable'`, or a custom type. See [ProductType constant class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Enums/ProductType.php). |
| **include** | Accepts an array of integers: only includes products with IDs in the array. |
| **exclude** | Accepts an array of integers: excludes products with IDs in the array. |
| **parent** | Accepts an integer: post ID of the product parent. |
| **parent_exclude** | Accepts an array of integers: excludes products with parent IDs in the array. |
| **order** | Accepts a string: `'DESC'` or `'ASC'`. Use with `'orderby'`. Default: `'DESC'`. |
| **orderby** | Accepts a string: `'none'`, `'ID'`, `'name'`, `'type'`, `'rand'`, `'date'`, `'modified'`. Default: `'date'`. |
| **return** | Return type. Accepts a string: `'ids'` or `'objects'`. Default: `'objects'`. |

#### Examples

```php
// Get draft products.
$products = wc_get_products( array( 'status' => 'draft' ) );
```

```php
// Using constant class for status.
$products = wc_get_products( array( 'status' => \Automattic\WooCommerce\Enums\ProductStatus::DRAFT ) );
```

```php
// Get external products.
$products = wc_get_products( array( 'type' => 'external' ) );
```

```php
// Using constant class for type.
$products = wc_get_products( array( 'type' => \Automattic\WooCommerce\Enums\ProductType::EXTERNAL ) );
```

```php
// Get external products limited to specific IDs.
$args = array(
    'type' => 'external',
    'include' => array( 134, 200, 210, 340 ),
);
$products = wc_get_products( $args );
```

```php
// Get products that aren't the current product.
$products = wc_get_products( array( 'exclude' => array( $product->get_id() ) ) );
```

```php
// Get products with a specific parent.
$products = wc_get_products( array( 'parent' => 20 ) );
```

```php
// Get most recently modified products.
$args = array(
    'orderby' => 'modified',
    'order' => 'DESC',
);
$products = wc_get_products( $args );
```

```php
// Get some random products.
$products = wc_get_products( array( 'orderby' => 'rand' ) );
```

```php
// Return only product IDs.
$products = wc_get_products( array( 'return' => 'ids' ) );
```

## Product archive URL query parameters

The query parameters in this reference are PHP arguments for `wc_get_products()` and `WC_Product_Query`. Storefront product archives, including the shop page and product category pages, can also read query parameters from the URL to build the main catalog query. For example, the `orderby` URL query parameter changes the catalog sort order.

To link visitors to a catalog view that lists products with prices before products without prices, sort the archive by price from high to low:

```text
https://example.com/shop/?orderby=price-desc
https://example.com/product-category/clothing/?orderby=price-desc
```

The `price-desc` value maps to the "Price: high to low" catalog sort. Products with no price or a zero price are sorted after products with a higher price. Use `orderby=price` for the "Price: low to high" catalog sort.

### Pagination

| Parameter | Description |
| --------- | ----------- |
| **limit** | Accepts an integer: maximum number of results to retrieve or `-1` for unlimited. Default: site `posts_per_page` setting. |
| **page** | Accepts an integer: page of results to retrieve. Does nothing if `'offset'` is used. |
| **offset** | Accepts an integer: amount to offset product results. |
| **paginate** | Accepts a boolean: true for pagination, or false for not. Default: `false`. If enabled, modifies the return results to give an object with fields: `products` (array of found products), `total` (number of found products), and `max_num_pages` (total number of pages). |

#### Examples

```php
// Get latest 3 products.
$products = wc_get_products( array( 'limit' => 3 ) );
```

```php
// First 3 products.
$args = array(
    'limit' => 3,
    'page'  => 1,
);
$page_1_products = wc_get_products( $args );

// Second 3 products.
$args = array(
    'limit' => 3,
    'page'  => 2,
);
$page_2_products = wc_get_products( $args );
```

```php
// Get products with extra info about the results.
$results = wc_get_products( array( 'paginate' => true ) );
echo $results->total . " products found\n";
echo 'Page 1 of ' . $results->max_num_pages . "\n";
if ( count( $results->products ) > 0 ) {
    echo 'First product id is: ' . $results->products[0]->get_id() . "\n";
}
```

```php
// Get second to fifth most-recent products.
$args = array(
    'limit' => 4,
    'offset' => 1,
);
$products = wc_get_products( $args );
```

### Product lookup

| Parameter | Description |
| --------- | ----------- |
| **sku** | Accepts a string: product SKU to match on. Does partial matching on the SKU. |
| **name** | Accepts a string: the product name (title) to match on. Case sensitivity depends on the collation of the WordPress posts table. |
| **tag** | Accepts an array: limit results to products assigned to specific tags by slug. |
| **product_tag_id** | Accepts an integer or array of integers: limit results to products assigned to specific tags by ID. |
| **category** | Accepts an array: limit results to products assigned to specific categories by slug. |
| **product_category_id** | Accepts an integer or array of integers: limit results to products assigned to specific categories by ID. |

#### Examples

```php
// Get products with "PRDCT" in their SKU (e.g. PRDCT-1 and PRDCT-2).
$products = wc_get_products( array( 'sku' => 'PRDCT' ) );
```

```php
// Get a product named "Test Product".
$products = wc_get_products( array( 'name' => 'Test Product' ) );
```

```php
// Get products with the "Excellent" or "Modern" tags.
$products = wc_get_products( array( 'tag' => array( 'excellent', 'modern' ) ) );
```

```php
// Get products by tag IDs.
$products = wc_get_products( array( 'product_tag_id' => array( 17, 23 ) ) );
```

```php
// Get shirts.
$products = wc_get_products( array( 'category' => array( 'shirts' ) ) );
```

```php
// Get products by category IDs.
$products = wc_get_products( array( 'product_category_id' => array( 17, 23 ) ) );
```

### Dimensions & pricing

| Parameter | Description |
| --------- | ----------- |
| **weight** | Accepts a float: the weight measurement to match on. |
| **length** | Accepts a float: the length measurement to match on. |
| **width** | Accepts a float: the width measurement to match on. |
| **height** | Accepts a float: the height measurement to match on. |
| **price** | Accepts a float: the current price to match on. |
| **regular_price** | Accepts a float: the regular price to match on. |
| **sale_price** | Accepts a float: the sale price to match on. |
| **total_sales** | Accepts an integer: gets products with that many sales. |

#### Examples

```php
// Get products 5.5 units wide and 10 units long.
$args = array(
    'width' => 5.5,
    'length' => 10,
);
$products = wc_get_products( $args );
```

```php
// Get products that currently cost 9.99.
$products = wc_get_products( array( 'price' => 9.99 ) );
```

```php
// Get products that have never been purchased.
$products = wc_get_products( array( 'total_sales' => 0 ) );
```

### Product settings

| Parameter | Description |
| --------- | ----------- |
| **virtual** | Accepts a boolean: limit to virtual products. |
| **downloadable** | Accepts a boolean: limit to downloadable products. |
| **featured** | Accepts a boolean: limit to featured products. |
| **sold_individually** | Accepts a boolean: limit to products sold individually. |
| **manage_stock** | Accepts a boolean: limit to products with stock management enabled. |
| **reviews_allowed** | Accepts a boolean: limit to products that allow reviews. |
| **backorders** | Accepts a string: `'yes'`, `'no'`, or `'notify'`. |
| **visibility** | Accepts a string: `'visible'`, `'catalog'`, `'search'`, or `'hidden'`. See [CatalogVisibility constant class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Enums/CatalogVisibility.php). |
| **download_limit** | Accepts an integer: the download limit or `-1` for unlimited. |
| **download_expiry** | Accepts an integer: the download expiry (days) or `-1` for unlimited. |

#### Examples

```php
// Get downloadable products that don't allow reviews.
$args = array(
    'downloadable' => true,
    'reviews_allowed' => false,
);
$products = wc_get_products( $args );
```

```php
// Get products that allow backorders.
$products = wc_get_products( array( 'backorders' => 'yes' ) );
```

```php
// Get products that show in the catalog.
$products = wc_get_products( array( 'visibility' => 'catalog' ) );
```

```php
// Using constant class for visibility.
$products = wc_get_products( array( 'visibility' => \Automattic\WooCommerce\Enums\CatalogVisibility::CATALOG ) );
```

```php
// Get products with unlimited downloads.
$products = wc_get_products( array( 'download_limit' => -1 ) );
```

### Stock & inventory

| Parameter | Description |
| --------- | ----------- |
| **stock_quantity** | Accepts an integer: the quantity of a product in stock. |
| **stock_status** | Accepts a string: `'outofstock'`, `'instock'`, or `'onbackorder'`. See [ProductStockStatus constant class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Enums/ProductStockStatus.php). |

#### Examples

```php
// Get products that only have one left in stock.
$products = wc_get_products( array( 'stock_quantity' => 1 ) );
```

```php
// Get out of stock products.
$products = wc_get_products( array( 'stock_status' => 'outofstock' ) );
```

```php
// Using constant class for stock status.
$products = wc_get_products( array( 'stock_status' => \Automattic\WooCommerce\Enums\ProductStockStatus::OUT_OF_STOCK ) );
```

### Tax & shipping

| Parameter | Description |
| --------- | ----------- |
| **tax_status** | Accepts a string: `'taxable'`, `'shipping'`, or `'none'`. See [ProductTaxStatus constant class](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Enums/ProductTaxStatus.php). |
| **tax_class** | Accepts a string: a tax class slug. |
| **shipping_class** | Accepts a string or array of strings: one or more shipping class slugs. |

#### Examples

```php
// Get taxable products.
$products = wc_get_products( array( 'tax_status' => 'taxable' ) );
```

```php
// Using constant class for tax status.
$products = wc_get_products( array( 'tax_status' => \Automattic\WooCommerce\Enums\ProductTaxStatus::TAXABLE ) );
```

```php
// Get products in the "Reduced Rate" tax class.
$products = wc_get_products( array( 'tax_class' => 'reduced-rate' ) );
```

```php
// Get products in the "Bulky" shipping class.
$products = wc_get_products( array( 'shipping_class' => 'bulky' ) );
```

### Reviews & ratings

| Parameter | Description |
| --------- | ----------- |
| **average_rating** | Accepts a float: the average rating. |
| **review_count** | Accepts an integer: the number of reviews. |

#### Examples

```php
// Get products with all 5-star ratings.
$products = wc_get_products( array( 'average_rating' => 5.0 ) );
```

```php
// Get products with 1 review.
$products = wc_get_products( array( 'review_count' => 1 ) );
```

### Date

Date arguments receive values following the standard format described below, allowing for more flexible queries.

| Parameter | Description |
| --------- | ----------- |
| **date_created** | Matches product creation date. Accepts a string in standard format. |
| **date_modified** | Matches product modification date. Accepts a string in standard format. |
| **date_on_sale_from** | Matches sale start date. Accepts a string in standard format. |
| **date_on_sale_to** | Matches sale end date. Accepts a string in standard format. |

#### Standard format

- `YYYY-MM-DD` - Matches on products during that one day in site timezone.
- `>YYYY-MM-DD` - Matches on products after that one day in site timezone.
- `>=YYYY-MM-DD` - Matches on products during or after that one day in site timezone.
- `<YYYY-MM-DD` - Matches on products before that one day in site timezone.
- `<=YYYY-MM-DD` - Matches on products during or before that one day in site timezone.
- `YYYY-MM-DD...YYYY-MM-DD` - Matches on products during or in between the days in site timezone.
- `TIMESTAMP` - Matches on products during that one second in UTC timezone.
- `>TIMESTAMP` - Matches on products after that one second in UTC timezone.
- `>=TIMESTAMP` - Matches on products during or after that one second in UTC timezone.
- `<TIMESTAMP` - Matches on products before that one second in UTC timezone.
- `<=TIMESTAMP` - Matches on products during or before that one second in UTC timezone.
- `TIMESTAMP...TIMESTAMP` - Matches on products during or in between the seconds in UTC timezone.

#### Examples

```php
// Get downloadable products created in the year 2016.
$products = wc_get_products( array(
    'downloadable' => true,
    'date_created' => '2016-01-01...2016-12-31',
) );
```

## Adding support for custom parameters

It is possible to add support for custom parameters in `wc_get_products()` or `WC_Product_Query`. To do this you need to filter the generated query.

```php
/**
 * Handle a custom 'customvar' query var to get products with the 'customvar' meta.
 * @param array $query - Args for WP_Query.
 * @param array $query_vars - Query vars from WC_Product_Query.
 * @return array modified $query
 */
function handle_custom_query_var( $query, $query_vars ) {
	if ( ! empty( $query_vars['customvar'] ) ) {
		if ( ! isset( $query['meta_query'] ) ) {
			$query['meta_query'] = array();
		}
		$query['meta_query'][] = array(
			'key'   => 'customvar',
			'value' => sanitize_text_field( $query_vars['customvar'] ),
		);
	}

	return $query;
}
add_filter( 'woocommerce_product_data_store_cpt_get_products_query', 'handle_custom_query_var', 10, 2 );
```

Usage:

```php
$products = wc_get_products( array( 'customvar' => 'somevalue' ) );
```


---

## Shipping method API

*Source: features/shipping/shipping-method-api.md*

# Shipping method API

WooCommerce has a Shipping Method API which plugins can use to add their own rates. This article will take you through the steps to creating a new shipping method based on the core Flat Rate method that interacts with the Shipping API.

## Create a plugin

First off, create a regular WordPress/WooCommerce plugin - see our [Building Your First Extension guide](/docs/extensions/getting-started-extensions/building-your-first-extension) to get started. You'll define your shipping method class in this plugin file and maintain it outside of WooCommerce.

## Checking for WooCommerce and creating a function to house your class

Before we attempt to load our class, we need to make sure that WooCommerce is active and the primary classes and functions necessary for us to work are available. Once we know those are available, we can add an action to initialize our class, and a filter to add our method to the primary shipping method list.

```php
/**
 * If WooCommerce is active, then these classes and function will exist.
 */
if ( class_exists( 'woocommerce' ) && class_exists( 'WC_Shipping_Method' ) && function_exists( 'WC' ) ) {
	// We add an action to init our shipping method class, and a filter to add our shipping method to the method list.
	add_action( 'woocommerce_shipping_init', 'your_shipping_method_init' );
	add_filter( 'woocommerce_shipping_methods', 'your_shipping_method_add' );
}

/**
 * Your function to add your shipping method to the shipping method list.
 */
function your_shipping_method_add( $methods ) {
	$methods['your_shipping_method'] = 'WC_Your_Shipping_Method';
	return $methods;
}

/**
 * Your function to init your shipping method class.
 */
function your_shipping_method_init() {
    // Your class will go here
}
```

## Create your class

Now we create your class to place inside the function just created. It is best to make sure the class doesn't already exist to make sure there are no unexpected fatal errors. The class will need to extend the shipping method class so that we have access to the Shipping and Settings APIs. We also make sure to declare necessary properties and then define more options/properties in the constructor, and we end with a call to the init method.

```php
if ( ! class_exists( 'WC_Your_Shipping_Method' ) ) {
	class WC_Your_Shipping_Method extends WC_Shipping_Method {
		/**
		 * Shipping method cost.
		 *
		 * @var string
		 */
		public $cost;

		/**
		 * Shipping method type.
		 *
		 * @var string
		 */
		public $type;

		/**
		 * Constructor for your shipping class.
		 *
		 * @param  int  $instance_id Shipping method instance ID. A new instance ID is assigned per instance created in a shipping zone.
		 * @return void
		 */
		public function __construct( $instance_id = 0 ) {
			$this->id                 = 'your_shipping_method'; // ID for your shipping method. Should be unique.
			$this->instance_id        = absint( $instance_id );
			$this->method_title       = __( 'Your Shipping Method', 'your_text_domain' );  // Title shown in admin.
			$this->method_description = __( 'Description of your shipping method', 'your_text_domain' ); // Description shown in admin.
			$this->supports           = array(
				'settings',                // Provides a stand alone settings tab for your shipping method under WooCommerce > Settings > Shipping.
				'shipping-zones',          // Allows merchants to add your shipping method to shipping zones.
				'instance-settings',       // Allows for a page where merchants can edit the instance of your method included in a shipping zone.
				'instance-settings-modal', // Allows for a modal where merchants can edit the instance of your method included in a shipping zone.
			);

			// Additional initialization of the shipping method.
			$this->init();
		}
	}
}
```

## Defining settings/options

We want to make sure to add an action for the shipping method when options are updated to call `process_admin_options`, this will save any settings entered by a merchant/admin when they choose to save.

Options are then able to be defined using the [WooCommerce settings API](https://developer.woocommerce.com/docs/settings-api/). We have two additional methods `init_form_fields` and `init_instance_form_fields` that will initialize the form fields for both the stand alone settings and instance settings for us. Additional options, such as the title, tax status, etc, are set via the `get_option` method of the Settings API. These are set for either the stand alone page, or the instance settings, whichever is being displayed.


```php
	/**
	 * Additional initialization of options for the shipping method not necessary in the constructor.
	 *
	 * @return void
	 */
	public function init() {
		// Save settings in admin if any have been defined. (using Shipping/Settings API)
		add_action( 'woocommerce_update_options_shipping_' . $this->id, array( $this, 'process_admin_options' ) );

		// Init stand alone settings and also the instance settings form fields.
		$this->init_form_fields();
		$this->init_instance_form_fields();

		// Use the Settings API to get the saved options to use for the settings fields.
		$this->title      = $this->get_option( 'title' );
		$this->tax_status = $this->get_option( 'tax_status' );
		$this->cost       = $this->get_option( 'cost' );
		$this->type       = $this->get_option( 'type', 'class' );
	}

	/**
	 * Our method to initialize our form fields for our stand alone settings page, if needed.
	 *
	 * @return void
	 */
	public function init_form_fields() {
		// Set the form_fields property to an array that will be able to be used by the Settings API to show the fields on the page.
		$this->form_fields = array(
			'title'      => array(
				'title'       => __( 'Name', 'your_text_domain' ),
				'type'        => 'text',
				'description' => __( 'Your customers will see the name of this shipping method during checkout.', 'your_text_domain' ),
				'default'     => __( 'Your shipping method', 'your_text_domain' ),
				'placeholder' => __( 'e.g. Standard national', 'your_text_domain' ),
				'desc_tip'    => true, // Include this if you would like your description to show as a tooltip.
			),
			'tax_status' => array(
				'title'   => __( 'Tax status', 'your_text_domain' ),
				'type'    => 'select',
				'class'   => 'wc-enhanced-select',
				'default' => 'taxable',
				'options' => array(
					'taxable' => __( 'Taxable', 'your_text_domain' ),
					'none'    => _x( 'None', 'Tax status', 'your_text_domain' ),
				),
			),
			'cost'       => array(
				'title'             => __( 'Cost', 'your_text_domain' ),
				'type'              => 'text',
				'placeholder'       => '',
				'description'       => __( 'Enter a cost (excl. tax).', 'your_text_domain' ),
				'default'           => '0',
				'desc_tip'          => true,
				'sanitize_callback' => array( $this, 'sanitize_cost' ),
			),
		);
	}

	/**
	 * Our method to initialize our form fields for separate instances.
	 *
	 * @return void
	 */
	private function init_instance_form_fields() {
		// Define some strings that will be used several times for the cost description and link.
		$cost_desc = __( 'Enter a cost (excl. tax).', 'your_text_domain' );
		$cost_link = sprintf( '<span id="wc-shipping-advanced-costs-help-text">%s <a target="_blank" href="https://woocommerce.com/document/flat-rate-shipping/#advanced-costs">%s</a>.</span>', __( 'Charge a flat rate per item, or enter a cost formula to charge a percentage based cost or a minimum fee. Learn more about', 'your_text_domain' ), __( 'advanced costs', 'your_text_domain' ) );

		// Start the array of fields.
		$fields = array(
			'title'      => array(
				'title'       => __( 'Name', 'your_text_domain' ),
				'type'        => 'text',
				'description' => __( 'Your customers will see the name of this shipping method during checkout.', 'your_text_domain' ),
				'default'     => __( 'Your shipping method', 'your_text_domain' ),
				'placeholder' => __( 'e.g. Standard national', 'your_text_domain' ),
				'desc_tip'    => true,
			),
			'tax_status' => array(
				'title'   => __( 'Tax status', 'your_text_domain' ),
				'type'    => 'select',
				'class'   => 'wc-enhanced-select',
				'default' => 'taxable',
				'options' => array(
					'taxable' => __( 'Taxable', 'your_text_domain' ),
					'none'    => _x( 'None', 'Tax status', 'your_text_domain' ),
				),
			),
			'cost'       => array(
				'title'             => __( 'Cost', 'your_text_domain' ),
				'type'              => 'text',
				'class'             => 'wc-shipping-modal-price',
				'placeholder'       => '',
				'description'       => $cost_desc,
				'default'           => '0',
				'desc_tip'          => true,
				'sanitize_callback' => array( $this, 'sanitize_cost' ),
			),
		);

		/**
		 * Flat rate shipping has the ability to add rates per shipping class, so here we get the shipping classes and then provide fields
		 * for merchants/admins to use to be able to specify these costs. 
		 */
		$shipping_classes = WC()->shipping()->get_shipping_classes();

		if ( ! empty( $shipping_classes ) ) {
			$fields['class_costs'] = array(
				'title'       => __( 'Shipping class costs', 'your_text_domain' ),
				'type'        => 'title',
				'default'     => '',
				/* translators: %s: URL for link */
				'description' => sprintf( __( 'These costs can optionally be added based on the <a target="_blank" href="%s">product shipping class</a>. Learn more about <a target="_blank" href="https://woocommerce.com/document/flat-rate-shipping/#shipping-classes">setting shipping class costs</a>.', 'your_text_domain' ), admin_url( 'admin.php?page=wc-settings&tab=shipping&section=classes' ) ),
			);
			foreach ( $shipping_classes as $shipping_class ) {
				if ( ! isset( $shipping_class->term_id ) ) {
					continue;
				}
				$fields[ 'class_cost_' . $shipping_class->term_id ] = array(
					/* translators: %s: shipping class name */
					'title'             => sprintf( __( '"%s" shipping class cost', 'your_text_domain' ), esc_html( $shipping_class->name ) ),
					'type'              => 'text',
					'class'             => 'wc-shipping-modal-price',
					'placeholder'       => __( 'N/A', 'your_text_domain' ),
					'description'       => $cost_desc,
					'default'           => $this->get_option( 'class_cost_' . $shipping_class->slug ),
					'desc_tip'          => true,
					'sanitize_callback' => array( $this, 'sanitize_cost' ),
				);
			}

			$fields['no_class_cost'] = array(
				'title'             => __( 'No shipping class cost', 'your_text_domain' ),
				'type'              => 'text',
				'class'             => 'wc-shipping-modal-price',
				'placeholder'       => __( 'N/A', 'your_text_domain' ),
				'description'       => $cost_desc,
				'default'           => '',
				'desc_tip'          => true,
				'sanitize_callback' => array( $this, 'sanitize_cost' ),
			);

			$fields['type'] = array(
				'title'       => __( 'Calculation type', 'your_text_domain' ),
				'type'        => 'select',
				'class'       => 'wc-enhanced-select',
				'default'     => 'class',
				'options'     => array(
					'class' => __( 'Per class: Charge shipping for each shipping class individually', 'your_text_domain' ),
					'order' => __( 'Per order: Charge shipping for the most expensive shipping class', 'your_text_domain' ),
				),
				'description' => $cost_link,
			);
		}

		// And finally we set the instance_form_fields property for the Shipping API to use.
		$this->instance_form_fields = $fields;
	}
```

## Sanitizing the cost

In the previous code snippets you can see that there is a `sanitize_callback` to use `sanitize_cost`, while this may not always be needed, it is still good to keep sanitizing user input in mind. Since a cost field will need to be a text field to allow for a decimal separator, we need to make sure the value entered is valid. For this, we introduce the below method.

```php
	/**
	 * Sanitize the cost value.
	 * This method is called when the `sanitize_callback` method is called in the Settings API while the values input by the merchant are being saved.
	 *
	 * @param string $value Unsanitized value.
	 * @return string
	 * @throws Exception If the cost is not numeric.
	 */
	public function sanitize_cost( $value ) {
		// If the value is null, then set it to zero. Run the value through WordPress core sanitization functions, the remove the currency symbol, if present.
		$value = is_null( $value ) ? '0' : $value;
		$value = wp_kses_post( trim( wp_unslash( $value ) ) );
		$value = str_replace( array( get_woocommerce_currency_symbol(), html_entity_decode( get_woocommerce_currency_symbol() ) ), '', $value );

		// Get the current locale and all possible decimal separators.
		$locale   = localeconv();
		$decimals = array( wc_get_price_decimal_separator(), $locale['decimal_point'], $locale['mon_decimal_point'], ',' );

		// Remove whitespace, then decimals, and then invalid start/end characters.
		$value = preg_replace( '/\s+/', '', $value );
		$value = str_replace( $decimals, '.', $value );
		$value = rtrim( ltrim( $value, "\t\n\r\0\x0B+*/" ), "\t\n\r\0\x0B+-*/" );

		// If the value is not numeric, then throw an exception.
		if ( ! is_numeric( $value ) ) {
			throw new Exception( 'Invalid cost entered.' );
		}
		return $value;
	}
```

## Adding a rate

Rates are added via the Shipping API using the `add_rate` method. Below is a breakdown of available options, and in the next section we will put this to use.

Your shipping method can pass as many rates as needed, just ensure that the id for each is different. The user will get to choose rate during checkout.

```php
$rate = array(
    'label' => '',   // Label for the rate.
    'cost'  => '0',  // Amount for shipping or an array of costs (for per item shipping).
    'taxes' => '',   // Pass an array of taxes, or pass nothing to have it calculated for you, or pass 'false' to calculate no tax for this method.
    'calc_tax' => 'per_order' // Calc tax per_order or per_item. Per item needs an array of costs passed via 'cost'.
);

// Register the rate
$this->add_rate( $rate );
```

## The calculate_shipping() method

The method to use to add your rates is `calculate_shipping`, WooCommerce will call this when doing shipping calculations in the cart and checkout. Do your plugin specific calculations here and then add the rates via the Shipping API.

Here we also include the `find_shipping_classes` method, which gets the shipping classes from each item in the package.

```php
	/**
	* Calculate the shipping costs.
	*
	* @param array $package Package of items from cart.
	*/
	public function calculate_shipping( $package = array() ) {
		// Get the rate set for this instance.
		$rate = array(
			'id'      => $this->get_rate_id(), // Get the instance rate ID from the Shipping API.
			'label'   => $this->title,
			'cost'    => 0,
			'package' => $package,
		);

		// Calculate the costs.
		$has_costs = false; // True when a cost is set. False if all costs are blank strings.
		$cost      = $this->get_option( 'cost' );

		// If a cost has been set, then we evaluate the cost to make sure it is valid.
		if ( '' !== $cost ) {
			$has_costs    = true;
			$rate['cost'] = $cost;
		}

		// Flat rate shipping has the ability to set a cost per shipping class, so here we get the shipping classes and add those costs, as well.
		$shipping_classes = WC()->shipping()->get_shipping_classes();
		if ( ! empty( $shipping_classes ) ) {
			// Check to see if there are shipping classes assigned to the products in the package/cart.
			$found_shipping_classes = $this->find_shipping_classes( $package );
			$highest_class_cost     = 0;

			// If shipping classes are found to be assigned to the products, then we go through each shipping class.
			foreach ( $found_shipping_classes as $shipping_class => $products ) {
				// Also handles backwards compatibility when slugs were used instead of ids.
				$shipping_class_term = get_term_by( 'slug', $shipping_class, 'product_shipping_class' );
				$class_cost   = $shipping_class_term && $shipping_class_term->term_id ? $this->get_option( 'class_cost_' . $shipping_class_term->term_id, $this->get_option( 'class_cost_' . $shipping_class, '' ) ) : $this->get_option( 'no_class_cost', '' );

				// If a cost is not assigned to the shipping class, then we move to the next class.
				if ( '' === $class_cost ) {
					continue;
				}

				// We have a shipping class cost, so we evaluate the class cost to confirm it is valid.
				$has_costs = true;

				/**
				* Flat rate has two options when it comes to shipping class, per class or per order.
				* Here we check that setting so we can apply the costs accordingly.
				*/
				if ( 'class' === $this->type ) {
					$rate['cost'] += $class_cost;
				} else {
					$highest_class_cost = $class_cost > $highest_class_cost ? $class_cost : $highest_class_cost;
				}
			}

			// If the cost is per order, then we apply the highest class cost to the base cost.
			if ( 'order' === $this->type && $highest_class_cost ) {
				$rate['cost'] += $highest_class_cost;
			}
		}

		if ( $has_costs ) {
			$this->add_rate( $rate );
		}

		/**
		* Developers can add additional flat rates based on this one via this action since @version 2.4.
		*
		* Previously there were (overly complex) options to add additional rates however this was not user.
		* friendly and goes against what Flat Rate Shipping was originally intended for.
		*/
		do_action( 'woocommerce_' . $this->id . '_shipping_add_rate', $this, $rate );
	}

	/**
	* Finds and returns shipping classes and the products with said class.
	*
	* @param mixed $package Package of items from cart.
	* @return array
	*/
	public function find_shipping_classes( $package ) {
		$found_shipping_classes = array();

		foreach ( $package['contents'] as $item_id => $values ) {
			if ( $values['data']->needs_shipping() ) {
				$found_class = $values['data']->get_shipping_class();

				if ( ! isset( $found_shipping_classes[ $found_class ] ) ) {
					$found_shipping_classes[ $found_class ] = array();
				}

				$found_shipping_classes[ $found_class ][ $item_id ] = $values;
			}
		}

		return $found_shipping_classes;
	}
```

## Piecing it all together

Our trimmed down version of the Flat Rate shipping method as a stand alone plugin looks like this:

```php
<?php
/**
 * Plugin Name: Your Shipping plugin
 * Plugin URI: https://woocommerce.com/
 * Description: Your shipping method plugin
 * Version: 1.0.0
 * Author: WooCommerce
 * Author URI: https://woocommerce.com/
 * Text Domain: your_text_domain
 */

/**
 * If WooCommerce is active, then the class will exist.
 */
if ( class_exists( 'woocommerce' ) && class_exists( 'WC_Shipping_Method' ) && function_exists( 'WC' ) ) {
	// We add an action to init our shipping method class, and a filter to add our shipping method to the method list.
	add_action( 'woocommerce_shipping_init', 'your_shipping_method_init' );
	add_filter( 'woocommerce_shipping_methods', 'your_shipping_method_add' );
}

/**
 * Your function to add your shipping method to the shipping method list.
 */
function your_shipping_method_add( $methods ) {
	$methods['your_shipping_method'] = 'WC_Your_Shipping_Method';
	return $methods;
}

/**
 * Your function to init your shipping method class.
 */
function your_shipping_method_init() {
	/**
	 * Ideally this would include the class from another file, but for demonstration purposes we will include it here.
	 */
	if ( ! class_exists( 'WC_Your_Shipping_Method' ) ) {
		class WC_Your_Shipping_Method extends WC_Shipping_Method {
			/**
			 * Shipping method cost.
			 *
			 * @var string
			 */
			public $cost;

			/**
			 * Shipping method type.
			 *
			 * @var string
			 */
			public $type;

			/**
			 * Constructor for your shipping class.
			 *
			 * @param  int  $instance_id Shipping method instance ID. A new instance ID is assigned per instance created in a shipping zone.
			 * @return void
			 */
			public function __construct( $instance_id = 0 ) {
				$this->id                 = 'your_shipping_method'; // ID for your shipping method. Should be unique.
				$this->instance_id        = absint( $instance_id );
				$this->method_title       = __( 'Your Shipping Method', 'your_text_domain' );  // Title shown in admin.
				$this->method_description = __( 'Description of your shipping method', 'your_text_domain' ); // Description shown in admin.
				$this->supports           = array(
					'settings',                // Provides a stand alone settings tab for your shipping method under WooCommerce > Settings > Shipping.
					'shipping-zones',          // Allows merchants to add your shipping method to shipping zones.
					'instance-settings',       // Allows for a page where merchants can edit the instance of your method included in a shipping zone.
					'instance-settings-modal', // Allows for a modal where merchants can edit the instance of your method included in a shipping zone.
				);

				// Additional initialization of the shipping method.
				$this->init();
			}

			/**
			 * Additional initialization of options for the shipping method not necessary in the constructor.
			 *
			 * @return void
			 */
			public function init() {
				// Save settings in admin if any have been defined. (using Shipping/Settings API)
				add_action( 'woocommerce_update_options_shipping_' . $this->id, array( $this, 'process_admin_options' ) );

				// Init stand alone settings and also the instance settings form fields.
				$this->init_form_fields();
				$this->init_instance_form_fields();

				// Use the Settings API to get the saved options to use for the settings fields.
				$this->title      = $this->get_option( 'title' );
				$this->tax_status = $this->get_option( 'tax_status' );
				$this->cost       = $this->get_option( 'cost' );
				$this->type       = $this->get_option( 'type', 'class' );
			}

			/**
			 * Calculate the shipping costs.
			 *
			 * @param array $package Package of items from cart.
			 */
			public function calculate_shipping( $package = array() ) {
				// Get the rate set for this instance.
				$rate = array(
					'id'      => $this->get_rate_id(), // Get the instance rate ID from the Shipping API.
					'label'   => $this->title,
					'cost'    => 0,
					'package' => $package,
				);

				// Calculate the costs.
				$has_costs = false; // True when a cost is set. False if all costs are blank strings.
				$cost      = $this->get_option( 'cost' );

				// If a cost has been set, then we evaluate the cost to make sure it is valid.
				if ( '' !== $cost ) {
					$has_costs    = true;
					$rate['cost'] = $cost;
				}

				// Flat rate shipping has the ability to set a cost per shipping class, so here we get the shipping classes and add those costs, as well.
				$shipping_classes = WC()->shipping()->get_shipping_classes();
				if ( ! empty( $shipping_classes ) ) {
					// Check to see if there are shipping classes assigned to the products in the package/cart.
					$found_shipping_classes = $this->find_shipping_classes( $package );
					$highest_class_cost     = 0;

					// If shipping classes are found to be assigned to the products, then we go through each shipping class.
					foreach ( $found_shipping_classes as $shipping_class => $products ) {
						// Also handles backwards compatibility when slugs were used instead of ids.
						$shipping_class_term = get_term_by( 'slug', $shipping_class, 'product_shipping_class' );
						$class_cost   = $shipping_class_term && $shipping_class_term->term_id ? $this->get_option( 'class_cost_' . $shipping_class_term->term_id, $this->get_option( 'class_cost_' . $shipping_class, '' ) ) : $this->get_option( 'no_class_cost', '' );

						// If a cost is not assigned to the shipping class, then we move to the next class.
						if ( '' === $class_cost ) {
							continue;
						}

						// We have a shipping class cost, so we evaluate the class cost to confirm it is valid.
						$has_costs = true;

						/**
						 * Flat rate has two options when it comes to shipping class, per class or per order.
						 * Here we check that setting so we can apply the costs accordingly.
						 */
						if ( 'class' === $this->type ) {
							$rate['cost'] += $class_cost;
						} else {
							$highest_class_cost = $class_cost > $highest_class_cost ? $class_cost : $highest_class_cost;
						}
					}

					// If the cost is per order, then we apply the highest class cost to the base cost.
					if ( 'order' === $this->type && $highest_class_cost ) {
						$rate['cost'] += $highest_class_cost;
					}
				}

				if ( $has_costs ) {
					$this->add_rate( $rate );
				}

				/**
				 * Developers can add additional flat rates based on this one via this action since @version 2.4.
				 *
				 * Previously there were (overly complex) options to add additional rates however this was not user.
				 * friendly and goes against what Flat Rate Shipping was originally intended for.
				 */
				do_action( 'woocommerce_' . $this->id . '_shipping_add_rate', $this, $rate );
			}

			/**
			 * Finds and returns shipping classes and the products with said class.
			 *
			 * @param mixed $package Package of items from cart.
			 * @return array
			 */
			public function find_shipping_classes( $package ) {
				$found_shipping_classes = array();

				foreach ( $package['contents'] as $item_id => $values ) {
					if ( $values['data']->needs_shipping() ) {
						$found_class = $values['data']->get_shipping_class();

						if ( ! isset( $found_shipping_classes[ $found_class ] ) ) {
							$found_shipping_classes[ $found_class ] = array();
						}

						$found_shipping_classes[ $found_class ][ $item_id ] = $values;
					}
				}

				return $found_shipping_classes;
			}

			/**
			 * Sanitize the cost value.
			 * This method is called when the `sanitize_callback` method is called in the Settings API while the values input by the merchant are being saved.
			 *
			 * @param string $value Unsanitized value.
			 * @return string
			 * @throws Exception If the cost is not numeric.
			 */
			public function sanitize_cost( $value ) {
				// If the value is null, then set it to zero. Run the value through WordPress core sanitization functions, the remove the currency symbol, if present.
				$value = is_null( $value ) ? '0' : $value;
				$value = wp_kses_post( trim( wp_unslash( $value ) ) );
				$value = str_replace( array( get_woocommerce_currency_symbol(), html_entity_decode( get_woocommerce_currency_symbol() ) ), '', $value );

				// Get the current locale and all possible decimal separators.
				$locale   = localeconv();
				$decimals = array( wc_get_price_decimal_separator(), $locale['decimal_point'], $locale['mon_decimal_point'], ',' );

				// Remove whitespace, then decimals, and then invalid start/end characters.
				$value = preg_replace( '/\s+/', '', $value );
				$value = str_replace( $decimals, '.', $value );
				$value = rtrim( ltrim( $value, "\t\n\r\0\x0B+*/" ), "\t\n\r\0\x0B+-*/" );

				// If the value is not numeric, then throw an exception.
				if ( ! is_numeric( $value ) ) {
					throw new Exception( 'Invalid cost entered.' );
				}
				return $value;
			}

			/**
			 * Our method to initialize our form fields for our stand alone settings page, if needed.
			 *
			 * @return void
			 */
			public function init_form_fields() {
				// Set the form_fields property to an array that will be able to be used by the Settings API to show the fields on the page.
				$this->form_fields = array(
					'title'      => array(
						'title'       => __( 'Name', 'your_text_domain' ),
						'type'        => 'text',
						'description' => __( 'Your customers will see the name of this shipping method during checkout.', 'your_text_domain' ),
						'default'     => __( 'Your shipping method', 'your_text_domain' ),
						'placeholder' => __( 'e.g. Standard national', 'your_text_domain' ),
						'desc_tip'    => true, // Include this if you would like your description to show as a tooltip.
					),
					'tax_status' => array(
						'title'   => __( 'Tax status', 'your_text_domain' ),
						'type'    => 'select',
						'class'   => 'wc-enhanced-select',
						'default' => 'taxable',
						'options' => array(
							'taxable' => __( 'Taxable', 'your_text_domain' ),
							'none'    => _x( 'None', 'Tax status', 'your_text_domain' ),
						),
					),
					'cost'       => array(
						'title'             => __( 'Cost', 'your_text_domain' ),
						'type'              => 'text',
						'placeholder'       => '',
						'description'       => __( 'Enter a cost (excl. tax).', 'your_text_domain' ),
						'default'           => '0',
						'desc_tip'          => true,
						'sanitize_callback' => array( $this, 'sanitize_cost' ),
					),
				);
			}

			/**
			 * Our method to initialize our form fields for separate instances.
			 *
			 * @return void
			 */
			private function init_instance_form_fields() {
				// Define some strings that will be used several times for the cost description and link.
				$cost_desc = __( 'Enter a cost (excl. tax).', 'your_text_domain' );
				$cost_link = sprintf( '<span id="wc-shipping-advanced-costs-help-text">%s <a target="_blank" href="https://woocommerce.com/document/flat-rate-shipping/#advanced-costs">%s</a>.</span>', __( 'Charge a flat rate per item, or enter a cost formula to charge a percentage based cost or a minimum fee. Learn more about', 'your_text_domain' ), __( 'advanced costs', 'your_text_domain' ) );

				// Start the array of fields.
				$fields = array(
					'title'      => array(
						'title'       => __( 'Name', 'your_text_domain' ),
						'type'        => 'text',
						'description' => __( 'Your customers will see the name of this shipping method during checkout.', 'your_text_domain' ),
						'default'     => __( 'Your shipping method', 'your_text_domain' ),
						'placeholder' => __( 'e.g. Standard national', 'your_text_domain' ),
						'desc_tip'    => true,
					),
					'tax_status' => array(
						'title'   => __( 'Tax status', 'your_text_domain' ),
						'type'    => 'select',
						'class'   => 'wc-enhanced-select',
						'default' => 'taxable',
						'options' => array(
							'taxable' => __( 'Taxable', 'your_text_domain' ),
							'none'    => _x( 'None', 'Tax status', 'your_text_domain' ),
						),
					),
					'cost'       => array(
						'title'             => __( 'Cost', 'your_text_domain' ),
						'type'              => 'text',
						'class'             => 'wc-shipping-modal-price',
						'placeholder'       => '',
						'description'       => $cost_desc,
						'default'           => '0',
						'desc_tip'          => true,
						'sanitize_callback' => array( $this, 'sanitize_cost' ),
					),
				);

				/**
				 * Flat rate shipping has the ability to add rates per shipping class, so here we get the shipping classes and then provide fields
				 * for merchants/admins to use to be able to specify these costs. 
				 */
				$shipping_classes = WC()->shipping()->get_shipping_classes();

				if ( ! empty( $shipping_classes ) ) {
					$fields['class_costs'] = array(
						'title'       => __( 'Shipping class costs', 'your_text_domain' ),
						'type'        => 'title',
						'default'     => '',
						/* translators: %s: URL for link */
						'description' => sprintf( __( 'These costs can optionally be added based on the <a target="_blank" href="%s">product shipping class</a>. Learn more about <a target="_blank" href="https://woocommerce.com/document/flat-rate-shipping/#shipping-classes">setting shipping class costs</a>.', 'your_text_domain' ), admin_url( 'admin.php?page=wc-settings&tab=shipping&section=classes' ) ),
					);
					foreach ( $shipping_classes as $shipping_class ) {
						if ( ! isset( $shipping_class->term_id ) ) {
							continue;
						}
						$fields[ 'class_cost_' . $shipping_class->term_id ] = array(
							/* translators: %s: shipping class name */
							'title'             => sprintf( __( '"%s" shipping class cost', 'your_text_domain' ), esc_html( $shipping_class->name ) ),
							'type'              => 'text',
							'class'             => 'wc-shipping-modal-price',
							'placeholder'       => __( 'N/A', 'your_text_domain' ),
							'description'       => $cost_desc,
							'default'           => $this->get_option( 'class_cost_' . $shipping_class->slug ),
							'desc_tip'          => true,
							'sanitize_callback' => array( $this, 'sanitize_cost' ),
						);
					}

					$fields['no_class_cost'] = array(
						'title'             => __( 'No shipping class cost', 'your_text_domain' ),
						'type'              => 'text',
						'class'             => 'wc-shipping-modal-price',
						'placeholder'       => __( 'N/A', 'your_text_domain' ),
						'description'       => $cost_desc,
						'default'           => '',
						'desc_tip'          => true,
						'sanitize_callback' => array( $this, 'sanitize_cost' ),
					);

					$fields['type'] = array(
						'title'       => __( 'Calculation type', 'your_text_domain' ),
						'type'        => 'select',
						'class'       => 'wc-enhanced-select',
						'default'     => 'class',
						'options'     => array(
							'class' => __( 'Per class: Charge shipping for each shipping class individually', 'your_text_domain' ),
							'order' => __( 'Per order: Charge shipping for the most expensive shipping class', 'your_text_domain' ),
						),
						'description' => $cost_link,
					);
				}

				// And finally we set the instance_form_fields property for the Shipping API to use.
				$this->instance_form_fields = $fields;
			}
		}
	}
}
```


---

## Getting started

*Source: getting-started/README.md*

# Getting started

WooCommerce is a customizable, open-source eCommerce platform built on WordPress. It empowers businesses worldwide to sell anything from physical products and digital downloads to subscriptions, content, and even appointments.

* Get familiar with [WordPress Plugin Development](https://developer.wordpress.org/plugins/).
* Take a moment to familiarize yourself with our [Developer Resources](https://developer.wordpress.org/plugins/plugin-basics/).
* Join the [Woo Community Slack](https://woo.com/community-slack/)

---

## Build WooCommerce extensions

Explore comprehensive guides and resources to build and enhance WooCommerce extensions. Dive into development best practices and innovative techniques for creating powerful extensions.

* [How to build your first extension](/docs/extensions/getting-started-extensions/building-your-first-extension)
* [Designing a simple extension](/docs/extensions/getting-started-extensions/how-to-design-a-simple-extension)
* [Extension development best practices](/docs/extensions/best-practices-extensions/extension-development-best-practices)

Learn more about [extension development](/docs/extensions/getting-started-extensions/)

---

## Build WooCommerce themes

Discover the art of WooCommerce theme development. Learn about theme customization, design principles, and enhancing user experience to create visually appealing and functional themes.

* [How to set up and use a child theme](/docs/theming/theme-development/set-up-a-child-theme)
* [Classic theme developer handbook](/docs/theming/theme-development/classic-theme-developer-handbook)
* [Theme design and user experience guidelines](/docs/theming/theme-development/theme-design-ux-guidelines)

Learn more about [classic theme development](/docs/theming/theme-development/classic-theme-developer-handbook) or [Block theme development](/docs/theming/block-theme-development/theming-woo-blocks)

---

## Contribute to WooCommerce

Join our open-source community and contribute to WooCommerce. Explore how you can make a difference by tackling open issues and enhancing the WooCommerce ecosystem.

* [Visit the WooCommerce monorepo](https://github.com/woocommerce/woocommerce)
* [Open Issues on GitHub](https://github.com/woocommerce/woocommerce/issues)
* [Woo contributor guidelines](/docs/contribution/contributing/)

Learn more about [contributing](/docs/contribution/contributing)

---

## Additional resources

* [WooCommerce Official Website](https://woocommerce.com/)
* [Woo Marketplace](https://woocommerce.com/marketplace)
* All [WooCommerce Repositories on GitHub](https://woocommerce.github.io/)

---

## Not a developer?

This documentation site is intended for developers. If you're a merchant or are new to WooCommerce, please check out [woocommerce.com](https://woocommerce.com/) for our merchant-facing docs.


---

## AI

*Source: getting-started/ai.md*

# AI

This guide provides an overview of AI tools and how to use them to enhance your WooCommerce development workflows.

## MCP

WooCommerce includes native support for the Model Context Protocol (MCP), enabling AI assistants and tools to interact directly with WooCommerce stores through a standardized protocol. Visit our full [MCP documentation](/docs/features/mcp/) for more information.

## AI Documentation Tools

### LLMS.txt Files

To feed the WooCommerce Developer Documentation into your LLM or AI-assisted IDE, you have two options:

1. [`llms.txt`](https://developer.woocommerce.com/docs/llms.txt) - A table of contents that includes the title, URL, and description of each document in the developer docs.
2. [`llms-full.txt`](https://developer.woocommerce.com/docs/llms-full.txt) - A full Markdown-formatted export of the entire documentation in one file.

If you are using an IDE like Cursor or Windsurf, we recommend adding these links as custom documentation so that you can reference them as needed.

**Note** that these do not include the contents of the [WooCommerce Code Reference](https://woocommerce.github.io/code-reference/).

### Serve as Markdown

If you want to view the documentation as Markdown files, you can use append `.md` to the end of any documentation URL. For example, to view this page as Markdown, you can visit:   

```plain
https://developer.woocommerce.com/docs/getting-started/ai.md
``` 

### Copy to Markdown

On every page of the Developer Docs, you'll see a Clipboard icon in the upper-right-hand corner. Selecting this icon will copy the current doc in Markdown formatting, which you can paste into your LLM's chat interface.

## AI Development Tools

### Agent Skills for Contributors

The WooCommerce monorepo includes [agent skills](https://agentskills.io/home) that provide AI assistants with procedural guidance for common development tasks. These skills are located in the `.ai/skills/` directory at the root of the repository.

Each skill contains a `SKILL.md` file with step-by-step instructions for tasks like:

- Backend PHP development and testing conventions
- Code review standards and best practices
- Git workflows and commit conventions
- Build and linting processes
- UI copy and documentation guidelines

Skills are designed to be tool-agnostic and can be used with various AI coding assistants. To explore available skills, browse the [`.ai/skills/` directory](https://github.com/woocommerce/woocommerce/tree/trunk/.ai/skills) in the repository.

### Agent Skills for Extending

If you are building on top of WordPress and WooCommerce, the [WordPress/agent-skills](https://github.com/WordPress/agent-skills) and [woocommerce/agent-skills](https://github.com/woocommerce/agent-skills) repositories provide reusable guidance for AI coding assistants.

The WordPress skills cover foundational WordPress development patterns, while the WooCommerce skills build on those foundations with guidance for WooCommerce extension development. Review both repositories for installation instructions.

### Cursor Rules files for contributors

The `.cursor/rules/` directory contains configuration files that provide AI assistants with specific guidance for working with the WooCommerce codebase. These files help ensure consistent development practices and workflows.


---

## Resources for debugging

*Source: getting-started/debugging.md*

# Resources for debugging

## WordPress

A good place to start is usually the debugging tools built into WordPress itself:

The documentation for [Debugging in WordPress c](https://wordpress.org/documentation/article/debugging-in-wordpress/)overs a number of environment variables you can set to enable WordPress’s core debugging tools.

### Query Monitor

A popular plugin for WordPress developers is [Query Monitor](https://wordpress.org/plugins/query-monitor/), the developer tools for WordPress. Query Monitor enables debugging of database queries, PHP errors, AJAX/Rest requests, hooks and actions, block editor blocks, enqueued scripts and stylesheets, HTTP API calls, and more.

### Email Debugging

When working in a local WooCommerce environment, we recommend enabling tools like Mailpit or Mailhog to redirect all transactional emails to a log rather then being sent.

Alternatively, you can use a plugin like Stop Emails to disable any accidental email triggering.

## WooCommerce

### Logging

WooCommerce has a logging system that can be very helpful for finding and tracking errors on your site:

* [Logging in WooCommerce](/docs/best-practices/data-management/logging)

### Coming Soon Mode

WooCommerce's coming soon mode allows you to temporarily make your site invisible to the public while you work on it.

* [Integrating with coming soon mode](/docs/extensions/extension-onboarding/integrating-coming-soon-mode)

## PHP/JavaScript Debugging

### Xdebug

If you're using `wp-env` to run a local development environment (this is the recommended method for the WooCommerce monorepo), you can activate Xdebug and then use an IDE like VS Code or PhpStorm to set breakpoints and step through the code as it executes:

* [Using Xdebug](https://github.com/WordPress/gutenberg/tree/trunk/packages/env#using-xdebug)


---

## Developer tools

*Source: getting-started/developer-tools.md*

# Developer tools

This guide provides an overview of essential tools and libraries for WooCommerce development. It's intended for developers looking to enhance their WooCommerce projects efficiently.

## Productivity Tools

Use these resources to power up your WooCommerce development workflows.

### Development

#### [wp-cli](https://wp-cli.org/)

This is the command-line interface for [WordPress](https://wordpress.org/). You can update plugins, configure multisite installations and much more, without using a web browser.

#### [wc-cli](/docs/wc-cli/cli-overview)

When WooCommerce is running on a WordPress installation, the WP-CLI is extended with additional functionality for managing your store data.

#### [wp-env](https://www.npmjs.com/package/@wordpress/env)

This command-line tool lets you easily set up a local WordPress Docker environment for building and testing plugins and themes. It's simple to install and requires no configuration.

#### [woocommerce/eslint-plugin](https://www.npmjs.com/package/@woocommerce/eslint-plugin)

This is an [ESLint](https://eslint.org/) plugin including configurations and custom rules for WooCommerce development.

#### [WordPress Scripts](https://www.npmjs.com/package/@wordpress/scripts)

The ⁠@wordpress/scripts package is a set of tools and scripts designed to streamline the development process of WordPress projects, particularly for block development and custom Gutenberg integrations. It includes a Webpack build process along with configuration for tasks like linting, styling, and testing.

It also includes the [Dependency Extraction Webpack Plugin](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin), which allows JavaScript bundles produced by webpack to leverage WordPress style dependency sharing without an error-prone process of manually maintaining a dependency list.

### Testing

#### [Smooth Generator](https://github.com/woocommerce/wc-smooth-generator)

A plugin to help you generate WooCommerce-related data for testing. Use the WP Admin interface for basic operations, or the CLI tool for more advanced features. Download and install the latest version from the [Releases page](https://github.com/woocommerce/wc-smooth-generator/releases) and review the [documentation on GitHub](https://github.com/woocommerce/wc-smooth-generator).

#### [WooCommerce Dummy Payments Gateway](https://github.com/woocommerce/woocommerce-gateway-dummy)

A dummy payment gateway for your WooCommerce development needs, with built-in support for subscriptions and the block-based checkout.

#### [QIT](https://qit.woo.com/)

QIT is a testing platform for WooCommerce plugins and themes with managed tests, E2E tests, and disposable local testing environments.

## Libraries

Use these resources to help take some of the heavy lifting off of fetching and transforming data \-- as well as creating UI elements.

### API Clients

#### [WooCommerce REST API - JavaScript](https://www.npmjs.com/package/@woocommerce/woocommerce-rest-api)

The official JavaScript library for working with the WooCommerce REST API.

#### [WooCommerce Store API](https://developer.woocommerce.com/docs/category/store-api/)

The Store API provides public Rest API endpoints for the development of customer-facing cart, checkout, and product functionality. It follows many of the patterns used in the WordPress REST API.

In contrast to the WooCommerce REST API, the Store API is unauthenticated and does not provide access to sensitive store data or other customer information.

#### [wordpress/api-fetch](https://www.npmjs.com/package/@wordpress/api-fetch)

The `@wordpress/api-fetch` package is a utility that simplifies AJAX requests to the WordPress REST API. It's a wrapper around `window.fetch` that provides a consistent interface for handling authentication, settings, and errors, allowing developers to easily interact with WordPress backend services.

### Components

#### [WooCommerce Components](https://www.npmjs.com/package/@woocommerce/components)

This package includes a library of React components that can be used to create pages in the WooCommerce admin area. To preview these components, review the [Woo Storybook](https://woocommerce.github.io/woocommerce/).

#### [WordPress Components](https://www.npmjs.com/package/@wordpress/components)

This package includes a library of generic WordPress components that can be used for creating common UI elements shared between screens and features of the WordPress dashboard. To preview these components, review the [Gutenberg Storybook](https://wordpress.github.io/gutenberg/).

### JavaScript Utility Packages

#### [CSV Export](https://www.npmjs.com/package/@woocommerce/csv-export)

A set of functions to convert data into CSV values, and enable a browser download of the CSV data.

#### [Currency](https://www.npmjs.com/package/@woocommerce/currency)

A collection of utilities to display and work with currency values.

#### [Data](https://www.npmjs.com/package/@woocommerce/data)

Utilities for managing the WooCommerce Admin data store.

#### [Date](https://www.npmjs.com/package/@woocommerce/date)

A collection of utilities to display and work with date values.

#### [Navigation](https://www.npmjs.com/package/@woocommerce/navigation)

A collection of navigation-related functions for handling query parameter objects, serializing query parameters, updating query parameters, and triggering path changes.

#### [Number](https://www.npmjs.com/package/@woocommerce/number)

A collection of utilities to properly localize numerical values in WooCommerce.


---

## Setting up your development environment

*Source: getting-started/development-environment.md*

# Setting up your development environment

## Recommended software

There are some specific software requirements you will need to consider when developing WooCommerce extensions. The necessary software includes:

* [Git](https://git-scm.com/) for version control of your source code  
* [Node.js](https://nodejs.org/) to run node-based scripts and build processes. PNPM installs and uses the Node version pinned in the repository automatically, so a version manager such as [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) is optional.  
* [Pnpm](https://pnpm.io/) is an npm alternative required if you are building WooCommerce from the repository  
* [Composer](https://getcomposer.org/) is an optional dependency management tool for PHP-based development  
* [WP-CLI](http://wp-cli.org/) is the command line interface for WordPress

Most WordPress hosting environments *do not include Node and Composer* by default, so when distributing extensions and themes, it’s important to include all built assets.

Note: A POSIX compliant operating system (e.g., Linux, macOS) is assumed. If you're working on a Windows machine, the recommended approach is to use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) (available since Windows 10).

## Setting up a reusable WordPress development environment

In addition to the software shared above, you'll also want to have some way of setting up a local development server stack. There are a number of different tools available for this, each with a certain set of functionality and limitations. We recommend choosing from the options below that fit your preferred workflow best.

### WordPress Studio - Recommended Approach

For easy local development environments, we recommend [WordPress Studio](https://developer.wordpress.com/studio/), the local development environment supported by the [WordPress.com](https://developer.wordpress.com) team. Studio includes the ability to manage multiple local website environments, as well as integrations with your code editor and terminal. Studio also features a WordPress-specific AI Assistant, easy imports from WordPress backups, Blueprint support, free public preview sites, and two-way sync with sites hosted on WordPress.com or Pressable.

### wp-env

[wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) is a command-line utility maintained by the WordPress community that allows you to set up and run custom WordPress environments with [Docker](https://www.docker.com/) and JSON manifests. The repository includes a `.wp-env.json` file specifically for contributing to WooCommerce core.

### General PHP-based web stack tools

Below is a collection of tools to help you manage your environment that are not WordPress-specific.

* [MAMP](https://www.mamp.info/en/mac/) - A local server environment that can be installed on Mac or Windows.  
* [WAMP](https://www.wampserver.com/en/) - A Windows web development environment that lets you create applications with Apache2, PHP, and MySQL.  
* [XAMPP](https://www.apachefriends.org/index.html) - An easy-to-install Apache distribution containing MariaDB, PHP, and Perl. It's available for Windows, Linux, and OS X.  
* [Laravel Herd / Valet](https://herd.laravel.com/) - A minimalist and fast development environment for macOS (Valet) and Windows (Herd), optimized for Laravel and other PHP applications.
* [Lando](https://lando.dev/) - A powerful, Docker-based tool for defining and managing local development services across various languages and frameworks.
* [DDEV](https://ddev.com/) - An open-source, Docker-based tool for streamlined local web development, supporting many CMS and frameworks like Drupal and WordPress.
* [vvv](https://varyingvagrantvagrants.org/) is a highly configurable, cross-platform, and robust environment management tool powered by VirtualBox and Vagrant. 

### Minimum server requirements

Regardless of the tool you choose for managing your development environment, you should make sure it [meets the server recommendations](https://woocommerce.com/document/server-requirements/?utm_source=wooextdevguide) for WooCommerce as well as the [requirements for running WordPress](https://wordpress.org/about/requirements/).

## Add WooCommerce Core to your environment

When developing for WooCommerce, it's helpful to install a development version of WooCommerce Core.

### Option 1: WooCommerce Beta Tester

If installing WooCommerce through the traditional WordPress dashboard, you can also install the [WooCommerce Beta Tester](/docs/contribution/testing/beta-testing) extension to change the version, including access to upcoming betas and release candidates. The WooCommerce Beta tester is available through the [Woo Marketplace](https://woocommerce.com/marketplace). 

### Option 2: Clone the WooCommerce Core repository

You can also work directly against the `trunk` or upcoming release branch of WooCommerce Core in your development environment by:

1. Cloning the WooCommerce Core repository.  
2. Installing and activating the required Node version and PNPM.  
3. Installing WooCommerce’s dependencies.  
4. Building WooCommerce.  
5. Symlinking the `plugin/woocommerce` directory to your `wp-content/plugins` directory

#### Clone the WooCommerce Core repository

You can clone the WooCommerce Core repository locally using the following CLI command:

```shell
cd /your/server/wp-content/plugins
git clone https://github.com/woocommerce/woocommerce.git
cd woocommerce
```

#### Install Node

You need [Node.js](https://nodejs.org/) installed to run PNPM and the build scripts. You do not need to match a specific Node version yourself: PNPM reads the version pinned in `pnpm-workspace.yaml` (`useNodeVersion`, mirrored in `.nvmrc`) and installs and uses it automatically for every script it runs.

If you would like a tool to install and switch between Node versions, [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) is one option. With nvm installed, running `nvm install` from the repository root picks up the pinned version from `.nvmrc`. You can learn more in [the nvm GitHub repository](https://github.com/nvm-sh/nvm?tab=readme-ov-file#intro).

#### Install dependencies

To install WooCommerce dependencies, use the following CLI command:

```shell
pnpm install --frozen-lockfile
```

#### Build WooCommerce

Use the following CLI command to compile the JavaScript and CSS that WooCommerce needs to operate:

```shell
pnpm build
```

Note: If you try to run WooCommerce on your server without generating the compiled assets, you may experience errors and other unwanted side-effects.

#### Symlink the WooCommerce plugin 

To load the WooCommerce plugin into your local development environment, you can create a symbolic link from the WooCommerce plugin in your cloned repository to your local WordPress development environment.

```shell
ln -s woocommerce/plugins/woocommerce /path-to-local/wp-content/plugins
```

#### Generating a `woocommerce.zip` asset

Alternatively, you can generate a `woocommerce.zip` file with the following command:

```shell
pnpm build:zip
```

A `woocommerce.zip` file may be helpful if you’d like to upload a modified version of WooCommerce to a separate test environment.


---

## Project Structure

*Source: getting-started/project-structure.md*

# Project Structure

## Prerequisites

WooCommerce adheres to WordPress code standards and guidelines, so it's best to familiarize yourself with [WordPress Development](https://learn.wordpress.org/tutorial/introduction-to-wordpress/) as well as [PHP](https://www.php.net/). Currently WooCommerce requires PHP 7.4 or newer.

Knowledge and understanding of [WooCommerce hooks and filters](https://woocommerce.com/document/introduction-to-hooks-actions-and-filters/?utm_source=wooextdevguide) will allow you to add and change code without editing core files. You can learn more about WordPress hooks and filters in the [WordPress Plugin Development Handbook](https://developer.wordpress.org/plugins/hooks/).

## Recommended reading

WooCommerce extensions are a specialized type of WordPress plugin. If you are new to WordPress plugin development, take a look at some of the articles in the [WordPress Plugin Developer Handbook](https://developer.wordpress.org/plugins/).

## Anatomy of a WordPress environment

While development environments can vary, the basic file structure for a WordPress environment should be consistent.

When developing a WooCommerce extension, you'll usually be doing most of your work within the `public_html/` directory of your local server.

There are three directories in a WordPress installation. The `wp-admin` and `wp-includes` directories include core functionality and should not be modified. The third directory, `wp-content` is where custom configurations and user-generated media is stored.

 Take some time to familiarize yourself with a few key paths inside `wp-content`:

* `wp-content/debug.log` is the file where WordPress writes the important output such as errors and other messages that can be useful for debugging.  
* `wp-content/plugins`/ is the directory on the server where WordPress plugin folders live.  
* `wp-content/themes/` is the directory on the server where WordPress theme folders live. A theme is a collection of templates and styles, and WordPress can have only one active theme.

Finally, at the root of your WordPress installation is one more configurable file, `wp-config.php`. This file acts similarly to a `.env` file and stores important security credentials and variables that define your environment configuration.

## WooCommerce Plugin Structure 

When adding WooCommerce to a WordPress installation, you can either install the plugin from inside the WordPress dashboard or manually upload the plugin directory to the `wp-content/plugins` directory. 

**Important:** The WooCommerce repository is a monorepo that includes multiple plugins and packages. To install WooCommerce from the repository, you cannot simply clone the entire repo into `wp-content/plugins`. The WooCommerce plugin sits in the monorepo inside the `plugins/` directory, so if you’re planning to develop from the repository, we recommend cloning it outside of your local WordPress installation and then using a symlink to “place” it in `wp-content/plugins`. 

Each plugin, package, and tool has its own `package.json` file containing project-specific dependencies and scripts. Most projects also contain a `README.md` file with any project-specific setup instructions and documentation.

* [**Plugins**](http://github.com/woocommerce/woocommerce/tree/trunk/plugins): Our repository contains plugins that relate to or otherwise aid in the development of WooCommerce.  
    * [**WooCommerce Core**](http://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce): The core WooCommerce plugin is available in the plugins directory.  
* [**Packages**](http://github.com/woocommerce/woocommerce/tree/trunk/packages): Contained within the packages directory are all of the [PHP](http://github.com/woocommerce/woocommerce/tree/trunk/packages/php) and [JavaScript](http://github.com/woocommerce/woocommerce/tree/trunk/packages/js) provided for the community. Some of these are internal dependencies and are marked with an `internal-` prefix.  
* [**Tools**](http://github.com/woocommerce/woocommerce/tree/trunk/tools): We also have a growing number of tools within our repository. Many of these are intended to be utilities and scripts for use in the monorepo, but, this directory may also contain external tools.

If you'd like to learn more about how our monorepo works, [please check out this guide here](http://github.com/woocommerce/woocommerce/tree/trunk/tools/README.md).

## Theming and Extending Functionality

Unless you’re contributing directly to WooCommerce core, you will not edit WordPress or WooCommerce files directly. All modification of functionality is done by creating a custom extension or modifying the `functions.php` file of your active theme. 

To edit the *design* of a WooCommerce store, we recommend modifying or creating a custom theme. Learn more about theming WooCommerce in our [Theme Development Handbook](/docs/theming/theme-development/classic-theme-developer-handbook).

To edit the *functionality* of a WooCommerce store, you have multiple options. First, you can use the [Woo Marketplace](https://woocommerce.com/marketplace) to find a suitable, pre-made extension that meets your needs. For simple customizations, you can learn more about easy ways to add [code snippets](/docs/code-snippets/) to your store. For more advanced development needs, we recommend building a custom extension (i.e. a WordPress plugin). 


---

## Scaffolding and sample store data

*Source: getting-started/scaffolding.md*

# Scaffolding and sample store data

WooCommerce offers a number of starter kits and scaffolds depending on what you are building.

## Starter Themes

If you’re designing a WooCommerce store, you have two options for theme development: Classic Themes and Block Themes.

-   Classic themes use PHP templates to override designs to key pages on your store, including your product pages, product archives, shopping cart, and checkout page. While sites running a classic theme can use the WordPress block editor, many of the templates are not editable within the editor itself.
-   Block themes use the WordPress site editor to generate every aspect of the WordPress site, including the header and footer, product pages, archives, and the cart and checkout pages. Designs built in the site editor can be exported into flat HTML files, but the files themselves are typically edited in the WordPress editor.

### Storefront Theme (Classic)

Storefront is Woo’s flagship classic theme, available in the [WordPress Theme Directory](https://wordpress.org/themes/). You can either rename and modify the theme itself, or override specific aspects of it using a child theme.

For more information on building a classic WooCommerce theme, read our classic theme development handbook. For a comprehensive guide on creating a child block theme and understanding the differences between a classic and block theme, please refer to [WooCommerce block theme development](/docs/theming/block-theme-development/theming-woo-blocks) and [WordPress block child theme development](https://learn.wordpress.org/lesson-plan/create-a-basic-child-theme-for-block-themes/).

### Block Starter Themes

If you are completely new to block theme development, please check [Develop Your First Low-Code Block Theme](https://learn.wordpress.org/course/develop-your-first-low-code-block-theme/) to learn about block theme development, and explore the [Create Block Theme plugin](https://wordpress.org/plugins/create-block-theme/) tool when you're ready to create a new theme.

For more information, check out our [Block Theme Development handbook](/docs/theming/block-theme-development/theming-woo-blocks).

## Extension Scaffolds

### @woocommerce/create-woo-extension

[Create Woo Extension](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/create-woo-extension/) is an NPX command that scaffolds an entire WooCommerce extension for your store. The generated extensions adds a React-based settings page integrating with WooCommerce Admin. Also included are PHP and Javascript unit testing, linting, and Prettier IDE configuration for WooCommerce and WordPress.

Read our full tutorial on using the [create-woo-extension package](/docs/extensions/getting-started-extensions/building-your-first-extension).

### @woocommerce/extend-cart-checkout-block

This is a template to be used with `@wordpress/create-block` to create a WooCommerce Blocks extension starting point. To install and use it, follow the instructions in [`@woocommerce/extend-cart-checkout-block`](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/extend-cart-checkout-block/). Please note that this example contains multiple other examples of extensibility, not just inner blocks.

### WooCommerce admin extension examples

Inside of the WooCommerce plugin are a set of example extensions that showcase different use-cases for modifying WooCommerce core functionality. Some examples include adding a custom report, a custom payment gateway, and modifying the WooCommerce dashboard.

Read our full tutorial showcasing [how to extend WooCommerce analytics reports](/docs/features/analytics/extending-woocommerce-admin-reports).

## Relevant WordPress Scaffolds

### Default WordPress Theme

The default WordPress theme (Twenty-Twenty Five as of the time of this writing) is a great place to see the best practices and standard conventions of a WordPress block theme. Using the Create Block Theme tool, you can modify the theme design from within the site edtitor and then export your new design to a custom child theme.

### @wordpress/create-block

If you’re adding additional content or design elements to WordPress, it may make sense to create a custom block. The WordPress block editor package library includes a scaffolding tool called WordPress Create Block that helps you spin up custom blocks that can be inserted into any page or template.

Read more about the [`wordpress/create-block` package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/).

## Sample Store Data

### Core Plugin Sample Data

It may be helpful to load your local store with sample data. In the WooCommerce core plugin, you can find CSV and XML files that can be imported directly into WooCommerce using the WordPress admin or via WC-CLI. The sample data is located in [`/plugins/woocommerce/sample-data/`](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/sample-data).

### Smooth Generator

For more advanced testing, you may want sample customers and order data. [Smooth Generator](https://github.com/woocommerce/wc-smooth-generator) is a plugin to help you generate WooCommerce-related data for testing. Use the WP Admin interface for basic operations, or the CLI tool for more advanced features. Download and install the latest version from the [Releases page](https://github.com/woocommerce/wc-smooth-generator/releases) and browse the repository for more documentation.


---

## Tools for low-code development

*Source: getting-started/tools-for-low-code-development.md*

# Tools for low-code development

## Introduction

This guide provides an introduction to low-code solutions, such as Gutenberg and WooCommerce Store Editing, as well as other page builders and pre-built components for creating WooCommerce stores without custom coding. By understanding and leveraging these tools, low code builders can assemble stores with minimal coding and focus on the design and user experience aspects of their e-commerce websites.

## Audience

This guide is intended for low code builders or anyone with a basic understanding of WordPress and WooCommerce who wants to create online stores without the need for extensive custom coding.

## Prerequisites

To follow this guide, you should have:

1. A basic understanding of WordPress and WooCommerce.
2. A WordPress website with WooCommerce installed and activated.

## Step 1 - Using Gutenberg and WooCommerce Store Editing

Gutenberg is the default block editor in WordPress that allows you to create and edit pages by adding and customizing blocks. WooCommerce has extended Gutenberg's functionality, enabling you to create and customize WooCommerce-specific elements, such as product pages and shop pages.

To use Gutenberg and WooCommerce Store Editing:

1. Ensure your WordPress installation is up-to-date to have the latest version of Gutenberg.
2. Install and activate a Block Theme to enable Store Editing features for WooCommerce.

With Gutenberg and WooCommerce Store Editing, you can create and customize your store's pages using a wide variety of blocks, such as text, images, buttons, and WooCommerce-specific blocks like product grids and shopping carts.

## Step 2 - Exploring alternative page builders

While Gutenberg and WooCommerce Store Editing are powerful options for building low-code WooCommerce stores, you may also consider using other page builders for more advanced features or specific use cases. Some popular page builders compatible with WooCommerce include:

1. Elementor
2. Beaver Builder
3. Divi Builder
4. WPBakery Page Builder

Choose a page builder that fits your needs and budget, then install and activate it on your WordPress website. These page builders typically offer a library of pre-built components that you can use to create a fully functional WooCommerce store without writing custom code.

## Step 3 - Utilizing pre-built components and templates

Many page builders, including Gutenberg, offer pre-built components or blocks that can be easily added to your pages. These components can include design elements like buttons, forms, and image galleries, as well as WooCommerce-specific components like product grids and shopping carts.

Additionally, some page builders and WooCommerce extensions offer pre-built store templates that you can import and customize to create a fully functional online store quickly. These templates can save you time and effort by providing a professionally designed starting point for your store.

To use pre-built components and templates:

1. Open your preferred page builder's editor (Gutenberg or another page builder).
2. Browse through the available components/blocks or templates and find the ones that suit your needs.
3. Add the components to your pages and customize them using the provided settings and options.

## Conclusion

By leveraging low-code solutions like Gutenberg, WooCommerce Store Editing, and other page builders, you can create a fully functional WooCommerce store without the need for custom coding. This guide has introduced you to the basics of using these tools, helping you understand the available options and assemble your store with minimal coding. With the right combination of tools and templates, you can create a professional, user-friendly e-commerce website that meets your business needs.


---

## Version control and deployment

*Source: getting-started/version-control-deployment.md*

# Version control and deployment

Because WordPress and WooCommerce are both developer frameworks *and* content management systems, it’s important to plan ahead for how you will version control your code and deploy changes to a live environment. A common rule is that “code goes up, content goes down,” meaning that you’ll push your custom code up from a local or staging environment, but never the contents of your database or user-generated content that lives in the `wp-content/uploads` directory.

## Considerations

There is no one-size-fits-all approach to deploying WordPress. Your hosting environment may have a dedicated approach that you need to follow, especially at more enterprise-level hosts like [WordPress VIP](https://docs.wpvip.com/development-workflow/). 

Based on the [project structure](/docs/getting-started/project-structure) of a WordPress installation and your unique needs, you may be version controlling and deploying different parts of your `wp-content` directory. Some common approaches include:

1. Version control starts from the root directory of WordPress, but includes a `.gitignore` file that ignores most of WordPress core and plugins, if your hosting company manages WordPress updates for you. An example `.gitignore` file is available [here from GitHub](https://github.com/github/gitignore/blob/main/WordPress.gitignore) and you can update it to ensure that your custom code is version controlled. This approach is more popular with builders who are managing each site in its own repository.   
2. Version control just the directory that you are working in, typically in `wp-content/plugins/your-extension` or `wp-content/themes/your-theme`. This approach is more common for extension and theme developers who are broadly distributing their code across multiple sites.

**Note:** Do not commit your `wp-config.php` file to a public repository. It may include sensitive information and most likely it will have differences from your local and production environments. 

## Building and Deployment

Most WordPress hosting environments *do not have support* for Node or Composer. You’ll need to confirm with the environment that you’re deploying to, but keep this in mind when setting up your workflow. Some popular approaches include:

1. Committing built files to your repository. Plugins and themes that come from the WordPress.org directory, for example, include all built assets for easy updates.  
2. Adding a build step via a tool like GitHub Actions or a separate CI/CD pipeline.


---

## Cart and checkout blocks theming

*Source: theming/block-theme-development/cart-and-checkout.md*

# Cart and checkout blocks theming 

> [!IMPORTANT]
> We strongly discourage writing CSS code based on existing block class names and prioritize using global styles when possible. We especially discourage writing CSS selectors that rely on a specific block being a descendant of another one, as users can move blocks around freely, so they are prone to breaking. Similar to WordPress itself, we consider the HTML structure within components, blocks, and block templates to be "private", and subject to further change in the future, so using CSS to target the internals of a block or a block template is _not recommended or supported_.

If your theme overrides `page-cart.html` or `page-checkout.html`, keep the Cart and Checkout blocks in the assigned page content and render that content from the template with `core/post-content`. See [Cart and Checkout page templates](/docs/theming/block-theme-development/theming-woo-blocks#cart-and-checkout-page-templates) for the recommended template structure.

## Buttons

WC Blocks introduces the button component, it differs from a generic `button` in that it has some default styles to make it correctly fit in the Blocks design.

![Button screenshot](https://user-images.githubusercontent.com/3616980/86381945-e6fd6c00-bc8d-11ea-8811-7e546bea69b9.png)

Themes can still style them to match theme colors or styles as follows:

```css
.wc-block-components-button {
	background-color: #d5502f;
	color: #fff;
	/* More rules can be added to modify the border, shadow, etc. */
}
/* It might be needed to modify the hover, focus, active and disabled states too */
```

![Button screenshot with custom styles](https://user-images.githubusercontent.com/3616980/86381505-b6b5cd80-bc8d-11ea-8ceb-cfbe84b411d4.png)

Notice the button component doesn't have the `.button` class name. So themes that wrote some styles for buttons might want to apply some (or all) of those styles to the button component as well.

## Mobile submit container

In small viewports, the Cart block displays the _Proceed to Checkout_ button inside a container fixed at the bottom of the screen.

![Submit container screenshot](https://user-images.githubusercontent.com/3616980/86382876-393e8d00-bc8e-11ea-8d0b-e4e347ea4773.png)

By default, the container has a white background so it plays well with the button component default colors. Themes that want to apply the same background color as the rest of the page can do it with the following code snippet:

```css
.wc-block-cart__submit-container {
	background-color: #f9f4ee;
}
```

Take into consideration the container has a top box shadow that might not play well with some dark background colors. If needed, it can be modified directly setting the `color` property (internally, shadow color uses `currentColor`, so it honors the `color` property):

```css
.wc-block-cart__submit-container::before {
	color: rgba( 214, 209, 203, 0.5 );
}
```

Alternatively, themes can override the `box-shadow` property completely:

```css
.wc-block-cart__submit-container::before {
	box-shadow: 0 -10px 20px 10px rgba( 214, 209, 203, 0.5 );
}
```

![Submit container screenshot with custom styles](https://user-images.githubusercontent.com/3616980/86382693-27f58080-bc8e-11ea-894e-de378af3e2bb.png)

## Item quantity badge

The item quantity badge is the number that appears next to the image in the _Order summary_ section of the _Checkout_ block sidebar.

![Order summary screenshot](https://user-images.githubusercontent.com/3616980/83862844-c8559500-a722-11ea-9653-2fc8bcd544d2.png)

By default, it uses a combination of black and white borders and shadows so it has enough contrast with themes with light and dark backgrounds. Themes can modify the colors with their own palette with a single CSS selector and four properties. For example:

```css
.wc-block-components-order-summary-item__quantity {
	background-color: #f9f4ee;
	border-color: #4b3918;
	box-shadow: 0 0 0 2px #f9f4ee;
	color: #4b3918;
}
```

![Order summary screenshot with custom styles for the item quantity badge](https://user-images.githubusercontent.com/3616980/83863109-2e421c80-a723-11ea-9bf7-2033a96cf5b2.png)


---

## CSS styling for themes

*Source: theming/block-theme-development/css-styling.md*

# CSS styling for themes

## Block and component class names

> [!IMPORTANT]
> We strongly discourage writing CSS code based on existing block class names and prioritize using global styles when possible. We especially discourage writing CSS selectors that rely on a specific block being a descendant of another one, as users can move blocks around freely, so they are prone to breaking. Similar to WordPress itself, we consider the HTML structure within components, blocks, and block templates to be "private", and subject to further change in the future, so using CSS to target the internals of a block or a block template is _not recommended or supported_.

WooCommerce Blocks follows BEM for class names, as [stated in our coding guidelines](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/docs/contributors/coding-guidelines.md). All classes start with one of these two prefixes:

-   `.wc-block-`: class names specific to a single block.
-   `.wc-block-components-`: class names specific to a component. The component might be reused by different blocks.

The combination of block class names and component class names allows themes to style each component either globally or only in specific blocks. As an example, you could style all prices to be italics with:

```css
/* This will apply to all block prices */
.wc-block-components-formatted-money-amount {
	font-style: italic;
}
```

But if you only wanted to make it italic in the Checkout block, that could be done adding the block selector:

```css
/* This will apply to prices in the checkout block */
.wc-block-checkout .wc-block-components-formatted-money-amount {
	font-style: italic;
}
```

**Note:** for backwards compatibility, some components might have class names with both prefixes (ie: `wc-block-sort-select` and `wc-block-components-sort-select`). In those cases, the class name with `.wc-block-` prefix is deprecated and shouldn't be used in new code. It will be removed in future versions. If an element has both classes always style the one with `.wc-block-components-` prefix.

## Container query class names

Some of our components have responsive classes depending on the container width. The reason to use these classes instead of CSS media queries is to adapt to the container where the block is added (CSS media queries only allow reacting to viewport sizes).

Those classes are:

| Container width | Class name  |
| --------------- | ----------- |
| \>700px         | `is-large`  |
| 521px-700px     | `is-medium` |
| 401px-520px     | `is-small`  |
| \<=400px        | `is-mobile` |

As an example, if we wanted to do the Checkout font size 10% larger when the container has a width of 521px or wider, we could do so with this code:

```css
.wc-block-checkout.is-medium,
.wc-block-checkout.is-large {
	font-size: 1.1em;
}
```

### CSS Container Queries for Cart and Checkout blocks

WooCommerce defines the top-level wrappers of Cart and Checkout blocks as CSS containers. These containers use `container-type: inline-size`:

```css
.wp-block-woocommerce-checkout {
	container-type: inline-size;
}
```

Developers can use CSS Container Queries (`@container`) to style child components based on parent width, eliminating the need for JS-added classes such as `.is-large` which are considered legacy. Legacy classes remain in place for backwards compatibility, but we recommend using the container approach for cleaner styling and fewer layout shifts.

**Note:** Container queries work as long as there isn't another container in between the checkout blocks wrapper and the element being styled. If you define additional CSS containers in your theme or plugins, they may interfere with the container query behavior.

There are SCSS mixins available as convenient helpers for targeting the same width breakpoints previously defined by classes like `.is-large`, `.is-medium`, `.is-small` and `.is-mobile`. These mixins make it easier to style inner content within the Cart and Checkout blocks based on the container width.

```scss
// Before, using JS generated CSS class
.is-large {
	.your-class {
		padding: 2rem;
	}
}

// After, using the container mixin
@include cart-checkout-large-container {
	.your-class {
		padding: 2rem;
	}
}

// After, using pure CSS
@container (min-width: 700px) {
	.your-class {
		padding: 2rem;
	}
}
```

## WC Blocks _vs._ theme style conflicts for semantic elements

WooCommerce Blocks uses HTML elements according to their semantic meaning, not their default layout. That means that some times blocks might use an anchor link (`<a>`) but display it as a button. Or the other way around, a `<button>` might be displayed as a text link. Similarly, headings might be displayed as regular text.

In these cases, Blocks include some CSS resets to undo most default styles introduced by themes. A `<button>` that is displayed as a text link will probably have resets for the background, border, etc. That will solve most conflicts out-of-the-box but in some occasions those CSS resets might not have effect if the theme has a specific CSS selector with higher specificity. When that happens, we really encourage theme developers to decrease their selectors specificity so Blocks styles have preference, if that's not possible, themes can write CSS resets on top.

## Hidden elements

WC Blocks use the [`hidden` HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/hidden) to hide some elements from the UI so they are not displayed in screens neither read by assistive technologies. If your theme has some generic styles that tweak the CSS display property of blocks elements (ie: `div { display: block; }`), make sure you correctly handle the hidden attribute: `div[hidden] { display: none; }`.

## Legacy classes from WooCommerce (.price, .star-rating, .button...)

WooCommerce Blocks avoids using legacy unprefixed classes as much as possible. However, you might find some of them that have been added for backwards compatibility. We still encourage themes to use the prefixed classes when possible, this avoids conflicts with other plugins, the editor, etc.


---

## Theming for Woo blocks

*Source: theming/block-theme-development/theming-woo-blocks.md*

# Theming for Woo blocks

---

**Note:** We're assuming you have some previous knowledge about block theme development and some WordPress concepts. If you are completely new to block theme development, please check [Develop Your First Low-Code Block Theme](https://learn.wordpress.org/course/develop-your-first-low-code-block-theme/)
to learn about block theme development, and explore
the [Create Block Theme plugin](https://wordpress.org/plugins/create-block-theme/) tool when you're ready to create a new theme.

---

## General concepts

### Block templates

WooCommerce comes with several [block templates](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/templates/templates/blockified) by default. Those are:

- Single Product (`single-product.html`)
- Product Catalog (`archive-product.html`)
    - Products by Category (`taxonomy-product_cat.html`)
    - Products by Tag (`taxonomy-product_tag.html`)
    - Products by Attribute (`taxonomy-product_attribute.html`)
- Product Search Results (`product-search-results.html`)
- Page: Coming soon (`page-coming-soon.html`)
- Page: Cart (`page-cart.html`)
- Page: Checkout (`page-checkout.html`)
- Order Confirmation (`order-confirmation.html`)

Block themes can customize those templates in the following ways:

- It's possible to override the templates by creating a file with the same file name under the `/templates` folder. For example, if a block theme contains a `wp-content/themes/yourtheme/templates/single-product.html` template, it will take priority over the WooCommerce default Single Product template.
- Products by Category, Products by Tag and Products by Attribute templates fall back to the Product Catalog template. In other words, if a theme provides an `archive-product.html` template but doesn't provide a `taxonomy-product_cat.html` template, the Products by Category template will use the `archive-product.html` template. Same for the Products by Tag and Products by Attribute templates.
- It's possible to create templates for specific products and taxonomies. For example, if the theme provides a template with file name of `single-product-cap.html`, that template will be used when rendering the product with slug `cap`. Similarly, themes can provide specific taxonomy templates: `taxonomy-product_cat-clothing.html` would be used in the product category with slug `clothing`.
- Always keep in mind users can make modifications to the templates provided by the theme via the Site Editor.

#### Cart and Checkout page templates

The `page-cart.html` and `page-checkout.html` templates should render the content from the assigned Cart and Checkout pages. Add layout, headers, footers, and other template-level content around the page content, but keep the Cart and Checkout blocks in the corresponding page content.

WooCommerce's default `page-cart.html` template uses the `woocommerce/page-content-wrapper` block with `woocommerce/store-notices`, `core/post-title`, and `core/post-content` inside it:

```html
<!-- wp:woocommerce/page-content-wrapper {"page":"cart"} -->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:woocommerce/store-notices /-->
    <!-- wp:post-title {"align":"wide", "level":1} /-->
    <!-- wp:post-content {"align":"wide"} /-->
</main>
<!-- /wp:group -->
<!-- /wp:woocommerce/page-content-wrapper -->
```

The default `page-checkout.html` template uses the same wrapper and store notices, but renders page content without a page title:

```html
<!-- wp:woocommerce/page-content-wrapper {"page":"checkout"} -->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:woocommerce/store-notices /-->
    <!-- wp:post-content {"align":"wide"} /-->
</main>
<!-- /wp:group -->
<!-- /wp:woocommerce/page-content-wrapper -->
```

Use the same pattern when overriding `page-cart.html` or `page-checkout.html` in a theme. Avoid placing `woocommerce/cart` or `woocommerce/checkout` directly in these template files as a replacement for `core/post-content`. If the template bypasses page content, the page editor can become out of sync with what shoppers see, and WooCommerce features that inspect the assigned page content may not detect the Cart or Checkout block correctly.

### Block template parts

WooCommerce also comes with two specific [block template parts](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/templates/parts):

- Mini-Cart (`mini-cart.html`): used inside the Mini-Cart block drawer.
- Checkout header (`checkout-header.html`): used as the header in the Checkout template.

Similarly to the templates, they can be overridden by themes by adding a file with the same file name under the `/parts` folder.

### Global styles

WooCommerce blocks rely on [global styles](https://developer.wordpress.org/themes/global-settings-and-styles/styles/) for their styling. Global styles can be defined by themes via `theme.json` or by users via Appearance > Editor > Styles and offer several advantages over plain CSS:

- Better performance, as only the required CSS is printed into the page, reducing the bundle size to render a page.
- Can be easily customized by users via the UI.
- Gracefully handle conflicts between plugins and themes.
- Are not affected by markup or class name updates into individual blocks or components.
- Don't depend on a specific nesting order of blocks: users can freely move blocks around without styles breaking.

#### Example

For example, let's imagine you are building a theme and would like to customize the Product Price block styles, you can do so by adding these properties in your `theme.json`:

```JSON
"styles": {
	"blocks": {
		"woocommerce/product-price": {
			"color": {
				"background": "#00cc00",
				"text": "#fff"
			},
			"typography": {
				"fontStyle": "italic",
				"fontWeight": "700"
			}
		}
		...
	}
	...
}
```

| Before | After |
| --- | --- |
| ![Product Collection block showing the Product Price block with default styles](https://github.com/woocommerce/woocommerce/assets/3616980/fbc11b83-f47b-4b25-bdeb-df798b251cce) | ![Product Collection block showing the Product Price styled with background and text colors and italic and bold typography](https://github.com/woocommerce/woocommerce/assets/3616980/c9730445-b9df-4e96-8204-a10896ac2c5a) |

You can find more [documentation on global styles](https://developer.wordpress.org/themes/global-settings-and-styles/styles/) in developer.wordpress.org. You can also find the [list of WooCommerce blocks and their names in the docs](/docs/block-development/reference/block-references).


---

## Theme design guidelines

*Source: theming/theme-design.md*

# Theme design guidelines

This page covers general guidelines and best practices to follow so your theme experience aligns with ecommerce industry standards and WooCommerce. A strong theme design should support a great online shopping experience, maximize sales, remain easy to use, integrate cleanly, and encourage strong UX adoption.

We recommend you review the [UI best practices for WordPress](https://developer.wordpress.org/themes/advanced-topics/ui-best-practices/) to ensure your theme is aligned with the WordPress theme requirements.

Make sure your theme fits one or more industries currently available in the [WooCommerce themes store](https://woocommerce.com/product-category/themes). The theme should offer enough originality and distinctiveness in its design, while keeping it familiar, to be distinguished from other themes on the WooCommerce theme store. Your theme should avoid copying existing themes on the WooCommerce theme store or other WordPress theme marketplaces.

## Design

High-quality design is an important aspect of an online store, and that is driven by the theme design and content. The design of the theme should be simple, consistent, uncluttered, memorable, intuitive, efficient, and functional. When designing a new theme for WooCommerce, pay special attention to the following areas.

### Layout

The theme should be up to industry standards in terms of hierarchy, flow, content balance, and white space.

Theme authors must ensure that store pages, such as shop, product page, categories, cart, checkout, and profile pages, fit seamlessly with the theme since they are the central point of a WooCommerce theme.

The theme is expected to be fully functional and optimized for common device types such as laptops, tablets, and smartphones.

### Typography

The theme should provide elegant and legible font pairings that promote a comfortable reading experience.

Consistent and harmonious font sizes, line widths, and spacing must be employed across all pages and device types.

The theme typography must consist of a small number of typefaces that complement each other, generally no more than two.

Use proper capitalization, avoiding all caps with the exception of some UI elements such as buttons and tabs.

### Iconography

Icons used in the theme should portray a direct meaning of the actions or situations they represent and be used consistently regarding sizing, positioning, and color.

### Color

The theme must follow a harmonious and consistent color scheme across UI elements and all pages. The color scheme should consist of a small number of colors that contain:

- A primary or accent dominant color
- One or two secondary colors that complement the primary color
- Neutral colors, such as white, black, and gray

The color palette used in text and graphical UI components must be compliant with the [WCAG AA conformance level](https://www.w3.org/TR/WCAG20/#conformance) or above.

### Patterns

The theme must employ a consistent set of patterns that are used across pages, such as:

- Navigation, sidebars, and footer
- Content blocks, such as titles, paragraphs, lists, product details, reviews, and image showcases
- Forms structure and elements, such as fields, drop-downs, and buttons
- Tables
- Lists
- Notices

## Accessibility

Your theme must meet the [WordPress Accessibility Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/).

For more information on accessibility, check out the [WordPress accessibility quick start guide](https://make.wordpress.org/accessibility/handbook/best-practices/quick-start-guide/).

## Branding

The theme must not contain any branding or references to theme authors in locations that interfere with the normal operation of an online store. Theme authors can include links to their websites on the theme footer. Affiliate linking is not permitted.

The interface should solely focus on the experience. The usage of notices, banners, large logos, or any promotional materials is not allowed in the admin interface.

## Customization

> This section applies to development of non-block themes only. For more specific guidance on development of block themes, refer to the [WordPress Developer's Guide to Block Themes](https://learn.wordpress.org/course/a-developers-guide-to-block-themes-part-1/).

Themes have to rely on the customizer for any type of initial setup. Specific onboarding flows are not permitted.

Any customization supported by the theme, such as layout options, additional features, block options, etc, should be delivered in the customizer or on block settings for blocks that are included in the theme.

Themes should not bundle or require the installation of additional plugins/extensions or frameworks that provide additional options or functionality. For more information on customization, check out the [WordPress theme customization API](https://codex.wordpress.org/Theme_Customization_API).

On activation, themes shouldn't override the WordPress theme activation flow by taking the user into other pages.

## Demos and sample content

Upon submission, theme authors must provide a way for the theme to be showcased and tested. The sample content or demo should refrain from using custom graphics or assets that will not be present in the deliverables to avoid merchant confusion and broken expectations, such as using logos or illustrations. When creating a theme for a specific vertical, theme authors should consider using sample content that aligns with the vertical.

All imagery and text should be appropriate for all ages and family-friendly. The theme author should consider using imagery that is inclusive of ages, nationalities, etc. The theme should refrain from using imagery that looks like stock photography.

The theme must be distributed and cleared of all the necessary licenses for assets such as images, fonts, icons, etc.


---

## Classic theme development handbook

*Source: theming/theme-development/classic-theme-developer-handbook.md*

# Classic theme development handbook

---

**Note:** this document is geared toward the development of classic themes. Check this other document for [block theme development](../block-theme-development/theming-woo-blocks.md).

---

WooCommerce looks great with all WordPress themes as of version 3.3, even if they are not WooCommerce-specific themes and do not formally declare support. Templates render inside the content, and this keeps everything looking natural on your site.

Non-WooCommerce themes, by default, also include:

- Zoom feature enabled - ability to zoom in/out on a product image
- Lightbox feature enabled - product gallery images pop up to examine closer
- Comments enabled, not Reviews - visitors/buyers can leave comments as opposed to product ratings or reviews

If you want more control over the layout of WooCommerce elements or full reviews support your theme will need to integrate with WooCommerce. There are a few different ways you can do this, and they are outlined below.

## Theme Integration

There are three possible ways to integrate WooCommerce with a theme. If you are using WooCommerce 3.2 or below (**strongly discouraged**) you will need to use one of these methods to ensure WooCommerce shop and product pages are rendered correctly in your theme. If you are using a version of WooCommerce 3.3 or above you only need to do a theme integration if the automatic one doesn't meet your needs.

### Using `woocommerce_content()`

This solution allows you to create a new template page within your theme that is used for **all WooCommerce taxonomy and post type displays**. While an easy catch-all solution, it does have a drawback in that this template is used for **all WooCommerce taxonomies** (product categories, etc.) and **post types** (product archives, single product pages). Developers are encouraged to use the hooks instead (see below).

To set up this template page:

1. **Duplicate page.php:** Duplicate your theme's `page.php` file, and name it `woocommerce.php`. This path to the file should follow this pattern: `wp-content/themes/YOURTHEME/woocommerce.php`.
2. **Edit your page (woocommerce.php)**: Open up your newly created `woocommerce.php` in a text editor.
3. **Replace the loop:** Next you need to find the loop (see [The_Loop](https://codex.wordpress.org/The_Loop)). The loop usually starts with code like this:

```php
<?php if ( have_posts() ) :
```

It usually ends with this:

```php
<?php endif; ?>
```

This varies between themes. Once you have found it, **delete it**. In its place, put:

```php
<?php woocommerce_content(); ?>
```

This will make it use **WooCommerce's loop instead**. Save the file. You're done.

**Note:** When creating `woocommerce.php` in your theme's folder, you will not be able to override the `woocommerce/archive-product.php` custom template as `woocommerce.php` has priority over `archive-product.php`. This is intended to prevent display issues.

### Using hooks

The hook method is more involved, but it is also more flexible. This is similar to the method we use when creating themes. It's also the method we use to integrate nicely with WordPress default themes.

Insert a few lines in your theme's `functions.php` file.

First unhook the WooCommerce wrappers:

```php
remove_action( 'woocommerce_before_main_content', 'woocommerce_output_content_wrapper', 10);
remove_action( 'woocommerce_after_main_content', 'woocommerce_output_content_wrapper_end', 10);
```

Then hook in your own functions to display the wrappers your theme requires:

```php
add_action('woocommerce_before_main_content', 'my_theme_wrapper_start', 10);
add_action('woocommerce_after_main_content', 'my_theme_wrapper_end', 10);

function my_theme_wrapper_start() {
    echo '<section id="main">';
}

function my_theme_wrapper_end() {
    echo '</section>';
}
```

Make sure that the markup matches that of your theme. If you're unsure of which classes or IDs to use, take a look at your theme's `page.php` for guidance.

**Whenever possible use the hooks to add or remove content. This method is more robust than overriding the templates.** If you have overridden a template, you have to update the template any time the file changes. If you are using the hooks, you will only have to update if the hooks change, which happens much less frequently.

### Using template overrides

For information about overriding the WooCommerce templates with your own custom templates read the **Template Structure** section below. This method requires more maintenance than the hook-based method, as templates will need to be kept up-to-date with the WooCommerce core templates.

## Declaring WooCommerce Support

If you are using custom WooCommerce template overrides in your theme you need to declare WooCommerce support using the `add_theme_support` function. WooCommerce template overrides are only enabled on themes that declare WooCommerce support. If you do not declare WooCommerce support in your theme, WooCommerce will assume the theme is not designed for WooCommerce compatibility and will use shortcode-based unsupported theme rendering to display the shop.

Declaring WooCommerce support is straightforward and involves adding one function in your theme's `functions.php` file.

### Basic Usage

```php
function mytheme_add_woocommerce_support() {
    add_theme_support( 'woocommerce' );
}

add_action( 'after_setup_theme', 'mytheme_add_woocommerce_support' );
```

Make sure you are using the `after_setup_theme` hook and not the `init` hook. Read more about this in [the documentation for `add_theme_support`](https://developer.wordpress.org/reference/functions/add_theme_support/).

### Usage with Settings

```php
function mytheme_add_woocommerce_support() {
    add_theme_support( 'woocommerce', array(
        'thumbnail_image_width' => 150,
        'single_image_width'    => 300,

        'product_grid'          => array(
            'default_rows'    => 3,
            'min_rows'        => 2,
            'max_rows'        => 8,
            'default_columns' => 4,
            'min_columns'     => 2,
            'max_columns'     => 5,
        ),
    ) );
}

add_action( 'after_setup_theme', 'mytheme_add_woocommerce_support' );
```

These are optional theme settings that you can set when declaring WooCommerce support.

`thumbnail_image_width` and `single_image_width` will set the image sizes for the shop. If these are not declared when adding theme support, the user can set image sizes in the Customizer under the **WooCommerce > Product Images** section.

The `product_grid` settings let theme developers set default, minimum, and maximum column and row settings for the Shop. Users can set the rows and columns in the Customizer under the **WooCommerce > Product Catalog** section.

### Product gallery features (zoom, swipe, lightbox)

The product gallery introduced in 3.0.0 ([read here for more information](https://developer.woocommerce.com/2016/10/19/new-product-gallery-merged-in-to-core-for-2-7/)) uses Flexslider, Photoswipe, and the jQuery Zoom plugin to offer swiping, lightboxes, and other neat features.

In versions `3.0`, `3.1`, and `3.2`, the new gallery is off by default and needs to be enabled using a snippet (below) or by using a compatible theme. This is because it's common for themes to disable the WooCommerce gallery and replace it with their own scripts.

In versions `3.3+`, the gallery is off by default for WooCommerce compatible themes unless they declare support for it (below). 3rd party themes with no WooCommerce support will have the gallery enabled by default.

To enable the gallery in your theme, you can declare support like this:

```php
add_theme_support( 'wc-product-gallery-zoom' );
add_theme_support( 'wc-product-gallery-lightbox' );
add_theme_support( 'wc-product-gallery-slider' );
```

You do not have to support all three parts of the gallery; you can pick and choose features. If a feature is not enabled, the scripts will not be loaded and the gallery code will not execute on product pages.

If gallery features are enabled (e.g., you have a theme that enabled them, or you are running a theme that is not compatible with WooCommerce), you can disable them with `remove_theme_support`:

```php
remove_theme_support( 'wc-product-gallery-zoom' );
remove_theme_support( 'wc-product-gallery-lightbox' );
remove_theme_support( 'wc-product-gallery-slider' );
```

You can disable any parts; you do not need to disable all features.

## Template Structure

WooCommerce template files contain the **markup** and **template structure** for **the frontend and the HTML emails** of your store. If some structural change in HTML is necessary, you should override a template.

When you open these files, you will notice they all contain **hooks** that allow you to add or move content without needing to edit the template files themselves. This method protects against upgrade issues, as the template files can be left completely untouched.

Template files can be found within the `**/woocommerce/templates/**` directory.

### How to Edit Files

Edit files in an **upgrade-safe way** using *overrides*. Copy them into a directory within your theme named `/woocommerce`, keeping the same file structure but removing the `/templates/` subdirectory.

Example: To override the admin order notification, copy `wp-content/plugins/woocommerce/templates/emails/admin-new-order.php` to `wp-content/themes/yourtheme/woocommerce/emails/admin-new-order.php`.

The copied file will now override the WooCommerce default template file.

**Warning:** Do not delete any WooCommerce hooks when overriding a template. This would prevent plugins hooking in to add content.

**Warning:** Do not edit these files within the core plugin itselfe as they are overwritten during the upgrade process and any customizations will be lost.

## CSS Structure

Inside the `assets/css/` directory, you will find the stylesheets responsible for the default WooCommerce layout styles.

Files to look for are `woocommerce.scss` and `woocommerce.css`.

- `woocommerce.css` is the minified stylesheet - it's the CSS without any of the spaces, indents, etc. This makes the file very fast to load. This file is referenced by the plugin and declares all WooCommerce styles.
- `woocommerce.scss` is not directly used by the plugin, but by the team developing WooCommerce. We use [SASS](http://sass-lang.com/) in this file to generate the CSS in the first file.

The CSS is written to make the default layout compatible with as many themes as possible by using percentage-based widths for all layout styles. It is, however, likely that you'll want to make your own adjustments.

### Modifications

To avoid upgrade issues, we advise not editing these files but rather using them as a point of reference.

If you just want to make changes, we recommend adding some overriding styles to your theme stylesheet. For example, add the following to your theme stylesheet to make WooCommerce buttons black instead of the default color:

```css
a.button, 
button.button, 
input.button, 
#review_form #submit {
    background:black; 
}
```

WooCommerce also outputs the theme name (plus other useful information, such as which type of page is being viewed) as a class on the body tag, which can be useful for overriding styles.

### Disabling WooCommerce styles

If you plan to make major changes, or create a theme from scratch, then you may prefer your theme not reference the WooCommerce stylesheet at all. You can tell WooCommerce to not use the default `woocommerce.css` by adding the following code to your theme's `functions.php` file:

```php
add_filter( 'woocommerce_enqueue_styles', '__return_false' );
```

With this definition in place, your theme will no longer use the WooCommerce stylesheet and give you a blank canvas upon which you can build your own desired layout and styles.

Styling a WooCommerce theme from scratch for the first time is no easy task. There are many different pages and elements that need to be styled, and if you're new to WooCommerce, you are probably not familiar with many of them. A non-exhaustive list of WooCommerce elements to style can be found in this [WooCommerce Theme Testing Checklist](https://developer.files.wordpress.com/2017/12/woocommerce-theme-testing-checklist.pdf).


---

## Conditional tags in WooCommerce

*Source: theming/theme-development/conditional-tags.md*

# Conditional tags in WooCommerce

## What are "conditional tags"?

The conditional tags of WooCommerce and WordPress can be used in your template files to change what content is displayed based on what *conditions* the page matches. For example, you may want to display a snippet of text above the shop page. With the `is_shop()` conditional tag, you can.

Because WooCommerce uses custom post types, you can also use many of WordPress' conditional tags. See [codex.wordpress.org/Conditional_Tags](https://codex.wordpress.org/Conditional_Tags) for a list of the tags included with WordPress.

**Note**: You can only use conditional query tags after the `posts_selection` [action hook](https://codex.wordpress.org/Plugin_API/Action_Reference#Actions_Run_During_a_Typical_Request) in WordPress (the `wp` action hook is the first one through which you can use these conditionals). For themes, this means the conditional tag will never work properly if you are using it in the body of functions.php. If a conditional tag is used before it's supposed to, it won't trigger any error or warning: it will simply return `false`, even if the condition it checks for would be met later in the request.

## Available conditional tags

All conditional tags test whether a condition is met, and then return either `TRUE` or `FALSE`. **Conditions under which tags output `TRUE` are listed below the conditional tags**.

The list below holds the main conditional tags. To see all conditional tags, visit the [WooCommerce API Docs](https://woocommerce.com/wc-apidocs/).

### WooCommerce page

- `is_woocommerce()`  
  Returns true if on a page which uses WooCommerce templates (cart and checkout are standard pages with shortcodes and thus are not included).

### Main shop page

- `is_shop()`  
  Returns true when on the product archive page (shop).

### Product category page

- `is_product_category()`  
  Returns true when viewing a product category archive.
- `is_product_category( 'shirts' )`  
  When the product category page for the 'shirts' category is being displayed.
- `is_product_category( array( 'shirts', 'games' ) )`  
  When the product category page for the 'shirts' or 'games' category is being displayed.

### Product tag page

- `is_product_tag()`  
  Returns true when viewing a product tag archive
- `is_product_tag( 'shirts' )`  
  When the product tag page for the 'shirts' tag is being displayed.
- `is_product_tag( array( 'shirts', 'games' ) )`  
  When the product tag page for the 'shirts' or 'games' tags is being displayed.

### Single product page

- `is_product()`  
  Returns true on a single product page. Wrapper for is_singular.

### Cart page

- `is_cart()`  
  Returns true on the cart page.

### Checkout page

- `is_checkout()`  
  Returns true on the checkout page.

### Customer account pages

- `is_account_page()`  
  Returns true on the customer's account pages.

### Endpoint

- `is_wc_endpoint_url()`  
  Returns true when viewing a WooCommerce endpoint
- `is_wc_endpoint_url( 'order-pay' )`  
  When the endpoint page for order pay is being displayed.
- And so on for other endpoints...

### Ajax request

- `is_ajax()`  
  Returns true when the page is loaded via ajax.

## Working example

The example illustrates how you would display different content for different categories.

```php
if ( is_product_category() ) {

  if ( is_product_category( 'shirts' ) ) {
    echo 'Hi! Take a look at our sweet t-shirts below.';
  } elseif ( is_product_category( 'games' ) ) {
    echo 'Hi! Hungry for some gaming?';
  } else {
    echo 'Hi! Check out our products below.';
  }

}
```


---

## How to fix outdated WooCommerce templates

*Source: theming/theme-development/fixing-outdated-woocommerce-templates.md*

# How to fix outdated WooCommerce templates

## Template Updates and Changes

We sometimes update the default templates when a new version of WooCommerce is released. This applies to major releases (WooCommerce 2.6, 3.0, and 4.0) but also to minor releases (WooCommerce 3.8.0).

Starting in WooCommerce version 3.3, most themes look great with WooCommerce. 

[Our developer-focused blog](https://developer.woocommerce.com/blog/) will list any template file changes with each release. You may need to update templates yourself or contact the theme author for an update if:

- you are using a theme with older templates or an older version of WooCommerce, or
- you modified templates or are using a child theme.

Most theme authors fix themes in a timely manner, so you only need to update your theme to get the updated templates.

Alternatively, you can select and use a different theme that already uses current WooCommerce templates.

## How to Update Outdated Templates

You need to determine what templates to update, make a backup of the old templates, and then restore any customizations.

1. Go to WooCommerce > Status > System Status. Scroll to the end of the page where there is a list of templates overridden by your theme/child theme and a warning message that they need to be updated.
2. Save a backup of the outdated template.
3. Copy the default template from `wp-content/plugins/woocommerce/templates/[path-to-the-template]` and paste it in your theme folder found at `wp-content/themes/[path-to-theme]`.
4. Open the template you pasted into the theme folder with a text editor, such as Sublime, Visual Studio Code, BBEdit, Notepad++, and replicate any changes that you had to the previous template in your new, updated template file.

We recognize that it can be time-consuming. This is why we try to avoid changing WooCommerce templates, but sometimes it is wise to break backward compatibility.

## FAQ

### Where can I find the latest version of WooCommerce?

If you are looking for the default templates to use for updating, you want to use the latest version of WooCommerce. There are a few easy ways to get the templates:

- Access the files via FTP if your current WooCommerce installation is up to date.
- Find the templates per WooCommerce version in our [Template Structure documentation](https://woocommerce.com/document/template-structure/).
- Download the latest version from [the WordPress.org plugin page](https://wordpress.org/plugins/woocommerce/).
- Download the latest release from [the GitHub repository](https://github.com/woocommerce/woocommerce/releases).

### Why don't you make a button to click and update everything?

It is impossible to make a video or a one-click update. Why? Because there are thousands of themes, and every theme is coded differently. One size does not fit all.


---

## Image sizing for theme developers

*Source: theming/theme-development/image-sizes.md*

# Image sizing for theme developers

**Note:** this document was created for use when developing classic themes (as opposed to block themes). Check this other document for [block theme development](../block-theme-development/theming-woo-blocks.md).

To display images in your catalog, WooCommerce registers a few image sizes which define the actual image dimensions to be used. These sizes include:

- `woocommerce_thumbnail` - used in the product 'grids' in places such as the shop page.
- `woocommerce_single` - used on single product pages.
- `woocommerce_gallery_thumbnail` - used below the main image on the single product page to switch the gallery.

`woocommerce_single` shows the full product image, as uploaded, so is always uncropped by default. It defaults to 600px width. `woocommerce_gallery_thumbnail` is always square cropped and defaults to 100x100 pixels. This is used for navigating images in the gallery. `woocommerce_thumbnail` defaults to 300px width, square cropped so the product grids look neat. The aspect ratio for cropping can be customized by the store owner. It is important to note that despite the actual image widths that are set, themes can ultimately change the size images are displayed using CSS, and image widths may be limited by the product grid/column widths.

## Themes can define image sizes

Starting with WooCommerce 3.3.0, themes can declare what sizes should be used when declaring WooCommerce support. If a theme defines the image sizes (widths), the store owner will not be able to change them, but the size defined should be optimal for the theme.

```php
add_theme_support( 'woocommerce', array(
    'thumbnail_image_width' => 200,
    'gallery_thumbnail_image_width' => 100,
    'single_image_width' => 500,
) );
```

When calling WordPress functions which expect an image size e.g. [`wp_get_attachment_image_src`](https://developer.wordpress.org/reference/functions/wp_get_attachment_image_src), you should use the image size names - these are:

- `woocommerce_thumbnail`
- `woocommerce_single`
- `woocommerce_gallery_thumbnail`

Store owners will still be able to control aspect ratio and cropping (see below).

## Customize image sizes in the customizer

The customizer houses the options which control thumbnails in WooCommerce. ![Settings in the customizer](https://woocommerce.wordpress.com/wp-content/uploads/2017/12/imagefeature.png?w=712) If the theme is declaring image sizes, the top section will be hidden and only the cropping option will be visible. Changing the cropping option, or widths, will update the preview on the right side to show how things will look. Changes will not be visible to customers until the customizer is  'published' and [the thumbnails have been regenerated to the new dimensions](./thumbnail-image-regeneration.md). The thumbnail cropping section in the customizer allows store owners to select one of three cropping ratio settings for images in the catalog:

- 1:1 (Square cropping)
- Custom (Store owner can enter a custom aspect ratio)
- Uncropped (Preserve single image aspect ratio)

Actual image dimensions are then calculated based on the cropping option selected, and the image width.

## Changing image sizes via hooks

Whilst themes can fix image sizes at certain widths, and store owners can control widths and aspect ratios, if you need more control over thumbnail sizes there are some hooks available to you. The `wc_get_image_size` function is used by WooCommerce to get the image size dimensions. The return value of this is passed through a filter: `woocommerce_get_image_size_{SIZE_NAME_WITHOUT_WOOCOMMERCE_PREFIX}` If using this hook you'll be passed an array of sizes, similar to this:

```php
array(
    'width' => 200,
    'height' => 200,
    'crop' => 1,
)
```

So for example, if I wanted to change gallery thumbnails to be 150x150px uncropped images, you could use the following code:

```php
add_filter( 'woocommerce_get_image_size_gallery_thumbnail', function( $size ) {
    return array(
        'width' => 150,
        'height' => 150,
        'crop' => 0,
    );
} );
```

We don't recommend plugins and themes go this route because it removes control from the store owner and their settings won't be respected, but the option is there for store owners. **Note:** after making changes to image sizes you may need to [regenerate your thumbnails](https://github.com/woocommerce/woocommerce/wiki/Thumbnail-Image-Regeneration-in-3.3) so the new sizes are used for existing images.

## Changing what image sizes are used in WooCommerce via hooks

As well as the above hook, some template functions in WooCommerce run the image size through a filter so you can use something other than the WooCommerce registered image sizes. The following filters exist:

| Filter                                | Description                                                       | Default                            |
|---------------------------------------|-------------------------------------------------------------------|------------------------------------|
| `single_product_archive_thumbnail_size` | Controls the size used in the product grid/catalog.                | `woocommerce_thumbnail`            |
| `subcategory_archive_thumbnail_size`    | Controls the size used in the product grid/catalog for category images. | `woocommerce_thumbnail`            |
| `woocommerce_gallery_thumbnail_size`    | Controls the size used in the product gallery, below to main image, to switch to a different image. | Array representing the dimensions of the `gallery_thumbnail` image size. Usually `array( 100, 100 )`. |
| `woocommerce_gallery_image_size`        | Controls the size used in the product gallery.                    | `woocommerce_single`               |
| `woocommerce_gallery_full_size`         | Controls the size used in the product gallery to zoom or view the full size image. | `full`                             |

**Note:** `full` is a size registered by WordPress and set in `Settings > Media.` As an example, let's say I wanted to make the gallery thumbnail size used the `thumbnail` size registered by WordPress instead of `woocommerce_gallery_thumbnail`. The following snippet would do the job:

```php
add_filter( 'woocommerce_gallery_thumbnail_size', function( $size ) {
    return 'thumbnail';
} );
```

**Note:** The hooks listed above are used by WooCommerce core. If a theme has custom template files or uses it's own functions to output images, these filters may not be in use.


---

## How to set up and use a child theme

*Source: theming/theme-development/set-up-a-child-theme.md*

# How to set up and use a child theme

**Note:** This document is intended for creating and using classic child themes. For a comprehensive guide on creating a child block theme and understanding the differences between a classic and block theme, please refer to [WooCommerce block theme development](../block-theme-development/theming-woo-blocks.md) and [WordPress block child theme development](https://learn.wordpress.org/lesson-plan/create-a-basic-child-theme-for-block-themes/).


Sometimes, you might need to customize your theme or WooCommerce beyond what is possible via the options. These guidelines will teach you the basics of how to go about customizing your site by using a child theme.

## What is a child theme?

Before we start it's important that you understand what a child theme is. In short, a child theme is a layer that you put on top of the parent theme to make alterations without having to develop a new theme from scratch. There are two major reasons to use child themes:

- Theme developers can use child themes as a way to offer variations on a theme, similar to what we do with the [Storefront child themes](https://woocommerce.com/products/storefront/)
- Developers can use child themes to host customizations of the parent theme or any plugin on the site since the child theme will get priority over the plugins and parent theme

Read [this guide from the WordPress Codex](https://developer.wordpress.org/themes/advanced-topics/child-themes/).

## Make a backup

Before customizing a website, you should always ensure that you have a backup of your site in case anything goes wrong. More info at: [Backing up WordPress content](https://woocommerce.com/document/backup-wordpress-content/).

## Getting started

To get started, we need to prepare a child theme.

### Making the child theme

First, we need to create a new stylesheet for our child theme. Create a new file called `style.css` and put this code in it:

```css
/*
Theme Name: Child Theme
Version: 1.0
Description: Child theme for Woo.
Author: Woo
Author URI: https://woocommerce.com
Template: themedir
*/
```

Next, we need to change the **Template** field to point to our installed WooTheme. In this example, we'll use the Storefront theme, which is installed under `wp-content/themes/storefront/`. The result will look like this:

```css
/*
Theme Name: Storefront Child
Version: 1.0
Description: Child theme for Storefront.
Author: Woo
Author URI: https://woocommerce.com
Template: storefront
*/

/* --------------- Theme customization starts here ----------------- */
```

**Note:** With Storefront, you do not need to enqueue any of the parent theme style files with PHP from the theme's `functions.php` file or `@import` these into the child themes `style.css` file as the main parent Storefront theme does this for you.

With Storefront, a child theme only requires a blank `functions.php` file and a `style.css` file to get up and running.

## Uploading and activating

You can upload the child theme either through your FTP client, or using the Add New theme option in WordPress.

- **Through FTP.** If you're using FTP, it means that you go directly to the folders of your website. That means you'll need **FTP access** to your host, so you can upload the new child theme. If you don't have this, you should talk to your host and they can give you your FTP login details, and then download an FTP program to upload your files.
- **Through the WP Dashboard.** If you create a .zip file of your child theme folder you can then simply upload that to your site from the **WordPress > Appearance > Themes > Add New** section.

Once you've done that, your child theme will be uploaded to a new folder in `wp-content/themes/`, for example, `wp-content/themes/storefront-child/`. Once uploaded, we can go to our **WP Dashboard > Appearance > Themes** and activate the child theme.

## Customizing design and functionality

Your child theme is now ready to be modified. Currently, it doesn't hold any customization, so let's look at a couple of examples of how we can customize the child theme without touching the parent theme.

### Design customization

Let's do an example together where we change the color of the site title. Add this to your `/storefront-child/style.css`:

```css
.site-branding h1 a {
    color: red;
}
```

After saving the file and refreshing our browser, you will now see that the color of the site title has changed!

### Template changes

**Note:** This doesn't apply to Storefront child themes. Any customizations to a Storefront child theme's files will be lost when updating. Instead of customizing the Storefront child theme's files directly, we recommended that you add code snippets to a customization plugin. We've created one to do just this. Download [Theme Customizations](https://github.com/woocommerce/theme-customisations) for free.

But wait, there's more! You can do the same with the template files (`*.php`) in the theme folder. For example if w, wanted to modify some code in the header, we need to copy header.php from our parent theme folder `wp-content/themes/storefront/header.php` to our child theme folder `wp-content/themes/storefront-child/header.php`. Once we have copied it to our child theme, we edit `header.php` and customize any code we want. The `header.php` in the child theme will be used instead of the parent theme's `header.php`.

The same goes for WooCommerce templates. If you create a new folder in your child theme called "WooCommerce", you can make changes to the WooCommerce templates there to make it more in line with the overall design of your website. More on WooCommerce's template structure [can be found here](https://woocommerce.com/document/template-structure/).

### Functionality changes

**NOTE**: The functions.php in your child theme should be **empty** and not include anything from the parent theme's functions.php.

The `functions.php` in your child theme is loaded **before** the parent theme's `functions.php`. If a function in the parent theme is **pluggable**, it allows you to copy a function from the parent theme into the child theme's `functions.php` and have it replace the one in your parent theme. The only requirement is that the parent theme's function is **pluggable**, which basically means it is wrapped in a conditional if statement e.g:

```php
if ( ! function_exists( "parent_function_name" ) ) {
    parent_function_name() {
        ...
    }
}
```

If the parent theme function is **pluggable**, you can copy it to the child theme `functions.php` and modify the function to your liking.

## Template directory vs stylesheet directory

WordPress has a few things that it handles differently in child themes. If you have a template file in your child theme, you have to modify how WordPress includes files. `get_template_directory()` will reference the parent theme. To make it use the file in the child theme, you need to change use `get_stylesheet_directory();`.

[More info on this from the WP Codex](https://developer.wordpress.org/themes/advanced-topics/child-themes/#referencing-or-including-other-files)

## Child theme support

Although we do offer basic child theme support that can easily be answered, it still falls under theme customization, so please refer to our [support policy](https://woocommerce.com/support-policy/) to see the extent of support we give. We highly advise anybody confused with child themes to use the [WordPress forums](https://wordpress.org/support/forums/) for help.

## Sample child theme

Download the sample child theme at the top of this article to get started. Place the child theme in your **wp-content/themes/** folder along with your parent theme.


---

## Template structure & Overriding templates via a theme

*Source: theming/theme-development/template-structure.md*

# Template structure & Overriding templates via a theme

---

**NOTE** This document makes reference to classic themes which use PHP templates. If you are working on a block theme with HTML templates, [please check the Theming docs for block themes](../block-theme-development/theming-woo-blocks.md).
Overview

---

## Overview

WooCommerce template files contain the markup and template structure for the frontend and HTML emails of your store.

## Template list

The various template files on your WooCommerce site can be found via an FTP client or your hosts file manager, in `/wp-content/plugins/woocommerce/templates/`. Alternatively, you can find the [template files on our repository on GitHub](https://github.com/woocommerce/woocommerce/blob/trunk/docs/theme-development/template-structure.md).

Note: if you are looking for the template files of older versions, you can find them in these paths:

-   Versions 6.0.0 and later: `https://github.com/woocommerce/woocommerce/tree/[VERSION_NUMBER]/plugins/woocommerce/templates`
    -   For example, to find the template files for WooCommerce 9.4.0, you would navigate to [https://github.com/woocommerce/woocommerce/tree/9.4.0/plugins/woocommerce/templates](https://github.com/woocommerce/woocommerce/tree/9.4.0/plugins/woocommerce/templates).
-   Versions prior to 6.0.0: `https://github.com/woocommerce/woocommerce/tree/[VERSION_NUMBER]/templates`
    -   For example, to find the template files for WooCommerce 5.9.0, you would navigate to [https://github.com/woocommerce/woocommerce/tree/5.9.0/templates](https://github.com/woocommerce/woocommerce/tree/5.9.0/templates).

## Changing Templates via Hooks

When you open a template file, you will notice they all contain _hooks_ that allow you to add/move content without needing to edit template files themselves. Hooks are a way for one piece of code to interact/modify another piece of code at specific, pre-defined spots. This method allows implementing a code snippet that "hooks" into a particular a theme location. It avoids upgrade issues, as the template files can be left completely untouched and doesn't require a child theme to be configured.

Let's take a look at [/wp-content/plugins/woocommerce/templates/emails/admin-new-order.php](https://github.com/woocommerce/woocommerce/blob/8.9.0/plugins/woocommerce/templates/emails/admin-new-order.php) and see what a hook looks like. Starting on line 30, we see the following code, which is responsible for producing the order details section of the New Order email.

```php
/*
 * @hooked WC_Emails::order_details() Shows the order details table.
 * @hooked WC_Structured_Data::generate_order_data() Generates structured data.
 * @hooked WC_Structured_Data::output_structured_data() Outputs structured data.
 * @since 2.5.0
 */
do_action( 'woocommerce_email_order_details', $order, $sent_to_admin, $plain_text, $email );
```

The code above outputs the block highlighted in red in the image below, which is the New Order email a shop manager receives following a successful order on their site:

![image](https://woocommerce.com/wp-content/uploads/2020/05/templating-using-hooks.webp)

The code below can be used as a starting point to build out desired functionality. It can then be added to a code snippets plugin to modify the output at that particular location in the template, without having to edit the template itself. The same goes for other hooks, wherever in the templates they may appear.

```php
add_action( 'woocommerce_email_order_details', 'my_custom_woo_function');
function my_custom_woo_function() {
    /* Your code goes here */
}
```

## Changing Templates by Editing the Files

Editing files directly in a plugin or a parent theme creates the risk of causing errors that could bring a site to a grinding halt. But more importantly, any changes made in this way will disappear when the plugin or theme updates itself; a process that entirely deletes the old version and replaces it with a fresh, updated copy.

Instead, the recommended approach is to [set up a child theme](https://developer.woocommerce.com/docs/how-to-set-up-and-use-a-child-theme/), which creates a safe directory where to make overriding changes that will not be automatically updated.

For this example, let's call our child theme `storefront-child`. With `storefront-child` in place, edits can be made in an upgrade-safe way by using overrides. Copy the template into a directory within your child theme named `/storefront-child/woocommerce/` keeping the same file structure but removing the `/templates/` subdirectory.

To override the admin order notification in our example, copy `wp-content/plugins/woocommerce/templates/emails/admin-new-order.php` to `wp-content/themes/storefront-child/woocommerce/emails/admin-new-order.php`

The copied file will now override the WooCommerce default template file, so you can make any changes you wish to the copied file, and see it reflected in the resulting output.

---

**Note** A (desirable) side-effect of your templates being upgrade-safe is that WooCommerce core templates will update, but your custom overrides will not. You may occasionally see notices in your System Status report that says, e.g. "version 3.5.0 is out of date. The core version is 3.7.0". Should that happen, follow the Fixing Outdated WooCommerce Templates guide to bring them in line.

---

## Declare Theme Support for Custom Templates

If you are a theme developer or using a theme with custom templates, you must declare WooCommerce theme support using the `add_theme_support` function. See [Declaring WooCommerce Support in Themes](/docs/theming/theme-development/classic-theme-developer-handbook/#declaring-woocommerce-support).

If your theme has `woocommerce.php`, you will be unable to override `woocommerce/archive-product.php` custom template in your theme, as `woocommerce.php` has priority over other template files. This is intended to prevent display issues.

---

Need support with editing your Woo store? WooExpert agencies are here to help. They are trusted agencies with a proven track record of building highly customized, scalable online stores.
[Hire an Expert](https://woocommerce.com/customizations/).


---

## Theme design and user experience guidelines

*Source: theming/theme-development/theme-design-ux-guidelines.md*

# Theme design and user experience guidelines

This guide covers general guidelines and best practices to follow in order to ensure your theme experience aligns with ecommerce industry standards and WooCommerce for providing a great online shopping experience, maximizing sales, ensuring ease of use, seamless integration, and strong UX adoption.

We recommend you review the [UI best practices for WordPress](https://developer.wordpress.org/themes/advanced-topics/ui-best-practices/) to ensure your theme is aligned with the WordPress theme requirements.

Make sure your theme fits one or more industries currently available in the [WooCommerce themes store](https://woocommerce.com/product-category/themes). It's important that the theme offers enough originality and distinctiveness in its design, while keeping it familiar, in order to be distinguished from other themes on the WooCommerce theme store. Your theme should avoid copying existing themes on the WooCommerce theme store or other WordPress theme marketplaces.

## Design


High-quality design is an important aspect of an online store, and that is driven by the theme design and content. The design of the theme should be simple, consistent, uncluttered, memorable, intuitive, efficient, and functional. When designing a new theme for WooCommerce special attention should be given to:

### Layout

The theme should be up to industry standards in terms of hierarchy, flow, content balance, and white space.

Theme authors must ensure that store pages (shop, product page, categories, cart, checkout, profile page, etc) fit seamlessly with the theme since they are the central point of a WooCommerce theme.

The Theme is expected to be fully functional and optimized to be accessed on common device types such as laptops, tablets, and smartphones.

### Typography

The theme should provide elegant and legible font pairings that promote a comfortable reading experience.

Consistent and harmonious font sizes, line widths and spacing must be employed across all pages and device types.

The theme typography must consist of a small number of typefaces that complement each other, generally no more than two.

Proper capitalization is used, avoiding all caps (with the exception of some UI elements such as buttons, tabs, etc).

### Iconography

Icons used in the theme portray a direct meaning of the actions/situations they are representing and are used consistently regarding sizing positioning and color.

### Color

The theme must follow a harmonious and consistent color scheme across UI elements and all pages. The color scheme should consist of small number of colors that contain:

- A primary/accent dominant color
- One or two secondary colors that complement the primary
- Neutral colors (white, black, gray)

The color palette used in text and graphical UI components must be compliant with the [WCAG AA conformance level](https://www.w3.org/TR/WCAG20/#conformance) or above.

### Patterns

The theme must employ a consistent set of patterns that are used across pages, such as:

- Navigation, sidebars, footer
- Content blocks (titles, paragraphs, lists, product details, reviews, image showcases, etc)
- Forms structure and elements (fields, drop-downs, buttons, etc)
- Tables
- Lists
- Notices

## Accessibility

The theme must meet the [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG20/) (WCAG). Meeting 100% conformance with WCAG 2.0 is hard work; meet the AA level of conformance at a minimum.

For more information on accessibility, check out the [WordPress accessibility quick start guide](https://make.wordpress.org/accessibility/handbook/best-practices/quick-start-guide/).

## Customization

Themes have to rely on the customizer for any type of initial set up. Specific onboarding flows are not permitted.

Any customization supported by the theme, such as layout options, additional features, block options, etc, should be delivered in the customizer or on block settings for blocks that are included in the theme.

Themes should not bundle or require the installation of additional plugins/extensions (or frameworks) that provide additional options or functionality. For more information on customisation, check out the [WordPress theme customization API](https://codex.wordpress.org/Theme_Customization_API)**.**

On activation, themes shouldn't override the WordPress theme activation flow by taking the user into other pages.

## Branding

The theme must not contain any branding or references to theme authors in locations that interfere with the normal operation of an online store. Theme authors can include links to their websites on the theme footer. Affiliate linking is not permitted.

The interface should solely focus on the experience, the usage of notices, banners, large logos, or any promotional materials is not allowed in the admin interface.

## Demos and sample content

Upon submission theme authors must provide a way for the theme to be showcased and tested. The sample content/demo should refrain from using custom graphics/assets that will not be present in the deliverables to avoid merchant confusion and broken expectations (examples: using logos, illustrations). When creating a theme for a specific vertical theme authors should consider using sample content that aligns with the vertical.

All imagery and text should be appropriate for all ages/family-friendly. The theme author should consider using imagery that is inclusive of ages, nationalities, etc. The theme should refrain from using imagery that looks like 'stock photography'.

The theme must be distributed and cleared of all the necessary licenses for assets such as images, fonts, icons, etc.


---

## Thumbnail image regeneration

*Source: theming/theme-development/thumbnail-image-regeneration.md*

# Thumbnail image regeneration

WooCommerce 3.3 introduced thumbnail regeneration functionality. In the past when image size settings were changed you would need to install an external plugin and then have it regenerate all WordPress image thumbnails before the changes would be visible.

The new image regeneration functionality, combined with the introduction of WooCommerce image settings in the customizer, now ensure that as you make changes to your store image settings you can preview the changes in real-time within the customizer.

## How it works

When you make changes to image sizes/aspect ratios in the customiser, or if your theme changes image sizes, WC will detect these changes and queue a background regeneration job. The 2 events which can trigger this are:

- Publishing settings in the customizer
- Switching themes

Whilst in the customizer, size changes can be previewed due to our on-the-fly image regen. These changes will not be persisted to the live site until you hit publish.

### Background jobs and BasicAuth

If your site is behind BasicAuth, both async requests and background processes will fail to complete. This is because WP Background Processing relies on the WordPress HTTP API, which requires you to attach your BasicAuth credentials to requests.

You can pass these credentials via a snippet, see:[BasicAuth documentation](https://github.com/A5hleyRich/wp-background-processing#basicauth).

### Viewing background regeneration logs

To view the logs for background image regeneration go to `WooCommerce > Status > Logs` and select the `wc-background-regeneration` log from the dropdown.

This log file will list images which have been processed and when the job was completed or cancelled.

### Cancelling a background regeneration job

As of WooCommerce 3.3.2 you will see an admin notice when background image regeneration is running. Within this notice is a link to cancel the job.

Cancelling the job will stop more thumbnails being regenerated. If image sizes do not look correct inside your catalog, you'll need to run thumbnail regeneration manually (either using our tool, or using another plugin such as [Regenerate Thumbnails](https://en-gb.wordpress.org/plugins/regenerate-thumbnails/).

### CDN plugins

Most CDN plugins listen to WordPress core hooks and upload generated thumbnails to their service once created. This will continue to function with our background image regeneration code. Generation may be slower due to uploading the images to the 3rd party service as it progresses.

## How to disable background regeneration

The `woocommerce_background_image_regeneration` filter can be used to disable background regeneration completely. Example code:

```php
add_filter( 'woocommerce_background_image_regeneration', '__return_false' );
```

Once disabled, you'll need to regenerate thumbnails manually using another tool should you change image size settings and need new thumbnails.

Alternatively, you can use the [Jetpack Photon module](https://jetpack.com/support/photon/) which can do image resizing on the fly and will be used instead of background regeneration as of WooCommerce 3.3.2.

## Using Jetpack Photon instead

[Jetpack](https://jetpack.com/) is a plugin by Automattic, makers of WordPress.com. It gives your self-hosted WordPress site some of the functionality that is available to WordPress.com-hosted sites.

[The Photon module](https://jetpack.com/support/photon/) makes the images on your site be served from WordPress.com's global content delivery network (CDN) which should speed up the loading of images. 

Photon can create thumbnails on the fly which means you'll never need to use our background image regeneration functionality.


---

## Managing custom attributes in WooCommerce menus and taxonomy archives

*Source: theming/theme-development/using-custom-attributes-in-menus.md*

# Managing custom attributes in WooCommerce menus and taxonomy archives

Attributes that can be used for the layered nav are a custom taxonomy, which means you can display them in menus, or display products by attributes. This requires some work on your part, and archives must be enabled.

## Register the taxonomy for menus

When registering taxonomies for your custom attributes, WooCommerce calls the following hook:

```php
$show_in_nav_menus = apply_filters('woocommerce_attribute_show_in_nav_menus', false, $name);
```

So, for example, if your attribute slug was `size` you would do the following to register it for menus:

```php
add_filter('woocommerce_attribute_show_in_nav_menus', 'wc_reg_for_menus', 1, 2);

function wc_reg_for_menus( $register, $name = '' ) {
if ( $name == 'pa_size' ) $register = true;
return $register;
}
```

Custom attribute slugs are prefixed with `pa_`, so an attribute called `size` would be `pa_size`

Now use your attribute in  **Appearance > Menus**. You will notice, however, that it has default blog styling when you click on a link to your taxonomy term.

## Create a template

You need to theme your attribute to make it display products as you want. To do this:

1.  Copy `woocommerce/templates/taxonomy-product_cat.php` into your theme folder
2.  Rename the template to reflect your attribute - in our example we'd use `taxonomy-pa_size.php`

You should now see this template when viewing taxonomy terms for your custom attribute.


---

## WooCommerce CLI Frequently Asked Questions

*Source: wc-cli/cli-faq.md*

# WooCommerce CLI Frequently Asked Questions

## General Questions

### What is WooCommerce CLI?

- WooCommerce CLI (WC-CLI) is a command-line interface for managing WooCommerce settings and data. It provides a fast and efficient way to perform many tasks that would otherwise require manual work via the WordPress admin interface.

### How do I install WooCommerce CLI?

- WooCommerce CLI is included as part of WooCommerce from version 3.0.0 onwards. Ensure you have WooCommerce 3.0.0 or later installed, and you automatically have access to WC-CLI.

### Is WooCommerce CLI different from WP-CLI?

- WooCommerce CLI is a part of WP-CLI specifically designed for WooCommerce. While WP-CLI deals with general WordPress management, WC-CLI focuses on WooCommerce-specific tasks.

## Technical Questions

### How can I create a backup of my WooCommerce data?

- WC-CLI doesn't directly handle backups. However, you can use other WP-CLI commands to export WooCommerce data or rely on WordPress backup plugins.

### Can I update WooCommerce settings using the CLI?

- Yes, you can update many WooCommerce settings using WC-CLI. For example, to update store email settings, you would use a command like wp wc setting update [options].

## Troubleshooting

### Why am I getting a "permission denied" error?

- This error often occurs if your user role doesn't have the necessary permissions. Ensure you're using an account with administrative privileges.

### What should I do if a command is not working as expected

- Check for typos and verify the command syntax with --help. If the issue persists, consult the Command Reference or seek support from the WooCommerce community.

### What do I do if I get 404 errors when using commands?

If you are getting a 401 error like `Error: Sorry, you cannot list resources. {"status":401}`, you are trying to use the command unauthenticated. The WooCommerce CLI as of 3.0 requires you to provide a proper user to run the action as. Pass in your user ID using the `--user` flag.

### I am trying to update a list of X, but it's not saving

Some ‘lists' are actually objects. For example, if you want to set categories for a product, the REST API expects an array of objects.

To set this you would use JSON like this:

```bash
wp wc product create --name='Product Name' --categories='[ { "id" : 21 } ]' --user=admin
```

## Advanced Usage

### Can I use WooCommerce CLI for bulk product updates?

- Yes, WC-CLI is well-suited for bulk operations. You can use scripting to loop through a list of products and apply updates.

### How do I handle complex queries with WC-CLI?

- WC-CLI supports various arguments and filters that you can use to build complex queries. Combining these with shell scripting can yield powerful results.


---

## WooCommerce CLI Overview

*Source: wc-cli/cli-overview.md*

# WooCommerce CLI Overview

## Introduction to WooCommerce CLI

WooCommerce CLI (WC-CLI) offers an efficient way to manage WooCommerce (WC) stores via the command line. This tool is a part of WC from version 3.0.0 onwards and leverages the capabilities of the WC REST API. This means that most tasks achievable through the REST API can also be performed via the command line.

For documentation on WC versions 2.5 and 2.6's CLI, visit [Legacy CLI commands](https://github.com/woocommerce/woocommerce/wiki/Legacy-CLI-commands-(v2.6-and-below)).

## About WP-CLI

WP-CLI is a powerful set of command-line tools for managing WordPress installations. You can update plugins, configure multisite installations, and much more, all without using a web browser. For more information, visit the [official WP-CLI website](http://wp-cli.org/).

## Getting Started with WooCommerce CLI

To begin using WC-CLI, ensure that you have WP-CLI installed and that you are running WooCommerce 3.0.0 or later. The CLI commands are accessed through the `wp wc` command. For a full list of available commands, type `wp wc` in your command-line interface.

For specific details on commands and their usage, refer to the [command reference](/docs/wc-cli/wc-cli-commands/). The [how-to guide](/docs/wc-cli/using-wc-cli/) provides a practical approach to common tasks, ideal for those new to WC-CLI or looking for quick solutions.

## Additional Resources

For those interested in exploring further, the following resources might be helpful:

- [WC REST API Documentation](https://developer.woocommerce.com/docs/category/rest-api/)
- [Testing files for our CLI tests](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/tests/cli/features)


---

## How to Use WooCommerce CLI

*Source: wc-cli/using-wc-cli.md*

# How to Use WooCommerce CLI

## Introduction

This guide aims to assist beginners in using WooCommerce CLI (WC-CLI) for managing WooCommerce stores via the command line.

## Getting Started

- Ensure WP-CLI is installed and WooCommerce is at least version 3.0.0.
- To check WC-CLI availability:

```bash
wp wc --info
```

### General Command Structure

The general syntax for WC-CLI commands is:

```bash
wp wc [command] [options]
```

For detailed help on any specific command, use:

```bash
wp wc [command] --help
```

## Basic Tasks

### 1. Listing Products

To list all products in your WooCommerce store:

```bash
wp wc product list
```

### 2. Creating a New Product

To create a new product:

```bash
wp wc product create --name="New Product" --type="simple" --regular_price="19.99"
```

### 3. Updating a Product

To update an existing product (e.g., product ID 123):

```bash
wp wc product update 123 --regular_price="24.99"
```

### 4. Deleting a Product

To delete a product (e.g., product ID 123):

```bash
wp wc product delete 123 --force
```

For a complete list of WC-CLI commands, check out our [WC-CLI commands](/docs/wc-cli/wc-cli-commands/) documentation.


---

## WooCommerce CLI Commands

*Source: wc-cli/wc-cli-commands/README.md*

# WooCommerce CLI Commands

## Overview

This document serves as a comprehensive reference for the WooCommerce Command Line Interface (WC-CLI) commands. It includes syntax, options, and brief descriptions for each command. These commands are applicable for WooCommerce version 3.0.0 and later.

## General Command Structure

The general syntax for WC-CLI commands is:

```bash
wp wc [command] [options]
```

For detailed help on any specific command, use:

```bash
wp wc [command] --help
```

## Commands

| Command | Description |
| --- | --- |
| [wc blueprint](/docs/wc-cli/wc-cli-commands/wc-blueprint/) | Imports and exports WooCommerce Blueprints. |
| [wc com](/docs/wc-cli/wc-cli-commands/wc-com/) | Interacts with extensions from the WooCommerce.com marketplace via CLI. |
| [wc customer](/docs/wc-cli/wc-cli-commands/wc-customer/) | Manage WooCommerce customer resources. |
| [wc customer_download](/docs/wc-cli/wc-cli-commands/wc-customer-download/) | Manage WooCommerce customer download resources. |
| [wc hpos](/docs/wc-cli/wc-cli-commands/wc-hpos/) | Commands for managing High-Performance Order Storage (HPOS). For detailed examples, see [HPOS CLI tools](/docs/features/orders/high-performance-order-storage/cli-tools/). |
| [wc order_note](/docs/wc-cli/wc-cli-commands/wc-order-note/) | Manage WooCommerce order note resources. |
| [wc palt](/docs/wc-cli/wc-cli-commands/wc-palt/) | Commands for managing the product attributes lookup table. The table stores denormalized product attribute term data used to speed up catalog filtering. |
| [wc payment_gateway](/docs/wc-cli/wc-cli-commands/wc-payment-gateway/) | Manage WooCommerce payment gateway resources. |
| [wc product](/docs/wc-cli/wc-cli-commands/wc-product/) | Manage WooCommerce product resources. |
| [wc product_attribute](/docs/wc-cli/wc-cli-commands/wc-product-attribute/) | Manage WooCommerce product attribute resources. |
| [wc product_attribute_term](/docs/wc-cli/wc-cli-commands/wc-product-attribute-term/) | Manage WooCommerce product attribute term resources. |
| [wc product_cat](/docs/wc-cli/wc-cli-commands/wc-product-cat/) | Manage WooCommerce product category resources. |
| [wc product_review](/docs/wc-cli/wc-cli-commands/wc-product-review/) | Manage WooCommerce product review resources. |
| [wc product_shipping_class](/docs/wc-cli/wc-cli-commands/wc-product-shipping-class/) | Manage WooCommerce product shipping class resources. |
| [wc product_tag](/docs/wc-cli/wc-cli-commands/wc-product-tag/) | Manage WooCommerce product tag resources. |
| [wc product_variation](/docs/wc-cli/wc-cli-commands/wc-product-variation/) | Manage WooCommerce product variation resources. |
| [wc setting](/docs/wc-cli/wc-cli-commands/wc-setting/) | Manage WooCommerce setting resources. |
| [wc shipping_method](/docs/wc-cli/wc-cli-commands/wc-shipping-method/) | Manage WooCommerce shipping method resources. |
| [wc shipping_zone](/docs/wc-cli/wc-cli-commands/wc-shipping-zone/) | Manage WooCommerce shipping zone resources. |
| [wc shipping_zone_location](/docs/wc-cli/wc-cli-commands/wc-shipping-zone-location/) | Manage WooCommerce shipping zone location resources. |
| [wc shipping_zone_method](/docs/wc-cli/wc-cli-commands/wc-shipping-zone-method/) | Manage WooCommerce shipping zone method resources. |
| [wc shop_coupon](/docs/wc-cli/wc-cli-commands/wc-shop-coupon/) | Manage WooCommerce shop coupon resources. |
| [wc shop_order](/docs/wc-cli/wc-cli-commands/wc-shop-order/) | Manage WooCommerce shop order resources. |
| [wc shop_order_refund](/docs/wc-cli/wc-cli-commands/wc-shop-order-refund/) | Manage WooCommerce shop order refund resources. |
| [wc tax](/docs/wc-cli/wc-cli-commands/wc-tax/) | Manage WooCommerce tax resources. |
| [wc tax_class](/docs/wc-cli/wc-cli-commands/wc-tax-class/) | Manage WooCommerce tax class resources. |
| [wc tool](/docs/wc-cli/wc-cli-commands/wc-tool/) | Runs WooCommerce system status tools from the CLI. |
| [wc update](/docs/wc-cli/wc-cli-commands/wc-update/) | Runs all pending WooCommerce database updates. |
| [wc webhook](/docs/wc-cli/wc-cli-commands/wc-webhook/) | Manage WooCommerce webhook resources. |
| [wc webhook_delivery](/docs/wc-cli/wc-cli-commands/wc-webhook-delivery/) | Manage WooCommerce webhook delivery resources. |


---

## wc blueprint

*Source: wc-cli/wc-cli-commands/wc-blueprint.md*

Imports and exports WooCommerce Blueprints.

## wc blueprint import `<schema-path>`

Import a WooCommerce Blueprint schema file.

- `--show-messages` - Show debug messages. Supported log levels: all, error, info, debug.

## wc blueprint export `<save-to-filename>`

Export a WooCommerce Blueprint schema file.

- `--steps` - name of steps to export.


---

## wc com

*Source: wc-cli/wc-cli-commands/wc-com.md*

Interacts with extensions from the WooCommerce.com marketplace via CLI.

## wc com connect

Connect the store to WooCommerce.com with an application password.

- `--password` - WooCommerce.com application password. If omitted, the command prompts for it.
- `--force` - Disconnect the site first and force a new connection if the site is already connected.

## wc com disconnect

Disconnect the store from WooCommerce.com.

- `--yes` - Do not prompt for confirmation.

## wc com extension list

List extensions owned by the connected site.

- `--format` - Render output in a particular format.

    Default: table

    Options: table, csv, json, yaml

- `--fields` - Limit the output to specific object fields.

    Default: all

    Options: product_slug, product_name, auto_renew, expires_on, expired, sites_max, sites_active, maxed

## wc com extension install `<extension>...`

Install one or more plugins from the WooCommerce.com marketplace.

- `--force` - If set, the command will overwrite any installed version of the extension without prompting for confirmation.
- `--activate` - If set, the plugin will be activated after installation.
- `--activate-network` - If set, the plugin will be network activated immediately after installation
- `--insecure` - Retry downloads without certificate validation if TLS handshake fails. Note: This makes the request vulnerable to a MITM attack.


---

## wc customer_download

*Source: wc-cli/wc-cli-commands/wc-customer-download.md*

Manage WooCommerce customer download resources.

## wc customer_download list `<customer_id>`

List all customer downloads.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope


---

## wc customer

*Source: wc-cli/wc-cli-commands/wc-customer.md*

Manage WooCommerce customer resources.

## wc customer list

List all customers.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--exclude` - Ensure result set excludes specific IDs.
- `--include` - Limit result set to specific IDs.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by object attribute.
- `--email` - Limit result set to resources with a specific email.
- `--role` - Limit result set to resources with a specific role.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc customer create

Create a new customer.

- `--email` - New user email address. (*Required*)
- `--first_name` - Customer first name.
- `--last_name` - Customer last name.
- `--username` - New user username.
- `--password` - New user password. (*Required*)
- `--billing` - List of billing address data.
- `--shipping` - List of shipping address data.
- `--meta_data` - Meta data.
- `--porcelain` - Output just the id when the operation is successful.

## wc customer get `<id>`

Get a single customer.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc customer update `<id>`

Update an existing customer.

- `--email` - The email address for the customer.
- `--first_name` - Customer first name.
- `--last_name` - Customer last name.
- `--username` - Customer login name.
- `--password` - Customer password.
- `--billing` - List of billing address data.
- `--shipping` - List of shipping address data.
- `--meta_data` - Meta data.
- `--porcelain` - Output just the id when the operation is successful.

## wc customer delete `<id>`

Delete an existing customer.

- `--force` - Required to be true, as resource does not support trashing.
- `--reassign` - ID to reassign posts to.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc hpos

*Source: wc-cli/wc-cli-commands/wc-hpos.md*

Commands for managing High-Performance Order Storage (HPOS). For detailed examples, see [HPOS CLI tools](/docs/features/orders/high-performance-order-storage/cli-tools/).

The older `wc cot` namespace is deprecated. Use `wc hpos` instead of the remaining deprecated aliases: `wc cot count_unmigrated`, `wc cot sync`, `wc cot verify_cot_data`, `wc cot enable`, and `wc cot disable`. The `wc cot migrate` command is fully deprecated and no longer works.

## wc hpos status

Displays a summary of HPOS settings and sync status for the site.

## wc hpos enable

Set custom order tables as the authoritative order datastore after running compatibility and sync checks.

- `--for-new-shop` - Enable HPOS only if this is a new shop, regardless of whether tables are in sync.
- `--with-sync` - Also enable compatibility mode, which keeps the HPOS and posts datastores in sync.
- `--ignore-plugin-compatibility` - Enable HPOS even if active plugins are incompatible with HPOS.

## wc hpos disable

Set the posts datastore as authoritative after confirming HPOS and posts tables are in sync.

- `--with-sync` - Also disable compatibility mode, which stops keeping the HPOS and posts datastores in sync.

## wc hpos compatibility-info

Show WooCommerce-aware plugins known to be compatible, incompatible, or uncertain for HPOS.

- `--include-inactive` - Include inactive plugins in the compatibility lists.
- `--display-filenames` - Display plugin file names instead of plugin names.

## wc hpos compatibility-mode enable

Enables compatibility mode, which keeps the HPOS and posts datastores in sync.

## wc hpos compatibility-mode disable

Disables compatibility mode, which stops keeping the HPOS and posts datastores in sync.

## wc hpos count_unmigrated

Prints the number of orders pending sync.

## wc hpos sync

Sync order data between the custom order tables and the core WordPress post tables.

- `--batch-size` - The number of orders to process in each batch.

    Default: 500

## wc hpos verify_data

Verify migrated order data with original posts data.

- `--batch-size` - The number of orders to verify in each batch.

    Default: 500

- `--start-from` - Order ID to start from.
- `--end-at` - Order ID to end at.
- `--verbose` - Output errors as they happen in each batch instead of aggregating them at the end.
- `--order-types` - Comma-separated list of order types to verify. Defaults to `wc_get_order_types( 'cot-migration' )`.
- `--re-migrate` - Attempt to re-migrate orders that fail verification. Use only after confirming the destination datastore should be overwritten.

## wc hpos diff `<order_id>`

Display differences for an order between the HPOS and posts datastores.

- `--format` - Render output in a particular format.

    Default: table

    Options: table, csv, json, yaml

## wc hpos backfill `<order_id>`

Backfill an order from either the HPOS or posts datastore.

- `--from` - Source datastore. (*Required*)
- `--to` - Destination datastore. (*Required*)
- `--meta_keys` - Comma-separated list of meta keys to backfill.
- `--props` - Comma-separated list of order properties to backfill.

Datastore options: hpos, posts

## wc hpos cleanup `<all|id|range>...`

Remove redundant data from the postmeta table for migrated orders when HPOS is enabled.

- `--batch-size` - Number of orders to process per batch. Applies only when cleaning up all orders.

    Default: 500

- `--force` - Clean up post meta even if the post appears to have been updated more recently than the order.


---

## wc order_note

*Source: wc-cli/wc-cli-commands/wc-order-note.md*

Manage WooCommerce order note resources.

## wc order_note list `<order_id>`

List all order notes.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--type` - Limit result to customers or internal notes.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc order_note create `<order_id>`

Create a new order note.

- `--note` - Order note content. (*Required*)
- `--customer_note` - If true, the note will be shown to customers and they will be notified. If false, the note will be for admin reference only.
- `--porcelain` - Output just the id when the operation is successful.

## wc order_note get `<order_id>` `<id>`

Get a single order note.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc order_note delete `<order_id>` `<id>`

Delete an existing order note.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc palt

*Source: wc-cli/wc-cli-commands/wc-palt.md*

Commands for managing the product attributes lookup table. The table stores denormalized product attribute term data used to speed up catalog filtering.

## wc palt enable

Enable usage of the product attributes lookup table.

- `--force` - Skip confirmation when enabling table usage while regeneration is in progress, was aborted, or the lookup table is empty.

## wc palt disable

Disables usage of the product attributes lookup table.

## wc palt info

Displays information about the product attributes lookup table.

## wc palt regenerate_for_product `<product_id>`

Regenerate product attributes lookup table data for one product.

- `--disable-db-optimization` - Do not use optimized database access even if products are stored as custom post types.

## wc palt abort_regeneration

Abort background regeneration of the product attributes lookup table.

- `--cleanup` - Also clean up temporary data, so regeneration cannot be resumed but can be restarted.

## wc palt resume_regeneration

Resumes background regeneration of the product attributes lookup table after it has been aborted.

## wc palt cleanup_regeneration_progress

Deletes temporary data used during product attributes lookup table regeneration.

## wc palt initiate_regeneration

Initiate background regeneration of the product attributes lookup table using scheduled actions.

- `--force` - Do not prompt for confirmation if the product attributes lookup table is not empty.

## wc palt regenerate

Regenerate the product attributes lookup table immediately without using scheduled tasks.

- `--force` - Do not prompt for confirmation if the product attributes lookup table is not empty.
- `--from-scratch` - Start table regeneration from scratch even if regeneration is already in progress.
- `--disable-db-optimization` - Do not use optimized database access even if products are stored as custom post types.
- `--batch-size` - How many products to process in each iteration of the loop.

    Default: 10


---

## wc payment_gateway

*Source: wc-cli/wc-cli-commands/wc-payment-gateway.md*

Manage WooCommerce payment gateway resources.

## wc payment_gateway list

List all payment gateways.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc payment_gateway get `<id>`

Get a single payment gateway.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc payment_gateway update `<id>`

Update an existing payment gateway.

- `--title` - Payment gateway title on checkout.
- `--description` - Payment gateway description on checkout.
- `--order` - Payment gateway sort order.
- `--enabled` - Payment gateway enabled status.
- `--settings` - Payment gateway settings.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc product_attribute_term

*Source: wc-cli/wc-cli-commands/wc-product-attribute-term.md*

Manage WooCommerce product attribute term resources.

## wc product_attribute_term list `<attribute_id>`

List all product attribute terms.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--exclude` - Ensure result set excludes specific ids.
- `--include` - Limit result set to specific ids.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by resource attribute.
- `--hide_empty` - Whether to hide resources not assigned to any products.
- `--parent` - Limit result set to resources assigned to a specific parent.
- `--product` - Limit result set to resources assigned to a specific product.
- `--slug` - Limit result set to resources with a specific slug.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc product_attribute_term create `<attribute_id>`

Create a new product attribute term.

- `--name` - Name for the resource. (*Required*)
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--description` - HTML description of the resource.
- `--menu_order` - Menu order, used to custom sort the resource.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_attribute_term get `<attribute_id>` `<id>`

Get a single product attribute term.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc product_attribute_term update `<attribute_id>` `<id>`

Update an existing product attribute term.

- `--name` - Term name.
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--description` - HTML description of the resource.
- `--menu_order` - Menu order, used to custom sort the resource.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_attribute_term delete `<attribute_id>` `<id>`

Delete an existing product attribute term.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc product_attribute

*Source: wc-cli/wc-cli-commands/wc-product-attribute.md*

Manage WooCommerce product attribute resources.

## wc product_attribute list

List all product attributes.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc product_attribute create

Create a new product attribute.

- `--name` - Name for the resource. (*Required*)
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--type` - Type of attribute.
- `--order_by` - Default sort order.
- `--has_archives` - Enable/Disable attribute archives.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_attribute get `<id>`

Get a single product attribute.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc product_attribute update `<id>`

Update an existing product attribute.

- `--name` - Attribute name.
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--type` - Type of attribute.
- `--order_by` - Default sort order.
- `--has_archives` - Enable/Disable attribute archives.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_attribute delete `<id>`

Delete an existing product attribute.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc product_cat

*Source: wc-cli/wc-cli-commands/wc-product-cat.md*

Manage WooCommerce product category resources.

## wc product_cat list

List all product categories.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--exclude` - Ensure result set excludes specific ids.
- `--include` - Limit result set to specific ids.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by resource attribute.
- `--hide_empty` - Whether to hide resources not assigned to any products.
- `--parent` - Limit result set to resources assigned to a specific parent.
- `--product` - Limit result set to resources assigned to a specific product.
- `--slug` - Limit result set to resources with a specific slug.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc product_cat create

Create a new product category.

- `--name` - Name for the resource. (*Required*)
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--parent` - The ID for the parent of the resource.
- `--description` - HTML description of the resource.
- `--display` - Category archive display type.
- `--image` - Image data.
- `--menu_order` - Menu order, used to custom sort the resource.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_cat get `<id>`

Get a single product category.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc product_cat update `<id>`

Update an existing product category.

- `--name` - Category name.
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--parent` - The ID for the parent of the resource.
- `--description` - HTML description of the resource.
- `--display` - Category archive display type.
- `--image` - Image data.
- `--menu_order` - Menu order, used to custom sort the resource.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_cat delete `<id>`

Delete an existing product category.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc product_review

*Source: wc-cli/wc-cli-commands/wc-product-review.md*

Manage WooCommerce product review resources.

## wc product_review list `<product_id>`

List all product reviews.

- `--id` - Unique identifier for the review.
- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc product_review create `<product_id>`

Create a new product review.

- `--id` - Unique identifier for the review.
- `--review` - Review content. (*Required*)
- `--date_created` - The date the review was created, in the site's timezone.
- `--date_created_gmt` - The date the review was created, as GMT.
- `--rating` - Review rating (0 to 5).
- `--name` - Name of the reviewer. (*Required*)
- `--email` - Email of the reviewer. (*Required*)
- `--porcelain` - Output just the id when the operation is successful.

## wc product_review get `<product_id>` `<id>`

Get a single product review.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc product_review update `<product_id>` `<id>`

Update an existing product review.

- `--review` - The content of the review.
- `--date_created` - The date the review was created, in the site's timezone.
- `--date_created_gmt` - The date the review was created, as GMT.
- `--rating` - Review rating (0 to 5).
- `--name` - Reviewer name.
- `--email` - Reviewer email.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_review delete `<product_id>` `<id>`

Delete an existing product review.

- `--force` - Whether to bypass trash and force deletion.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc product_shipping_class

*Source: wc-cli/wc-cli-commands/wc-product-shipping-class.md*

Manage WooCommerce product shipping class resources.

## wc product_shipping_class list

List all product shipping classes.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--exclude` - Ensure result set excludes specific ids.
- `--include` - Limit result set to specific ids.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by resource attribute.
- `--hide_empty` - Whether to hide resources not assigned to any products.
- `--product` - Limit result set to resources assigned to a specific product.
- `--slug` - Limit result set to resources with a specific slug.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc product_shipping_class create

Create a new product shipping class.

- `--name` - Name for the resource. (*Required*)
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--description` - HTML description of the resource.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_shipping_class get `<id>`

Get a single product shipping class.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc product_shipping_class update `<id>`

Update an existing product shipping class.

- `--name` - Shipping class name.
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--description` - HTML description of the resource.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_shipping_class delete `<id>`

Delete an existing product shipping class.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc product_tag

*Source: wc-cli/wc-cli-commands/wc-product-tag.md*

Manage WooCommerce product tag resources.

## wc product_tag list

List all product tags.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--exclude` - Ensure result set excludes specific ids.
- `--include` - Limit result set to specific ids.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by resource attribute.
- `--hide_empty` - Whether to hide resources not assigned to any products.
- `--product` - Limit result set to resources assigned to a specific product.
- `--slug` - Limit result set to resources with a specific slug.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc product_tag create

Create a new product tag.

- `--name` - Name for the resource. (*Required*)
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--description` - HTML description of the resource.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_tag get `<id>`

Get a single product tag.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc product_tag update `<id>`

Update an existing product tag.

- `--name` - Tag name.
- `--slug` - An alphanumeric identifier for the resource unique to its type.
- `--description` - HTML description of the resource.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_tag delete `<id>`

Delete an existing product tag.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc product_variation

*Source: wc-cli/wc-cli-commands/wc-product-variation.md*

Manage WooCommerce product variation resources.

## wc product_variation list `<product_id>`

List all product variations.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--after` - Limit response to resources published after a given ISO8601 compliant date.
- `--before` - Limit response to resources published before a given ISO8601 compliant date.
- `--exclude` - Ensure result set excludes specific IDs.
- `--include` - Limit result set to specific ids.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by object attribute.
- `--parent` - Limit result set to those of particular parent IDs.
- `--parent_exclude` - Limit result set to all items except those of a particular parent ID.
- `--slug` - Limit result set to products with a specific slug.
- `--status` - Limit result set to products assigned a specific status.
- `--type` - Limit result set to products assigned a specific type.
- `--sku` - Limit result set to products with a specific SKU.
- `--featured` - Limit result set to featured products.
- `--category` - Limit result set to products assigned a specific category ID.
- `--tag` - Limit result set to products assigned a specific tag ID.
- `--shipping_class` - Limit result set to products assigned a specific shipping class ID.
- `--attribute` - Limit result set to products with a specific attribute.
- `--attribute_term` - Limit result set to products with a specific attribute term ID (requires an assigned attribute).
- `--tax_class` - Limit result set to products with a specific tax class.
- `--in_stock` - Limit result set to products in stock or out of stock.
- `--on_sale` - Limit result set to products on sale.
- `--min_price` - Limit result set to products based on a minimum price.
- `--max_price` - Limit result set to products based on a maximum price.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc product_variation create `<product_id>`

Create a new product variation.

- `--description` - Variation description.
- `--sku` - Unique identifier.
- `--regular_price` - Variation regular price.
- `--sale_price` - Variation sale price.
- `--date_on_sale_from` - Start date of sale price, in the site's timezone.
- `--date_on_sale_from_gmt` - Start date of sale price, as GMT.
- `--date_on_sale_to` - End date of sale price, in the site's timezone.
- `--date_on_sale_to_gmt` - End date of sale price, as GMT.
- `--visible` - Define if the attribute is visible on the "Additional information" tab in the product's page.
- `--virtual` - If the variation is virtual.
- `--downloadable` - If the variation is downloadable.
- `--downloads` - List of downloadable files.
- `--download_limit` - Number of times downloadable files can be downloaded after purchase.
- `--download_expiry` - Number of days until access to downloadable files expires.
- `--tax_status` - Tax status.
- `--tax_class` - Tax class.
- `--manage_stock` - Stock management at variation level.
- `--stock_quantity` - Stock quantity.
- `--in_stock` - Controls whether or not the variation is listed as "in stock" or "out of stock" on the frontend.
- `--backorders` - If managing stock, this controls if backorders are allowed.
- `--weight` - Variation weight (lbs).
- `--dimensions` - Variation dimensions.
- `--shipping_class` - Shipping class slug.
- `--image` - Variation image data.
- `--attributes` - List of attributes.
- `--menu_order` - Menu order, used to custom sort products.
- `--meta_data` - Meta data.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_variation get `<product_id>` `<id>`

Get a single product variation.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc product_variation update `<product_id>` `<id>`

Update an existing product variation.

- `--description` - Variation description.
- `--sku` - Unique identifier.
- `--regular_price` - Variation regular price.
- `--sale_price` - Variation sale price.
- `--date_on_sale_from` - Start date of sale price, in the site's timezone.
- `--date_on_sale_from_gmt` - Start date of sale price, as GMT.
- `--date_on_sale_to` - End date of sale price, in the site's timezone.
- `--date_on_sale_to_gmt` - End date of sale price, as GMT.
- `--visible` - Define if the attribute is visible on the "Additional information" tab in the product's page.
- `--virtual` - If the variation is virtual.
- `--downloadable` - If the variation is downloadable.
- `--downloads` - List of downloadable files.
- `--download_limit` - Number of times downloadable files can be downloaded after purchase.
- `--download_expiry` - Number of days until access to downloadable files expires.
- `--tax_status` - Tax status.
- `--tax_class` - Tax class.
- `--manage_stock` - Stock management at variation level.
- `--stock_quantity` - Stock quantity.
- `--in_stock` - Controls whether or not the variation is listed as "in stock" or "out of stock" on the frontend.
- `--backorders` - If managing stock, this controls if backorders are allowed.
- `--weight` - Variation weight (lbs).
- `--dimensions` - Variation dimensions.
- `--shipping_class` - Shipping class slug.
- `--image` - Variation image data.
- `--attributes` - List of attributes.
- `--menu_order` - Menu order, used to custom sort products.
- `--meta_data` - Meta data.
- `--porcelain` - Output just the id when the operation is successful.

## wc product_variation delete `<product_id>` `<id>`

Delete an existing product variation.

- `--force` - Whether to bypass trash and force deletion.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc product

*Source: wc-cli/wc-cli-commands/wc-product.md*

Manage WooCommerce product resources.

## wc product list

List all products.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--after` - Limit response to resources published after a given ISO8601 compliant date.
- `--before` - Limit response to resources published before a given ISO8601 compliant date.
- `--exclude` - Ensure result set excludes specific IDs.
- `--include` - Limit result set to specific ids.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by object attribute.
- `--parent` - Limit result set to those of particular parent IDs.
- `--parent_exclude` - Limit result set to all items except those of a particular parent ID.
- `--slug` - Limit result set to products with a specific slug.
- `--status` - Limit result set to products assigned a specific status.
- `--type` - Limit result set to products assigned a specific type.
- `--sku` - Limit result set to products with a specific SKU.
- `--featured` - Limit result set to featured products.
- `--category` - Limit result set to products assigned a specific category ID.
- `--tag` - Limit result set to products assigned a specific tag ID.
- `--shipping_class` - Limit result set to products assigned a specific shipping class ID.
- `--attribute` - Limit result set to products with a specific attribute.
- `--attribute_term` - Limit result set to products with a specific attribute term ID (requires an assigned attribute).
- `--tax_class` - Limit result set to products with a specific tax class.
- `--in_stock` - Limit result set to products in stock or out of stock.
- `--on_sale` - Limit result set to products on sale.
- `--min_price` - Limit result set to products based on a minimum price.
- `--max_price` - Limit result set to products based on a maximum price.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc product create

Create a new product.

- `--name` - Product name.
- `--slug` - Product slug.
- `--type` - Product type.
- `--status` - Product status (post status).
- `--featured` - Featured product.
- `--catalog_visibility` - Catalog visibility.
- `--description` - Product description.
- `--short_description` - Product short description.
- `--sku` - Unique identifier.
- `--regular_price` - Product regular price.
- `--sale_price` - Product sale price.
- `--date_on_sale_from` - Start date of sale price, in the site's timezone.
- `--date_on_sale_from_gmt` - Start date of sale price, as GMT.
- `--date_on_sale_to` - End date of sale price, in the site's timezone.
- `--date_on_sale_to_gmt` - End date of sale price, as GMT.
- `--virtual` - If the product is virtual.
- `--downloadable` - If the product is downloadable.
- `--downloads` - List of downloadable files.
- `--download_limit` - Number of times downloadable files can be downloaded after purchase.
- `--download_expiry` - Number of days until access to downloadable files expires.
- `--external_url` - Product external URL. Only for external products.
- `--button_text` - Product external button text. Only for external products.
- `--tax_status` - Tax status.
- `--tax_class` - Tax class.
- `--manage_stock` - Stock management at product level.
- `--stock_quantity` - Stock quantity.
- `--in_stock` - Controls whether or not the product is listed as "in stock" or "out of stock" on the frontend.
- `--backorders` - If managing stock, this controls if backorders are allowed.
- `--sold_individually` - Allow one item to be bought in a single order.
- `--weight` - Product weight (lbs).
- `--dimensions` - Product dimensions.
- `--shipping_class` - Shipping class slug.
- `--reviews_allowed` - Allow reviews.
- `--upsell_ids` - List of up-sell products IDs.
- `--cross_sell_ids` - List of cross-sell products IDs.
- `--parent_id` - Product parent ID.
- `--purchase_note` - Optional note to send the customer after purchase.
- `--categories` - List of categories.
- `--tags` - List of tags.
- `--images` - List of images.
- `--attributes` - List of attributes.
- `--default_attributes` - Defaults variation attributes.
- `--menu_order` - Menu order, used to custom sort products.
- `--meta_data` - Meta data.
- `--porcelain` - Output just the id when the operation is successful.

## wc product get `<id>`

Get a single product.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc product update `<id>`

Update an existing product.

- `--name` - Product name.
- `--slug` - Product slug.
- `--type` - Product type.
- `--status` - Product status (post status).
- `--featured` - Featured product.
- `--catalog_visibility` - Catalog visibility.
- `--description` - Product description.
- `--short_description` - Product short description.
- `--sku` - Unique identifier.
- `--regular_price` - Product regular price.
- `--sale_price` - Product sale price.
- `--date_on_sale_from` - Start date of sale price, in the site's timezone.
- `--date_on_sale_from_gmt` - Start date of sale price, as GMT.
- `--date_on_sale_to` - End date of sale price, in the site's timezone.
- `--date_on_sale_to_gmt` - End date of sale price, as GMT.
- `--virtual` - If the product is virtual.
- `--downloadable` - If the product is downloadable.
- `--downloads` - List of downloadable files.
- `--download_limit` - Number of times downloadable files can be downloaded after purchase.
- `--download_expiry` - Number of days until access to downloadable files expires.
- `--external_url` - Product external URL. Only for external products.
- `--button_text` - Product external button text. Only for external products.
- `--tax_status` - Tax status.
- `--tax_class` - Tax class.
- `--manage_stock` - Stock management at product level.
- `--stock_quantity` - Stock quantity.
- `--in_stock` - Controls whether or not the product is listed as "in stock" or "out of stock" on the frontend.
- `--backorders` - If managing stock, this controls if backorders are allowed.
- `--sold_individually` - Allow one item to be bought in a single order.
- `--weight` - Product weight (lbs).
- `--dimensions` - Product dimensions.
- `--shipping_class` - Shipping class slug.
- `--reviews_allowed` - Allow reviews.
- `--upsell_ids` - List of up-sell products IDs.
- `--cross_sell_ids` - List of cross-sell products IDs.
- `--parent_id` - Product parent ID.
- `--purchase_note` - Optional note to send the customer after purchase.
- `--categories` - List of categories.
- `--tags` - List of tags.
- `--images` - List of images.
- `--attributes` - List of attributes.
- `--default_attributes` - Defaults variation attributes.
- `--menu_order` - Menu order, used to custom sort products.
- `--meta_data` - Meta data.
- `--porcelain` - Output just the id when the operation is successful.

## wc product delete `<id>`

Delete an existing product.

- `--force` - Whether to bypass trash and force deletion.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc setting

*Source: wc-cli/wc-cli-commands/wc-setting.md*

Manage WooCommerce setting resources.

## wc setting get `<id>`

Get a single setting.

- `--group` - Settings group ID.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc setting update `<id>`

Update an existing setting.

- `--group` - Settings group ID.
- `--value` - Setting value.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc shipping_method

*Source: wc-cli/wc-cli-commands/wc-shipping-method.md*

Manage WooCommerce shipping method resources.

## wc shipping_method list

List all shipping methods.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc shipping_method get `<id>`

Get a single shipping method.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope


---

## wc shipping_zone_location

*Source: wc-cli/wc-cli-commands/wc-shipping-zone-location.md*

Manage WooCommerce shipping zone location resources.

## wc shipping_zone_location list `<id>`

List all shipping zone locations.

- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope


---

## wc shipping_zone_method

*Source: wc-cli/wc-cli-commands/wc-shipping-zone-method.md*

Manage WooCommerce shipping zone method resources.

## wc shipping_zone_method list `<zone_id>`

List all shipping zone methods.

- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc shipping_zone_method create `<zone_id>`

Create a new shipping zone method.

- `--order` - Shipping method sort order.
- `--enabled` - Shipping method enabled status.
- `--settings` - Shipping method settings.
- `--method_id` - Shipping method ID. (*Required*)
- `--porcelain` - Output just the id when the operation is successful.

## wc shipping_zone_method get `<zone_id>` `<instance_id>`

Get a single shipping zone method.

- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc shipping_zone_method update `<zone_id>` `<instance_id>`

Update an existing shipping zone method.

- `--order` - Shipping method sort order.
- `--enabled` - Shipping method enabled status.
- `--settings` - Shipping method settings.
- `--porcelain` - Output just the id when the operation is successful.

## wc shipping_zone_method delete `<zone_id>` `<instance_id>`

Delete an existing shipping zone method.

- `--force` - Whether to bypass trash and force deletion.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc shipping_zone

*Source: wc-cli/wc-cli-commands/wc-shipping-zone.md*

Manage WooCommerce shipping zone resources.

## wc shipping_zone list

List all shipping zones.

- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc shipping_zone create

Create a new shipping zone.

- `--name` - Shipping zone name. (*Required*)
- `--order` - Shipping zone order.
- `--porcelain` - Output just the id when the operation is successful.

## wc shipping_zone get `<id>`

Get a single shipping zone.

- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc shipping_zone update `<id>`

Update an existing shipping zone.

- `--name` - Shipping zone name.
- `--order` - Shipping zone order.
- `--porcelain` - Output just the id when the operation is successful.

## wc shipping_zone delete `<id>`

Delete an existing shipping zone.

- `--force` - Whether to bypass trash and force deletion.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc shop_coupon

*Source: wc-cli/wc-cli-commands/wc-shop-coupon.md*

Manage WooCommerce shop coupon resources.

## wc shop_coupon list

List all shop coupons.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--after` - Limit response to resources published after a given ISO8601 compliant date.
- `--before` - Limit response to resources published before a given ISO8601 compliant date.
- `--exclude` - Ensure result set excludes specific IDs.
- `--include` - Limit result set to specific ids.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by object attribute.
- `--code` - Limit result set to resources with a specific code.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc shop_coupon create

Create a new shop coupon.

- `--code` - Coupon code. (*Required*)
- `--amount` - The amount of discount. Should always be numeric, even if setting a percentage.
- `--discount_type` - Determines the type of discount that will be applied.
- `--description` - Coupon description.
- `--date_expires` - The date the coupon expires, in the site's timezone.
- `--date_expires_gmt` - The date the coupon expires, as GMT.
- `--individual_use` - If true, the coupon can only be used individually. Other applied coupons will be removed from the cart.
- `--product_ids` - List of product IDs the coupon can be used on.
- `--excluded_product_ids` - List of product IDs the coupon cannot be used on.
- `--usage_limit` - How many times the coupon can be used in total.
- `--usage_limit_per_user` - How many times the coupon can be used per customer.
- `--limit_usage_to_x_items` - Max number of items in the cart the coupon can be applied to.
- `--free_shipping` - If true and if the free shipping method requires a coupon, this coupon will enable free shipping.
- `--product_categories` - List of category IDs the coupon applies to.
- `--excluded_product_categories` - List of category IDs the coupon does not apply to.
- `--exclude_sale_items` - If true, this coupon will not be applied to items that have sale prices.
- `--minimum_amount` - Minimum order amount that needs to be in the cart before coupon applies.
- `--maximum_amount` - Maximum order amount allowed when using the coupon.
- `--email_restrictions` - List of email addresses that can use this coupon.
- `--meta_data` - Meta data.
- `--porcelain` - Output just the id when the operation is successful.

## wc shop_coupon get `<id>`

Get a single shop coupon.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc shop_coupon update `<id>`

Update an existing shop coupon.

- `--code` - Coupon code.
- `--amount` - The amount of discount. Should always be numeric, even if setting a percentage.
- `--discount_type` - Determines the type of discount that will be applied.
- `--description` - Coupon description.
- `--date_expires` - The date the coupon expires, in the site's timezone.
- `--date_expires_gmt` - The date the coupon expires, as GMT.
- `--individual_use` - If true, the coupon can only be used individually. Other applied coupons will be removed from the cart.
- `--product_ids` - List of product IDs the coupon can be used on.
- `--excluded_product_ids` - List of product IDs the coupon cannot be used on.
- `--usage_limit` - How many times the coupon can be used in total.
- `--usage_limit_per_user` - How many times the coupon can be used per customer.
- `--limit_usage_to_x_items` - Max number of items in the cart the coupon can be applied to.
- `--free_shipping` - If true and if the free shipping method requires a coupon, this coupon will enable free shipping.
- `--product_categories` - List of category IDs the coupon applies to.
- `--excluded_product_categories` - List of category IDs the coupon does not apply to.
- `--exclude_sale_items` - If true, this coupon will not be applied to items that have sale prices.
- `--minimum_amount` - Minimum order amount that needs to be in the cart before coupon applies.
- `--maximum_amount` - Maximum order amount allowed when using the coupon.
- `--email_restrictions` - List of email addresses that can use this coupon.
- `--meta_data` - Meta data.
- `--porcelain` - Output just the id when the operation is successful.

## wc shop_coupon delete `<id>`

Delete an existing shop coupon.

- `--force` - Whether to bypass trash and force deletion.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc shop_order_refund

*Source: wc-cli/wc-cli-commands/wc-shop-order-refund.md*

Manage WooCommerce shop order refund resources.

## wc shop_order_refund list `<order_id>`

List all shop order refunds.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--after` - Limit response to resources published after a given ISO8601 compliant date.
- `--before` - Limit response to resources published before a given ISO8601 compliant date.
- `--exclude` - Ensure result set excludes specific IDs.
- `--include` - Limit result set to specific ids.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by object attribute.
- `--parent` - Limit result set to those of particular parent IDs.
- `--parent_exclude` - Limit result set to all items except those of a particular parent ID.
- `--dp` - Number of decimal points to use in each resource.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc shop_order_refund create `<order_id>`

Create a new shop order refund.

- `--amount` - Refund amount.
- `--reason` - Reason for refund.
- `--refunded_by` - User ID of user who created the refund.
- `--meta_data` - Meta data.
- `--line_items` - Line items data.
- `--api_refund` - When true, the payment gateway API is used to generate the refund.
- `--porcelain` - Output just the id when the operation is successful.

## wc shop_order_refund get `<order_id>` `<id>`

Get a single shop order refund.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc shop_order_refund delete `<order_id>` `<id>`

Delete an existing shop order refund.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc shop_order

*Source: wc-cli/wc-cli-commands/wc-shop-order.md*

Manage WooCommerce shop order resources.

## wc shop_order list

List all shop orders.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--after` - Limit response to resources published after a given ISO8601 compliant date.
- `--before` - Limit response to resources published before a given ISO8601 compliant date.
- `--exclude` - Ensure result set excludes specific IDs.
- `--include` - Limit result set to specific ids.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by object attribute.
- `--parent` - Limit result set to those of particular parent IDs.
- `--parent_exclude` - Limit result set to all items except those of a particular parent ID.
- `--status` - Limit result set to orders assigned a specific status.
- `--customer` - Limit result set to orders assigned a specific customer.
- `--product` - Limit result set to orders assigned a specific product.
- `--dp` - Number of decimal points to use in each resource.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc shop_order create

Create a new shop order.

- `--parent_id` - Parent order ID.
- `--status` - Order status.
- `--currency` - Currency the order was created with, in ISO format.
- `--customer_id` - User ID who owns the order. 0 for guests.
- `--customer_note` - Note left by customer during checkout.
- `--billing` - Billing address.
- `--shipping` - Shipping address.
- `--payment_method` - Payment method ID.
- `--payment_method_title` - Payment method title.
- `--transaction_id` - Unique transaction ID.
- `--meta_data` - Meta data.
- `--line_items` - Line items data.
- `--shipping_lines` - Shipping lines data.
- `--fee_lines` - Fee lines data.
- `--coupon_lines` - Coupons line data.
- `--set_paid` - Define if the order is paid. It will set the status to processing and reduce stock items.
- `--porcelain` - Output just the id when the operation is successful.

## wc shop_order get `<id>`

Get a single shop order.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc shop_order update `<id>`

Update an existing shop order.

- `--parent_id` - Parent order ID.
- `--status` - Order status.
- `--currency` - Currency the order was created with, in ISO format.
- `--customer_id` - User ID who owns the order. 0 for guests.
- `--customer_note` - Note left by customer during checkout.
- `--billing` - Billing address.
- `--shipping` - Shipping address.
- `--payment_method` - Payment method ID.
- `--payment_method_title` - Payment method title.
- `--transaction_id` - Unique transaction ID.
- `--meta_data` - Meta data.
- `--line_items` - Line items data.
- `--shipping_lines` - Shipping lines data.
- `--fee_lines` - Fee lines data.
- `--coupon_lines` - Coupons line data.
- `--set_paid` - Define if the order is paid. It will set the status to processing and reduce stock items.
- `--porcelain` - Output just the id when the operation is successful.

## wc shop_order delete `<id>`

Delete an existing shop order.

- `--force` - Whether to bypass trash and force deletion.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc tax_class

*Source: wc-cli/wc-cli-commands/wc-tax-class.md*

Manage WooCommerce tax class resources.

## wc tax_class list

List all tax classes.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc tax_class create

Create a new tax class.

- `--name` - Tax class name. (*Required*)
- `--porcelain` - Output just the id when the operation is successful.

## wc tax_class delete `<slug>`

Delete an existing tax class.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc tax

*Source: wc-cli/wc-cli-commands/wc-tax.md*

Manage WooCommerce tax resources.

## wc tax list

List all taxes.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--exclude` - Ensure result set excludes specific IDs.
- `--include` - Limit result set to specific IDs.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by object attribute.
- `--class` - Sort by tax class.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc tax create

Create a new tax.

- `--country` - Country ISO 3166 code.
- `--state` - State code.
- `--postcode` - Postcode / ZIP.
- `--city` - City name.
- `--rate` - Tax rate.
- `--name` - Tax rate name.
- `--priority` - Tax priority.
- `--compound` - Whether or not this is a compound rate.
- `--shipping` - Whether or not this tax rate also gets applied to shipping.
- `--order` - Indicates the order that will appear in queries.
- `--class` - Tax class.
- `--porcelain` - Output just the id when the operation is successful.

## wc tax get `<id>`

Get a single tax.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc tax update `<id>`

Update an existing tax.

- `--country` - Country ISO 3166 code.
- `--state` - State code.
- `--postcode` - Postcode / ZIP.
- `--city` - City name.
- `--rate` - Tax rate.
- `--name` - Tax rate name.
- `--priority` - Tax priority.
- `--compound` - Whether or not this is a compound rate.
- `--shipping` - Whether or not this tax rate also gets applied to shipping.
- `--order` - Indicates the order that will appear in queries.
- `--class` - Tax class.
- `--porcelain` - Output just the id when the operation is successful.

## wc tax delete `<id>`

Delete an existing tax.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## wc tool

*Source: wc-cli/wc-cli-commands/wc-tool.md*

Runs WooCommerce system status tools from the CLI.

## wc tool list

List all system status tools.

- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc tool run `<id>`

Run a system status tool.


---

## wc update

*Source: wc-cli/wc-cli-commands/wc-update.md*

Runs all pending WooCommerce database updates.


---

## wc webhook_delivery

*Source: wc-cli/wc-cli-commands/wc-webhook-delivery.md*

Manage WooCommerce webhook delivery resources.

## wc webhook_delivery list `<webhook_id>`

List all webhook deliveries.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc webhook_delivery get `<webhook_id>` `<id>`

Get a single webhook delivery.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope


---

## wc webhook

*Source: wc-cli/wc-cli-commands/wc-webhook.md*

Manage WooCommerce webhook resources.

## wc webhook list

List all webhooks.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--page` - Current page of the collection.
- `--per_page` - Maximum number of items to be returned in result set. Defaults to 100 items.
- `--search` - Limit results to those matching a string.
- `--after` - Limit response to resources published after a given ISO8601 compliant date.
- `--before` - Limit response to resources published before a given ISO8601 compliant date.
- `--exclude` - Ensure result set excludes specific IDs.
- `--include` - Limit result set to specific ids.
- `--offset` - Offset the result set by a specific number of items.
- `--order` - Order sort attribute ascending or descending.
- `--orderby` - Sort collection by object attribute.
- `--status` - Limit result set to webhooks assigned a specific status.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, ids, yaml, count, headers, body, envelope

## wc webhook create

Create a new webhook.

- `--name` - A friendly name for the webhook.
- `--status` - Webhook status.
- `--topic` - Webhook topic. (*Required*)
- `--secret` - Webhook secret. (*Required*)
- `--delivery_url` - Webhook delivery URL. (*Required*)
- `--porcelain` - Output just the id when the operation is successful.

## wc webhook get `<id>`

Get a single webhook.

- `--context` - Scope under which the request is made; determines fields present in response.
- `--fields` - Limit response to specific fields. Defaults to all fields.
- `--field` - Get the value of an individual field.
- `--format` - Render response in a particular format.

    Default: table

    Options: table, json, csv, yaml, headers, body, envelope

## wc webhook update `<id>`

Update an existing webhook.

- `--name` - A friendly name for the webhook.
- `--status` - Webhook status.
- `--topic` - Webhook topic.
- `--secret` - Secret key used to generate a hash of the delivered webhook and provided in the request headers. The default is an MD5 hash from the current user's ID|username if not provided.
- `--porcelain` - Output just the id when the operation is successful.

## wc webhook delete `<id>`

Delete an existing webhook.

- `--force` - Required to be true, as resource does not support trashing.
- `--porcelain` - Output just the id when the operation is successful.


---

## WooCommerce CLI Examples

*Source: wc-cli/wc-cli-examples.md*

# WooCommerce CLI Examples

Full documentation for every command is available using `--help`. Below are some example commands to show what the CLI can do.

All the examples below use user ID 1 (usually an admin account), but you should replace that with your own user account.

You can also find other examples (without output) by looking at [the testing files for our CLI tests](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/tests/cli/features).

Each command will have a `.feature` file. For example, [these some payment gateway commands](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/tests/cli/features/payment_gateway.feature).

## Clearing the product/shop transients cache

Command: 

`$ wp wc tool run clear_transients --user=1`

Response:

`Success: Updated system_status_tool clear_transients.`

## Listing all system tools

Command: 

`$ wp wc tool list --user=1`

Response:

```bash
+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+
| id                         | name                             | action                        | description                                                                       |
+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+
| clear_transients           | WC transients                    | Clear transients              | This tool will clear the product/shop transients cache.                           |
| clear_expired_transients   | Expired transients               | Clear expired transients      | This tool will clear ALL expired transients from WordPress.                       |
| delete_orphaned_variations | Orphaned variations              | Delete orphaned variations    | This tool will delete all variations which have no parent.                        |
| recount_terms              | Term counts                      | Recount terms                 | This tool will recount product terms - useful when changing your settings in a wa |
|                            |                                  |                               | y which hides products from the catalog.                                          |
| reset_roles                | Capabilities                     | Reset capabilities            | This tool will reset the admin, customer and shop_manager roles to default. Use t |
|                            |                                  |                               | his if your users cannot access all of the WooCommerce admin pages.               |
| clear_sessions             | Customer sessions                | Clear all sessions            | <strong class="red">Note:</strong> This tool will delete all customer session dat |
|                            |                                  |                               | a from the database, including any current live carts.                            |
| install_pages              | Install WooCommerce pages        | Install pages                 | <strong class="red">Note:</strong> This tool will install all the missing WooComm |
|                            |                                  |                               | erce pages. Pages already defined and set up will not be replaced.                |
| delete_taxes               | Delete all WooCommerce tax rates | Delete ALL tax rates          | <strong class="red">Note:</strong> This option will delete ALL of your tax rates, |
|                            |                                  |                               |  use with caution.                                                                |
| reset_tracking             | Reset usage tracking settings    | Reset usage tracking settings | This will reset your usage tracking settings, causing it to show the opt-in banne |
|                            |                                  |                               | r again and not sending any data.                                                 |
+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+
```

## Creating a customer

Command:

`$ wp wc customer create --email='woo@woo.local' --user=1 --billing='{"first_name":"Bob","last_name":"Tester","company":"Woo", "address_1": "123 Main St.", "city":"New York", "state:": "NY", "country":"USA"}' --shipping='{"first_name":"Bob","last_name":"Tester","company":"Woo", "address_1": "123 Main St.", "city":"New York", "state:": "NY", "country":"USA"}' --password='hunter2' --username='mrbob' --first_name='Bob' --last_name='Tester'`

Response:

`Success: Created customer 17.`

## Getting a customer in CSV format

Command:

`$ wp wc customer get 17 --user=1 --format=csv`

Response:

```bash
Field,Value
id,17
date_created,2016-12-09T20:22:10
date_modified,2016-12-09T20:22:10
email,woo@woo.local
first_name,Bob
last_name,Tester
role,customer
username,mrbob
billing,"{""first_name"":""Bob"",""last_name"":""Tester"",""company"":""Woo"",""address_1"":""123 Main St."",""address_2"":"""",""city"":""New York"",""state"":"""",""postcode"":"""","
"country"":""USA"",""email"":"""",""phone"":""""}"
shipping,"{""first_name"":""Bob"",""last_name"":""Tester"",""company"":""Woo"",""address_1"":""123 Main St."",""address_2"":"""",""city"":""New York"",""state"":"""",""postcode"":"""",
""country"":""USA""}"
is_paying_customer,false
meta_data,"[{""id"":825,""key"":""shipping_company"",""value"":""Woo""},{""id"":829,""key"":""_order_count"",""value"":""0""},{""id"":830,""key"":""_money_spent"",""value"":""0""}]"
orders_count,0
total_spent,0.00
avatar_url,http://2.gravatar.com/avatar/5791d33f7d6472478c0b5fa69133f09a?s=96
```

## Adding a customer note on order 355

Command:

`$ wp wc order_note create 355 --note="Great repeat customer" --customer_note=true --user=1`

Response:

`Success: Created order_note 286.`

## Getting an order note

Command:

`$ wp wc order_note get 355 286 --user=1`

Response:

```bash
+---------------+-----------------------+
| Field         | Value                 |
+---------------+-----------------------+
| id            | 286                   |
| date_created  | 2016-12-09T20:27:26   |
| note          | Great repeat customer |
| customer_note | true                  |
+---------------+-----------------------+
```

## Updating a coupon

Command:

`$ wp wc shop_coupon update 45 --amount='10' --discount_type='percent' --free_shipping=true --user=1`

Response:

`Success: Updated shop_coupon 45.`

## Getting a coupon

Command:

`$ wp wc shop_coupon get 45 --user=1`

Response:

```bash
+-----------------------------+---------------------+
| Field                       | Value               |

+-----------------------------+---------------------+
| id                          | 45                  |
| code                        | hello               |
| amount                      | 10.00               |
| date_created                | 2016-08-09T17:37:28 |
| date_modified               | 2016-12-09T20:30:32 |
| discount_type               | percent             |
| description                 | Yay                 |
| date_expires                | 2016-10-22T00:00:00 |
| usage_count                 | 2                   |
| individual_use              | false               |
| product_ids                 | []                  |
| excluded_product_ids        | []                  |
| usage_limit                 | null                |
| usage_limit_per_user        | null                |
| limit_usage_to_x_items      | null                |
| free_shipping               | true                |
| product_categories          | []                  |
| excluded_product_categories | []                  |
| exclude_sale_items          | false               |
| minimum_amount              | 0.00                |
| maximum_amount              | 0.00                |
| email_restrictions          | []                  |
| used_by                     | ["1","1"]           |
| meta_data                   | []                  |
+-----------------------------+---------------------+
```

## Upgrading the database using WP CLI

When new versions of WooCommerce are released, often you'll be prompted to run a database upgrade. Whilst it's possible to do this through WP admin, advanced users may prefer to run these upgrades via the CLI, for example, on busy stores where timeouts could occur.

To update the database, use the following CLI command:

`$ wp wc update`

There are no extra arguments needed, and only the pending upgrades will be run. Once the updates have been run, the new version will be shown.


---

## Billing API for SaaS products

*Source: woo-marketplace/billing-api-saas.mdx*

# Billing API for SaaS products

## Introduction

Woo Marketplace's Billing API enables you to sell subscriptions for your SaaS app on the Woo Marketplace, via our in-house billing and subscription system. Woo Marketplace's Billing API supports recurring payments, free trials, upgrades, downgrades, and one-time payments.

Follow this guide to get your billing powered by WooCommerce's world-class billing system, and listed on the Woo Marketplace. You can integrate the Billing API with your existing sign-up and purchase flows, or create a different experience specifically for customers coming from WooCommerce.com.

[View API reference documentation](https://woocommerce-saas-billing-api.view.fast/)

## Set up your SaaS App

To complete integrating WooCommerce Billing into your SaaS app, you'll need a sandbox and the API reference. The various API flows are described below.

To get started, please [submit your product](/docs/woo-marketplace/submitting-your-product/) to the WooCommerce Marketplace. Include details about your product and upload a zip file to test whether your product utilizes a WordPress plugin to connect to your app. We will review your product to determine if it is a good fit before granting sandbox access.

### Sandbox for testing

The integration with the SaaS Billing API should be implemented and tested inside the sandbox, before being opened up for production usage. The differences between production and sandbox are the domain (sandbox.woocommerce.com) and the API credentials. Switching from sandbox to production should just be a matter of changing the domain name, API key and secret.

**Sandbox domain:** `https://sandbox.woocommerce.com/`
**Base URL for API on the sandbox:** `https://sandbox.woocommerce.com/wp-json/wccom/billing/1.0/`

### Local Development

There are a couple of things to consider when developing locally:

1. The `return_url` API parameter doesn't accept `localhost` as a value. You can map the localhost IP to a domain in your `hosts` file and use that instead. Example: `127.0.0.1 app.local`

2. Your app must be publicly accessible for webhook calls to reach it. One option is to use a service such as ngrok.com to expose it to the internet. You don't need the `hosts` file mapping in this case. You'll use the generated public URL instead.

### SaaS application settings

Once your submission is advanced from Business Review, we will create an app for you on our sandbox to complete the integration. From this sandbox vendor account, you can view and edit your SaaS application settings. After setup, you'll be able to log in to your vendor dashboard and access your SaaS application settings.

Navigate to **SaaS Apps** to view the list of applications. You'll likely have only one.

![SaaS Apps list](./_media/image-85.png)

To access the application's settings, click on the API key. On the settings page, you can view and copy your API key and secret, generate a new API key & secret pair, and add/edit/remove the webhook URL associated with your application.

![SaaS application settings](./_media/image-86.png)

### API reference

**API reference documentation:** [https://woocommerce-saas-billing-api.view.fast/](https://woocommerce-saas-billing-api.view.fast/)

You can download the OpenAPI specification file from the documentation link above and use it with any tool that supports this standard. For example, you can import it into Postman to get a ready-to-use collection of requests.

Please note that all paths in the reference documentation are relative to the base URL. For example, the `/subscriptions` endpoint will be resolved into the full URL `https://woocommerce.com/wp-json/wccom/billing/1.0/subscriptions`.

### Authentication

Each vendor application is issued a set of credentials (API key and secret) during onboarding. To authenticate API requests, you need to use the [Basic](https://tools.ietf.org/html/rfc7617) authentication method and pass the following HTTP header with your request:

`Authorization: Basic base64encode(api_key:api_secret)`

Here's an example of a POST request to the /subscriptions endpoint to initiate a plan purchase (please replace ENCODED_KEY_SECRET_STRING with your own secret key):

```bash
curl --request POST \
  --url https://sandbox.woocommerce.com/wp-json/wccom/billing/1.0/subscriptions \
  --header 'Authorization: Basic ENCODED_KEY_SECRET_STRING' \
  --header 'Content-Type: application/json' \
  --data '{"name": "test plan", "price": 199.99, "billing_period": "year", "billing_interval": 1, "return_url": "https://example.com"}'
```

### Technical review

Your integration with the WooCommerce.com billing system goes through a technical review before the SaaS product can be listed in the marketplace. Once your integration with the WooCommerce.com sandbox is ready, please send us a link where we can test it so we can confirm everything's working great. It doesn't need to be your live environment, but it should be a working example that can be accessed by our technical team for review.

## Creating a Subscription

![The flow for completing a purchase using WooCommerce.com's Billing API](./_media/saas-billing-contract-flow.png)

Merchants need to go through the contract sign-up flow to acquire an active subscription to your SaaS plan.

### 1. Merchant clicks a link to purchase a plan

Either via a link on your website, or from the Woo Marketplace, merchants follow a link to purchase your paid SaaS plan.

The customer is then directed to WooCommerce.com to pay for their purchase.

Before purchasing, it is useful to have the customer sign up for an account. This account can then be linked in your SaaS app to the paid purchase, once confirmed.

Please ensure that customers coming from WooCommerce.com are distinguished from others: the only available payment method for them is WooCommerce.com's billing system.

If there are several plans available in your application, you can have the merchant choose one before initiating the purchase.

You may also decide to not show the merchant anything and initiate the purchase immediately, as described in the next step.

### 2. Initiate the purchase

Make an **API call to WooCommerce.com's Billing API** with the subscription plan information. You'll receive a **confirmation URL** in the response.

Typical [subscription plan information](https://woocommerce-saas-billing-api.view.fast/#/paths/~1subscriptions/post) includes:

- the plan name
- price
- billing period
- billing interval
- trial period (optional)
- trial length (optional)
- Return URL

The return URL is a URL in your application where we'll redirect the merchant after they complete the purchase on WooCommerce.com.

The confirmation URL is unique on WooCommerce.com. Your application needs to redirect the merchant to it to confirm and pay for the subscription.

The response also contains a unique subscription contract ID in the form of a UUID, which you can use to associate the subscription in our systems with your application's internal customer ID.

If you initiate the purchase immediately when the customer lands on the application, and then redirect to WooCommerce.com confirmation URL during the same request, the operation will take less than a few seconds to complete. The experience for the merchant is seamless, as if they never left WooCommerce.com.

### 3. Merchant confirms the purchase

The application redirects the merchant to the confirmation URL on WooCommerce.com, where they'll confirm and pay for the subscription. The merchant goes through a familiar checkout experience, with all the necessary payment information pre-filled if they've purchased from WooCommerce.com before.

Note: The application must associate a successful purchase with a user only after the user has given "consent" and completed the entire checkout flow on WooCommerce.com. The application must account for interruptions during the purchase flow, e.g app crashes, connection drops, power outages, etc. This also includes if the user is redirected to WooCommerce.com checkout and then navigates back to your application instead of confirming the purchase. The application should not update with the plan information until the user confirms their purchase on WooCommerce.com.

### 4. Merchant is redirected to your application

After the merchant confirms and completes the purchase, they are redirected to the return URL you provided in the initiation step. If you haven't already signed up the merchant, you can do it in this phase. The return URL passes the contract ID in a GET parameter, so you can associate it with your internal customer ID.

WooCommerce.com also makes a webhook call to your webhook URL with the saas_billing_contract.activated topic. This signals that the contract was confirmed and the payment was successful.

## Free Trials

Our billing system optionally supports free trials. Free trials help reduce the number of refunds and cancellations by allowing merchants to see if the service is a good fit for them before purchasing. You can specify the trial period during the subscription signup initiation phase. Pass the trial_period and trial_length parameters during the initial API call.

We automatically charge the subscription price when the trial period ends if the merchant didn't cancel the subscription. You will get a webhook call with the saas_billing_contract.renewed topic and the contract details. Please review the webhook section for more information.

## Switching between subscriptions

The Billing API supports subscription upgrades, downgrades, and crossgrades. Use this feature to change the billing interval (ex. monthly to yearly) or switch to a subscription with a higher, lower, or equal price per day.

### The typical flow

1. **Initiate the switch**
   Initiate a subscription switch using the POST /subscriptions/\{contractID\} endpoint. Provide all of the necessary information, as described in the API documentation. There will be a confirmation_url parameter in the response. Redirect the merchant to this URL so they can confirm the switch and pay any prorated amount. Please see the API documentation for more details.

2. **Merchant confirms the switch**
   The merchant lands on WooCommerce.com to confirm the switch. If a prorated amount is due, or if one was passed in the previous step, they'll need to pay to complete the switch. If the new subscription is cheaper (a downgrade) they'll be credited for the difference by having their subscription extended.

3. **Merchant is redirected to your application**
   Once the merchant confirms the switch, the subscription is updated on WooCommerce.com and they are redirected to the return URL you provided in the initiation phase. The contract id is appended to this URL as a GET parameter. This is a good time to update their subscription in your systems. WooCommerce.com also makes a server-to-server call to your webhook URL with the saas_billing_contract.updated topic. The webhook request body contains the contract object. Check out the webhook section for more details.

### How proration works

The Billing API automatically adjusts the next payment date and charges any prorated fee by looking at the cost per day of the old and new subscriptions.

#### Downgrade

The system compensates the merchant for the prepaid amount by pushing the next payment date into the future. It multiplies the price per day of the old subscription with the number of days left in the current billing cycle. It uses this amount to cover as many days as possible at the new subscription price per day. The merchant doesn't pay a prorated fee when they downgrade their subscription.

#### Example: Downgrade proration

A merchant purchased a $100/year subscription on the 1st of January. They downgrade to a $6/month subscription two months into the billing cycle. As a result, the system pushes the next payment date to the 19th of April of the following year.

- Price/day of the old subscription → $0.27/day ( $100 / 365 days )
- Price/day of the new subscription → $0.2/day ( $6 / 30 days )
- Total days spent on old plan → 59 days ( 31 in Jan + 28 in Feb )
- Days remaining on old plan → 306 ( 365 – 59 )
- Total prepaid credit remaining → $82.62 ( 306 days left * $0.27/day )
- The number of days the credit can cover for the new plan → 414 days ( $82.62 / $0.2 = 413.1 rounded up to 414 )
- Next payment date → April 19th, 2023 ( March 1st + 414 days )

#### Crossgrade

It's the simplest type of switch to understand. The price per day doesn't change in this case. The system doesn't change the next payment date or charge a prorated fee.

#### Example: Crossgrade equal price/day

A merchant switches from a $10/month subscription to a $120/year one (or vice versa). The price per day is the same, $0.33. The subscription will renew after the prepaid month is up at $120 for the following year.

### Upgrade

#### Upgrading to a subscription with a shorter billing cycle

The system doesn't charge the merchant a prorated fee when they upgrade to a subscription with a shorter billing cycle. It brings the next payment date closer to the upgrade date, depending on the nr. of days spent in the old billing cycle. The next payment date can be as early as the upgrade date.

#### Example: Upgrade to shorter billing cycle

A merchant subscribes to a $10/month subscription. Twelve days into the billing cycle, they upgrade to a $7/week subscription. Notice the billing cycle of the new subscription is shorter, so no prorated fee is charged.

The system adjusts the next payment date. It multiplies the days spent in the old billing cycle, 12, with the new subscription price per day of $1. The resulting amount, $12, is higher than the new subscription price of $7. So it charges the merchant $7 for renewal and sets the next payment date a week into the future. The same applies when the amount is equal to the new subscription price.

When the amount is lower, it compensates for the difference by extending the renewal date with the number of days covered by the resulting amount, counting from the upgrade date.

#### Upgrading to a subscription with an equal or longer billing cycle

The system charges a prorated fee when the merchant upgrades to a subscription with a billing cycle equal to or longer than the old one. It calculates the prorated fee by multiplying the nr. of days remaining in the current subscription's billing cycle with the price per day difference between the two subscriptions. The next payment date doesn't change in this case.

#### Example: Upgrade to equal or longer billing cycle

The merchant subscribes to a $10/month subscription. Fifteen days into the billing cycle, they upgrade to a $150/year subscription. Note that the billing cycle is longer in this case, so a prorated fee is due. The cost per day for the old and new subscriptions is approximately $0.33 and $0.41, respectively. The price difference between the two is $0.08 per day. There are 15 days left in the current billing cycle, so the system charges a proration fee of $0.08 x 15 days, resulting in a $1.20 upgrade cost. The subscription will renew after those 15 days at $150/year.

## One-time charges

The Billing API also supports one-time charges. This feature can be used to charge merchants for things that are not renewable. For example, say you're offering email delivery services and you want to offer credit packs to your customers to use during promotions, or whenever they need an extra boost. These don't incur recurring charges and can be purchased as needed. The typical one-time charge flow is very similar to the subscription signup flow and is described below.

### 1. Initiate the charge

Initiate a charge by calling the POST /charges endpoint. Provide the necessary information as described in the API documentation. The response will have a confirmation_url. Redirect the merchant to this URL. See the API documentation for more details.

### 2. Merchant confirms the charge

The merchant lands on WooCommerce.com and confirms the charge details. Once they complete the payment, they're redirected to the return URL you provided in the initiation phase.

### 3. Merchant is redirected to your application

The merchant is redirected back to you via the return URL. The charge contract id is appended to this URL as a GET parameter. This is a good time to add the product they paid for to their account. WooCommerce.com also makes a server-to-server call to your webhook URL with the saas_billing_contract.activated topic. The webhook request body will have the charge object. Please review the webhook section for more details.

## Renewals

WooCommerce.com handles renewals automatically. It provides a hands-off experience for merchants, like all other products sold through the Marketplace.

Your application needs to support automatic renewals. Please make sure the merchant doesn't have to take any manual action on your end for the renewal to occur.

Use the webhook system to get notifications about renewals. We'll notify you about successful and failed renewals alike. If a renewal fails, we'll place the subscription in the paused state and notify you. We'll make further attempts to renew the subscription in the following days and notify you if we succeed. We don't delete expired subscriptions. Feel free to cancel an expired subscription at your discretion.

WooCommerce.com will email merchants before and on the day of the renewal. Feel free to send any renewal-related communication of your own to them as well.

## Refunds

Merchants can request a refund for all of the following types of SaaS billing orders. There is no limit on the number of days after payment during which the refund can be requested:

- Subscription contract sign-up
- Subscription plan upgrade
- Subscription renewal
- One-time charge

As a vendor, you will receive an email notification when a refund is requested for any of your SaaS products. You can review all the pending refund requests in your vendor dashboard by going to the "SaaS Apps -> Pending Refunds" page.

![View pending refund requests for your SaaS applications](./_media/image-87.png)

You can review each request, contact the merchant if you want to discuss the reasons for their refund request, and finally decide to either Approve or Reject the request. You need to provide a reason if you are rejecting a refund request.

If you approve a refund request for a SaaS billing order, the underlying SaaS contract will also be canceled.

WooCommerce.com also makes server-to-server calls to your webhook URL with the saas_billing_contract.refunded and saas_billing_contract.canceled topics. The webhook request body contains the contract object. Check out the webhook section for more details.

## Subscription cancellations

Merchants must be able to cancel a subscription from your application, so please make sure that feature is implemented. There is a dedicated endpoint in the HTTP API to cancel contracts. Please review our API documentation for the DELETE endpoints.

If the merchant cancels the subscription, the expectation is that they'll benefit from their current plan until the end of the prepaid period.

For example, if a yearly subscription is canceled after 3 months the merchant will benefit from your service for the remaining 9 months. What you do with the merchant account in your application after they cancel their subscription is up to you.

## Webhooks

We send notifications to your application about important events in the lifecycle of your subscriptions. The events are listed below and always include a snapshot of the contract in the request's body and reflects the state of the contract at the time of the call.

![Webhook example](./_media/webhook.png)

Webhook calls expect a successful HTTP code in response. Otherwise, the delivery is considered to have failed. A retry system will attempt to call your webhook endpoint again, up to five times, increasing the pause between each retry. Be sure to have monitoring in place for your webhook endpoint. There's no other way to get updates on some of the contract events. A typical request body payload looks like this:

**Example: Subscription contract payload**

```json
{
  "subscription":{
    "id":"4733be9c-8d6c-4a78-a4f8-268a64770985",
    "status":"active",
    "next_payment_date":"2022-08-24 14:13:42",
    "end_date":null,
    "billing_intents":[
      {
        "id":1,
        "status":"completed",
        "payload":{},
        "created_at":"2022-06-24 14:13:35",
        "updated_at":"2022-06-24 14:14:06"
      }
    ],
    "transactions":[
      {
        "id":1,
        "billing_intent_id":1,
        "created_at":"2022-06-24 14:13:42",
        "completed_at":"2022-06-24 14:14:03",
        "amount":89.5,
        "amount_refunded":0,
        "url":"https://woocommerce.com/my-account/view-order/172"
      },
      {
        "id":2,
        "billing_intent_id":1,
        "created_at":"2022-07-24 14:13:42",
        "completed_at":"2022-07-24 14:14:23",
        "amount":89.5,
        "amount_refunded":0,
        "url":"https://woocommerce.com/my-account/view-order/179"
      }
    ]
  }
}
```

**Example: One-time charge contract payload**

```json
{
  "charge":{
    "id":"68f28fbe-8510-4369-8f80-c5a5380c85db",
    "status":"active",
    "billing_intents":[
      {
        "id":1,
        "status":"completed",
        "payload":{},
        "created_at":"2022-07-01 10:21:24",
        "updated_at":"2022-07-01 10:22:39"
      }
    ],
    "transactions":[
      {
        "id":1,
        "billing_intent_id":1,
        "created_at":"2022-07-01 10:21:31",
        "completed_at":"2022-07-01 10:22:39",
        "amount":89.5,
        "amount_refunded":0,
        "url":"https://woocommerce.com/my-account/view-order/199"
      }
    ]
  }
}
```

As you can see, we don't share merchant information via webhooks. They are primarily used to notify you, the vendor, about various changes in the lifetime of a contract. The request payload includes the contract ID, status, and any billing intents. The event that triggers the webhook call is delivered as a topic and can be found in the x-wc-webhook-topic request header.

The topics that are currently available are:

- **saas_billing_contract.activated** – This event signals a merchant successfully checked out with a subscription or one-time charge. This indicates the contract is paid for and active. You can use this event to activate their plan or feature.
- **saas_billing_contract.updated** – This event is specific to subscriptions. It's fired when a merchant successfully confirms a plan upgrade or downgrade and pays the prorated amount (if any). The contract status is active. You can use this event to update their plan in your system.
- **saas_billing_contract.renewed** – This event is specific to subscriptions and is fired when a successful subscription renewal occurs. This event indicates that the merchant was successfully charged the renewal amount. The contract status is active.
- **saas_billing_contract.paused** – This event is specific to subscriptions and is fired when a subscription contract status becomes paused. This happens when a renewal is due, but for whatever reason, we couldn't process it. Issues with the payment method usually cause this, but we have systems to retry renewals. The subscription will eventually be paid for and trigger a renewed event or expire, in which case a canceled event will be triggered. You can use this event to reach out to the customer if you wish.
- **saas_billing_contract.canceled** – This one is fired when a subscription or one-time charge is canceled. Use this to deactivate a merchant's plan or feature based on the end of the prepaid term date. Please note that charges can only be canceled before the merchant confirms them. As the vendor, you can cancel contracts using the corresponding DELETE call described in the API documentation. Please note that when you cancel the contract, the customer is entitled to continue using the plan until the prepaid period ends. The date is included in the contract payload in the body of the webhook call. Don't worry. We'll send a follow-up event when the prepaid period ends. The contract or charge included with the webhook call will have the canceled status.
- **saas_billing_contract.prepaid_term_ended** – This follow-up event is fired when the prepaid period for a canceled contract is reached. Use this to deactivate a merchant's plan or feature.
- **saas_billing_contract.refunded** – This one is fired when a subscription or one-time charge is refunded. You can find the refunded amount by inspecting the amount_refunded field on the latest transaction (from the transactions property of the subscription or one-time charge).

The request body payload is signed with the API secret, and the signature is included with the X-WC-Webhook-Signature request header. You can use the signature to confirm the integrity of the payload.

An example of PHP code to make the validation:

```php
$api_secret = 'YOUR_SECRET';
$payload = file_get_contents( 'php://input' );
$provided_signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$valid_signature = base64_encode( hash_hmac( 'sha256', $payload, $api_secret, true ) );

if (hash_equals($valid_signature, $provided_signature)) {
  $request_origin_confirmed = true;
} else {
  $request_origin_confirmed = false;
}
```

To enable webhook notifications, you need to provide a URL in your application that accepts webhook requests. The URL must be publicly accessible, with no authentication or IP whitelisting. We currently support one webhook endpoint per application. You can add, update, or remove the application's webhook URL in your SaaS application settings.

### SaaS webhook testing tool

This tool is only available on the sandbox to help with the integration step. This is not available in production as it has side effects for payments, user communication, subscription status, etc. This tool aims to help you, the vendor, test your webhook integration in an easy, repeatable way.

To use the webhook testing tool, log into your vendor dashboard on sandbox.woocommerce.com and navigate to SaaS Apps > Webhooks.

Input any contract UUID you'd like to test webhook calls against in the form and hit enter or click on Select for testing. The page will reload with the contract selected. You can trigger webhook calls for the selected contract by clicking on the appropriate event button on the page. Please note that the available events depend on the current contract status. The webhook call is triggered async, so it may take up to a minute to receive the call. You can read more about the available webhook events in the webhooks section of this documentation. Make sure you have a webhook URL set up in your SaaS Application settings.

## Questions & answers

<details>
<summary>Is there support for multi-currency?</summary>

Not at the moment. Only USD is currently supported. We're considering adding currencies like EUR or GBP, but there's no ETA.

</details>

<details>
<summary>How are taxes handled?</summary>

We add tax on top of the original price to comply with the merchant's local regulations. The tax amount will vary depending on the merchant's country of residence and will be calculated automatically. You can add a notice about this in your application to inform merchants that the total may differ due to tax.

There's no reliable way to confidently calculate tax before the merchant lands on WooCommerce.com and submits their billing details. Many factors determine the tax calculation. This makes it impossible to make a correct prediction without having all the necessary data upfront (such as billing address, IP address, validated VAT ID, and others).

</details>

<details>
<summary>Do my application and WooCommerce.com exchange merchant personal information?</summary>

No, we don't share personal details like email, name, or address with the vendor application. And we don't expect you to either. The flows are designed to work without exchanging personal information. So, if you need any personal data from the merchant, you can request it from them during sign-up.

</details>

<details>
<summary>How do I link a merchant with their subscription on WooCommerce.com?</summary>

You can map them using the unique contract ID appended to the return URL the merchant is redirected to after a successful purchase. The billing API and webhooks also use this ID to identify the subscription. There's no need to use personal information to map merchants to purchases.

</details>

<details>
<summary>My SaaS product allows for multi-store connections. Can I still integrate with the billing API?</summary>

Yes. You can offer a multi-site plan for purchase. The billing API doesn't support setting a quantity parameter in its current iteration. However, you can factor the multisite aspect into the contract and offer a multisite subscription. You can then track the usage internally using a combination of the contract ID and a store identifier.

</details>

<details>
<summary>Do I need to apply billing requirements to all customers?</summary>

Getting listed on the WooCommerce.com Marketplace enables software vendors to offer their products to a broad audience of millions of registered users. As with any other marketplace, you must follow some guidelines and requirements to get your product listed. This improves customers' overall quality and experience, so they choose to purchase through us rather than from software vendors directly.

These requirements don't apply to all your customers, only those from WooCommerce.com. You can use your current billing system and flows for your existing customer base or customers from sources other than our marketplace.

</details>

<details>
<summary>How do I apply a discount to a subscription?</summary>

When initiating a contract sign-up via the API, you can set a price by specifying the lower amount in the price param when submitting the POST /subscriptions request.

</details>

## Glossary

- **Vendor** – SaaS service provider partnering with WooCommerce.com to sell their solution via the WooCommerce.com marketplace.
- **Vendor application (application)** – The Vendor's application integrates with the Billing API to communicate with WooCommerce.com.
- **Merchant** – WooCommerce.com user, purchasing the SaaS product.
- **Subscription plan (plan)** – A subscription product.
- **Subscription contract (contract)** – Agreement in which merchant consents to have their payment method charged recurrently in exchange for the service the SaaS Vendor offers.
- **One-time charge (charge)** – A one-off (non-renewable) charge.
- **Contract sign-up** – Creating a subscription or charge contract and getting the merchant's confirmation.


---

## Marketplace Content Style Guide

*Source: woo-marketplace/content-style-guide.md*

# Marketplace Content Style Guide

This guide provides formatting and writing standards for creating product pages and documentation on the WooCommerce Marketplace. Following these guidelines ensures consistency across the Marketplace and creates a professional experience for merchants browsing and purchasing extensions.

For product page structure, required elements, and asset specifications, refer to [Product Page Content and Assets](/docs/woo-marketplace/product-page-content-and-assets/).

## Writing Standards

### Product Naming Convention

Use the format "Product Name for WooCommerce" rather than "WooCommerce Product Name" throughout the product copy.

This format ensures your product name complies with [trademark rules](https://woocommerce.com/trademark-guidelines/) and leads with its unique identifier, improving discoverability and clarity.

### Grammar and Punctuation

Follow the [WooCommerce grammar, punctuation, and capitalization guide](/docs/best-practices/coding-standards/grammar-punctuation-capitalization/) for comprehensive guidance. Key points include:

**Use the Oxford comma** when listing three or more items:

- ✓ "Track orders, manage inventory, and process refunds."
- ✗ "Track orders, manage inventory and process refunds."

**Use active voice** instead of passive voice whenever possible:

- ✓ "The extension sends email notifications when orders ship."
- ✗ "Email notifications are sent by the extension when orders are shipped."

**Capitalization:**

- Use sentence case for headings (capitalize only the first word and proper nouns)
- Do not use ALL CAPS for emphasis
- Capitalize product names, features, and WooCommerce terminology correctly

**Spelling and terminology:**

- Use American English spelling
- Use "ecommerce" (lowercase, no hyphen)
- Use "WooCommerce" (not "Woocommerce" or "wooCommerce")

## Formatting Guidelines

Maintain clean, consistent formatting by following these standards. Custom styling interferes with the Marketplace design system and creates an inconsistent experience.

### Text Formatting

**Do not:**

- Center headings or body text
- Alter the default text color
- Add custom font sizes or font families
- Use bold or italic formatting excessively

**Do:**

- Use left-aligned text throughout
- Allow headings and paragraphs to inherit default styles
- Use bold sparingly for key terms only

### Headings

**Do not:**

- Include more than one H1 tag per page (the product title serves as the H1)
- Center-align headings
- Apply custom colors or styles to headings

**Do:**

- Use H2 for main sections
- Use H3 for subsections within an H2 section
- Maintain a logical heading hierarchy (do not skip levels)

### Sections and Layout

**Do not:**

- Create custom-styled sections or containers
- Add borders around sections
- Apply background colors to content areas
- Add custom spacing between sections
- Add additional styles to columns

**Do:**

- Use standard paragraph and heading blocks
- Let the Marketplace template handle section spacing
- Use the default column block without style modifications

### Lists

**Do not:**

- Customize bullet or number designs with custom CSS
- Add custom spacing between list items
- Create nested lists more than two levels deep

**Do:**

- Use the standard unordered or ordered list blocks
- Apply the approved list classes for styled checkmarks (see Formatting Tools below)

## Content Restrictions

### Emojis

Do not use emojis in product pages or documentation. Emojis can cause accessibility issues, display inconsistently across devices, and create an unprofessional appearance.

- ✗ "🚀 Boost your sales!"
- ✓ "Boost your sales"

### External Links

Do not include links to external websites. All support and documentation links should point to Marketplace URLs:

- Link to your product documentation hosted on WooCommerce.com
- Link to Marketplace support resources
- Do not link to external support portals, documentation sites, or landing pages

## Formatting Tools

The WooCommerce Marketplace provides several formatting tools to create visually appealing content while maintaining consistency.

### Styled List Classes

Use these CSS classes to create professional checkmark lists:

#### Primary checkmark list (wccom-tick-list-primary)

Creates bold checkmarks in green circles. Use for main benefit lists at the top of your product description.

```html
<ul class="wccom-tick-list-primary">
  <li>Accept payments globally</li>
  <li>Automatic tax calculation</li>
  <li>Real-time shipping rates</li>
</ul>
```

#### Secondary checkmark list (wccom-tick-list-secondary)

Creates lightweight green checkmarks. Use for feature lists and secondary content throughout the page.

```html
<ul class="wccom-tick-list-secondary">
  <li>Supports 100+ currencies</li>
  <li>PCI compliant</li>
  <li>Automatic updates</li>
</ul>
```

### Callout Boxes

Use the box shortcode to highlight important information. Available styles:

#### Info box

For general tips and helpful information:

```plain
[box]This extension requires WooCommerce 8.0 or higher.[/box]
```

This component can be used with or without `style="info"`.

#### Alert box (style="alert")

For warnings or important notices:

```plain
[box style="alert"]Backup your site before updating to the latest version.[/box]
```

#### Error box (style="error")

For critical warnings or known limitations:

```plain
[box style="error"]This extension is not compatible with multisite installations.[/box]
```

#### Success box (style="success")

For positive confirmations or best practices:

```plain
[box style="success"]Your API credentials are securely encrypted and stored.[/box]
```

:::info
Use callout boxes sparingly. Overuse reduces their impact and creates visual clutter.
:::

## Documentation Standards

When creating documentation for your product, follow these additional guidelines:

### Structure

- Begin with a clear introduction explaining what the extension does
- Please use the synced pattern titled "Docs – Installation." This explains how our mutual customers should install purchases from WooCommerce.com.
- Document all your product's features and settings
- Provide troubleshooting guidance for common issues

For detailed documentation frameworks, refer to [Support and Documentation Best Practices](/docs/extensions/best-practices-extensions/support-and-documentation/).

### Images and Screenshots

When adding visual content:

- Use the modern WordPress admin color scheme
- Use a recent core WordPress theme unless documenting a different theme
- Ensure screenshots are clear and legible
- Optimize file size
- Do not include sensitive or personal information in screenshots
- Add alt text to all images for accessibility


---

## Earning the Excellence Verified badge on the Woo Marketplace

*Source: woo-marketplace/excellence-verified-badge.md*

# Earning the Excellence Verified badge on the Woo Marketplace

The Woo Marketplace is a trusted source for merchants searching for high-quality extensions to add to their stores. That trust is what brings merchants in ready to buy, and it's what makes the Marketplace worth selling on. The Excellence Verified badge builds on it. It marks the products that reach the highest tier, checked for security, compatibility, maintenance, and merchant ratings.

This guide explains what the badge offers, how a product earns it, where vendors can check their current status, and how to close the gap.

## What the badge offers

Products that earn the Excellence Verified badge stand out across the Marketplace. The badge:

- Appears on the product page and on product cards in listings.
- Raises visibility in Discover, including a dedicated area for badged products.
- Includes the product when merchants filter to badged products only.

More benefits are on the way as the program grows, including promotional placements for badged products across more areas.

Products that don't earn the badge aren't penalized in any way. They keep their existing visibility and placement. The badge adds recognition for the products that reach the top tier.

## How to earn a badge

The badge is built on four factors, and a product needs to do well on all of them:

- **Secure**: scanned for vulnerabilities and malicious code.
- **Compatible**: installs and runs cleanly on current WordPress and WooCommerce.
- **Maintained**: kept up to date with recent releases.
- **Merchant-approved**: rated 4.0+ by real merchants.

The first three are measured by the Quality Insights Toolkit (QIT). Here's what feeds each one:

- **Secure**: WPScan, code security analysis, secret-leak detection, and malware scans.
- **Compatible**: plugin metadata validation, the HPOS compatibility declaration, coding standards, and activation without fatal errors on current WordPress and WooCommerce versions.
- **Maintained**: up-to-date "tested up to" headers, dependency vulnerability checks, and a passing end-to-end test package.

For the full list of managed tests and what each one checks, see the [QIT documentation](https://qit.woo.com/docs/), specifically the Managed Tests and Test Packages sections.

The fourth factor, Merchant-approved, has two parts and a product needs both: a strong average customer rating, and enough reviews to reflect real use. This is the part no code change can fix. It rewards products that merchants trust over time.

The exact thresholds were calibrated at launch and will evolve as the program grows. The Vendor Dashboard shows each product's QIT checklist and current badge state, so it's the place to check technical progress: Vendor **Dashboard** > **Products**.

## How to improve a product's badge standing

Most products already meet several of the requirements, so there's no starting from scratch. Products that fall short are usually close, and a few targeted fixes get there.

**Start with validation**. It's the most common blocker and one of the easiest to fix. Validation checks plugin metadata: license headers and version requirements. These are small, well-defined changes that don't touch product logic.

**Declare HPOS compatibility honestly.** Validation also checks the HPOS compatibility declaration, and this one is not a metadata edit. If a product handles orders, declare compatibility only once the order code supports HPOS. The declaration tells merchants what the product does, so setting it to true without the support behind it hides the warning WooCommerce would otherwise show them. Test order flows with HPOS enabled first — QIT accepts `--optional_features=hpos` — then declare. The [HPOS recipe book](/docs/features/orders/high-performance-order-storage/recipe-book/) covers what to check.

**Add a test package.** The check confirms that a product's own end-to-end suite runs and passes. Test packages are published to the QIT registry through the QIT CLI and stored there, never inside the zip your customers download, so there is no download bloat and no change to your product's code. The value goes beyond the badge: a real suite catches regressions before they reach merchants and makes it safer to ship updates as WordPress and WooCommerce evolve. A suite that genuinely exercises the product is worth far more than a placeholder. The [test package quickstart](https://qit.woo.com/docs/test-packages/tutorials/quickstart/) covers the setup.

**Keep compatibility headers current**. The recent-work check looks for recent WordPress and WooCommerce versions in the "tested up to" headers. Update these with each release.

**Clear any security findings.** If WPScan, code security, or any malware scan flags something, treat it as a priority. These protect merchants directly.

On the satisfaction side, there's no shortcut. Strong support, clear documentation, and a product that does what it promises are what build a strong rating over time.

## Keeping the badge

The badge isn't a one-time award. A product holds it while it keeps meeting all four factors.

Status is re-checked automatically as new versions ship and as ratings change. If a product drops below the bar on any factor, the badge comes off until the product qualifies again. The Quality tab always shows what needs attention, so the path back is clear.

## Timeline and what to expect

The badge is live on the Marketplace, and it arrived in stages that left time to prepare.

Vendors got visibility into their status through the dashboard first. An adjustment window of at least two weeks followed before the thresholds were locked, leaving time for metadata and test-package fixes, and pass rates were measured before the final thresholds were set and the badge went live.

The checks are automated and run continuously, so launch was never the only chance to qualify. A product that missed the badge at launch can earn it at any point after: every new version is a fresh opportunity.

Changes to the program and its criteria will continue to be announced in vendor comms before they take effect.

## Frequently asked questions

<details>
<summary>How many products had the badge at launch?</summary>

Only a limited share of products qualified at launch. Many are only a few targeted fixes away, so that number is expected to grow as vendors make improvements.

</details>

<details>
<summary>Does the badge cover themes and business services?</summary>

Not in the first phase. The Excellence Verified badge starts with extensions, and we'll evaluate expanding it to other product types as the program grows.

</details>

<details>
<summary>Is the badge a certification?</summary>

No. It's a quality signal based on measurable tests and real customer ratings, not a formal certification or endorsement.

</details>

<details>
<summary>What's the most effective first step?</summary>

Passing validation and adding a working test package. Those two account for most near-misses, and neither requires changing a product's core code.

</details>

<details>
<summary>Will the criteria change?</summary>

Yes. The program will continually refine its requirements over time based on vendor, merchant, and agency feedback, so the products with the highest quality are rewarded with the badge. Any changes will be communicated before they take effect.

</details>


---

## Getting started

*Source: woo-marketplace/getting-started.md*

# Getting started

We are excited to have you here! The WooCommerce.com Marketplace connects trusted developers and merchants worldwide to create powerful and flexible online stores.

## Why you should sell in the Woo Marketplace

- **Access to a global network** of WooCommerce merchants
- **Built-in brand recognition and trust** by listing your product in the official WooCommerce Marketplace
- **Revenue sharing** designed to support your business growth
- **Opportunities** to be featured in WooCommerce marketing campaigns
- **Insights and feedback** from a community of active merchants and developers

## Are you a good fit?

We are looking for products that:

- Solve real merchant problems
- Are secure, well-documented, and well-maintained
- Follow [security](https://developer.wordpress.org/apis/security/), [development](/docs/extensions/best-practices-extensions/extension-development-best-practices/), and [user experience](/docs/extensions/ux-guidelines-extensions/best-practices/) best practices
- Offer high-quality merchant support
- Include [a clear and sustainable monetization model](/docs/woo-marketplace/monetization-expectations/), whether through direct sales, subscriptions, or another approach

## The agreement

To join the WooCommerce Marketplace, vendors must offer high-quality, secure products, provide strong customer support, and follow WooCommerce's guidelines around listings, updates, pricing, and communication. The commercial terms are based on a revenue share model, with 70% of sales going to the vendor.

[Read the full Marketplace Vendor Agreement](https://woocommerce.com/woo-vendor-agreement/).

## The submission journey

### Step 1: Prepare your product

1. Build and thoroughly test your extension or theme.
2. Ensure it meets our [technical](/docs/extensions/best-practices-extensions/extension-development-best-practices/), [user experience](/docs/extensions/ux-guidelines-extensions/best-practices/) (UX), and [security standards](https://developer.wordpress.org/apis/security/).
3. Write clear and comprehensive [documentation](/docs/extensions/best-practices-extensions/support-and-documentation/).

### Step 2: Apply for a Marketplace partner account

Once your application is approved, you can submit your product to be listed in the Marketplace.

### Step 3: Submit your product

Provide detailed product information, demo links, and test instructions for review.

### Step 4: Product review

1. Our team reviews your submission for functionality, security, compatibility, and UX.
2. You may receive feedback and revision requests.

### Step 5: Launch and sell

1. Once approved, your product is listed in the WooCommerce.com Marketplace.
2. After launch, maintain and update your product, and provide ongoing merchant support.

## Helpful resources

- [Submission guidelines](/docs/woo-marketplace/submitting-your-product/)
- [Extension developer handbook](/docs/extensions/getting-started-extensions/)
- [Block theme developer handbook](/docs/theming/block-theme-development/theming-woo-blocks)
- [SaaS Billing API](/docs/woo-marketplace/billing-api-saas/)
- [Marketplace Vendor Agreement](https://woocommerce.com/woo-vendor-agreement/)

## Ready to apply?

1. [Apply for a Woo Marketplace partner account](https://woocommerce.com/partners/).
2. Before you submit, review the full [submission guidelines](/docs/woo-marketplace/submitting-your-product/#pre-submission-checklist) for detailed steps.
3. When you're ready, [submit your product](/docs/woo-marketplace/submitting-your-product/).

We look forward to helping you succeed in the WooCommerce Marketplace!


---

## Woo Marketplace

*Source: woo-marketplace/index.mdx*

import DocCardList from '@theme/DocCardList';

Documentation for developers publishing extensions, themes, and integrations on the Woo Marketplace.

<DocCardList />


---

## Managing products in the Woo Marketplace

*Source: woo-marketplace/managing-products.md*

# Managing products in the Woo Marketplace

Developers selling in the WooCommerce.com Marketplace can edit their product pages, access information like usage data and sales, and manage reviews.

## Editing a product page

Most of the work for managing products can be done via the [vendor dashboard](https://woocommerce.com/wp-admin/).

- From your vendor dashboard, navigate to _Products > All Products_.
- Select the product you want to work on.

From there, you can see information about usage, upload a new version, or edit the product page. [Review our product page guidelines](/docs/woo-marketplace/product-page-content-and-assets/).

![Product management interface in vendor dashboard](./_media/manage-products-overview.png)

### Uploading new versions

To maintain a high-quality and competitive Marketplace, we encourage all vendors to regularly update their products. Consistent updates ensure compatibility with the latest versions of WooCommerce and WordPress, improve security and performance, and deliver ongoing value to customers.

[Review our product update guidelines and best practices](/docs/woo-marketplace/product-update-guidelines/).

### Adding or editing documentation

To review, edit, or add documentation, navigate to _Documentation_ in your vendor dashboard. [Review our guidelines for creating effective documentation](/docs/extensions/best-practices-extensions/support-and-documentation).

![Documentation management interface](./_media/manage-products-documentation.png)

## Understanding product sales

Vendors have access to reports on how their products are performing, including:

- **Earnings**: New sales, renewal sales, and refund amount.
- **Commissions**: The amount the vendor earns from **net** product sales. Net revenue is defined as **revenue received from extension purchases minus refunds, chargebacks, disputes, discounts, and affiliate fees**.
- **Subscriptions**: Total active subscriptions, including new and renewing this month, as well as refund and renewal rates.

To view this information, log in to your vendor dashboard and navigate to _Analytics > Overview_.

![Analytics overview dashboard](./_media/manage-products-analytics.png)


---

## Manage your Woo Marketplace partner account

*Source: woo-marketplace/managing-your-account.mdx*

# Manage your Woo Marketplace partner account

Partners selling on the Woo Marketplace can edit their store profile and update their support email from the Partner dashboard. For some changes, we ask that you contact the Marketplace team for help.

To access store settings, click the **Store** menu under **_Settings_** in your [partner dashboard](https://woocommerce.com/wp-admin/).

## Business legal name and contact address

When you first join the WooCommerce Marketplace, we'll ask you to complete the **_Business Legal Name_** and **_Business Contact Address_** fields. These allow us to set up an account for you on our accounting platform so you can get paid for your extension sales.

![Screenshot of business name and address settings in the WooCommerce Marketplace Partner Dashboard.](./_media/vendor-store-settings-1.png)

If you make changes to the business name, you'll see a prompt to resign the **Partner Agreement**. Please click on **Partner Agreement** in the left menu, scroll down and tick the box to agree, then save. If the business name changes to a new entity after you have started selling, we will reach out about setting up a new accounting profile.

To change your vendor name, [please contact us](https://woocommerce.com/wp-admin/admin.php?page=wcpv-vendor-support).

## Vendor logo and profile

Your vendor logo and profile are a great way to tell more about yourself and your company to prospective customers! This will appear at the public profile for your brand along with your extensions.

![Screenshot of logo and profile settings in the WooCommerce Marketplace Partner Dashboard.](./_media/vendor-logo-profile.png)

- **Do:** Upload a logo for your company that **does not include** the [WooCommerce brand or trademark](https://woocommerce.com/trademark-guidelines/).
- **Do:** Tell your brand story. Why are you a great WooCommerce partner?
- **Do:** Link to your website homepage (optional). Use the same URL listed in your vendor profile if you opt to include it.
- **Don't:** Link to other products you sell outside of WooCommerce.com.
- **Don't:** Link to another contact form other than the **[WooCommerce.com contact page](https://woocommerce.com/my-account/contact-support/).**

## Other settings

**Required settings:**

- **Vendor email:** Where we send updates about orders and any other communication.
- **Support email:** The address that will receive support and presales requests.
- **Website:** Your company's website. This will not be displayed on your vendor profile.

**Optional settings:**

- **Average response time:** List in hours, not currently shown on profiles.
- **Privacy policy URL:** A link to the privacy policy on your website.
- **Support Languages:** Languages in which you offer support.
- **TOS URL:** A link to the terms of service on your website.
- **Timezone:** Timezone setting, not displayed.

![Screenshot of other settings in the WooCommerce Marketplace Partner Dashboard.](./_media/vendor-more-settings.png)

## Tools

Additional tools to help you with vendor information are available in **[Settings > Tools](https://woocommerce.com/wp-admin/admin.php?page=partner-dashboard-tools)** in the vendor dashboard.

### Google Analytics

Add your own Google Analytics tag to the Vendor Dashboard to get insights on the pages for your products, documentation and profile.

![Screenshot of field to add Google Analytics in the vendor dashboard.](./_media/vendor-tools-google-analytics.png)

### Customer subscription details

Type in a customer email and press **enter** to verify their account owns your product and qualifies for support.

### Vendor details

Need to know how to reach another vendor? Type the vendor name and hit Enter to see their support email address.

### Changelog validator

Test your `changelog.txt` file to ensure that it meets [Woo Marketplace standards](/docs/extensions/core-concepts/changelog-txt/) by copying the text of the file and pasting it into the text box. You can also use our ChatGPT [Changelog Formatter](https://chatgpt.com/g/g-9b3SlOWTF-woocommerce-com-changelog-formatter) to automatically revise your existing changelog to use in your extension.

## FAQs

<details>
<summary>How can I add someone to help me manage my products?</summary>

- We can add additional Vendor Admins to your profile at your request. Vendor Admins can assist with updating products and documentation as well as view sales reports, reviews, and feature requests.
- To request another admin, [contact us via the link in your dashboard](https://woocommerce.com/wp-admin/admin.php?page=wcpv-vendor-support) or email [partners@woocommerce.com](mailto:partners@woocommerce.com) using your current partner account email. Please first ensure that they have [created a WooCommerce.com account](https://woocommerce.com/sso?new=1&next=%2Fwoocommerce%2F) with [two-step authentication enabled](https://wordpress.com/support/security/two-step-authentication/).

</details>


---

## Monetization expectations for Marketplace plugins

*Source: woo-marketplace/monetization-expectations.md*

# Monetization expectations for Marketplace plugins

When listing a plugin on the Woo Marketplace, it's important to understand how we approach monetization. Our goal is to ensure alignment between how your plugin generates value and how that value is captured, creating a transparent experience for merchants and sustainable partnerships for developers.

:::note
We do not currently accept free plugins that have no path to monetization. There should be a path to monetization either within the plugin itself or through connection to other paid products or services that then fall into one of the monetization models listed below.
:::

## Matching monetization models

The monetization model for your Marketplace listing should reflect the way your solution generates revenue:

- **Standalone functionality plugins**: Plugins that extend WooCommerce with features not tied to an external system can be sold through the standard Marketplace license model, with billing handled directly through Woo.
- **Integration plugins**: Plugins that connect WooCommerce to an external service or platform require a monetization approach that matches how the integrated system bills merchants.

## Standalone plugin licensing

For plugins that add functionality to WooCommerce without connecting to an external service, we offer two listing options:

### Paid license

The Marketplace supports a single-site license model. If you sell your plugin elsewhere with multi-site licenses or tiered packages, your Marketplace listing should use a price that closely matches your existing single-site license fee.

### Freemium

If your plugin offers both free and paid tiers, you can list it using our Freemium model. This allows merchants to install a free version of your plugin with the option to upgrade to a paid tier for additional features. Freemium listings help merchants try before they buy while giving you an opportunity to demonstrate value and drive upgrades.

Freemium is ideal for plugins where:

- An additional plugin is needed to provide the upgraded features
- Core functionality works well as a free offering
- Premium features provide clear, demonstrable value worth upgrading for
- You want to build a user base before converting to paid

## Integration plugin requirements

For plugins that integrate WooCommerce with an external system, we have specific expectations:

### First-party development preferred

We strongly prefer that integration plugins are built and maintained by the company that owns or operates the external system being integrated. This ensures:

- Merchants have a direct relationship with the company billing them
- Technical support comes from the team with deepest product knowledge
- Long-term maintenance aligns with the external system's roadmap

In particular, payment extensions must be developed/maintained by Woo or the payment provider directly, and meet minimum quality standards.

If you're a third-party developer building an integration for a system you don't operate, we encourage you to connect with that company directly or [contact our Marketplace team](#questions-about-your-billing-structure) to discuss your specific situation.

### Appropriate billing structure

Plugins that connect to externally-billed services cannot use the standard paid Marketplace license model. Instead, you must use one of the following options:

| Billing Model | Description | Best For |
| --- | --- | --- |
| **Billing API** (recommended) | Our API handles subscription billing on behalf of your service, with validation endpoints to confirm payment status and active subscriptions. Billing shifts to Woo, and you receive payouts based on the revenue share model. [View Billing API documentation →](https://woocommerce.com/document/billing-api-for-saas-products/) | SaaS providers who want Woo to manage the billing relationship with merchants. |
| **Partnership Agreement** | An agreement that extends our [Marketplace Vendor Agreement](https://woocommerce.com/woo-vendor-agreement/) to accommodate solutions where billing occurs outside of WooCommerce. The plugin is listed free on the Marketplace. | Companies with existing billing relationships and infrastructure. |

### About the Partnership Agreement

The Partnership Agreement is available as an alternative when the Billing API is not suitable for your business model. However, this option requires formal agreement to our partnership conditions and is subject to approval at our discretion. We assess each application to ensure alignment with Marketplace standards and merchant experience expectations.

If you're considering this option, we recommend [contacting our Marketplace team](#questions-about-your-billing-structure) early in your planning process to discuss eligibility and requirements before investing development effort.

## Theme licensing

Themes listed on the Woo Marketplace use the standard paid license model only. Billing is handled directly through Woo using a single-site license fee.

If you sell your theme elsewhere with multi-site licenses or tiered packages, your Marketplace listing should use a price that closely matches your existing single-site license fee.

## Business services

Business services (such as consulting, development, or managed services) require a formal agreement and prior approval from the Marketplace team before listing.

If you offer business services that complement WooCommerce and would like to explore listing on the Marketplace, please [contact the Marketplace team](#questions-about-your-billing-structure) to discuss your offering and eligibility requirements.

## Questions about your billing structure?

If you're unsure which monetization model applies to your plugin, theme, or service, or if you'd like to discuss partnership options before submitting for review, please [contact the Marketplace team](https://woocommerce.com/partnerships-contact/). We recommend reaching out early in your planning process to ensure alignment before you invest significant development effort.

## Related resources

- [Marketplace Vendor Agreement](https://woocommerce.com/woo-vendor-agreement/) — Standard terms for all Marketplace vendors
- [Billing API for SaaS Products](https://woocommerce.com/document/billing-api-for-saas-products/) — Technical documentation for integrating with our billing system
- [Submitting Your Product](https://woocommerce.com/document/submitting-your-product-to-the-woo-marketplace/) — Complete submission guidelines


---

## Product page content and assets

*Source: woo-marketplace/product-page-content-and-assets.mdx*

# Product page content and assets

This document is designed to walk you through each step of editing your product page, detailing the assets you'll need and offering a few recommendations to maximize its effectiveness. Whether you're introducing a new product or refining an existing listing, the success of your page hinges on a clear, engaging, and user-friendly presentation.

## Editing the product page

1. Log in to your [Vendor Dashboard](https://woocommerce.com/wp-admin/).
2. Navigate to _Products > [All Products](https://woocommerce.com/wp-admin/edit.php?post_type=product)_.
3. Select the product you want to work on.

From there, you can see information about usage, upload a new version, or edit the product page.

![Product edit interface](./_media/product-page-edit.png)

## Product icon

The product icon is the key visual element in all occurrences of your product in the Woo Marketplace. The image should be:

- **The logo of your product, not your brand.** For example, a Gmail extension would display a Gmail logo icon, not the Google logo.
- A **160×160px** image file in JPG or PNG format.
- The image is displayed at 80x80px, so please mind legibility. We recommend logos/symbols rather than text that would be too small to read.
- Please keep the icon content inside the **112×112px** area. This region of the image is unlikely to be hidden from view.
- We use the `border-radius` property to define the radius of the icon's corners, so please don't add rounded corners to your image.

![Product icon guidelines](./_media/product-icon-guidelines.png)

![Product icon examples](./_media/highlight-card-example.png)

- Upload it under _Product Data > Woo Product Data > Product Icon_.

![Product icon upload location](./_media/product-gallery-upload.png)

- If a non-transparent image is used, please be sure to update the background color accordingly.

## Highlight card

The highlight card background color sits behind the product icon and is applied to special placements across WooCommerce.com (see the example below from the Marketplace homepage):

![Highlight card example in Marketplace](./_media/image.png)

Provide a hex color code under _Product Data > Woo Product Data > Highlight card background color_.

![Highlight card color field](./_media/image-1.png)

## Product thumb

Product thumbs are used for themes and business services. It is not necessary to add one for extensions.

- The minimum image size is 555x416px.
- Reusing the featured image is acceptable.

## Short description

Keep it short and powerful. Besides the product page, the short description is also used in the product card, or the excerpt Google uses in the search results page.

![Short description example](./_media/image_2a07b1.png)

To add/edit the short descriptions, when editing a product, scroll down to the bottom of the screen.

![Short description field location](./_media/Screenshot20on202022-04-2920at2014-15-53.png)

## Gallery

The media gallery gives you the opportunity to put your product in its best light. We recommend using it for as much as possible.

![Gallery example](./_media/image_6326de.png)

### Images

Images should be:

- 896×550 px or larger

To upload images, use the native WooCommerce gallery in the product editor, as described in the image above, and always start with the Featured Image.

### Video

The gallery supports one embeddable video per product (e.g. YouTube, Vimeo). If there's a video attached, it will always show as the first item in the gallery.

To embed a video, when editing a product, scroll down to the _Product Data_ section and click the _Featured Video_ tab. Paste in your video's embed code and click _Update_.

![Video embed location](./_media/image_f55706.png)

## Product description

![Product description editor](./_media/image_85894c.png)

When creating product pages, it's essential to communicate effectively, ensuring the content is accessible and engaging for everyone. The description gives you the most opportunity to highlight what's valuable about your product from a customer's perspective. Here are a few recommendations to help you get the best of it:

- **Optimize for AI** ― By using a direct, factual tone and clear headings that answer "what is" and "how-to." This helps generative engines cite your content as the definitive answer to a user's question.
- **Focus on Sales, Not Specs** ― Design your description to highlight key benefits, keeping technical details for documentation. This approach helps customers understand the value of your product without getting bogged down by complexity.
- **Start With Top Benefits** ― Lists are not only easy to scan but also make your most compelling selling points stand out, ensuring they're memorable and immediately accessible. A 3-5 points list format allows users to quickly understand the unique advantages your product delivers.
- **Explain Like I'm 5** ― Aim to present your products in a way that anyone, even a beginner, can understand. Simplify your explanations without compromising the message, making sure concepts are broken down into fundamental, easy-to-grasp ideas.
- **Sell the Hole, Not the Drill** ― Remember, customers are looking for solutions, not specifications. Start with the benefits your product offers, then mention the features. For instance, instead of leading with "This phone case is made of carbon fibers," highlight "Protect your phone from any fall with our ultra-durable case." It's about solving problems, not listing specifications.
- **Simple and Clear Language** ― Use plain, straightforward language that avoids industry jargon and complex terms. Break down elaborate concepts into simple explanations. This approach makes your content accessible to beginners and experts alike, ensuring everyone understands the value of your products.
- **Visual Aids and Examples** ― Leverage diagrams, screenshots, and examples to illustrate your points. Visual aids can turn abstract concepts into tangible ideas, making them easier to grasp. Leave the screenshots showcasing the settings screens or other technical parts for the documentation.
- **Empathy and Understanding** ― Acknowledge the challenges users might face, offering reassurance and support to boost their confidence in using your products.

Please do not use/paste in emojis.

See more about formatting in our [Marketplace Content Style Guide](/docs/woo-marketplace/content-style-guide/).

## FAQs

Frequently asked questions (FAQs) are incredibly valuable for potential customers, helping to clarify common pre-purchase questions and boosting customer confidence in your extensions. A well-crafted FAQ section can effectively address buyer hesitations, reduce pre-sale inquiries, and ultimately translate into revenue.

We strongly encourage you to update your existing FAQs to take advantage of this new dedicated section.

![FAQ section example](./_media/image_65ae27.png)

<details>
<summary>What to include in your FAQs</summary>

- **Usage highlights**: Think about what would appear on your product's packaging — describe how your product enhances user experience or solves common issues, but keep it brief. Add links to the documentation if longer text is needed.
- **Specific use cases**: Provide clear examples or scenarios demonstrating how customers can practically use your product.
- **Compatibility and prerequisites**: Clearly state any compatibility requirements or prerequisites. Does your product integrate seamlessly with other WooCommerce extensions or plugins?
- **Performance impact**: Address concerns customers might have about your extension's impact on their site's loading speed or overall performance.
- **Customer support encouragement**: Use the FAQ as an opportunity to reassure customers that they can always reach out to support if they have additional questions.
- **Troubleshooting and support access**: Include direct links or guidance for easily accessing troubleshooting guides and support resources.

</details>

<details>
<summary>What to avoid</summary>

- Highly technical instructions or step-by-step installation guides (these belong in your detailed documentation).
- Overly long or complicated answers: keep it concise and non-technical.
- Marketing language without substance — promotional phrases like "the best plugin ever!" FAQs should directly answer practical customer questions.
- Broad questions like "Why choose our extension?" Instead, provide specific details that users commonly inquire about.
- Lengthy explanations. Provide concise answers and link to documentation for detailed instructions.
- Excess formatting: For best legibility results, keep the styling and formatting of your paragraph down to a minimum. Writing everything in bold, CAPS, or italics doesn't help.

</details>

<details>
<summary>How to add FAQs to your product page</summary>

Go to the [Vendor Dashboard](https://woocommerce.com/wp-admin/edit.php?post_type=product) and edit the product page for one of your products.

![FAQ editor location](./_media/image_937e91.png)

</details>

## Product data features

To lay a stronger foundation for search and category filters, we've added new product data fields. The new data points are used for product features, search keywords, and product compatibility.

While we're still exploring how they'll shape the broader search and categorization experience over time, these attributes will provide more control over how products appear in search results and which filters they match, leading to a more accurate and intuitive experience for customers.

![Product data features](./_media/image_b42b52.png)

### What you need to know

- These data points have been auto-populated using AI as a first step. This helps streamline the process and gives you a starting point.
- We encourage you to review the AI-generated content to ensure it accurately reflects your product and make any updates needed.
- You'll see these fields in your product back-end when editing any of your products.
- These attributes are used in the In-app product previews (starting with WooCommerce 9.9). This means your shoppers benefit from richer, more informative previews of your products.

![In-app product preview example](./_media/image_1d1a86.png)

### Why this matters

- Customers will enjoy a cleaner, more relevant, and smoother shopping experience.
- Vendors will gain greater visibility and control over how their products are discovered.

## Listing requirements

**Requirements:** Product requirements can be added under the _Woo Product Data_ tab.

![Product requirements location](./_media/image_5fb815.png)

## Product name

### Naming guidelines

The product name is the first thing customers see when searching for products, so choosing an appropriate name is an important step. Choose a name that explains what your product does or why it's useful.

Tips for how to craft a good product name:

- **Brief** – Aim for 1 to 5 words, the fewer the better
- **Scannable** – Easy to understand
- **Unique** – Drives clicks to read more and makes it easier to find the listing via search
- **Customer focused** – Use your customers' words rather than your own

The name should NOT:

- Violate trademark guidelines of WooCommerce or any other brand name.
- Be a description of your product; use the short description to highlight the main benefits.
- Use adjectives like "best" or "amazing"
- Closely copy an existing listing name.

### Changing a product's name

To have the name of a product changed, please get in touch with the Woo Marketplace team via your Vendor Dashboard.

![Change product name location](./_media/image_35074a.png)

## Product price

To have the price of a product changed, please get in touch with the Woo Marketplace team via your Vendor Dashboard.

![Change product price location](./_media/image_b46eda.png)

## Demo

Providing product demos of your WooCommerce extension is important — it helps potential customers quickly understand how your product works, what features it offers, and how it can benefit their store. A demo builds trust, reduces hesitation, and can significantly increase conversions by showing the value of your extension in action.

Here are 3 things to make sure you include in your demo setup:

- **Show both front-end and back-end views** – Give users a complete picture of how the extension works from a store owner's and a customer's perspective.
- **Use secure (HTTPS) links** – This ensures user safety and builds trust when they visit your demo site.
- **Link directly to relevant pages** – Let users experience the extension in action without having to click around or guess where to go.

To add a link to your demo, when editing a product, go to the _Woo product data_ tab and find the _Demo URL_ field.

![Demo URL field location](./_media/image_a97955.png)


---

## Product update guidelines and best practices

*Source: woo-marketplace/product-update-guidelines.md*

# Product update guidelines and best practices

To maintain a high-quality and competitive Marketplace, we encourage all vendors to regularly update their products. Consistent updates ensure compatibility with the latest versions of WooCommerce and WordPress, improve security and performance, and deliver ongoing value to customers.

## Best practices

### TL;DR

- Update your product at minimum **every 6 months**.
- Align with the [WooCommerce core release calendar](https://developer.woocommerce.com/release-calendar/).
- Use tools such as the [Quality Insights Toolkit](https://qit.woo.com/) (QIT) and your **vendor dashboard**.
- Check the [feature request portal](https://woocommerce.com/document/feature-request-portal/) for product ideas.
- Regular updates = better customer trust and renewal rates.

## Why regular updates matter

- **Compatibility**: Ensures your product works seamlessly with the latest WooCommerce and WordPress releases.
- **Security**: Patches vulnerabilities and keeps customer sites secure.
- **Performance**: Enhances speed, reliability, and efficiency.
- **Customer trust**: Builds confidence in your brand and product longevity. Regularly updated products often see higher renewal rates. Each update is a reminder of the value of keeping a subscription.
- **Support load reduction**: Reduces the number of support tickets by proactively addressing issues.

### Recommendations

1. **Monitor the [WooCommerce release calendar](https://developer.woocommerce.com/release-calendar/)**: Anticipate changes that might impact your product.
2. **Engage customer feedback**: Use reviews, support tickets, and feature requests to inform improvements, new features, and community-requested improvements.
3. **Use semantic versioning**: Example: `v2.1.0` for features, `v3.0.0` for breaking changes.
4. **Test thoroughly**: Ensure updates are stable and backward-compatible where possible. Consider integrating the [Quality Insights Tool](https://qit.woo.com/docs/) (QIT) into your workflow to automatically detect potential issues.
5. **Document changes transparently**: Maintain clear, customer-facing changelogs, update the documentation and the product page if needed.

### Marketplace expectations

Products that fail to stay current with WooCommerce core and/or those that are not updated at least once every six months will be **flagged for removal** from the WooCommerce Marketplace.

### Recommended update cadence

- **Major releases**: At least quarterly, to align with [WooCommerce core releases](https://developer.woocommerce.com/release-calendar/).
- **Security fixes**: As needed, with urgency.
- **Minor improvements**: Monthly or as features and fixes are ready.
- **Documentation**: Keep changelogs and user guides current with each release.

## How to deploy updates

### Uploading new versions

Before uploading a new version of your extension, it is important to ensure that it passes all QIT quality standards. You can run these checks from your vendor dashboard by clicking the **_Quality Insights_** menu option.

[Learn more about QIT tests and how to run them](https://qit.woo.com/docs/).

You can upload the updated version after your extension passes all QIT checks.

Click the **Versions** tab. You'll see all the versions you've previously uploaded, including highlights about what was in each version.

![Product versions tab](./_media/product-update-versions.png)

Click the **Add version** button, then:

1. **Select the .zip file** you want to upload from your computer.
2. **Add the version number**.
3. Click **Submit new version**.

Once submitted, we will run the following tests on the uploaded file:

- [End-to-end](https://qit.woo.com/docs/managed-tests/woo-e2e) (E2E)
- [Activation](https://qit.woo.com/docs/managed-tests/activation)
- [Security](https://qit.woo.com/docs/managed-tests/security)
- [Woo API](https://qit.woo.com/docs/managed-tests/woo-api)
- [PHPCompatibility](https://qit.woo.com/docs/managed-tests/phpcompatibility)
- [Malware](https://qit.woo.com/docs/managed-tests/malware)

All vendor admins will receive email notifications throughout the process, including:

- **Confirmation:** Vendor admins will receive an email when a new version is submitted, confirming that it is in the queue. No action is needed.
- **Rejected:** If a version fails any part of our automated testing, vendor admins will receive an email including the specific error. Developers should try to resolve the error and submit a new version when ready.
- **Live:** If a version passes automated testing, it will be automatically deployed and made available to customers. No action is needed.

Activation, security, and malware test passes are required for a new product version to be deployed.

#### Formatting the changelog

[Learn more about changelog formatting and entry types](https://developer.woocommerce.com/docs/extensions/core-concepts/changelog-txt/#the-changelogtxt-file).

#### Common errors

If an upload fails, there are a few common errors you should check first:

- **The name of the file:** WooCommerce.com looks for a specific name for your .zip file and the main folder within it. You will see the expected name when you try to upload a product:

![Expected file name format](./_media/product-update-filename.png)

- **A changelog is present**: A file named `changelog.txt` must be present to serve as a record of what's changed from version to version.
- **Invalid changelog:** The `changelog.txt` file provided does not match the expected format.
- **Mismatched version header**: The version in the extension header does not match the version provided during the upload process.
- **Mismatched version numbers:** The version in the extension header and the `changelog.txt` do not match.

#### Viewing test results

The results from the automated tests will be in the **Submission Tests** table, which can be viewed by clicking the associated **View** link as shown in the image below:

![Test results view](./_media/product-update-test-results.png)

### Programmatically uploading new versions

To deploy an extension programmatically, it must be an extension update and **not** a new submission. This method serves as an alternative to logging into the vendor dashboard and using the user interface (UI) to perform the same action.

#### Generating an application password

1. Ensure that you are logged into your WooCommerce vendor dashboard.
2. [Create an application password](https://woocommerce.com/wp-admin/authorize-application.php?app_name=WCCOM+Product+Submissions&app_id=c08e8963-897b-46cd-91e9-e92488ac9120).

:::note
For extra security, this application password is scoped to the deploy endpoint and cannot be used to perform any other action on the user's behalf.
:::

#### Deploying your product

Make a POST request to deploy your product using the following command:

```bash
curl -X POST https://woocommerce.com/wp-json/wc/submission/runner/v1/product/deploy \
  -F "file=@/path/to/zip" \
  -F "product_id=<product_id>" \
  -F "username=<username>" \
  -F "password=<app_password>" \
  -F "version=<product_version>"
```

Replace `<product_id>`, `<username>`, `<app_password>`, and `<product_version>` with your actual product ID, username, application password, and product version, respectively.

#### Checking deployment status

To check the status of your deployment, use the following command:

```bash
curl -X POST https://woocommerce.com/wp-json/wc/submission/runner/v1/product/deploy/status \
  -F "product_id=<product_id>" \
  -F "username=<username>" \
  -F "password=<app_password>"
```

#### Status response

When you query the deployment status, the response will provide details about the progress, including the status of various test runs.

Below is an example of this response:

```json
{
  "status": "queued",
  "version": "1.0.0",
  "test_runs": {
    "12345": {
      "test_run_id": "12345",
      "status": "success",
      "test_type": "activation",
      "result_url": "https://qit.woo.com/?qit_results=12345"
    },
    "67890": {
      "test_run_id": "67890",
      "status": "success",
      "test_type": "api",
      "result_url": "https://qit.woo.com/?qit_results=67890"
    }
  }
}
```

> **Note:** Additional test run objects may be present in the response, one for each test type that was executed.

### Maximize compatibility and reliability via custom E2E tests

We strongly encourage contributing E2E tests for your extensions built on top of the QIT's [custom E2E testing framework](https://qit.woo.com/docs/custom-tests/introduction). By sharing these tests with us, you play a crucial role in ensuring true compatibility across different WordPress and WooCommerce versions, various PHP environments, and alongside other popular extensions.

Our custom E2E testing framework — equipped with a Dockerized development environment and simple-to-use command tools — empowers you to design and execute comprehensive tests using [Playwright](https://playwright.dev/) that are tailored to your extension's unique functionalities.

Not only does this initiative help mitigate potential compatibility issues before they affect users, but it also enhances the overall reliability of the products within our marketplace. Participating in this process not only contributes to a robust ecosystem but also elevates your extension's reputation for quality and reliability.

Review our [QIT custom test documentation](https://qit.woo.com/docs/custom-tests/introduction) to begin leveraging the power of custom tests to guarantee your extension works seamlessly in real-world scenarios and stands out in the competitive Marketplace.

## Need help?

Feel free to reach out to the Marketplace team for update planning, QIT help, or deployment issues.

Let's work together to keep the WooCommerce.com Marketplace innovative, secure, and reliable for everyone!


---

## Submitting your product to the Woo Marketplace

*Source: woo-marketplace/submitting-your-product.mdx*

# Submitting your product to the Woo Marketplace

We look forward to reviewing your extension, theme, or integration for listing in the WooCommerce.com Marketplace. Before getting started, make sure you have [applied for a Marketplace vendor account](https://woocommerce.com/partners/) and your application has been approved.

## Pre-submission checklist

<details>
<summary>Business review</summary>

This includes an analysis of the product's business model and revenue share structure with Woo, as well as product rationale, competition, and developer/company history.

- **Mutually beneficial partnership**: Products must share revenue with Woo, exclude spam links, affiliate links, or links to upsell products outside of the Woo Marketplace. See our [monetization expectations](/docs/woo-marketplace/monetization-expectations/).
- **Trademark compliance**: Ensure that product names do not violate Woo's [trademark guidelines](https://woocommerce.com/trademark-guidelines/#sg-trademarks). Select a unique name that builds your brand and sets your product apart from others. [Review our product name guidelines](/docs/woo-marketplace/product-page-content-and-assets/#naming-guidelines).
- **Competitive pricing**: Is the proposed price equal to or less than the price of the product sold in other environments? Select a suggested price that matches the price you sell elsewhere.

</details>

<details>
<summary>Development guideline compliance</summary>

- Products must follow [security best practices](https://developer.wordpress.org/apis/security/).
- Products must support PHP 7.4+ as a minimum (PHP 8.3+ strongly recommended).

:::warning PHP 7.4 End of Life
PHP 7.4 reached [End of Life](https://www.php.net/supported-versions.php) (EOL) in November 2022. Using it may expose sites to security vulnerabilities.
:::

- Products must support the two latest **major releases** of both [WooCommerce](https://wordpress.org/plugins/woocommerce/) and [WordPress](https://wordpress.org/download/).
- Products must adhere to foundational guidelines outlined in our [developer hub](https://developer.woocommerce.com/).
- If your pricing model is based on a standard, tiered monthly subscription, you will be required to implement the [SaaS Billing API](/docs/woo-marketplace/billing-api-saas/) before launch. API keys and sandbox access are granted manually after products are submitted for Marketplace consideration.
- Products must be able to pass the following [Quality Insights Toolkit](https://qit.woo.com/docs/) (QIT) tests:
    - [API](https://qit.woo.com/docs/managed-tests/woo-api)
    - [End-to-end](https://qit.woo.com/docs/managed-tests/woo-e2e) (E2E)
    - [Activation](https://qit.woo.com/docs/managed-tests/activation)
    - [Security](https://qit.woo.com/docs/managed-tests/security)
    - [PHPCompatibility](https://qit.woo.com/docs/managed-tests/phpcompatibility)
    - [Malware](https://qit.woo.com/docs/managed-tests/malware)
    - [Validation](https://qit.woo.com/docs/managed-tests/validation)

</details>

<details>
<summary>User experience compliance</summary>

- The product review includes a deeper analysis of the product's user experience (UX) and user interface (UI).
- Ensure that your product's [critical flows](https://developer.woocommerce.com/testing-extensions-and-maintaining-quality-code/critical-flows/) have been thoroughly tested. See an example of [critical flows in the core WooCommerce plugin](/docs/contribution/testing/core-critical-flows/).
- Extensions must adhere to [development best practices](/docs/extensions/best-practices-extensions/extension-development-best-practices/) and [UX guidelines](/docs/extensions/ux-guidelines-extensions/).
- Themes must adhere to [design](/docs/theming/theme-development/theme-design-ux-guidelines/), and [UX guidelines](/docs/theming/theme-design/). If you are submitting a block theme, also review [theme development](/docs/theming/block-theme-development/theming-woo-blocks/).
- **Accessibility**: It is important that all customers can use the stores where your extension is installed. Extension submissions must meet the [WordPress Accessibility Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/). For more information, review WordPress's [accessibility quick start guide](https://make.wordpress.org/accessibility/handbook/best-practices/quick-start-guide/).
- Does the product have a single core purpose and use WooCommerce features as much as possible?
- Can the product function "out of the box" without much configuration?

</details>

<details>
<summary>Compatibility with top Woo extensions</summary>

Products should not cause issues with widely-used Marketplace extensions. If your product is found to break any of these extensions when installed alongside them, it may be rejected or removed from the Marketplace.

Popular extensions include:

- [WooCommerce Bookings](https://woocommerce.com/products/woocommerce-bookings/)
- [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/)
- [Product Add-Ons](https://woocommerce.com/products/product-add-ons/)
- [Product Bundles](https://woocommerce.com/products/product-bundles/)
- [Min/Max Quantities](https://woocommerce.com/products/minmax-quantities/)
- [Shipment Tracking](https://woocommerce.com/products/shipment-tracking/)

</details>

<details>
<summary>Compatibility with core WooCommerce features</summary>

Visitors expect the WooCommerce.com Marketplace to be the leading source of extensions and themes for the optimal ecommerce experience. This means we only accept submissions which are compatible with the latest enhancements to the core WooCommerce platform and overall merchant experience.

[Review Woo's public roadmap](https://developer.woocommerce.com/roadmap/) for primary initiatives and expectations.

<details>
<summary>Block editor compatibility</summary>

As we evolve within the WordPress ecosystem, we're placing a strong emphasis on block editor compatibility for WooCommerce extensions. While we continue to support classic and hybrid approaches, prioritizing block editor compatibility ensures your extensions align with the latest trends and offer users a more intuitive and cohesive experience.

- **Cart and Checkout blocks**: The block-based Cart and Checkout is now the default experience in WooCommerce, offering a more streamlined and visually cohesive shopping experience. As a developer, prioritizing compatibility with these default blocks ensures your extensions and themes seamlessly integrate with the enhanced default shopping flow. [Review Cart and Checkout block architecture](https://developer.woocommerce.com/2023/09/18/architecture-of-cart-and-checkout-blocks/).
- **Extensions**: Eliminate shortcode dependency. Many plugins/extensions still rely on shortcodes to output content. To enhance block editor compatibility, it is essential that these shortcodes are provided as blocks. This not only future-proofs your product but also allows users to leverage the full potential of the block editor's capabilities.
- **Themes**: While we continue to accept classic and hybrid themes, we are **prioritizing block themes** for the Woo Marketplace. Block themes are designed to fully leverage the capabilities of the block editor and provide users with a more intuitive and flexible content creation experience.

</details>

<details>
<summary>HPOS compatibility</summary>

High-Performance Order Storage (HPOS) is the **default experience for new WooCommerce stores**. It moves order data from the WordPress post and postmeta tables to dedicated order tables to improve scalability and reliability.

:::info
**All new extension submissions must be HPOS-compatible.** View our [HPOS recipe book](/docs/features/orders/high-performance-order-storage/recipe-book/) for ways to support HPOS in your product.
:::

</details>

</details>

## Submitting a product for review

From your vendor dashboard, navigate to **Submissions > Submit Product** and select the product type you're planning to submit:

- Extension
- Theme
- SaaS
- Business Service

![Submit product type selection](./_media/submit-product-type.png)

:::note Freemium products
Freemium products — products with both free and paid versions — require **two separate submissions**, one for each model. These will later be merged into a single product page where users can choose between versions.
:::

### File upload and submission info

The information required varies slightly depending on the submission flow selected. To help streamline the submission process, we only ask for critical details:

- Product upload
- Business details
- Testing instructions

![Submission form](./_media/submission-form.png)

Next, **address any submission test failures** noted in the discussion dialog. In the event of failures — marked as *Failed* — please click the **View** link beside the failed test to review the results and upload a modified version of your submission.

![Submission test failures](./_media/submission-test-failures.png)

If necessary, **replace the previously uploaded file to test again.** When tests fail, the submission status updates to ***Changes required***.

To proceed, click the **Replace** button to replace the current .zip file with a corrected version. This will automatically restart the testing process.

![Replace zip file](./_media/replace-zip-file.png)

:::tip
If your product is at a stage other than *Changes required*, you will not be able to replace this file. Please comment within the submission to request a status change from the Marketplace team.
:::

## Review process

Once the submitted product passes automated code tests, it moves to our review queue. Once it has been reviewed, the reviewer will share feedback (if any) with you.

A review consists of the following steps:

1. **Business review**: to ensure your product is a good fit for the Marketplace, and that there is a business model to share revenue.
2. **Code review**: to ensure the submitted product's code is original, secure, and aligned with overall WordPress and WooCommerce quality standards.
3. **User experience (UX) review**: to ensure the product works as expected and its look and feel aligns with our UX guidelines.
4. **Launch preparations**: once a submission successfully passes these review phases, it will be formally approved and proceed to onboarding for launch.

## FAQs

<details>
<summary>How long will it take for my product to be reviewed?</summary>

Once the submission is in business review, you can expect a formal decision from a reviewer within 30 days. Throughout the review process, we may provide feedback and request changes before rejecting or approving a submission.

</details>

<details>
<summary>Can I resubmit a previously rejected product?</summary>

Yes. You are welcome to resubmit products, providing the previously-received feedback was incorporated and your product was improved to comply with our guidelines and quality standards.

</details>

<details>
<summary>Why does my QIT test result link show "Invalid URL" or say it has expired?</summary>

- QIT test result links are temporary signed URLs. They expire after a short period of time. This is expected and not an error.
- To get fresh results, re-run the test from the submission in your [Vendor Dashboard](https://woocommerce.com/wp-admin/). New links will be generated with the updated results.

</details>

## Submission support

For additional questions related to your submission, please use the discussion box below the **Submission Bot** results table in the **Submission progress** tab within your vendor dashboard.

![Submission support discussion box](./_media/submission-support.png)


---

## Support guidelines for the Woo Marketplace

*Source: woo-marketplace/support-guidelines.md*

# Support guidelines for the Woo Marketplace

Adhering to the support expectations outlined in this guide is a requirement under the Marketplace Vendor Agreement. Failure to meet these expectations may result in temporary or permanent removal of your products from the Marketplace.

By participating in the WooCommerce.com Marketplace, you're not just selling a product — you're offering a complete customer experience. Providing timely, high-quality support is a core part of that experience and a key factor in building long-term trust with your customers.

That said, great support is not only a requirement — it's a growth opportunity. Providing excellent support boosts customer loyalty, increases positive reviews, encourages repeat purchases, and strengthens your reputation in the Marketplace, ultimately contributing to your long-term growth and profitability.

## Support expectations

Marketplace vendors are responsible for customer support in line with WooCommerce's Support Policy, including:

- Timely responses to customer emails.
- Handling customer reviews and ratings promptly.
- Managing feature requests posted on product pages.

The WooCommerce team supports vendors by managing account issues, refunds, coupons, escalations, and live chat queries.

### Response times

Timely responses are critical. If you are unavailable or expect delays, communicate this clearly with the WooCommerce team and arrange to redirect support requests appropriately.

### Support ratings

Customers can rate their support experience seven (7) days after submitting a ticket. Maintaining good support ratings is crucial for continued Marketplace participation.

### Live chat

Marketplace vendors provide support exclusively via email. WooCommerce handles live chat queries and redirects product-specific requests to a vendor's support email address.

## How support works

### Ticket routing

Customers submit tickets through the support request form and are automatically routed to your designated support email address. Each support email includes:

- Product name
- Subscription dates
- System status report
- The customer's message.

### Specifying your support email address

Specify the email address that support tickets should be routed to in your vendor dashboard via _Settings > Store_. The WooCommerce team will also use this address to copy (CC) you in on tickets.

:::note
The Support Email field is different from Contact Email, which is used for order notifications.
:::

![Support Email field in the vendor dashboard](./_media/support-email-field.png)

### Getting set up for support ticket replies

- **Activate an autoresponder**: Automatically inform customers that you have received their request, including links to your privacy and data usage policies. Avoid promotional or affiliate links.
- **Deactivate any platform feedback requests**: Customers already receive feedback requests from the Woo Marketplace directly.

## Security and customer login credentials

If you need to log in to a merchant's store in order to successfully assist them, please follow these guidelines:

- **Only ask for login credentials once you have exhausted all other options.** This includes asking for screenshots and reproducing the problem on your own test site(s).
- **When asking for login credentials:**
    - Inform the customer that, under GDPR regulations, they must mention that they may need to give access to third-party support services in their store's terms and conditions.
    - Always ask the customer to create a temporary administrator account for you. (You will need to tweak the instructions in the document linked above as you do not have access to `woologin@woocommerce.com`.)
    - At the end of the support interaction, ask the merchant to remove this temporary account.
- **If the customer shares their details before you are able to provide the instructions above**, always point out that they ideally don't do this and that you strongly advise them to reset their password.
- **Never ask for plain-text passwords.** Instead, use a password-sharing service like [QuickForget.com](https://quickforget.com/) to create a unique, expiring link.

## Collaboration, refunds, and escalations

To collaborate with other Marketplace vendors, you can copy in (CC) relevant parties on support tickets. Contact information for other vendors is available from the WooCommerce team.

All refunds, coupons, and escalations are managed by WooCommerce. Forward relevant tickets by CCing the private email address from the Marketplace Developer P2.

## Marketplace support tools

### Active subscription checks

Subscription details are included in customer support emails. Additional checks can be done through your vendor dashboard via _Settings > Tools_.

![A customer's subscription details displayed in a vendor's dashboard](./_media/subscription-details.png)

### Reviews and ratings

Vendors are expected to monitor and respond to customer ratings and reviews as part of their support responsibilities. Addressing concerns promptly not only improves customer satisfaction but also demonstrates your commitment to quality service.

Keep in mind that customers are significantly more likely to leave a positive review following a helpful and timely support experience. Engaging positively with customer feedback — both praise and criticism — can strengthen your product reputation and foster long-term trust.

Reviews and ratings for your products are managed via your vendor dashboard.

![Reviews and ratings displayed in a vendor's dashboard](./_media/reviews-ratings.png)

### Feature requests

Customers can post feature requests via your product page. These requests are publicly visible and provide valuable insight into what users want from your product.

Vendors are expected to regularly monitor and respond to these requests like any other support channel. Timely, thoughtful engagement with feature requests demonstrates that you value user input and are actively working to improve your product.

Feature requests are a powerful tool for understanding how customers use your product, identifying common pain points, and shaping your product roadmap. By participating in these conversations, you can build trust and stay aligned with your customers' evolving needs.

Feature requests for your products are managed in your vendor dashboard via _Feature Requests_.

![Feature requests listed in a vendor's dashboard](./_media/feature-requests.png)


---