Supplies

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 to a supply object. Supplies are also used to automatically generate a quarterly tax report with currency conversion at official exchange rates.

If, for example, your supplies are transacted in USD but your reporting currency is in EUR, we will convert each amount accurately at the applicable exchange rate published by the European Central Bank. We currently support domestic VAT, VAT OSS report and EC Sales List (ESL).

Evidence Sufficiency

We help you ensure that the evidences attached to your supply object are sufficient. The evidence_status indicates whether they are sufficient or insufficient to prove the place of supply as stated in country_code. The status depends on the number of evidences you have configured in your tax treatment settings.

Synchronize With Integrations

You can create supply objects programmatically via this API endpoint or via integrations such as Stripe.

Integrations with other popular payment providers follow in due course and according to demand. Please write to team@vatstack.com if you require a particular integration. We’re open to discussing your needs.

The Supply Object

Key	Description
`id`	Unique identifier for the object.
`amount`	Amount in cents, as given in your request.
`amount_refunded`	Amount in cents refunded back to the customer.
`amount_total`	Total amount in cents charged in consideration of the `vat.inclusive` boolean. This is the amount that was actually charged the customer and is the difference between `amount` and `amount_refunded`.
`country_code`	2-letter ISO country code of the place of supply that is relevant for the `vat.rate`.
`created`	ISO date at which the object was created.
`currency`	3-letter ISO 4217 currency code used to charge the `amount`.
`description`	An arbitrary string to describe the supplied item. Often useful for displaying to users.
`evidence`	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 for reference.
`evidence_status`	Status of whether the attached evidence object sufficiently proves the place of supply established in `country_code`. Will be either `sufficient` or `insufficient`.
`invoice_number`	A custom string for the invoice number issued to the customer. It’s advisable to follow sequential numbering.
`issued`	ISO date at which `invoice_number` was issued.
`name`	A custom string for the name of the customer.
`notes`	A custom string for additional notes.
`updated`	ISO date at which the object was updated.
`validation`	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 for reference.
`vat.amount`	VAT amount in cents.
`vat.inclusive`	Specifies if the given `amount_total` is inclusive (common for EU consumers) or exclusive of VAT. This affects how the `vat.amount` is calculated.
`vat.rate`	VAT rate applicable for the place of supply established in `country_code`.
`vat.rate_type`	Automatically determined type of VAT rate based on inputs. Can be `null`, `exempt`, `reduced`, `reverse_charge`, `standard` or `zero`.

Create a Supply

Creates a supply object.

Request

Authorize with Secret Key

curl -X POST https://api.vatstack.com/v1/supplies \
     -H "X-API-KEY: sk_live_c283fd6d793076603646b197c7cb0424" \

Body Parameters

Parameter	Description
`amount` required	Amount in cents (e.g. 100.50 must be expressed as 10050). This common common workaround prevents unexpected rounding issues.
`amount_refunded` optional	Amount in cents refunded back to the customer.
`country_code` required	2-letter ISO country code of the place of supply that is relevant for the `vat.rate`.
`currency` required	3-letter ISO 4217 currency code used to charge the `amount`. The currency is used to correctly convert to your reporting currency.
`description` optional	A custom string to describe the supplied item.
`evidence` optional	Unique identifier of an evidence object. The pieces of non-contradictory evidence contained therein will affect the `evidence_status`.
`invoice_number` required	A custom string for the invoice number issued to the customer. It’s advisable to follow sequential numbering.
`issued` required	ISO date at which the invoice was issued to the customer.
`name` optional	A custom string for the name of the customer.
`notes` optional	A custom string for additional notes.
`validation` optional	Unique identifier of a validation object. This is useful if the customer had validated a VAT number beforehand. Its `valid` value can affect `vat.amount`, `vat.rate` and `amount_total` when zero-rating.
`vat.inclusive` optional	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.
`vat.rate` required	VAT rate must be either the `standard_rate` or one of the `reduced_rates` in the rate object 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 during checkout.

Note that vat should be sent as object with nested fields.

Response

Supply object successfully created.

{
  "amount": 9900,
  "amount_refunded": 0,
  "amount_total": 9900,
  "country_code": "IE",
  "created": "2020-06-04T21:53:37.326Z",
  "currency": "USD",
  "description": null,
  "evidence": {
    "bank_address": {
      "name": "VISA",
      "country_code": "IE"
    },
    "billing_address": {
      "city": "East Wall",
      "state": "Leinster",
      "country_code": "IE"
    },
    "ip_address": {
      "label": "92.251.255.11",
      "provider": "MaxMind GeoIP2",
      "city": "East Wall",
      "state": "Leinster",
      "country_code": "IE"
    },
    "required_count": 1,
    "created": "2020-06-04T21:53:21.698Z",
    "updated": "2020-06-04T21:53:21.698Z",
    "id": "5ed96d51336f006f30a50462"
  },
  "evidence_status": "sufficient",
  "id": "5ed96d61336f006f30a50463",
  "invoice_number": "310B7863-0007",
  "issued": "2020-06-04T20:43:17.582Z",
  "name": "John Casper",
  "notes": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "updated": "2020-06-04T21:53:37.326Z",
  "validation": null,
  "vat": {
    "inclusive": true,
    "rate_type": "standard",
    "rate": 23,
    "amount": 1851
  }
}

List All Supplies

Retrieves all supply objects in order of creation, with the most recent appearing highest.

Request

Authorize with Secret Key

curl -X GET https://api.vatstack.com/v1/supplies \
     -H "X-API-KEY: sk_live_c283fd6d793076603646b197c7cb0424" \

Query Parameters

Parameter	Description
`country_code` optional	The 2-letter ISO country code by which you want to filter your records.
`issued_since` optional	Show only objects where the `issued` date is this date or later. Format `YYYY-MM-DD`.
`issued_until` optional	Show only objects where the `issued` date is this date or earlier. Format `YYYY-MM-DD`.
`limit` optional	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
`name` optional	Show only objects with that customer name.
`page` optional	Integer for the current page.

Response

Supply objects successfully retrieved.

{
  "has_more": false,
  "supplies_count": 1,
  "supplies": [
    {
      "amount": 9900,
      "amount_refunded": 0,
      "amount_total": 9900,
      "country_code": "IE",
      "created": "2020-06-04T21:53:37.326Z",
      "currency": "USD",
      "description": null,
      "evidence": {
        "bank_address": {
          "name": "VISA",
          "country_code": "IE"
        },
        "billing_address": {
          "city": "East Wall",
          "state": "Leinster",
          "country_code": "IE"
        },
        "ip_address": {
          "label": "92.251.255.11",
          "provider": "MaxMind GeoIP2",
          "city": "East Wall",
          "state": "Leinster",
          "country_code": "IE"
        },
        "required_count": 1,
        "created": "2020-06-04T21:53:21.698Z",
        "updated": "2020-06-04T21:53:21.698Z",
        "id": "5ed96d51336f006f30a50462"
      },
      "evidence_status": "sufficient",
      "id": "5ed96d61336f006f30a50463",
      "invoice_number": "310B7863-0007",
      "issued": "2020-06-04T20:43:17.582Z",
      "name": "John Casper",
      "notes": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "updated": "2020-06-04T21:53:37.326Z",
      "validation": null,
      "vat": {
        "inclusive": true,
        "rate_type": "standard",
        "rate": 23,
        "amount": 1851
      }
    },
    ...
  ]
}

Retrieve a Supply

Retrieves a supply object by the :id path parameter.

Request

Authorize with Secret Key

curl -X GET https://api.vatstack.com/v1/supplies/:id \
     -H "X-API-KEY: sk_live_c283fd6d793076603646b197c7cb0424" \

Response

Supply object successfully retrieved.

{
  "amount": 9900,
  "amount_refunded": 0,
  "amount_total": 9900,
  "country_code": "IE",
  "created": "2020-06-04T21:53:37.326Z",
  "currency": "USD",
  "description": null,
  "evidence": {
    "bank_address": {
      "name": "VISA",
      "country_code": "IE"
    },
    "billing_address": {
      "city": "East Wall",
      "state": "Leinster",
      "country_code": "IE"
    },
    "ip_address": {
      "label": "92.251.255.11",
      "provider": "MaxMind GeoIP2",
      "city": "East Wall",
      "state": "Leinster",
      "country_code": "IE"
    },
    "required_count": 1,
    "created": "2020-06-04T21:53:21.698Z",
    "updated": "2020-06-04T21:53:21.698Z",
    "id": "5ed96d51336f006f30a50462"
  },
  "evidence_status": "sufficient",
  "id": "5ed96d61336f006f30a50463",
  "invoice_number": "310B7863-0007",
  "issued": "2020-06-04T20:43:17.582Z",
  "name": "John Casper",
  "notes": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "updated": "2020-06-04T21:53:37.326Z",
  "validation": null,
  "vat": {
    "inclusive": true,
    "rate_type": "standard",
    "rate": 23,
    "amount": 1851
  }
}

Update a Supply

Updates a supply object by the :id path parameter.

Request

Authorize with Secret Key

curl -X PUT https://api.vatstack.com/v1/supplies/:id \
     -H "X-API-KEY: sk_live_c283fd6d793076603646b197c7cb0424" \

Body Parameters

Parameter	Description
`amount` required	Amount in cents (e.g. 100.50 must be expressed as 10050). This common common workaround prevents unexpected rounding issues.
`amount_refunded` optional	Amount in cents refunded back to the customer.
`country_code` required	2-letter ISO country code of the place of supply that is relevant for the `vat.rate`.
`currency` required	3-letter ISO 4217 currency code used to charge the `amount`. The currency is used to correctly convert to your reporting currency.
`description` optional	A custom string to describe the supplied item.
`evidence` optional	Unique identifier of an evidence object. The pieces of non-contradictory evidence contained therein will affect the `evidence_status`.
`invoice_number` required	A custom field for the invoice number issued to the customer. It’s advisable to follow sequential numbering.
`issued` required	ISO date at which the invoice was issued to the customer.
`name` optional	A custom field for the name of the customer.
`notes` optional	A custom field for additional notes.
`validation` optional	Unique identifier of a validation object. This is useful if the customer had validated a VAT number beforehand. Its `valid` value can affect `vat.amount`, `vat.rate` and `amount_total` when zero-rating.
`vat.inclusive` optional	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.
`vat.rate` required	VAT rate must be either the `standard_rate` or one of the `reduced_rates` in the rate object 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 quotes object during checkout.

Note that vat should be sent as object with nested fields.

Response

Supply object successfully updated.

{
  "amount": 9900,
  "amount_refunded": 0,
  "amount_total": 9900,
  "country_code": "IE",
  "created": "2020-06-04T21:53:37.326Z",
  "currency": "USD",
  "description": null,
  "evidence": {
    "bank_address": {
      "name": "VISA",
      "country_code": "IE"
    },
    "billing_address": {
      "city": "East Wall",
      "state": "Leinster",
      "country_code": "IE"
    },
    "ip_address": {
      "label": "92.251.255.11",
      "provider": "MaxMind GeoIP2",
      "city": "East Wall",
      "state": "Leinster",
      "country_code": "IE"
    },
    "required_count": 1,
    "created": "2020-06-04T21:53:21.698Z",
    "updated": "2020-06-04T21:53:21.698Z",
    "id": "5ed96d51336f006f30a50462"
  },
  "evidence_status": "sufficient",
  "id": "5ed96d61336f006f30a50463",
  "invoice_number": "310B7863-0007",
  "issued": "2020-06-04T20:43:17.582Z",
  "name": "John Casper",
  "notes": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "updated": "2020-06-04T22:12:54.512Z",
  "validation": null,
  "vat": {
    "inclusive": true,
    "rate_type": "standard",
    "rate": 23,
    "amount": 1851
  }
}

Delete a Supply

Deletes a supply object by the :id path parameter.

Request

Authorize with Secret Key

curl -X DELETE https://api.vatstack.com/v1/supplies/:id \
     -H "X-API-KEY: sk_live_c283fd6d793076603646b197c7cb0424" \

Response

Supply object successfully deleted.

{
  "id": "5ed96d61336f006f30a50463",
  "deleted": true
}