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.

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:

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.
• Endpoints that do allow writes, for example, updating the current customer address, require a nonce-token.
• 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:

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.

Pagination

If collections contain many results, they may be paginated. When listing resources you can pass the following parameters:

In the example below, we list 20 products per page and return page 2.

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.

Status codes

The following table gives an overview of how the API functions generally behave.

The following table shows the possible return codes for API requests.

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. 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.

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.

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()
• Rest API Permissions Callbacks