Vatstack Supplies API
The Supplies API from Vatstack — 2 operation(s) for supplies.
OpenAPI Specification
openapi: 3.0.0
info:
title: Vatstack API Specification Batches Supplies 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: Supplies
paths:
/supplies:
post:
operationId: createSupply
summary: Creates a supply object.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
amount:
type: integer
description: Amount in **cents** (e.g. 100.50 must be expressed as 10050). This common common workaround prevents unexpected rounding issues.
amount_refunded:
type: integer
description: Amount in cents refunded back to the customer.
country_code:
type: string
description: 2-letter ISO country code of the place of supply that is relevant for the `vat.rate`.
currency:
type: string
description: 3-letter ISO 4217 currency code used to charge the `amount`. The currency is used to correctly convert to your reporting currency.
description:
type: string
description: A custom string to describe the supplied item.
evidence:
type: string
description: Unique identifier of an [evidence object](https://vatstack.com/docs/evidences). The pieces of non-contradictory evidence contained therein will affect the `evidence_status`.
format: uuid
invoice_number:
type: string
description: A custom string for the invoice number issued to the customer. It’s advisable to follow sequential numbering.
issued:
type: string
description: ISO date at which the invoice was issued to the customer.
name:
type: string
description: A custom string for the name of the customer.
notes:
type: string
description: A custom string for additional notes.
validation:
type: string
description: Unique identifier of a [validation object](https://vatstack.com/docs/validations). This is useful if you let your customer enter a VAT number beforehand. Its valid value can affect `vat.amount`, `vat.rate` and `amount_total` when zero-rating.
format: uuid
vat:
type: object
properties:
inclusive:
type: boolean
description: Boolean for whether the resulting VAT amount should be calculated inclusive or exclusive of VAT. Defaults to `false`. All other `vat` fields will be hydrated for you.
rate:
type: number
description: VAT rate must be either the `standard_rate` or one of the `reduced_rates` in the [rate object](https://vatstack.com/docs/rates) of `country_code`. If an invalid VAT rate is provided, it is automatically replaced with the `standard_rate`. The recommended way is to use the VAT rate determined by a previously generated [quote object](https://vatstack.com/docs/quotes) during checkout.
format: double
required:
- amount
- country_code
- invoice_number
- issued
required: true
responses:
'201':
description: Supply object successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/supply'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- secretKey: []
tags:
- Supplies
get:
operationId: getAllSupplies
summary: Retrieves all supply objects in order of creation, with the most recent appearing highest.
parameters:
- name: country_code
in: query
description: The 2-letter ISO country code by which you want to filter your records.
schema:
type: string
- name: issued_since
in: query
description: Show only objects where the `issued` date is this date or later. Format `YYYY-MM-DD`.
schema:
type: string
format: date
- name: issued_until
in: query
description: Show only objects where the `issued` date is this date or earlier. Format `YYYY-MM-DD`.
schema:
type: string
format: date
- 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: name
in: query
description: Show only objects with that customer name.
schema:
type: string
- name: page
in: query
description: Integer for the current page.
schema:
type: integer
format: int32
responses:
'200':
description: Supply 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
supplies_count:
type: integer
format: int32
supplies:
items:
$ref: '#/components/schemas/supply'
type: array
required:
- has_more
- supplies_count
- supplies
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- secretKey: []
tags:
- Supplies
/supplies/{id}:
get:
operationId: getSupplyById
summary: Retrieves a supply object.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Supply object successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/supply'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- secretKey: []
tags:
- Supplies
put:
operationId: updateSupplyById
summary: Updates a supply object by the {id} path parameter.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
amount:
type: integer
description: Amount in **cents** (e.g. 100.50 must be expressed as 10050). This common common workaround prevents unexpected rounding issues.
amount_refunded:
type: integer
description: Amount in cents refunded back to the customer.
country_code:
type: string
description: 2-letter ISO country code of the place of supply that is relevant for the `vat.rate`.
currency:
type: string
description: 3-letter ISO 4217 currency code used to charge the `amount`. The currency is used to correctly convert to your reporting currency.
description:
type: string
description: A custom string to describe the supplied item.
evidence:
type: string
description: Unique identifier of an [evidence object](https://vatstack.com/docs/evidences). The pieces of non-contradictory evidence contained therein will affect the `evidence_status`.
format: uuid
invoice_number:
type: string
description: A custom string for the invoice number issued to the customer. It’s advisable to follow sequential numbering.
issued:
type: string
description: ISO date at which the invoice was issued to the customer.
name:
type: string
description: A custom string for the name of the customer.
notes:
type: string
description: A custom string for additional notes.
validation:
type: string
description: Unique identifier of a [validation object](https://vatstack.com/docs/validations). This is useful if you let your customer enter a VAT number beforehand. Its valid value can affect `vat.amount`, `vat.rate` and `amount_total` when zero-rating.
format: uuid
vat:
type: object
properties:
inclusive:
type: boolean
description: Boolean for whether the resulting VAT amount should be calculated inclusive or exclusive of VAT. Defaults to `false`. All other `vat` fields will be hydrated for you.
rate:
type: number
description: VAT rate must be either the `standard_rate` or one of the `reduced_rates` in the [rate object](https://vatstack.com/docs/rates) of `country_code`. If an invalid VAT rate is provided, it is automatically replaced with the `standard_rate`. The recommended way is to use the VAT rate determined by a previously generated [quote object](https://vatstack.com/docs/quotes) during checkout.
format: double
required: true
responses:
'200':
description: Supply object successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/supply'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- secretKey: []
tags:
- Supplies
delete:
operationId: deleteSupplyById
summary: Deletes a supply object by the {id} path parameter.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Supply object successfully deleted.
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
security:
- secretKey: []
tags:
- Supplies
components:
schemas:
validation:
type: object
description: Validate your business customer’s VAT number against official government servers in real-time. The API asynchronously validates VAT numbers for you if government services experience downtime.
properties:
active:
type: boolean
description: Boolean indicating whether the company exists and is active. Use `valid` to check whether the business is also VAT-registered.
default: null
code:
type: string
description: In the event of an error, this field will contain the error code.
company_address:
type: string
description: Address of the company the VAT number is associated with. Servers of Germany and Spain won’t return a value for privacy reasons and will default to `null`.
default: null
company_name:
type: string
description: Name of the company the VAT number is associated with. Servers of Germany and Spain won’t return a value for privacy reasons and will default to `null`.
default: null
company_type:
type: string
description: Type of the company entity returned by the respective government service (where available).
default: null
consultation_number:
type: string
description: If you save your own VAT number in your dashboard, the reply will contain a unique consultation number. The consultation number enables you to prove to a tax administration of a Member State that you have checked a VAT number at the `requested` date, and obtained a validation result.
default: null
country_code:
type: string
description: 2-letter ISO country code. Note that while Greek VAT numbers contain the `EL` country code, our response will return the ISO country code `GR`.
maxLength: 2
minLength: 2
created:
type: string
description: ISO date at which the object was created.
format: date-time
id:
type: string
description: Unique identifier for the object.
format: uuid
query:
type: string
description: Your original query.
requested:
type: string
description: ISO date at which the validation request was originally performed. Types `eu_vat` and `gb_vat` do not specify a time.
format: date-time
type:
type: string
description: Type of VAT number.
enum:
- au_gst
- ch_vat
- eu_oss_vat
- eu_vat
- gb_vat
- no_vat
- sg_gst
updated:
type: string
description: ISO date at which the object was updated.
format: date-time
valid:
type: boolean
description: Boolean indicating whether the vat_number is registered for VAT. If government services are down, the value will be `null` and re-checked automatically for you.
default: null
valid_format:
type: boolean
description: Boolean indicating whether the VAT number contained in `query` is in a valid format.
vat_number:
type: string
description: VAT number extracted from your query without the country code.
required:
- query
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
supply:
type: object
description: Supplies are transactions of telecommunications, broadcasting and electronic (TBE) services. To document pieces of evidence for the place of supply, you can attach [evidence objects](https://vatstack.com/docs/evidences) to a supply object. Supplies are also used to automatically generate a quarterly tax report with currency conversion at official exchange rates.
properties:
amount:
type: integer
format: int32
amount_refunded:
type: integer
format: int32
amount_total:
type: integer
format: int32
country_code:
type: string
description: 2-letter ISO country code of the place of supply that is relevant for the `vat.rate`.
maxLength: 2
minLength: 2
created:
type: string
description: ISO date at which the object was created.
format: date-time
currency:
type: string
description: 3-letter ISO 4217 currency code used to charge the `amount`.
maxLength: 3
minLength: 3
description:
type: string
description: An arbitrary string to describe the supplied item. Often useful for displaying to users.
evidence:
type: object
description: Populated evidence object if an ID is attached. You can attach an evidence object with the `evidence` body parameter in the POST request. Defaults to `null`. See [evidence object](https://vatstack.com/docs/evidences) for reference.
$ref: '#/components/schemas/evidence'
evidence_status:
type: string
description: Status of whether the attached evidence object sufficiently proves the place of supply established in `country_code`. Will be either `sufficient` or `insufficient`.
id:
type: string
description: Unique identifier for the object.
format: uuid
invoice_number:
type: string
description: A custom string for the invoice number issued to the customer. It’s advisable to follow sequential numbering.
issued:
type: string
description: ISO date at which `invoice_number` was issued.
format: date-time
name:
type: string
description: A custom string for the name of the customer.
notes:
type: string
description: A custom string for additional notes.
updated:
type: string
description: ISO date at which the object was updated.
format: date-time
validation:
type: object
description: Populated validation object if an ID is attached. You can attach a validation object with the `validation` body parameter in the POST request. Defaults to `null`. See [validation object](https://vatstack.com/docs/validations) for reference.
$ref: '#/components/schemas/validation'
vat:
type: object
properties:
amount:
type: integer
description: VAT amount in cents.
format: int32
inclusive:
type: string
description: Specifies if the `amount_total` is inclusive (common for EU consumers) or exclusive of VAT. This affects how the `vat.amount` is calculated.
default: false
rate:
type: number
description: VAT rate applicable for the place of supply established in `country_code`.
format: double
rate_type:
type: string
description: Automatically determined type of VAT rate based on inputs. Can be `null`, `exempt`, `reduced`, `reverse_charge`, `standard` or `zero`.
required:
- amount
- country_code
- currency
- invoice_number
- issued
evidence:
type: object
description: Store pieces of evidence that confirm your customer’s location. Evidence object can be attached to a supply object and it can only be attached to one supply object at a time.
properties:
bank_address:
type: object
properties:
country_code:
type: string
description: 2-letter ISO country code of the bank or payment source.
maxLength: 2
minLength: 2
name:
type: string
description: Name of the bank or payment source.
billing_address:
type: object
properties:
city:
type: string
description: City of the customer’s billing address.
country_code:
type: string
description: 2-letter ISO country code of the customer’s billing address.
maxLength: 2
minLength: 2
line_1:
type: string
description: Line 1 of the customer’s billing address.
line_2:
type: string
description: Line 2 of the customer’s billing address.
postal_code:
type: string
description: Postal code of the customer’s billing address.
state:
type: string
description: State of the customer’s billing address.
created:
type: string
description: ISO date at which the object was created.
format: date-time
ip_address:
type: object
properties:
label:
type: string
description: The same IP address coming from the `ip_address.label` body parameter which will be geolocated automatically.
provider:
type: string
description: Provider used to geolocate `ip_address.label`. We use MaxMind® GeoIP2 geolocation technology by default but have a number of fallback providers.
city:
type: string
description: City of the geolocated IP address.
country_code:
type: string
description: 2-letter ISO country code of the geolocated IP address.
maxLength: 2
minLength: 2
state:
type: string
description: State of the geolocated IP address.
id:
type: string
description: Unique identifier for the object.
format: uuid
required_count:
type: integer
description: Required pieces of evidence according to your account’s regional settings.
format: int32
updated:
type: string
description: ISO date at which the object was updated.
format: date-time
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