openapi: 3.1.0
info:
  title: Magento REST Authentication Tax API
  description: 'The Adobe Commerce (Magento) REST API provides a comprehensive set of endpoints for interacting with all major aspects of an e-commerce store, including catalog management, orders, customers, inventory, shipping, and payments. It supports three authentication mechanisms: OAuth 1.0a for third-party integrations, token-based authentication for mobile apps and administrators, and guest access for select public endpoints. The API follows REST conventions and returns JSON responses, enabling developers to build integrations, automate store operations, and power headless commerce storefronts. All endpoints are versioned under the /V1 prefix and support searchCriteria query parameters for filtering, sorting, and paginating collection responses.'
  version: '2.4'
  contact:
    name: Adobe Commerce Developer Support
    url: https://developer.adobe.com/commerce/webapi/rest/
  termsOfService: https://www.adobe.com/legal/terms.html
servers:
- url: https://{store_domain}/rest/{store_code}
  description: Production Server
  variables:
    store_domain:
      default: your-store.example.com
      description: The hostname of your Adobe Commerce store
    store_code:
      default: V1
      description: Store code followed by API version. Use "all" as store code for admin-scope operations, or the specific store view code for store-scoped operations. The V1 version path segment follows.
security:
- bearerAuth: []
tags:
- name: Tax
  description: Tax configuration management including tax rates, tax rules, and tax classes used for order tax calculation.
paths:
  /V1/taxRates:
    get:
      operationId: listTaxRates
      summary: List tax rates
      description: Returns a paginated list of tax rates configured in the store. Tax rates define the percentage applied to taxable items based on country, region, and postal code matching rules. Admin authentication is required.
      tags:
      - Tax
      parameters:
      - $ref: '#/components/parameters/searchCriteriaFilterGroups'
      - $ref: '#/components/parameters/searchCriteriaSortOrders'
      - $ref: '#/components/parameters/searchCriteriaPageSize'
      - $ref: '#/components/parameters/searchCriteriaCurrentPage'
      responses:
        '200':
          description: Paginated list of tax rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxRateSearchResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    TaxRateSearchResults:
      type: object
      description: Paginated search results containing a list of tax rates.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TaxRate'
        total_count:
          type: integer
          description: Total number of matching tax rates.
    TaxRate:
      type: object
      description: A tax rate configuration defining the percentage applied to taxable items.
      properties:
        id:
          type: integer
          description: Numeric tax rate entity ID.
        tax_country_id:
          type: string
          description: ISO 3166-1 alpha-2 country code this rate applies to.
        tax_region_id:
          type: integer
          description: Numeric region ID this rate applies to. 0 for all regions.
        tax_postcode:
          type: string
          description: Postal code pattern this rate applies to. Use * as a wildcard.
        code:
          type: string
          description: Human-readable tax rate code (e.g. US-CA-*-Rate 1).
        rate:
          type: number
          description: Tax percentage rate (e.g. 8.25 for 8.25%).
    Error:
      type: object
      description: Standard error response returned for 4xx and 5xx responses.
      properties:
        message:
          type: string
          description: Human-readable error message.
        parameters:
          type: array
          description: Additional error context parameters.
          items:
            type: object
  parameters:
    searchCriteriaCurrentPage:
      name: searchCriteria[currentPage]
      in: query
      description: Page number to return. First page is 1.
      required: false
      schema:
        type: integer
        minimum: 1
    searchCriteriaFilterGroups:
      name: searchCriteria[filter_groups][0][filters][0][field]
      in: query
      description: Field name to filter on. Multiple filter groups and filters can be specified using indexed array notation. Filters within a group are OR'd; filter groups themselves are AND'd.
      required: false
      schema:
        type: string
    searchCriteriaSortOrders:
      name: searchCriteria[sortOrders][0][field]
      in: query
      description: Field name to sort results by. Direction is set in the corresponding direction parameter.
      required: false
      schema:
        type: string
    searchCriteriaPageSize:
      name: searchCriteria[pageSize]
      in: query
      description: Number of records to return per page. Default varies by resource.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 300
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from the /V1/integration/admin/token or /V1/integration/customer/token endpoint. Include in the Authorization header as "Bearer {token}".
externalDocs:
  description: Adobe Commerce REST API Documentation
  url: https://developer.adobe.com/commerce/webapi/rest/