WooCommerce Tax Rates API

openapi: 3.2.0
info:
  title: WooCommerce REST Cart Tax Rates API
  description: The WooCommerce REST API is the primary server-side interface for reading and writing WooCommerce store data programmatically. It follows REST conventions, uses JSON for all requests and responses, and is fully integrated with the WordPress REST API under the /wp-json/wc/v3/ namespace. The API covers products, product variations, product categories, product attributes, orders, order notes, order refunds, customers, coupons, tax rates, shipping zones, payment gateways, settings, webhooks, reports, and system status. Authentication uses Consumer Key and Consumer Secret pairs generated in the WooCommerce admin, transmitted over HTTPS via HTTP Basic Auth or OAuth 1.0a over plain HTTP.
  version: v3
  contact:
    name: WooCommerce Developer Support
    url: https://developer.woocommerce.com/docs/apis/rest-api/
  termsOfService: https://woocommerce.com/terms-conditions/
servers:
- url: https://example.com/wp-json/wc/v3
  description: Production Server (replace example.com with your store domain)
security:
- basicAuth: []
tags:
- name: Tax Rates
  description: Manage tax rates and tax classes applied at checkout
paths:
  /tax/rates:
    get:
      operationId: listTaxRates
      summary: WooCommerce List All Tax Rates
      description: Returns all configured tax rates. Supports filtering by tax class and ordering by priority, order, or ID.
      tags:
      - Tax Rates
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - name: class
        in: query
        description: 'Filter tax rates by tax class slug. Options: standard, reduced-rate, zero-rate, or any custom class slug.'
        required: false
        schema:
          type: string
        example: string-value
      responses:
        '200':
          description: List of tax rates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxRate'
              examples:
                listTaxRates200Example:
                  summary: Default listTaxRates 200 response
                  x-microcks-default: true
                  value:
                  - id: 1
                    country: string-value
                    state: string-value
                    postcode: string-value
                    city: string-value
                    rate: string-value
                    name: Example Name
                    priority: 1
                    compound: true
                    shipping: true
                    class: string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    TaxRate:
      type: object
      description: A configured tax rate applied at checkout.
      properties:
        id:
          type: integer
          description: Tax rate unique identifier.
          example: 1
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code for this rate.
          example: string-value
        state:
          type: string
          description: State code for this rate (empty for country-wide rates).
          example: string-value
        postcode:
          type: string
          description: Postcode or range for this rate.
          example: string-value
        city:
          type: string
          description: City name for this rate.
          example: string-value
        rate:
          type: string
          description: Tax rate percentage as a decimal string (e.g. 20.0000).
          example: string-value
        name:
          type: string
          description: Tax rate label shown to customers.
          example: Example Name
        priority:
          type: integer
          description: Priority of this tax rate (used when multiple rates match the same address).
          example: 1
        compound:
          type: boolean
          description: Whether this is a compound tax rate (applied on top of other taxes).
          example: true
        shipping:
          type: boolean
          description: Whether the tax applies to shipping costs.
          example: true
        class:
          type: string
          description: Tax class slug. Standard class is identified by an empty string.
          example: string-value
    Error:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: string-value
        message:
          type: string
          description: Human-readable error message.
          example: string-value
        data:
          type: object
          description: Additional error context including HTTP status code.
          properties:
            status:
              type: integer
              description: HTTP status code associated with the error.
          example:
            status: 1
  parameters:
    page:
      name: page
      in: query
      description: Current page of the collection. Defaults to 1.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    per_page:
      name: per_page
      in: query
      description: Maximum number of items per page. Defaults to 10, maximum 100.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth using the WooCommerce Consumer Key as the username and Consumer Secret as the password over HTTPS. Over plain HTTP use OAuth 1.0a one-legged authentication instead.
externalDocs:
  description: WooCommerce REST API Documentation
  url: https://woocommerce.github.io/woocommerce-rest-api-docs/