What we do
Tools
Industries
Department
How we workLet's talk →
Home/WooCommerce/WooCommerce API
WooCommerce developer reference

WooCommerce REST API: Endpoints, Paging, Batches and Errors

Your test call to /orders came back with ten orders, and the store has forty thousand. This page is for that moment: how WooCommerce pages results, how to ask only for what changed, how batch writes report failure, and which API you should be calling at all. Still need a key? The WooCommerce API page covers creating one and how auth works.

The numbers to know

Base: https://yourstore.com/wp-json/wc/v3/. Main resources: orders (with notes and refunds under each order), products (with variations under each product, plus attributes, categories, tags and reviews), customers, coupons, reports, taxes, shipping/zones, settings and webhooks.

Paging: 10 per page by default. Set per_page (WordPress caps it at 100) and page, which starts at 1. Totals come back in the X-WP-Total and X-WP-TotalPages headers, and the Link header carries next, prev, first and last URLs.

Only what changed: orders and products accept modified_after and modified_before (ISO 8601), plus dates_are_gmt=true so you aren't guessing the store's timezone. after and before filter on the created date instead.

Bulk writes: POST /products/batch (and the same on orders, customers, coupons and more) takes create, update and delete arrays, up to 100 objects by default.

An incremental order sync, call by call

The shape most back-office syncs settle on: pull what changed since the last good run, page through it, write it out, and only then move the bookmark.

  1. 1

    Store a high-water mark

    Keep the time of your last successful run in UTC. The first run is a full backfill; every run after that starts from this value.

  2. 2

    Ask for what changed, oldest first

    GET /orders?modified_after=2026-11-01T00:00:00&dates_are_gmt=true&orderby=modified&order=asc&per_page=100. Sorting by modified date keeps the pages stable while new edits come in.

    Watch for: older stores. The modified_after filter arrived in later WooCommerce versions, so check the store's version before relying on it, and fall back to pulling recent pages by date if it's missing.

  3. 3

    Follow the pages

    Read X-WP-TotalPages on the first response, or follow the Link header's rel="next" until there isn't one. WooCommerce's docs recommend the Link header over building page URLs yourself.

  4. 4

    Trim the payload

    Add WordPress's _fields parameter (for example _fields=id,status,date_modified_gmt,line_items,total) when you don't need the whole order. Smaller responses mean fewer timeouts on slow hosts.

  5. 5

    Write out, then move the mark

    Only update the high-water mark once every page has been processed. Overlap the next window by a few minutes and skip orders you've already seen by ID, so nothing edited at the boundary falls through.

Why a sync that passed on staging breaks on the live store

A batch call that "succeeded" with failures inside it

How you'll know: The batch returns 200, but a few products never changed. Each item in the response carries its own result, and failed ones have an error object instead of the updated record.

Fix: Read every item in the response, not the status code. Log the failures with their code and message and retry only those.

Asking for more than 100 per page

How you'll know: per_page=250 comes back as a 400 with rest_invalid_param.

Fix: Stay at 100 or below and page through. For very large pulls, combine that with modified_after so each run is small.

The host blocks you before WooCommerce does

How you'll know: Requests start returning 403, 429 or an HTML page from the host's firewall partway through a backfill. WooCommerce itself doesn't set a rate limit on the REST API, so this comes from the server.

Fix: Throttle requests, back off on failure, and run large backfills off-peak. If the host still blocks it, ask them to allowlist the integration's IP.

Reading errors as if they were all the same

How you'll know: Everything non-200 gets the same retry. The API returns JSON with code, message and data.status: 400 for a bad request, 401 for auth or permission, 404 for a missing resource, 500 for a server error.

Fix: Retry 500s and host throttling. Don't retry 400s and 401s, because the same request will fail the same way. A 401 on a key that used to work usually means its WordPress user was removed or lost permissions.

Custom data that seems to vanish

How you'll know: A field a plugin added at checkout isn't in the order's top-level fields.

Fix: Look in meta_data on the order and on each line item. That's where order numbers from other systems, custom product attributes and plugin fields end up.

REST API or Store API: which one you should be calling

Both live under /wp-json/, which is how people end up on the wrong one.

/wp-json/wc/v3

WooCommerce REST API

  • Authenticated with a key pair, with the permissions of the WordPress user behind it.
  • Full store data: every order, customer, product, refund and setting.
  • Meant for server-to-server work: accounting, ERP, warehouse, CRM.
  • Version v3 is current. v2 and v1 still exist for older code. The old Legacy REST API left WooCommerce core in 9.0 and now needs its own plugin.
/wp-json/wc/store/v1

Store API

  • Unauthenticated by design. It doesn't expose sensitive store or customer data.
  • Powers the block-based cart and checkout, using the shopper's own session.
  • Write calls like adding to cart need a nonce token.
  • Right for a custom storefront or headless checkout, wrong for a back-office sync.

If your code needs to see orders other shoppers placed, it belongs on wc/v3.

Questions people ask

How do I get a WooCommerce API key?

Create one in the WordPress admin under WooCommerce, Settings, Advanced, REST API, tied to a user and set to Read, Write or Read/Write. The step-by-step, plus how the key is sent over HTTPS and HTTP, is on the WooCommerce API page.

Is the WooCommerce API free to use?

Yes. It's built into WooCommerce, so there's no fee for API access. The cost is in building and looking after whatever you connect to it.

What's the difference between the WooCommerce REST API and the Store API?

The REST API (wc/v3) is authenticated and sees the whole store, so it's for back-office integrations. The Store API (wc/store/v1) is unauthenticated, works with the shopper's own session and powers the block cart and checkout. A backend sync built on the Store API won't see what it needs.

Does WooCommerce rate-limit API requests?

WooCommerce doesn't set a limit on the REST API itself. In practice the limit comes from your hosting: shared and budget hosts often throttle or block bursts of requests, which looks like the API failing when it's the server protecting itself.

How many records can I get per request from the WooCommerce API?

Ten by default, and up to 100 with per_page. Batch endpoints take up to 100 objects per call by default. Use X-WP-TotalPages or the Link header to page through the rest.

Should I poll the API or use webhooks?

Usually both. Webhooks tell you about a new or updated order straight away, and a scheduled modified_after pull catches anything a webhook missed while your endpoint was down. Setup and delivery are covered on WooCommerce webhooks.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.