Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 39 ยท REST API and Integrations

The REST API and the Store API

Learn the two WooCommerce REST APIs: wc/v3 with API keys for back-office integrations and the Store API for storefronts, with pagination, nonces, Cart-Token and extensions.

WooCommerce ships two different REST APIs, and mixing them up is the most common mistake in integrations. The REST API (wc/v3) is for trusted back-office clients: an ERP, a mobile admin app, a script that imports products. It authenticates with API keys and can read and change almost everything. The Store API (wc/store/v1) is for the shopper's own browser: it powers the Cart and Checkout blocks, works for guests, and only exposes what a shopper may see and do.

This lesson shows how each one authenticates, how to page and filter results, how a storefront keeps a cart without cookies, and how to add your own data to a Store API response. The real endpoints need a running WordPress, so the real calls are read-only here. The runnable examples are plain PHP stand-ins on the site's runner that reproduce the behavior (pagination headers, key permissions) and say so. For the underlying WordPress mechanics, see REST API Basics and Custom REST Endpoints.

Two APIs, two audiences

flowchart LR
    A["ERP or admin script"] -->|"API key (Basic auth over HTTPS)"| B["wc/v3<br/>products, orders, customers"]
    C["Shopper's browser<br/>(Cart and Checkout blocks)"] -->|"Nonce or Cart-Token"| D["wc/store/v1<br/>cart, checkout, products"]
    B --> E["WooCommerce CRUD layer"]
    D --> E

Both APIs end in the same CRUD classes, but they check different credentials and expose different data.

wc/v3 wc/store/v1
Who calls it Servers and admin tools you trust The shopper's browser
Credentials Consumer key and secret (or a logged-in admin with a nonce) Store API nonce, or Cart-Token
Data Orders, customers, settings, reports, everything Public catalog, the shopper's own cart and checkout
Caching Never public Never public for cart; product reads may be cacheable

Never ship wc/v3 keys to a browser. Anything in JavaScript on a public page is public.

The wc/v3 REST API

Endpoints live under /wp-json/wc/v3/: products, products/<id>/variations, orders, orders/<id>/refunds, customers, coupons, system_status, and more. The usual verbs apply: GET reads, POST creates, PUT or PATCH updates, DELETE removes (with ?force=true for a permanent delete).

Authentication with keys

Keys are created in WooCommerce > Settings > Advanced > REST API. You choose a user, a description and permissions (Read, Write or Read/Write). WooCommerce shows a consumer key (ck_...) and consumer secret (cs_...) once; it stores only a hash of the secret. Over HTTPS you send them as HTTP Basic credentials:

Terminal
curl https://shop.example.com/wp-json/wc/v3/orders?status=processing \
  -u ck_xxxxxxxx:cs_xxxxxxxx

Rules that matter:

  • Use HTTPS. Over plain HTTP WooCommerce falls back to OAuth 1.0a signatures, which are fiddly and still expose the payload.
  • A key acts as the user you picked, and its Read or Write permission limits the verbs. A Read-only key cannot POST.
  • Give each integration its own key so you can revoke one without breaking the rest.
  • Keys belong in server-side environment variables or a secrets store, never in a repository.

Pagination, filters and batches

Collections are paged. You control the page with page (starting at 1) and per_page (default 10, at most 100). The total is not in the body: read the headers.

HTTP
GET /wp-json/wc/v3/products?per_page=50&page=2&status=publish&orderby=date&order=desc
HTTP
X-WP-Total: 1342
X-WP-TotalPages: 27
Link: <https://shop.example.com/wp-json/wc/v3/products?page=3&per_page=50>; rel="next",
      <https://shop.example.com/wp-json/wc/v3/products?page=1&per_page=50>; rel="prev"

Common filters include search, status, sku, category, after and before (ISO 8601 dates), modified_after, orderby and order; exact names differ per resource, so check the schema with an OPTIONS request on the collection. To change many items at once, use the batch endpoint, which accepts create, update and delete arrays (the default limit is 100 items per request):

JSON
POST /wp-json/wc/v3/products/batch
{
  "update": [
    { "id": 12, "regular_price": "19.90" },
    { "id": 13, "stock_quantity": 40, "manage_stock": true }
  ]
}

Syncing a large catalog? Walk the pages with modified_after so each run only fetches what changed, and respect the X-WP-TotalPages value instead of looping until an empty page.

The Store API

The Store API is public by design but never anonymous in the sense of "no checks". Reading the catalog (GET /wc/store/v1/products) needs no credentials. Changing a cart does.

Typical calls from a storefront:

JavaScript
// Read the cart
const cart = await fetch('/wp-json/wc/store/v1/cart').then(r => r.json());

// Add an item, passing the nonce WooCommerce handed out earlier
await fetch('/wp-json/wc/store/v1/cart/add-item', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Nonce: storeNonce },
  body: JSON.stringify({ id: 12, quantity: 2 }),
});

Nonces and the Cart-Token

Two mechanisms protect cart-changing requests:

  1. Nonce: each response includes a Nonce header; the client sends the latest value back in a Nonce request header. It proves the request comes from a page WooCommerce rendered, not from a forged cross-site form. Always take the most recent nonce: it rotates.
  2. Cart-Token: a signed token (a JWT) returned in the Cart-Token response header that identifies the cart. A headless storefront on another domain, or a mobile app, can send it back instead of relying on cookies, which cross-site browsers often block. It identifies a cart, not a logged-in user, so treat it like a session ID.

The practical effect: a cart can live in your server-rendered theme (cookies plus nonce) or in a separate front end (token), and both talk to the same endpoints.

Extending a response

Plugins add data under an extensions key, namespaced by plugin, so two plugins never collide. You register a data callback and a schema for it. This is the real, read-only API:

PHP
<?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'       => 'acme_gift',
        'data_callback'   => function () {
            return array( 'gift_wrap' => (bool) WC()->session->get( 'acme_gift_wrap', false ) );
        },
        'schema_callback' => function () {
            return array(
                'gift_wrap' => array(
                    'description' => __( 'Whether gift wrap is selected.', 'acme' ),
                    'type'        => 'boolean',
                    'context'     => array( 'view', 'edit' ),
                    'readonly'    => true,
                ),
            );
        },
        'schema_type'     => ARRAY_A,
    ) );
} );

The cart response then contains "extensions": { "acme_gift": { "gift_wrap": true } }. Writing is a separate step: the blocks extensibility lesson shows how a client posts data to a callback registered with woocommerce_store_api_register_update_callback. See Cart and Checkout Blocks Extensibility.

Schema matters

Every resource describes itself with a JSON schema: field names, types, readonly flags and contexts. Respect it. Return numbers and strings exactly as the schema says (WooCommerce prices are strings such as "19.90"), keep field names stable, and add fields rather than renaming them, because clients you do not control depend on them.

Runnable stand-ins

The examples below are not WooCommerce. There is no WordPress here. They reproduce two ideas in plain PHP so you can watch the numbers: how pagination headers are computed, and how a key's permissions limit what it may do.

PHP A paginated collection with X-WP-Total headers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Real WooCommerce builds the same headers inside the REST controller. The client loop is the part worth copying: it stops at X-WP-TotalPages and never needs an extra empty request.

PHP Key permissions: Read, Write and Read/Write

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The real implementation checks the same three questions in the same order: does the key exist, does the secret match, does the permission allow this verb. Note the status codes: a bad credential is 401, a good credential that is not allowed is 403.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which API should a headless storefront in a visitor's browser use to add a product to the cart?

    The Store API is designed for shoppers and exposes only their own cart. Putting wc/v3 keys in browser code would publish them to every visitor.
  2. 2. How does a wc/v3 client learn how many pages a collection has?

    The collection body is just the page of items. X-WP-Total and X-WP-TotalPages carry the counts, and a Link header gives next and prev URLs.
  3. 3. A client authenticates correctly with a Read-only key and sends POST. What does it get?

    Authentication succeeded, but authorization failed. That is 403 Forbidden; 401 is for missing or wrong credentials.
  4. 4. Where do plugins add their own fields to a Store API response?

    The extensions object, with one namespace per plugin, keeps third-party data from colliding. You register a data callback and a schema for it.

Summary

  • wc/v3 is for trusted servers and uses consumer keys over HTTPS; the Store API is for shoppers and uses a nonce or a Cart-Token.
  • Keys carry Read, Write or Read/Write permission and act as a chosen user. Give each integration its own key and keep secrets out of browsers and repositories.
  • Collections are paged with page and per_page (maximum 100); totals come from X-WP-Total and X-WP-TotalPages, and batch endpoints change many items in one request.
  • Add data to Store API responses under extensions, with a schema, using woocommerce_store_api_register_endpoint_data().
  • The TryIts are stand-ins that reproduce the logic; the real endpoints need WordPress and WooCommerce.

Next: Custom REST Endpoints and Outgoing Webhooks