> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avatcado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get VAT rates for a specific country

> Returns current VAT rates for a single country identified by its ISO 3166-1 alpha-2 code (e.g. NL, DE, GB, CH, NO).

This endpoint is free and unlimited. It does not count against your monthly quota.



## OpenAPI

````yaml /openapi/public.yaml get /v1/rates/{country_code}
openapi: 3.1.0
info:
  title: Avatcado API
  version: '1.0'
  description: >-
    Validate VAT and GST numbers across 32 countries with a single API call. Get
    company details, consultation numbers, and validity status from VIES, HMRC,
    BFS, BRREG, and ABR, with caching, rate limiting, and structured error
    responses built in.
  contact:
    name: Avatcado
    url: https://docs.avatcado.com
servers:
  - url: https://api.avatcado.com
    description: Production
security: []
paths:
  /v1/rates/{country_code}:
    get:
      tags:
        - VAT Rates
      summary: Get VAT rates for a specific country
      description: >-
        Returns current VAT rates for a single country identified by its ISO
        3166-1 alpha-2 code (e.g. NL, DE, GB, CH, NO).


        This endpoint is free and unlimited. It does not count against your
        monthly quota.
      operationId: getVatRateByCountry
      parameters:
        - schema:
            type: string
            minLength: 2
            maxLength: 2
            description: ISO 3166-1 alpha-2 country code (e.g. NL, DE, GB, CH, NO)
            example: NL
          required: true
          description: ISO 3166-1 alpha-2 country code (e.g. NL, DE, GB, CH, NO)
          name: country_code
          in: path
      responses:
        '200':
          description: VAT rates for the requested country
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleRateResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Missing or invalid API key
                  docs_url: https://docs.avatcado.com/errors/unauthorized
                meta:
                  request_id: 550e8400-e29b-41d4-a716-446655440000
        '404':
          description: No VAT rates found for the specified country code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: not_found
                  message: 'No VAT rates found for country code: XX'
                  docs_url: https://docs.avatcado.com/errors/not_found
                meta:
                  request_id: 550e8400-e29b-41d4-a716-446655440000
        '429':
          description: Burst rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Monthly validation limit exceeded
                  docs_url: https://docs.avatcado.com/errors/rate_limit_exceeded
                meta:
                  request_id: 550e8400-e29b-41d4-a716-446655440000
      security:
        - bearerAuth: []
components:
  schemas:
    SingleRateResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/VatRateData'
        meta:
          $ref: '#/components/schemas/RatesResponseMeta'
      required:
        - data
        - meta
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - error
        - meta
    VatRateData:
      type: object
      properties:
        country_code:
          type: string
          example: NL
          description: ISO 3166-1 alpha-2 country code
        country_name:
          type: string
          example: Netherlands
          description: Full country name
        currency:
          type: string
          example: EUR
          description: ISO 4217 currency code
        standard_rate:
          type: number
          example: 21
          description: Standard VAT rate percentage
        other_rates:
          type: array
          items:
            $ref: '#/components/schemas/VatRateEntry'
          description: Reduced, super-reduced, and zero rates
        updated_at:
          type: string
          example: '2026-01-01T00:00:00.000Z'
          description: When this rate data was last updated
      required:
        - country_code
        - country_name
        - currency
        - standard_rate
        - other_rates
        - updated_at
    RatesResponseMeta:
      type: object
      properties:
        request_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: Unique identifier for this request
      required:
        - request_id
    ErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: missing_parameter
        message:
          type: string
          description: Human-readable error message
          example: Query parameter 'vat_number' is required
        docs_url:
          type: string
          description: Link to documentation for this error code
          example: https://docs.avatcado.com/errors/missing_parameter
      required:
        - code
        - message
    ResponseMeta:
      type: object
      properties:
        request_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: Unique identifier for this request
        cached:
          type: boolean
          description: Whether this result was served from cache
        cached_at:
          type: string
          description: >-
            When the result was originally cached (only present when cached is
            true)
        stale:
          type: boolean
          description: >-
            Whether this is a stale cache result served because the upstream was
            unavailable
        source_status:
          type: string
          enum:
            - live
            - unavailable
            - degraded
          description: >-
            Upstream data source reliability. 'live' = confirmed fresh result.
            'unavailable' = upstream source was down, stale cache served.
            'degraded' = result may be unreliable (possible silent false
            negative from VIES, BFS, or BRREG).
          example: live
        mode:
          type: string
          enum:
            - test
          description: Present with value 'test' when using an avat_test_ API key
        request_duration_ms:
          type: integer
          description: Total request processing time in milliseconds
          example: 120
      required:
        - request_id
    VatRateEntry:
      type: object
      properties:
        rate:
          type: number
          example: 9
          description: Tax rate percentage
        type:
          type: string
          example: reduced
          description: Rate type (e.g. reduced, super_reduced, zero)
      required:
        - rate
        - type

````