openapi: 3.0.0
info:
  title: Vatstack API Specification Batches Rates API
  description: A suite of VAT APIs which let you validate VAT numbers with government services, look up VAT rates by ISO country code, calculate price quotes with centralized VAT rules and store transactions with each sale for VAT reporting.
  contact:
    email: team@vatstack.com
  version: 1.3.0
servers:
- url: https://api.vatstack.com/{basePath}
  description: Production API server.
  variables:
    basePath:
      default: v1
tags:
- name: Rates
paths:
  /rates:
    get:
      operationId: getAllRates
      summary: Retrieves all VAT rate objects, including standard VAT rates and VAT rates for digital products.
      parameters:
      - name: country_code
        in: query
        description: Filter results by a 2-letter ISO country code.
        schema:
          type: string
      - name: limit
        in: query
        description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
        schema:
          type: integer
          format: int32
      - name: member_state
        in: query
        description: Boolean to filter results by EU Member State.
        schema:
          type: boolean
      - name: page
        in: query
        description: Integer for the current page.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Rate objects successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  has_more:
                    description: True if this list has another page of items after this one that can be fetched.
                    type: boolean
                  rates_count:
                    type: integer
                    format: int32
                  rates:
                    items:
                      $ref: '#/components/schemas/rate'
                    type: array
                required:
                - has_more
                - rates_count
                - rates
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - publicKey: []
        secretKey: []
      tags:
      - Rates
  /rates/geolocate:
    get:
      operationId: getRateByIPAddress
      summary: Retrieves a geolocated VAT rate by IP address.
      parameters:
      - name: ip_address
        in: query
        description: IPv4 or IPv6 address to geolocate. If none is provided, the IP address of the request is used.
        schema:
          type: string
      responses:
        '200':
          description: Rate object successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rate'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - publicKey: []
        secretKey: []
      tags:
      - Rates
components:
  schemas:
    error:
      type: object
      description: Error response from the Vatstack API.
      properties:
        code:
          type: string
          description: For validations, a short string indicating the [error code](https://vatstack.com/docs/validations).
          maxLength: 50
        message:
          type: string
          description: Human-readable message providing more details about the error.
          maxLength: 250
    rate:
      type: object
      description: Keep the rates of your application up-to-date with a regular VAT rate lookup. This ensures that your invoice states the correct VAT across EU Member States. We have also started to add countries outside the EU and will keep them updated.
      properties:
        abbreviation:
          type: string
          description: Abbreviation of `local_name`.
        categories:
          type: object
          properties:
            audiobook:
              type: number
              format: double
            broadcasting:
              type: number
              format: double
            ebook:
              type: number
              format: double
            eperiodical:
              type: number
              format: double
            eservice:
              type: number
              format: double
            telecommunication:
              type: number
              format: double
        country_code:
          type: string
          description: 2-letter ISO country code.
          maxLength: 2
          minLength: 2
        country_name:
          type: string
          description: Corresponding English name of `country_code`.
        currency:
          type: string
          description: 3-letter ISO 4217 local currency code.
          maxLength: 3
          minLength: 3
        local_name:
          type: string
          description: Localized name of the VAT identification number.
        member_state:
          type: boolean
          description: Boolean indicating whether the country is an EU Member State.
        reduced_rates:
          type: array
          description: 3-letter ISO 4217 local currency code.
          items:
            type: number
            format: double
        standard_rate:
          type: number
          description: Standard VAT rate in percent.
          format: double
        vat_abbreviation:
          type: string
          description: Abbreviation of `vat_local_name`.
        vat_local_name:
          type: string
          description: Localized name of the VAT.
  securitySchemes:
    publicKey:
      type: apiKey
      name: X-API-KEY
      in: header
    secretKey:
      type: apiKey
      name: X-API-KEY
      in: header
externalDocs:
  description: Vatstack API Reference
  url: https://vatstack.com/docs