Skip to main content
Sign in Menu

IOSS integration guide

  • Updated

Introduction

This document helps you to integrate with Eurora API to ensure an automated flow of monthly sales data.

Note:

Unless otherwise specified, all the links of API calls and API documentation are for Production Environment. To access the links to Integration Environment, just replace the api.eurora.com part with api.integration.eurora.com.

Integrating with Eurora

Take the following steps to integrate with the Eurora API:

  1. Become our IOSS service client and get an IOSS number from Eurora.
  2. Eurora will create your account and issue you an API key. You will need to use this API key as your X-Auth-Token header parameter whenever you make a query.
  3. Choose the API endpoints you wish to integrate with (see descriptions below).
  4. Integrate with the chosen endpoints in Eurora's Integration environment. Use our Integration environment to test the endpoints and send us test data.
  5. If all seems well, integrate with the endpoints in Eurora's Production environment to start sending us real IOSS data.

Eurora's Integration environment API documentation can be found here.

Eurora's Production environment API documentation can be found here.

Sending IOSS sales data to Eurora 

For sending IOSS sales data to Eurora, we offer a set of endpoints:

  • Create order
  • Update order
  • Delete order
  • Upload bulk orders file

Create order (POST)

  • URL: https://api.eurora.com/vat-service/v1/order
  • API documentation: https://api.eurora.com/ioss-v1#operation/createOrder
  • Purpose: Send sales data to Eurora for monthly VAT returns. The first and the most important endpoint to start sending data.
  • When to use: We recommend sending the data when it's created in your system (e.g., moment of order confirmation), but we will also accept orders at a later date (sales data from the previous month must be sent to us latest by the 5th of the following month). 
  • Example: client from Italy bought shoes on the 10th of September and confirmed the order number 1234 in total amount of 122 euros, all mandatory sales data (i.e., description of goods-shoes, quantity-1, value per single item-100 euros, VAT rate-22%, order number 1234, order VAT payable 22 euros, destination country IT) should be sent to EURORA immediately or latest 5th of October. All other information related to the order can be sent later.

Update order (PUT)

  • URL: https://api.eurora.com/vat-service/v1/order/{uuid}
  • API documentation: https://api.eurora.com/ioss-v1#operation/updateOrder
  • Purpose: Fix erroneous data or add missing data to an existing order.
  • When to use: Whenever it becomes apparent that submitted data is wrong or insufficient (sales data from the previous month must be updated latest by the 5th of the following month)
  • Example: client from Italy bought shoes on the 10th of September and confirmed the order number 1234 in the total amount of 122 euros, all mandatory sales data (i.e., description of goods-shoes, quantity-1, value per single item-100 euros, VAT rate-20%, order number 1234, order VAT payable 20 euros, destination country IT) was sent to EURORA at 10th of September. On the 5th of October, the client gets feedback from EURORA that the VAT rate and VAT payable are incorrect. To fix the data update order endpoint is correct to use here.

Delete order (DELETE)

  • URL: https://api.eurora.com/vat-service/v1/order/{uuid}
  • API documentation: https://api.eurora.com/ioss-v1#operation/deleteOrder
  • Purpose: Delete an order that should not be declared on the IOSS return (e.g., order value exceeds 150 EUR; order contains excise goods; orders submitted were test orders).
  • When to use: Whenever it becomes apparent that an order should not be declared (sales data from the previous month must be corrected latest 5th of the following month)
  • Example: client from Estonia bought bags on the 10th of September and confirmed the order number 5678 in the total amount of 250 euros, all mandatory sales data was sent to EURORA on the 10th of September. On the 15th of September the seller finds out that incorrect order was sent to EURORA because the value of the goods is over 150 EUR and IOSS scheme can`t be used. To delete the wrong order, the delete order endpoint is correct to use here.

Upload bulk orders file (POST)

  • URL: https://api.eurora.com/vat-service/v1/order/bulk/upload
  • API documentation: https://api.eurora.com/ioss-v1#operation/uploadBulkOrdersFile
  • Purpose: Send sales data in bulk to Eurora for monthly VAT returns.
  • When to use: We recommend sending the bulk data when all your orders are created in your system (e.g., moment of order confirmation), but we will also accept orders at a later date (sales data from the previous month must be sent to us latest by the 5th of the following month). 
  • Example: Clients bought goods on the 10th of September and confirmed them with unique order numbers. All mandatory sales data (i.e., descriptions of goods - shoes, quantity - 1, value per single item-100 euros, VAT rate-22%, order numbers 1234, order VAT payable 22 euros, destination country IT) should be sent to EURORA immediately or at the latest 5th of October. All other data related to the orders can be sent later.

Please make sure that all query parameters and body fields are present before uploading a bulk orders file by following this instruction.

Correcting IOSS orders in case of returns, exchanges etc.

In case of product returns, exchanges, refunds, etc. where monetary values change, we offer a set of endpoints:

  • Create correction
  • Update correction
  • Delete correction
  • Upload bulk corrections file in .xlsx format

Create correction (POST)

  • URL: https://api.eurora.com/vat-service/v1/correction/{orderUuid}
  • API documentation: https://api.eurora.com/ioss-v1#operation/createCorrection
  • Purpose: Add a correction to an existing order in case of product returns, exchanges etc. and there are changes in monetary value in decreasing direction.
  • When to use: We recommend sending the data when it's created in your system (e.g., moment of credit note creation), but we will also accept corrections at a later date (but not later than 3 years after the date of the original order)
  • Example: client from Germany bought 2 T-shirts on the 15th of September and confirmed the order number 9101 in total amount of 50 euros, all mandatory sales data was sent to EURORA on the 15th of September. On the 30th of October, the client sends back one T-shirt and claims a refund of 20 euros. To correct the initial order, create correction endpoint is correct to use here because the monetary value connected to this order changed. Initially it was +50 euros and now it`s -20 euros.

Update correction (PUT)

  • URL: https://api.eurora.com/vat-service/v1/correction/{uuid}
  • API documentation: https://api.eurora.com/ioss-v1#operation/updateCorrection
  • Purpose: Fix erroneous correction data
  • When to use: Whenever it becomes apparent that current data is wrong (but not after the declaration for the period where correction is declared has already been submitted)
  • Example: On the 10th of October the client sends back the T-shirt and claims refund 20 euros. To correct the initial order, create correction endpoint was used on the 30th of October but at the same time seller finds out that correction was made to the amount 25 euros. To correct the initial correction, update correction endpoint is correct to use here.

Delete correction (DELETE)

  • URL: https://api.eurora.com/vat-service/v1/correction/{correctionUuid}
  • API documentation: https://api.eurora.com/ioss-v1#operation/deleteCorrection
  • Purpose: Delete a correction that should not be declared (e.g., a correction was sent with the wrong original order number).
  • When to use: Whenever it becomes apparent that a correction should not be declared (but not after the declaration for the period where correction is declared has already been submitted)
  • Example: On the 30th of October the client sends back the T-shirt and claims a refund of 20 euros. To correct the initial order, create correction endpoint was used on the 30th of October but at the same time seller finds out that correction was made to the order 1234 but the initial order was 9101. Delete correction endpoint is correct to use here, to delete the incorrect correction related to the order 1234.

Upload bulk corrections file in .xlsx format

  • URL: https://api.eurora.com/vat-service/v1/correction/bulk/upload
  • API documentation: https://api.eurora.com/ioss-v1#operation/uploadBulkCorrectionsFile
  • Purpose: Add bulk correction to existing orders in case of product returns, exchanges etc. and there are changes in monetary value in decreasing direction.
  • When to use: We recommend sending the bulk data when it's created in your system (e.g., moment of credit note creation), but we will also accept bulk corrections at a later date (but not later than 3 years after the date of the original order)
  • Example: client from Germany bought some goods on the 15th of September and confirmed them with unique order numbers in a total amount of 50 euros, all mandatory sales data was sent to EURORA on the 15th of September. On the 30th of October, the client sends back some pieces and claims a refund of 20 euros. To correct the initial orders, the upload bulk correction endpoint is correct to use here because the monetary value connected to these orders changed. Initially, it was +50 euros and now it`s -20 euros.

Requesting VAT report and other IOSS data from Eurora

After sending data to Eurora you can also request data back from Eurora to get an overview of your sales data. Eurora offers a range of endpoints for you to request data:

  • Get VAT report data
  • Get order
  • Get orders
  • Get correction
  • Get corrections

Get VAT report data (GET)

Get order (GET)

Get orders (GET)

  • URL: https://api.eurora.com/vat-service/v1/order
  • API documentation: https://api.eurora.com/ioss-v1#operation/getAll
  • Purpose: Request your orders’ data, including data errors or warnings (orderStatusDetails object). If any of the orders has a correction linked to it, the order will be returned with recalculated monetary values taking into account the corrections’ monetary values.
  • When to use: Whenever you wish to see orders' data
  • Additional info: This is a pageable response endpoint. This means that a subset (one page) of data is returned by every query. The size, page, sort field and sort direction can be specified in the query parameters. The total number of elements, number of pages and other relevant info can be found in the query response along with the orders' data in content object.

Get correction (GET)

Get corrections (GET)

  • URL: https://api.eurora.com/vat-service/v1/correction
  • API documentation: https://api.eurora.com/ioss-v1#operation/getCorrections
  • Purpose: Request your corrections' data. 
  • When to use: Whenever you wish to see corrections' data
  • Additional info: This is a pageable response endpoint. This means that a subset (one page) of data is returned by every query. The size, page, sort field and sort direction can be specified in the query parameters. The total number of elements, number of pages and other relevant info can be found in the query response along with the corrections’ data in content object.

API Documentation

Environment API Documentation API Collection
Production Link Link
Integration Link Link

 

Explanation of Data Fields of Create Order

Field Name Explanation

orderNumber

(mandatory*)

The order (transaction) number in online shop

 (i.e., ecommerce platform). Order number is used to keep track on each buyer´s order and must be unique. You can't send data with the same order number (id) twice.
trackingNumber The unique consignment number if the taxable person (supplier) is directly involved in the delivery. This number is created by the carrier and made available to the supplier.
date
(mandatory)		 The time of supply is the moment when the payment has been accepted, regardless of when the actual payment of money is made, whichever is the earliest. The date can't be in the future i.e., sending data in August, the date can`t be in September.
dispatchCountry Non-EU country from where the transport of goods starts. The country code should follow ISO 3166-2. LINK
destinationCountry
(mandatory)		 Member State of consumption (where is the delivery address). The country code should follow ISO 3166-2. LINK
destinationRegion The region of the Member State of consumption, for example, Madeira (PT-30), Azores (PT-20). Goods destination region ISO-3166-2 code. LINK
invoiceDate Date of the VAT invoice (if issued) or commercial invoice accompanying the goods for customs clearance.
invoiceNumber Number of the VAT invoice (if issued) or commercial invoice accompanying the goods for customs clearance.
paymentDate The date of payment received for the order.
paymentAmount Actual price paid for the order.
currency
(mandatory)		 The order (transaction) currency. The currency of the payment that has been received. The currency should follow ISO 4217. LINK
transportationPrice
(mandatory)		 This field must be filled with concrete value if transportation price indicated separately at the order (if not mark 0). Price excluding VAT.
transportationVatRate VAT rate (%) of destination country used to calculated transportation prices’ VAT.
Order transportation VAT amount VAT amount calculated from the transportation price: transportaionPrice multiplied with transportationVatRate.

insurancePrice

(mandatory)

 This field must be filled with concrete value if insurance price indicated separately at the order (if not mark 0). Price excluding VAT.
insuranceVatRate VAT rate (%) of destination country used to calculated insurance VAT.
insuranceVatAmount VAT amount calculated from the insurance price: insurancePrice multiplied with insuranceVatRate.
otherAdditionalCosts (mandatory) This field must be filled with concrete value if there are other additional costs indicated separately at the order (if not mark 0). Costs excluding VAT.
additionalCostsVatRate VAT rate (%) of destination country used to calculated other additional costs’ VAT.
additionalCostsVatAmount VAT amount calculated from the other additional costs: otherAdditionalCosts multiplied with additionalCostsVatRate.

vatPayable

(mandatory)

 Total VAT collected from the buyer for the order (Goods VAT payable+VAT from transport, insurance, other additional costs indicated at the order). 
goods - description
(applies per item, mandatory)		 Specific description of item so that the goods can be identified (e.g., ´clothes´ not acceptable, ´Cotton T-shirt´ acceptable. Please refer to Guidance on acceptable and unacceptable goods description published by EU Commission). Max 255 characters (min.3). Must be in English.

goods – hsCode

(applies per item)

 HS-code per item (internationally standardized system of names and numbers to classify traded products). HS-code format 0101000000, max 10 digits. 

goods – quantity

(applies per item, mandatory)

 Quantity of goods (pcs).

goods – value

(applies per item, mandatory)

 Product price excluding VAT (per single item). For example: If two t-shirts were sold with the order, then in the quantity box you must write 2, but the value box must contain the value of 1 t-shirt excluding VAT.

goods – vatRate

(applies per item, mandatory)

 VAT rate (%) of destination country per item (goods). Concrete VAT rate depends on the goods description (hsCode gives concrete rate) and destination country. General VAT rates are here. 

goods – vatPayable

(applies per item, mandatory)

 VAT amount calculated per concrete item (goods) group: goods – quantity multiplied with goods-value multiplied with goods - vatRate . Without this data we can’t submit VAT declaration. 

* Without this data we can`t submit VAT declaration.