swagger: "2.0"
schemes:
  - https
host: vatapi.com
basePath: /v1
info:
  description: A developer friendly API to help your business achieve VAT compliance
  title: VAT API
  version: "1"
  x-apisguru-categories:
    - financial
  x-logo:
    url: http://vatapi.com/graphics/logo.svg
  x-origin:
    - converter:
        url: https://github.com/lucybot/api-spec-converter
        version: 2.7.11
      format: swagger
      url: https://vatapi.com/api-docs.json
      version: "1.2"
  x-providerName: vatapi.com
securityDefinitions:
  apikey:
    description: Enter your API key
    in: header
    name: apikey
    type: apiKey
security:
  - apikey: []
tags:
  - name: api
paths:
  /country-code-check:
    get:
      operationId: country_code_check
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: The 2 digit country code
          in: query
          name: code
          required: true
          type: string
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Country_Code_Check"
      summary: Retrieve a countries VAT rates by its 2 digit country code
      tags:
        - api
  /currency-conversion:
    get:
      operationId: currency_conversion
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: The currency code you are converting from
          in: query
          name: currency_from
          required: true
          type: string
        - description: The currency code you are converting to
          in: query
          name: currency_to
          required: true
          type: string
        - description: Optional, an amount you are wanting to convert. Leave blank to just get the current rate
          in: query
          name: amount
          required: false
          type: integer
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Currency_Conversion"
      summary: Convert a currency
      tags:
        - api
  /invoice:
    post:
      operationId: create_invoice
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: Enter invoice data as JSON
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/Invoice_Data"
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Create_Invoice"
      summary: Create a VAT invoice
      tags:
        - api
  "/invoice/{id}":
    delete:
      operationId: invoice_delete
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: Enter an invoice id
          in: path
          name: id
          required: true
          type: integer
      responses:
        "200":
          description: No response was specified
      summary: Delete an invoice
      tags:
        - api
    get:
      operationId: get_invoice
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: Enter the invoice id
          in: path
          name: id
          required: true
          type: integer
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Retrieve_Invoice"
      summary: Retrieve an invoice
      tags:
        - api
    put:
      operationId: invoice_update
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: Enter an invoice id
          in: path
          name: id
          required: true
          type: integer
        - description: Enter invoice data as JSON
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/Update_Invoice_Array"
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Update_Invoice"
      summary: Update an existing invoice
      tags:
        - api
  /ip-check:
    get:
      operationId: ip_check
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: The IP address to search against
          in: query
          name: address
          required: true
          type: string
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/IP_Check"
      summary: Retrieve a countries VAT rates from an IP address
      tags:
        - api
  /usage-check:
    get:
      operationId: api_usage
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Api_Usage"
      summary: Check api requests remaining on current subscription plan
      tags:
        - api
  /vat-number-check:
    get:
      description: <p>We highly recommend if you are able, to check a VAT number on your end first to save wasted API lookups. It maybe that your customer has simply entered the wrong format. <a href='http://www.braemoor.co.uk/software/vat.shtml' target='_blank'>Heres a client side way to check the format using Javascript</a></p>
      operationId: vat_number_validate
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: The VAT number to validate
          in: query
          name: vatid
          required: true
          type: string
      responses:
        "200":
          description: No response was specified
      summary: Validate a VAT number
      tags:
        - api
  /vat-price:
    get:
      operationId: convert_price
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
        - description: The 2 digit country code
          in: query
          name: code
          required: true
          type: string
        - description: "The VAT rate to get the price for. Default: standard"
          in: query
          name: country_rate
          required: false
          type: string
        - description: The price you want converting
          in: query
          name: price
          required: true
          type: integer
        - description: Optional, if the price is including VAT set the type to 'incl'. Otherwise the default is assumed as excluding VAT already, 'excl'
          in: query
          name: type
          required: false
          type: string
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Convert_Price"
      summary: Convert a price to or from VAT price.
      tags:
        - api
  /vat-rates:
    get:
      operationId: vat_rates
      parameters:
        - description: The default response type is application/json if you would like to receive an XML response then set this to XML
          in: header
          name: Response-Type
          type: string
      responses:
        "200":
          description: No response was specified
          schema:
            $ref: "#/definitions/Vat_Rates"
      summary: Retrieve all current EU VAT rates
      tags:
        - api
definitions:
  Api_Usage:
    properties:
      requests_remaining:
        description: The number of api requests remaining in the current billing period
        type: integer
      requests_used:
        description: The number of api requests consumed within the last 30 days
        type: integer
      status:
        description: Response code
        type: integer
    required:
      - requests_remaining
      - requests_used
      - status
  Convert_Price:
    properties:
      country_code:
        description: The 2 digit country code
        type: string
      country_rate:
        description: The country_rate
        type: string
      price_excl_vat:
        description: The price excluding VAT
        type: integer
      price_incl_vat:
        description: The price including VAT
        type: integer
      rate:
        description: The rate % for the country_rate
        type: integer
      status:
        description: Response code
        type: integer
      vat:
        description: The total amount of VAT applied
        type: integer
    required:
      - country_code
      - country_rate
      - price_excl_vat
      - price_incl_vat
      - rate
      - status
      - vat
  Country_Code_Check:
    properties:
      country:
        description: The country name
        type: string
      country_code:
        description: The 2 digit country code
        type: string
      rates:
        $ref: "#/definitions/Country_Rates"
        description: An array of the EU VAT rates for that country
      status:
        description: Response code
        type: integer
      vat_applies:
        description: TRUE or FALSE, depending if country is within the EU.
        type: string
    required:
      - country
      - country_code
      - rates
      - status
      - vat_applies
  Country_Data:
    properties:
      country:
        description: The country name
        type: string
      rates:
        $ref: "#/definitions/Country_Rates"
        description: An array of the rates for the country
    required:
      - country
      - rates
  Country_Rates:
    properties:
      parking:
        $ref: "#/definitions/parking"
        description: The type of rate
      reduced:
        $ref: "#/definitions/reduced"
        description: The type of rate
      reduced_alt:
        $ref: "#/definitions/reduced_alt"
        description: The type of rate
      standard:
        $ref: "#/definitions/standard"
        description: The type of rate
      super_reduced:
        $ref: "#/definitions/super_reduced"
        description: The type of rate
    required:
      - parking
      - reduced
      - reduced_alt
      - standard
      - super_reduced
  Create_Invoice:
    properties:
      invoice:
        $ref: "#/definitions/Invoice_Array"
        description: The new invoice object
      status:
        description: Response code
        type: integer
    required:
      - invoice
      - status
  Currency_Conversion:
    properties:
      amount_from:
        description: The amount you are converting from
        type: string
      amount_to:
        description: The result amount you have converted to
        type: string
      currency_from:
        description: The currency code you are converting from
        type: string
      currency_to:
        description: The currency code you are converting to
        type: integer
      rate:
        description: The rate according to HMRC at time of sale
        type: string
      status:
        description: Response code
        type: integer
    required:
      - currency_from
      - currency_to
      - rate
      - status
  IP_Check:
    properties:
      country:
        description: The country name
        type: string
      country_code:
        description: The 2 digit country code
        type: string
      rates:
        $ref: "#/definitions/Country_Rates"
        description: An array of the EU VAT rates for that country
      status:
        description: Response code
        type: integer
      vat_applies:
        description: TRUE or FALSE, depending if country is within the EU.
        type: string
    required:
      - country
      - country_code
      - rates
      - status
      - vat_applies
  Invoice_Array:
    properties:
      business_address:
        description: Your business address
        type: string
      business_name:
        description: Your business name
        type: string
      conversion_rate:
        description: The rate of conversion at time of supply
        type: integer
      currency_code:
        description: 3 character currency code for invoice
        type: string
      currency_code_conversion:
        description: 3 character currency code to be converted from original transaction currency
        type: string
      customer_address:
        description: Your customers address
        type: string
      customer_name:
        description: Your customers name or trading name
        type: string
      customer_vat_number:
        description: Customers VAT number
        type: string
      date:
        description: The date the invoice was issued
        type: string
      discount_rate:
        description: The discount rate per item
        type: integer
      discount_total:
        description: Total amount of discount
        type: integer
      invoice_number:
        description: A sequential invoice number
        type: integer
      invoice_url:
        description: A perminant URL to your VAT invoice
        type: string
      items:
        description: An array of your invoice items
        items:
          $ref: "#/definitions/Invoice_Items"
        type: array
      logo_url:
        description: A URL to your logo image. Must be SSL hosted. https://sslimagehost.com is recommended
        type: string
      notes:
        description: Any notes attached to the invoice
        type: string
      subtotal:
        description: Total amount excluding VAT
        type: integer
      tax_point:
        description: (or 'time of supply') if this is different from the invoice date
        type: string
      total:
        description: Total amount of including VAT
        type: integer
      type:
        description: The type of invoice. Either 'sale' or 'refund'
        type: string
      vat_number:
        description: Your VAT number
        type: string
      vat_total:
        description: Total amount of VAT
        type: integer
    required:
      - business_address
      - business_name
      - currency_code
      - date
      - discount_total
      - invoice_number
      - invoice_url
      - items
      - subtotal
      - tax_point
      - total
      - type
      - vat_number
      - vat_total
  Invoice_Data:
    properties:
      business_address:
        description: Your business address
        type: string
      business_name:
        description: Your business name
        type: string
      conversion_rate:
        description: The rate of conversion at time of supply
        type: integer
      currency_code:
        description: 3 character currency code for invoice
        type: string
      currency_code_conversion:
        description: 3 character currency code to be converted from original transaction currency
        type: string
      customer_address:
        description: Your customers address
        type: string
      customer_name:
        description: Your customers name or trading name
        type: string
      customer_vat_number:
        description: Optional customers VAT number
        type: string
      date:
        description: The date the invoice was issued
        type: string
      discount_rate:
        description: The discount rate per item
        type: string
      items:
        description: An array of your invoice items
        items:
          $ref: "#/definitions/Invoice_Items"
        type: array
      notes:
        description: Add a note to the invoice.
        type: string
      price_type:
        description: Optional, if the price is including VAT set the type to 'incl'. Otherwise the default is assumed as excluding VAT already, 'excl'
        type: string
      tax_point:
        description: (or 'time of supply') if this is different from the invoice date
        type: string
      type:
        description: The type of invoice. Either 'sale' or 'refund'
        type: string
      vat_number:
        description: Your VAT number
        type: string
      zero_rated:
        description: To Zero-Rate the VAT, set to true.
        type: string
    required:
      - business_address
      - business_name
      - currency_code
      - items
      - type
      - vat_number
  Invoice_Items:
    properties:
      description:
        description: The item line description
        type: string
      price_each:
        description: The price of the individual item (Ex VAT)
        type: integer
      quantity:
        description: The quantity of the item
        type: integer
      vat_rate:
        description: The VAT rate at which the item is charged
        type: integer
    required:
      - description
      - price_each
      - quantity
      - vat_rate
  Retrieve_Invoice:
    properties:
      invoice:
        $ref: "#/definitions/Retrieve_Invoice_Array"
        description: The invoice array
      status:
        description: Response code
        type: string
    required:
      - invoice
      - status
  Retrieve_Invoice_Array:
    properties:
      business_address:
        description: Your business address
        type: string
      business_name:
        description: Your business name
        type: string
      conversion_rate:
        description: The rate of conversion at time of supply
        type: integer
      currency_code:
        description: 3 character currency code for invoice
        type: string
      currency_code_conversion:
        description: 3 character currency code to be converted from original transaction currency
        type: string
      customer_address:
        description: Your customers address
        type: string
      customer_name:
        description: Your customers name or trading name
        type: string
      customer_vat_number:
        description: Optional, customers VAT number
        type: string
      date:
        description: The date the invoice was issued
        type: string
      discount_rate:
        description: The discount rate per item
        type: integer
      discount_total:
        description: Total amount of discount
        type: integer
      id:
        description: The invoice ID
        type: integer
      invoice_url:
        description: A perminant URL to your VAT invoice
        type: string
      items:
        description: An array of your invoice items
        items:
          $ref: "#/definitions/Invoice_Items"
        type: array
      logo_url:
        description: A URL to your logo image. Must be SSL hosted. https://sslimagehost.com is recommended
        type: string
      notes:
        description: Any notes attached to the invoice
        type: string
      price_type:
        description: Optional, if the price is including VAT set the type to 'incl'. Otherwise the default is assumed as excluding VAT already, 'excl'
        type: string
      subtotal:
        description: Total amount excluding VAT
        type: integer
      tax_point:
        description: (or 'time of supply') if this is different from the invoice date
        type: string
      total:
        description: Total amount of including VAT
        type: integer
      type:
        description: The type of invoice. Either 'sale' or 'refund'
        type: string
      vat_number:
        description: Your VAT number
        type: string
      vat_total:
        description: Total amount of VAT
        type: integer
      zero_rated:
        description: To Zero-Rate the VAT, set to true.
        type: string
    required:
      - business_address
      - business_name
      - currency_code
      - date
      - discount_total
      - id
      - invoice_url
      - items
      - subtotal
      - tax_point
      - total
      - type
      - vat_number
      - vat_total
  Update_Invoice:
    properties:
      invoice:
        $ref: "#/definitions/Retrieve_Invoice_Array"
        description: The invoice array
      status:
        description: Response code
        type: string
    required:
      - invoice
      - status
  Update_Invoice_Array:
    properties:
      business_address:
        description: Your business address
        type: string
      business_name:
        description: Your business name
        type: string
      conversion_rate:
        description: The rate of conversion at time of supply
        type: integer
      currency_code:
        description: 3 character currency code for invoice
        type: string
      currency_code_conversion:
        description: 3 character currency code to be converted from original transaction currency
        type: string
      customer_address:
        description: Your customers address
        type: string
      customer_name:
        description: Your customers name or trading name
        type: string
      customervat_number:
        description: Customers VAT number
        type: string
      date:
        description: The date the invoice was issued
        type: string
      discount_rate:
        description: The discount rate per item
        type: string
      items:
        description: An array of your invoice items
        items:
          $ref: "#/definitions/Invoice_Items"
        type: array
      logo_url:
        description: A URL to your logo image. Must be SSL hosted. https://sslimagehost.com is recommended
        type: string
      notes:
        description: Add a note to the invoice.
        type: string
      tax_point:
        description: (or 'time of supply') if this is different from the invoice date
        type: string
      type:
        description: The type of invoice. Either 'sale' or 'refund'
        type: string
      vat_number:
        description: Your VAT number
        type: string
    required:
      - business_address
      - business_name
      - currency_code
      - customervat_number
      - items
      - type
  Vat_Rates:
    properties:
      countries:
        description: An array of the EU VAT countries and their respective rates
        items:
          $ref: "#/definitions/Vat_Rates_Countries"
        type: array
      status:
        description: Response code
        type: integer
    required:
      - countries
      - status
  Vat_Rates_Countries:
    properties:
      country_code:
        $ref: "#/definitions/Country_Data"
        description: The 2 digit country code
    required:
      - country_code
  parking:
    properties:
      applies_to:
        description: The type of goods the rate applies to
        type: string
      value:
        description: The % VAT rate
        type: integer
    required:
      - applies_to
      - value
  reduced:
    properties:
      applies_to:
        description: The type of goods the rate applies to
        type: string
      value:
        description: The % VAT rate
        type: integer
    required:
      - applies_to
      - value
  reduced_alt:
    properties:
      applies_to:
        description: The type of goods the rate applies to
        type: string
      value:
        description: The % VAT rate
        type: integer
    required:
      - applies_to
      - value
  standard:
    properties:
      value:
        description: The % VAT rate
        type: integer
    required:
      - value
  super_reduced:
    properties:
      applies_to:
        description: The type of goods the rate applies to
        type: string
      value:
        description: The % VAT rate
        type: integer
    required:
      - applies_to
      - value
