Introduction

Welcome to the Taxdoo API! You can use our API to send us new order data, upload purchase prices and monitor your distance selling thresholds.

You must provide a content-type header on each POST or PUT request. Unless otherwise specified, each call accepts and responds only with JSON. The content-type header is therefore "application/json". Always use UTF-8 as encoding.

We validate your request payload on every single request. If your payload is faulty, the response will contain validation errors with details.

Some fields appear on almost every response of our API. These fields are found in the SimpleResponse model.

We have set up a sandbox environment that you can use to develop your application. Read more about this in the Endpoints section.

Getting started

First read the following Authentication section.

If you want to send us transactions, please read first the Transactions section for general notes about our understanding and handling of your transactions. Then you have multiple options:

• POST /transactions is the most low-level approach. Use this if your data is only available as one row per ordered article. This call supports both sales and refunds.
• POST /orders supports an order - orderItem hierarchy with multiple articles within one order. This call also supports both sales and refunds.
• POST /refunds is like POST /orders, but does only support refunds. This call has a reduced set of required fields and is preferred if your refunds are available distinctly from sale orders.

Some other possible actions on our API:

• For uploading purchase prices and commodity codes, see Add Products
• For setting reduced vat rates for your products, see Set product tax rates
• To review your registrations use Get Registrations
• To monitor your distance selling threshold levels, use Get Threshold Status

Rate Limiting

Our API is equipped with a rolling window rate limiter. That means, the remaining calls do not reset e.g. every 60 seconds, but are limited over a period of time.

Example for a period of 60 seconds and a limit of 20 calls:

• You send 10 calls within 2 seconds, wait 30 seconds, and send 20 calls in the next 5 seconds: The last 10 calls will fail, because you send more than 20 calls within 60 seconds.
• You send 10 calls within 10 seconds, wait 30 seconds, again 10 calls, wait 30 seconds: You now have 10 calls left, because you only sent 10 calls within the last 60 seconds.

Our current rate limits are:

• Period: 60 seconds
• Call limit: 100

We may modify the call limit or the period in the future.

We return the following headers on each request that counted towards the limit:

• X-RateLimit-Remaining: The number of calls you currently have remaining at this exact point in time
• X-RateLimit-Reset: Number of seconds, when the limit completely resets. Always equals the period (see above)
• X-RateLimit-Limit: The call limit within the period

When you exceeded the limit, we respond with a 429 Too Many Requests and include a Retry-After header, which holds the amount of seconds until a new call can be made.

Only calls who passed authentication and input validation do count towards the call limit. Note that calls that failed for any other reason count towards the limit, even when we responded with 429 Too Many Requests. That means, once the limit is reached, sending consecutively new requests that fail with 429 Too Many Requests will prevent your limit from recovering.

Our sandbox and our live system are rate limited separately.

Endpoints

Endpoint for our live system:

https://api.taxdoo.com/

Endpoint for our sandbox:

https://sandbox-api.taxdoo.com/

The sandbox environment has the same calls and uses the same API tokens, but has a separate underlying database and a separate rate limiter. Therefore you can test your calls in development on our sandbox without affecting the rate limits of your production system.

Please note that we do not analyze your transactions in the sandbox, therefore your GET /thresholds calls will return an empty result. This also applies to the GET /registrations call.

Authentication

A personal API token is required for all API paths. The API token can be obtained from the Taxdoo Dashboard under Settings → API. The token has a maximum length of 1024 characters and is valid for about 1 year.

The token must be provided within the AuthToken header:

AuthToken: <Token>

Get current account

Example response:

{
  "status": "success",
  "account": "info@sellermail.de"
}

Use this simple call to retrieve the email address of the current account. It requires no parameters and is therefore the right choice to test if your token works.

HTTP Request

GET /account

Response

The response also includes fields from SimpleResponse.

Authentication with OAuth

For some endpoints this API requires OAuth for authentication. At this moment we only support the client credentials authentication method.

HTTP Request

POST https://auth.taxdoo.com/oauth2/token

HTTP headers

Payload

The payload must be grant_type=client_credentials.

Response

You may now use the following header to authenticate against endpoints with OAuth authentication:

Authorization: Bearer <access_token>

For operations that are related to a particular client, you must additionally provide the Client-Identifier header with the ID of client:

Client-Identifier: 1234

Transactions

A transaction represents the sale or the refund of one or multiple products of one single product type. A transaction has properties like payment and departure dates, transactions identifiers, quantity, description, item price, shipping price etc.

We identify transactions by a set of identifiers from a Platform object. Each transaction must have a channel Platform object and an optional source Platform object. The channel is required because it represents the actual platform where the sale occurred, e.g. Amazon, eBay or the own webshop, while the source object represents the data source from which the transaction was imported. Usually this is the ERP the merchant uses, e.g. Plentymarkets. If the source is not provided, we use the fields of the channel object to identify the transaction, otherwise we use the source fields.

This identifier set is used to avoid duplicates, i.e. inserting the same transaction multiple times has the same effect as inserting it only once. This also allows us to take transactions both from ERP Systems like Plentymarkets and directly from marketplaces like Amazon and eBay, while still be able to find these transactions on both platforms. This also allows you to push the same data multiple times into our API without having to worry about duplicates.

Be still careful not to mix the same data from different sources, e.g. do not insert transactions from an ERP (which includes Amazon transactions) along with transactions directly from Amazon, as the used identifier set will differ (source is used for the ERP transactions while the transactions directly from Amazon only include a channel).

Important: When inserting Refunds, take care of using the same channel and source objects like the underlying sale, but with a refundNumber set, i.e. transactionNumber, identifier, itemNumber and itemPosition must match both on channel and source (if provided). We only process refunds that are matchable with an underlying sale.

All your provided monetary amounts are summed up to the total_value field available in the GET /transactions response, i.e. if a discount should reduce the item_price for a sale, the discount field value must be negative. Also, we directly adopt your monetary amount values for refunds, that means, you must provide negated monetary amount values for refunds. For example, itemPrice and shipping are negative and discount (reducing the refund) is positive. There is no validation if the monetary amounts are appropriate for the given transaction type.

We automatically create a warehouse for each unknown senderAddress.

You need to provide all monetary amounts as gross values. If you provide a valid buyerVatNumber, we will handle the transaction as B2B. For transactions that are taxable before 2020, we will validate the buyerVatNumber with a simple regular expression. Starting from January 2020, we will check the buyerVatNumber against VIES in order to comply with the VAT Quick fixes. You can read more about that in our Blog (available in German and English).

The processing of submitted transactions / orders / refunds is delayed. The distance selling thresholds and reports of the current year and reporting period are usually updated on the next day. If the evaluation results of earlier years or reporting periods should be updated, please contact us.

If you add orders, refunds or transactions that would be taxable in any already closed period (i.e. we completed the reports for the period) the API returns a warning. We will not process transactions that are submitted too late until explicitly unlocked by us. It is important that you submit all transactions of a period until the 3rd of the following month, at 23:59.

Add Transactions

Example payload:

{
  "transactions": [
    {
      "type": "Sale",
      "channel": {
        "identifier": "EBY",
        "transactionNumber": "31415926",
        "itemNumber": "1234345"
      },
      "source": {
        "identifier": "PLTY",
        "transactionNumber": "7812378",
        "itemNumber": "9823490"
      },
      "paymentDate": "2017-04-05T14:03:55Z",
      "sentDate": "2017-04-05T14:35:41Z",
      "deliveryAddress": {
        "fullName": "John Johnson",
        "street": "Wall Street 3",
        "zip": "12345",
        "city": "Kings Landing",
        "state": "",
        "country": "DE"
      },
      "billingAddress": {
        "fullName": "Frank Smith",
        "street": "Ocean Drive 22",
        "zip": "12345",
        "city": "London",
        "state": "",
        "country": "PL"
      },
      "senderAddress": {
        "fullName": "Mustershop24",
        "street": "Westring 32",
        "zip": "987654",
        "city": "München",
        "state": "Bayern",
        "country": "DE"
      },
      "quantity": 2,
      "productIdentifier": "sku123",
      "description": "T-Shirt white",
      "transactionCurrency": "EUR",
      "itemPrice": 59.8
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Before you start, make sure you have read and understood the Transactions section.

Use this call to send us your transactions. Take care about sending us only completed orders, because updating transactions afterwards is much more costly and could violate the principles of proper accounting.

HTTP Request

POST /transactions

Request

Response

The response also includes fields from SimpleResponse.

Upload Csv Transactions

Example response:

{
  "status": "success",
  "insertedRows": 30
}

With this call you can upload csv files with our data schema. The first row must be the header. The columns are specified in the CsvTransaction model. The content-type header must equal "text/csv".

You can upload files with up to 5000 lines per call.

HTTP Request

POST /transactions/csv

Query Parameters

Request

Use the CSV as request body with rows fulfilling the schema CsvTransaction.

Response

The response also includes fields from SimpleResponse.

Get Transactions

Example response:

{
  "status": "success",
  "transactions": [
    {
      "type": "Sale",
      "channel": {
        "identifier": "EBY",
        "transactionNumber": "31415926",
        "itemNumber": "1234345"
      },
      "source": {
        "identifier": "PLTY",
        "transactionNumber": "7812378",
        "itemNumber": "9823490"
      },
      "paymentDate": "2017-04-05T14:03:55Z",
      "sentDate": "2017-04-05T14:35:41Z",
      "deliveryAddress": {
        "fullName": "John Johnson",
        "street": "Wall Street 3",
        "zip": "12345",
        "city": "Kings Landing",
        "state": "",
        "country": "DE"
      },
      "billingAddress": {
        "fullName": "Frank Smith",
        "street": "Ocean Drive 22",
        "zip": "12345",
        "city": "London",
        "state": "",
        "country": "PL"
      },
      "senderAddress": {
        "fullName": "Mustershop24",
        "street": "Westring 32",
        "zip": "987654",
        "city": "München",
        "state": "Bayern",
        "country": "DE"
      },
      "quantity": 2,
      "productIdentifier": "sku123",
      "description": "T-Shirt white",
      "transactionCurrency": "EUR",
      "itemPrice": 59.8
    }
  ]
}

Retrieve transactions by filter.

During the insertion of transactions, orders and refunds, the source and channel fields are transformed into primary and secondary fields. If only the channel object is provided, the fields from the channel are used as primary fields. Otherwise, the source fields are used as primary fields, while the channel fields are assigned to the secondary fields.

HTTP Request

GET /transactions

Query Parameters

Response

The response also includes fields from SimpleResponse.

Update Transactions

Example payload:

{
  "transactions": [
    {
      "id": 123,
      "type": "Sale",
      "channel": {
        "identifier": "EBY",
        "transactionNumber": "31415926",
        "itemNumber": "1234345"
      },
      "source": {
        "identifier": "PLTY",
        "transactionNumber": "7812378",
        "itemNumber": "9823490"
      },
      "paymentDate": "2017-04-05T14:03:55Z",
      "sentDate": "2017-04-05T14:35:41Z",
      "deliveryAddress": {
        "fullName": "John Johnson",
        "street": "Wall Street 3",
        "zip": "12345",
        "city": "Kings Landing",
        "state": "",
        "country": "DE"
      },
      "billingAddress": {
        "fullName": "Frank Smith",
        "street": "Ocean Drive 22",
        "zip": "12345",
        "city": "London",
        "state": "",
        "country": "PL"
      },
      "senderAddress": {
        "fullName": "Mustershop24",
        "street": "Westring 32",
        "zip": "987654",
        "city": "München",
        "state": "Bayern",
        "country": "DE"
      },
      "quantity": 2,
      "productIdentifier": "sku123",
      "description": "T-Shirt white",
      "transactionCurrency": "EUR",
      "itemPrice": 59.8
    }
  ]
}

Example response:

{
  "status": "success",
  "updatedRows": 30
}

Make sure that you have read and understood the Transactions section.

Use this call to update your transactions. The most common use case is converting a B2C to a B2B transaction by setting a buyerVatNumber.

Be careful with this call, as you could edit transactions of already closed periods.

Same payload as in the add transactions call, but the id of each transaction is required. All values of the transaction are overwritten by this call, therefore you must request the full transaction with GET /transactions before modifying it.

HTTP Request

PUT /transactions

Request

Response

The response also includes fields from SimpleResponse.

Delete Transactions

Example response:

{
  "status": "success",
  "deletedRows": 30
}

Make sure you have read and understood the Transactions section.

Use this call to delete transactions. We suggest you to not use this call within your daily workflow, as this indicates bad design. Do not use this call to remove transactions in case there has been a refund. Create a new refund instead.

We primarily intend this call to be used to remove transactions that have been transferred by accident, or to remove test transactions (especially from the sandbox).

This operation will fail if at least one transaction is within an already unlocked period.

Note that using this call can invalidate our distance selling threshold evaluations. If this could be the case, please contact our support.

The transaction IDs (for the ids parameter) can be retrieved using the GET /transactions call.

HTTP Request

DELETE /transactions

Query Parameters

Response

The response also includes fields from SimpleResponse.

Orders

An Order represents an order or a refund that a customer placed in your shop or one of your sale channels. Orders are internally converted to transactions so they are not retrievable. During the conversion all order-level amounts like shipping cost and gift wrap cost are allocated proportionally to the order items.

Using POST /orders over POST /transactions is especially more favorable when exporting data from an ERP software, as these often use an order-orderItem hierarchy with costs both on order and item level.

On this resource both sales and refunds are allowed. When handling refunds, many fields are ignored by our internal systems because they prefer fields from the underlying sale, like product_identifier, deliveryAddress, senderAddress and billingAddress.

The same note on refunds as in Transactions applies to this resource.

Add Orders

Example payload:

{
  "orders": [
    {
      "type": "Sale",
      "channel": {
        "identifier": "EBY",
        "transactionNumber": "63231231"
      },
      "source": {
        "identifier": "PLTY",
        "transactionNumber": "7812372138"
      },
      "paymentDate": "2017-04-05T14:03:55Z",
      "sentDate": "2017-04-05T14:35:41Z",
      "deliveryAddress": {
        "fullName": "John Johnson",
        "street": "Wall Street 3",
        "zip": "12345",
        "city": "Kings Landing",
        "state": "",
        "country": "DE"
      },
      "senderAddress": {
        "fullName": "Mustershop24",
        "street": "Westring 32",
        "zip": "987654",
        "city": "München",
        "state": "Bayern",
        "country": "DE"
      },
      "transactionCurrency": "EUR",
      "items": [
        {
          "quantity": 5,
          "productIdentifier": "sku123",
          "description": "Green biscuits Premium",
          "itemPrice": 50.2,
          "channelItemNumber": "22342",
          "sourceItemNumber": "2843928"
        },
        {
          "quantity": 1,
          "productIdentifier": "89283423",
          "description": "Charcoal 5kg",
          "itemPrice": 19.99,
          "channelItemNumber": "72384",
          "sourceItemNumber": "2843929"
        }
      ]
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Make sure that you have read and understood the Transactions section.

Use this call to send us your orders. Take care about sending us only completed orders.

HTTP Request

POST /orders

Request

Response

The response also includes fields from SimpleResponse.

Refunds

This is a convenience resource similar to Orders, but only allows refunds. This resource has a reduced set of required fields and is therefore preferred when handling sales and refunds differently on client-side.

The same note on refunds as in Transactions applies to this resource.

Add Refunds

Example payload:

{
  "refunds": [
    {
      "channel": {
        "identifier": "EBY",
        "transactionNumber": "63231231",
        "refundNumber": "112344"
      },
      "source": {
        "identifier": "PLTY",
        "transactionNumber": "7812372138",
        "refundNumber": "65831122"
      },
      "paymentDate": "2017-04-05T14:03:55Z",
      "transactionCurrency": "EUR",
      "items": [
        {
          "quantity": 5,
          "description": "Green biscuits Premium",
          "itemPrice": -50.2,
          "discount": 5.2,
          "channelItemNumber": "22342",
          "sourceItemNumber": "2843928"
        },
        {
          "quantity": 1,
          "description": "Charcoal 5kg",
          "itemPrice": -19.99,
          "channelItemNumber": "72384",
          "sourceItemNumber": "2843929"
        }
      ]
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Make sure that you have read and understood the Transactions section.

Use this call to send us your refunds. Take care about sending us only completed refunds.

Do not forget that the monetary amounts must be negative if a refund was issued to the customer.

HTTP Request

POST /refunds

Request

Response

The response also includes fields from SimpleResponse.

Movements

A movement represents the movement of goods between warehouses.

Similar to transactions, we identify movements by a set of identifiers from a MovementPlatform object. In contrary to transactions, there is just one platform object. We use this identifier set to avoid duplicates, i.e. inserting the same movement multiple times has the same effect as inserting it only once.
This allows you to push the same data multiple times into our API without having to worry about duplicates.

Get Movements

Example response:

{
  "status": "success",
  "movements": [
    {
      "id": 3909077,
      "sentDate": "2017-12-01T00:00:00.000Z",
      "arrivalDate": "2017-12-05T00:00:00.000Z",
      "platform": {
        "identifier": "AFN",
        "movementNumber": "980486868",
        "itemNumber": "12346",
        "itemPosition": 0
      },
      "senderAddress": {
        "id": 1,
        "amazonFulfillmentCenterId": "PRG1",
        "street": "Amazon Logistic Prague s.r.o. K Amazonu 235",
        "zip": "25261",
        "city": "Dobrovíz",
        "state": "Stredocesky kraj",
        "country": "CZ"
      },
      "deliveryAddress": {
        "id": 31,
        "amazonFulfillmentCenterId": "LTN4",
        "street": "Amazon.co.uk Unit DC1 (Prologis) Boscombe Road",
        "zip": "LU5 4FE",
        "city": "Dunstable",
        "state": "East of England",
        "country": "GB"
      },
      "quantity": 1,
      "weight": {
        "value": 84,
        "unit": "kg"
      },
      "commodityCode": "1111111111",
      "productIdentifier": "SKU-77967",
      "description": "Aerodynamische Stahl Messer",
      "purchaseCurrency": "EUR",
      "purchasePrice": 45.24,
      "results": {
        "departureCurrency": "CZK",
        "departureExchangeRate": 25.524,
        "departureTotalValue": 1154.71,
        "arrivalCurrency": "GBP",
        "arrivalExchangeRate": 0.8818,
        "arrivalTotalValue": 39.89
      },
      "inserted": "2018-06-01T14:35:14.000Z",
      "isValid": true
    }
  ]
}

Retrieves movements by filter.

HTTP Request

GET /movements

Query Parameters

Response

The response also includes fields from SimpleResponse.

Add Movements

Example payload:

{
  "movements": [
    {
      "sentDate": "2017-04-05T14:03:55Z",
      "arrivalDate": "2017-04-05T14:03:55Z",
      "platform": {
        "identifier": "AFN",
        "movementNumber": "2342-2223",
        "itemNumber": "1",
        "itemPosition": 0
      },
      "senderAddress": {
        "amazonFulfillmentCenterId": "PRG1"
      },
      "deliveryAddress": {
        "amazonFulfillmentCenterId": "HAM2"
      },
      "quantity": 1,
      "weight": {
        "unit": "kg",
        "value": 3
      },
      "productIdentifier": "SKU-12345",
      "commodityCode": "1234567890",
      "description": "Miniature fusion reactor",
      "purchasePrice": 30,
      "purchaseCurrency": "EUR"
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Before you start, make sure you have read and understood the Movements section.

You may submit movements (e.g. warehouse transfers) of goods using this endpoint. Note that we usually import FBA transactions directly from Amazon, so you do not need to submit us these. If you have your own warehouses or use a fulfillment service provider that is not supported by us, you can submit us the corresponding movements using this endpoint.

HTTP Request

POST /movements

Request

Response

The response also includes fields from SimpleResponse.

Products

Use this endpoint to map your product identifiers (e.g. sku) to the corresponding purchase prices and commodity codes (also called customs tariff number). Sending us your product details enables us to automatically match them with your orders, so you don't have to send us a csv file separately.

For each platform, we use the following fields as productIdentifier when importing transactions (this only applies to direct imports, e.g. Amazon sales that we import via the Plentymarkets API are imported with the variationId of Plentymarkets):

• Amazon: SellerSKU
• eBay: Sku (inventory reference identifier)
• Plentymarkets: The ID of the Variation
• JTL: cArtNr (Article Number)

There are two major reasons why we need product information:

• Amazon FBA movements: A mapping between Amazon SKU as productIdentifier and the purchase price is necessary for monthly filings
• Reduced tax rates: If you want us to apply reduced tax rates to your transactions, we may need a different productIdentifier for each platform. If we directly import data from Amazon, the Amazon SKU (like for movements) is sufficient.

Add Products

Example payload:

{
  "products": [
    {
      "description": "Couch Supreme red",
      "productIdentifier": "redcouch123",
      "commodityCode": "9394240000",
      "purchasePrice": 3200,
      "currency": "EUR"
    },
    {
      "description": "Wood table",
      "productIdentifier": "wt234bas",
      "commodityCode": "9394220000",
      "purchasePrice": 300,
      "currency": "EUR"
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Use this method to update data associated with your products. Posting products with product identifiers that already exist overwrites the existing entry.

HTTP Request

POST /products

Request

Response

The response also includes fields from SimpleResponse.

Upload Csv Products

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Use this call to upload your products with product identifiers and corresponding purchase prices as csv. The first row must be the header. The columns are exactly the same as the properties in the Product model. The content-type header must equal "text/csv".

You can pass the weight by using the columns weightValue and weightUnit and the supplementaryUnit by using the columns supplementaryValue and supplementaryUnit.

HTTP Request

POST /products/csv

Query Parameters

Request

Use the CSV as request body with rows fulfilling the schema CsvProduct.

Response

The response also includes fields from SimpleResponse.

Get Products

Example response:

{
  "status": "success",
  "products": [
    {
      "description": "Sessel in rot",
      "productIdentifier": "redcouch123",
      "commodityCode": "9394240000",
      "purchasePrice": 3200,
      "currency": "EUR"
    }
  ]
}

Returns all products of the current client.

The description and product_identifier params are exclusive, that means, no other query parameter is allowed if one of the exclusive query parameters is provided.

HTTP Request

GET /products

Query Parameters

Response

The response also includes fields from SimpleResponse.

Delete Products

Example response:

{
  "status": "success",
  "deletedRows": 30
}

Deletes products by their product_identifier. Deletion of multiple products at once is allowed. Please only use this call to delete test (fake) products or accidentally created products. Do not delete real products. If you wish to update existing product data, use the Add Products call instead.

HTTP Request

DELETE /products

Query Parameters

Response

The response also includes fields from SimpleResponse.

Set product tax rates

Example payload:

{
  "products": [
    {
      "productIdentifier": "sku1234",
      "rates": [
        {
          "country": "DE",
          "rateType": "standard_rate"
        },
        {
          "country": "PL",
          "rateType": "reduced_rate_1"
        },
        {
          "country": "BE",
          "rateType": "parking_rate"
        },
        {
          "country": "GB",
          "rateType": "zero_rate"
        }
      ]
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Updates the vat rates associated to a product. We assume the standard rate for all countries that are not set. We use placeholders like reduced_rate_1 for the vat rates (in case a country changes its vat rate). You can find the appropriate values in the Rate Types section.

The insertedCount of the response may be misleading. This is the raw value returned by our underlying database. E.g. for updated rows, 2 is returned instead of 1.

HTTP Request

POST /products/rates

Request

Response

The response also includes fields from SimpleResponse.

Get tax rates

Example response:

{
  "status": "success",
  "products": [
    {
      "commodityCode": "14569322323",
      "description": "Awesome sitting stone",
      "productIdentifier": "sku1234",
      "rates": [
        {
          "country": "DE",
          "rateType": "standard_rate",
          "value": 19
        },
        {
          "country": "PL",
          "rateType": "reduced_rate_1",
          "value": 8
        }
      ]
    }
  ]
}

Returns all tax rates for all products that have either a commodity code or an already set vat rate for one or more countries.

HTTP Request

GET /products/rates

Query Parameters

Response

The response also includes fields from SimpleResponse.

Client

Get client data

Example response:

{
  "status": "success",
  "legalName": "Merchant UG",
  "email": "info@bestshop.de",
  "created": "2017-04-05T14:35:41Z",
  "complianceActive": true,
  "address": {
    "fullName": "John Johnson",
    "street": "Wall Street 3",
    "zip": "12345",
    "city": "Kings Landing",
    "state": "",
    "country": "DE"
  }
}

Returns information about the current client.

HTTP Request

GET /client

Response

The response also includes fields from SimpleResponse.

Create a client

Example payload:

{
  "client": {
    "legalName": "Hans Riva e.K.",
    "entityType": "natural",
    "firstName": "Hans",
    "lastName": "Riva",
    "gender": "male",
    "countryOfBirth": "DE",
    "dateOfBirth": "2020-01-02",
    "companyAddress": {
      "street": "Weg 123",
      "state": "Redanien",
      "city": "Nowigrad",
      "zip": "123",
      "country": "DE"
    },
    "accounts": [
      {
        "email": "merchant@shop.de",
        "permissionLevel": "owner"
      },
      {
        "id": 12345,
        "permissionLevel": "employee"
      }
    ],
    "warehouses": [
      {
        "street": "Path of happiness 5",
        "state": "Scotland",
        "city": "Hogwarts",
        "zip": "99999",
        "country": "DE",
        "isStandard": true
      }
    ],
    "registrations": [
      {
        "country": "DE",
        "vatId": "DE123456789"
      }
    ]
  }
}

Example response:

{
  "status": "success",
  "clientId": 1111
}

This endpoint requires OAuth authentication.

A client represents a single merchant (i.e. legal entity) in our system. New clients can be created with this endpoint.

HTTP Request

POST /oauth/client

Request

Response

The response also includes fields from SimpleResponse.

Trigger onboarding

Example payload:

{
  "importStart": "2019-01-01T00:00:00Z",
  "platforms": [
    "Amazon",
    "Ebay",
    "JTL",
    "Afterbuy",
    "PlentyMarkets",
    "Shopify",
    "Actindo",
    "Billbee",
    "DreamRobot",
    "Xentral",
    "Cdiscount",
    "CSV"
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Signals that the initial imports were completed. This will trigger the initial processing of the submitted transaction data, and an email to the client with a preliminary overview of the results.

HTTP Request

POST /client/onboarding

Request

Response

The response also includes fields from SimpleResponse.

Addons

Retrieve active addons

Example response:

{
  "status": "success",
  "addons": [
    {
      "name": "datev",
      "firstPeriod": "2021-01",
      "lastPeriod": "9999-12"
    },
    {
      "name": "pro-forma",
      "firstPeriod": "2018-05",
      "lastPeriod": "2020-12"
    }
  ]
}

This endpoint requires OAuth authentication and the Client-Identifier header.

Returns a list of activated addons along with their time range. We use the period "9999-12" to indicate that the addon is active indefinitely.

HTTP Request

GET /oauth/addons

Response

The response also includes fields from SimpleResponse.

Activate addon

Example payload:

{
  "addon": {
    "name": "datev"
  }
}

Example response:

{
  "status": "success"
}

This endpoint requires OAuth authentication and the Client-Identifier header.

Use this endpoint to activate an addon. There may be only one active time range per addon at this time. Activating an addon that is already active is still possible, if the new time range is greater than the earlier time range. Otherwise, the request fails (i.e. you cannot deactivate an addon for a month where it was previously activated).

HTTP Request

POST /oauth/addons

Request

Response

Responds with a SimpleResponse.

Warehouses

With this endpoint you can manage your Warehouses. This simplifies using the POST Transactions and the POST Orders call, because you can simply provide a warehouse-id instead of the full SenderAddress.

A Merchant may only have one standard warehouse. The standard warehouse is important for some of our processes, e.g. it is displayed on pro-forma invoices.

Updating and removing warehouses is not allowed, as this could invalidate already processed transactions.

Add Warehouses

Example payload:

{
  "warehouses": [
    {
      "street": "Westring 32",
      "zip": "987654",
      "city": "München",
      "state": "Bayern",
      "country": "DE"
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Adds a warehouse. You can retrieve the id of the created warehouse afterwards via a GET /warehouses call.

HTTP Request

POST /warehouses

Request

Response

The response also includes fields from SimpleResponse.

Retrieve Warehouses

Example response:

{
  "status": "success",
  "warehouses": [
    {
      "id": 123,
      "street": "Westring 32",
      "zip": "987654",
      "city": "München",
      "state": "Bayern",
      "country": "DE"
    }
  ]
}

Returns all warehouse addresses of the current client.

HTTP Request

GET /warehouses

Response

The response also includes fields from SimpleResponse.

Registrations

Get registrations

Example response:

{
  "status": "success",
  "registrations": [
    {
      "country": "PL",
      "status": "completed",
      "vatId": "PL1234567890",
      "registrationDate": "2017-04-05T14:03:55Z"
    }
  ]
}

This resource returns information about your vat registration status for each country.

Currently only countries with the status "pending" or "completed" are returned. If the vat registration was not started for a country yet, it will not appear in the response.

HTTP Request

GET /registrations

Response

The response also includes fields from SimpleResponse.

Thresholds

Get threshold status

Example response:

{
  "status": "success",
  "thresholds": [
    {
      "year": 2017,
      "country": "AT",
      "value": 26251.32,
      "rateOfExceedance": 0.75,
      "isActive": true,
      "reason": "waiver",
      "activeFrom": "2016-04-018T12:34:56.000Z",
      "activeUntil": "9999-12-31T22:59:59.000Z"
    }
  ]
}

Returns the current threshold status for each country of the European Union in a specified year. Only countries are returned where the threshold value differs from zero, i.e. you sent an order there.

HTTP Request

GET /thresholds

Query Parameters

Response

The response also includes fields from SimpleResponse.

Summary

Get Period Summary

Example response:

{
  "status": "success",
  "preliminary": true,
  "summary": {
    "createdTime": "2018-06-01T09:30:43.377Z",
    "period": "2018-05",
    "taxes": [
      {
        "country": "AT",
        "currency": "EUR",
        "vatRate": 20,
        "count": 401,
        "net": 7371.06,
        "vat": 1474.64
      },
      {
        "country": "CZ",
        "currency": "CZK",
        "vatRate": 21,
        "count": 179,
        "net": 74023.14,
        "vat": 15544.9
      }
    ],
    "ecsales": [
      {
        "departureCountry": "CZ",
        "arrivalCountry": "DE",
        "currency": "CZK",
        "count": 24,
        "sum": 318347.39
      },
      {
        "departureCountry": "CZ",
        "arrivalCountry": "PL",
        "currency": "CZK",
        "count": 17,
        "sum": 244650.79
      }
    ],
    "ecpurchases": [
      {
        "departureCountry": "DE",
        "arrivalCountry": "CZ",
        "currency": "CZK",
        "count": 13,
        "sum": 154228.97
      },
      {
        "departureCountry": "DE",
        "arrivalCountry": "CZ",
        "currency": "CZK",
        "count": 13,
        "sum": 154228.97
      }
    ],
    "eu_sales": [
      {
        "country": "AT",
        "currency": "EUR",
        "count": 401,
        "sum": 8845.7
      },
      {
        "country": "CZ",
        "currency": "EUR",
        "count": 61,
        "sum": 1430.06
      }
    ],
    "export_sales": [
      {
        "country": "CZ",
        "currency": "CZK",
        "count": 77,
        "sum": 45348.82
      },
      {
        "country": "DE",
        "currency": "EUR",
        "count": 96,
        "sum": 2165.32
      }
    ],
    "platforms": [
      {
        "currency": "EUR",
        "primaryPlatform": "PLTY",
        "secondaryPlatform": "AFN",
        "sum": 15655.07,
        "count": 731
      },
      {
        "currency": "EUR",
        "primaryPlatform": "PLTY",
        "secondaryPlatform": "EBY",
        "sum": 15151.85,
        "count": 690
      }
    ],
    "b2b_sales": [
      {
        "departureCountry": "DE",
        "arrivalCountry": "FR",
        "currency": "EUR",
        "count": 5,
        "sum": 1255.97
      }
    ]
  }
}

Returns our summary of our findings for all transactions and movements within a specified period. The same information is displayed in our dashboard. The summary may show preliminary results.

All array fields in this data structure are aggregation results of sale, refund and movement data. The aggregated fields are always named sum, count, net and vat. All other fields in each aggregation are grouping fields.

The VAT facts mentioned in this documentation are documented in our Zendesk Help Center (only visible when logged in to the Taxdoo-Dashboard).

Note that for periods before the Brexit, GB is included in all aggregations with EU-scope. After the Brexit, GB may also be included in the aggregations with EU-scope, but will only refer to Northern Ireland.

In the following subsections the components of the summary are explained.

createdTime
The date-time where the summary was created (using RFC3339 format).

period
The period of the summary.

eu_countries_by_vat_fact
The newest and most flexible transaction summary for the EU scope. It includes all VAT facts. It is the result of an aggregation of the following values:

• taxCountry: The country of taxation
• departureCountry: The departure country
• arrivalCountry: The arrival country
• currency: The currency of the country of taxation
• taxRateType The VAT rate type to apply.
• vatRate: The VAT rate to apply corresponding to the taxRateType.
• vatFact: The VAT fact

The aggregated values are

• count: Number of transactions that were aggregated for this particular entry.
• net: The net sum.
• vat: The vat sum.

taxes
Owed VAT and net per country, currency and VAT rate. Before the introduction of the OSS, this included the payable VAT for each VAT rate in the respective country of taxation. Since the introduction of the OSS, this aggregation only includes the amounts to declare in local filings. This includes all transactions where the OSS is not applicable, such as domestic sales in the respective country. The values from this aggregation are used for the local filings.

ecsales
Intra-community supplies (EC Sales) per country pair and currency. This includes the outbound part of movements between Amazon warehouses, as well as VAT-exempt border-crossing B2B sales.

ecsales_no_b2b
Like ecsales, but without VAT-exempt border-crossing B2B sales.

ecpurchases
Intra-community purchases (EC Purchases) per country pair and currency. This includes the inbound part of movements between Amazon warehouses.

eu_sales
Sales and Refunds inside the EU combined per delivery country. The currency is the original order currency. Only for statistical purposes.

export_sales
Sales and Refunds leaving the EU combined per departure country. The currency is the currency in the departure country.

import_sales
Sales and Refunds from 3rd party countries to the EU aggregated by arrival country. The currency is the currency in the arrival country. This is a subset of taxes. Transactions that are reported via IOSS are not included.

platforms
Sales and Refunds combined per currency, primary and secondary platform. The currency is the original order currency, and the sum the gross amount. Only for statistical purposes. This statistic includes all processed transactions.

b2b_sales
VAT-exempt B2B Sales and Refunds. This is a subset of the ecsales statistic. Only for statistical purposes.

domestic_rc_sales
In some EU countries reverse charge applies under certain conditions. This aggregation only includes domestic B2B Sales and Refunds with the VAT fact B2B_DOMESTIC_RC.

domestic_rc_purchases
Domestic purchases where reverse charge is applied (usually commingling purchases via Amazon FBA).

taxable_purchases
Taxable purchases (usually commingling purchases via Amazon FBA).

purchases
Contains all purchases aggregated by departure and arrival country and by original currency. Includes the purchases of taxable_purchases and domestic_rc_purchases.

gb
This section contains a summary for the GB VAT evaluation results. This summary is only present for summaries after the Brexit. It contains the following fields:

gb.sales_taxable
Sales and Refunds taxable in the United Kingdom, aggregated by currency, vatRate and taxRateType (with the same meanings as in eu_countries_by_vat_fact).

gb.sales_exports
Sales and Refunds which are exports from the United Kingdom.

gb.sales_seller_imports
Sales and Refunds which are imports into the United Kingdom. The seller pays VAT.

gb.sales_marketplace_imports Sales and Refunds which are imports into the United Kingdom. The marketplace pays VAT. This also includes imports from 3rd party countries to Northern Ireland.

gb.sales_marketplace_domestic
Domestic Sales and Refunds within the United Kingdom. The marketplace pays VAT. This also includes domestic sales within Northern Ireland where the marketplace has to pay VAT.

gb.purchases_taxable
Taxable purchases (usually commingling purchases via Amazon FBA).

HTTP Request

GET /period-summary

Query Parameters

Response

The response also includes fields from SimpleResponse.

Report

Download Report

Example response:

{
  "preliminary": true,
  "status": "success",
  "url": "https://...",
  "expiresIn": 60
}

Returns a temporary link to download a report.

The following report types are allowed and can be downloaded:

• csv: The monthly CSV report
• excel: The monthly Excel report
• datev: The Datev export
• datev-payments: The Datev payments export
• oss: The quarterly OSS report
• ioss: The monthly IOSS report
• starting-balance : The existing starting balance and support files of accounting for existing customer in 2024

To download quarterly reports, supply the last month of the quarter as the period query parameter.

For the OSS and the IOSS reports, you may need to supply a country which has to match the country of establishment of your company at that time. If Taxdoo did not support your country of establishment at that time, you have to omit the country parameter. You will then be able to download our fallback Excel report.

If you get the error "Invalid input: report does not exist", this might have one of the following reasons:

• The report has not been generated yet
• If related to an addon: You have not booked the addon
• for OSS or IOSS reports: the supplied country is wrong

HTTP Request

GET /reports/download

Query Parameters

Response

The response also includes fields from SimpleResponse.

Filing

Contains endpoints to manage data related to filing.

OSS: Retrieve initial tax amounts

Example response:

{
  "status": "success",
  "amounts": [
    {
      "period": "2021-Q4",
      "reportCountry": "DE",
      "countryOfTaxation": "ES"
    },
    {
      "period": "2021-Q4",
      "reportCountry": "DE",
      "countryOfTaxation": "FR",
      "initialTaxAmount": 123.45
    }
  ]
}

In order to do corrections of periods where someone else than Taxdoo did OSS filings for the merchant, we need the amounts that were submitted for the OSS filing. With this endpoint you can retrieve the initial tax amounts per combination of year-quarter, report country and country of taxation. If the initialTaxAmount is missing for an entry, it needs to be populated.

HTTP Request

GET /filing/oss/initial-tax-amounts

Query Parameters

Response

The response also includes fields from SimpleResponse.

OSS: Submit initial tax amounts

Example payload:

{
  "amounts": [
    {
      "period": "2021-Q4",
      "reportCountry": "DE",
      "countryOfTaxation": "ES",
      "initialTaxAmount": 10.45
    },
    {
      "period": "2021-Q4",
      "reportCountry": "DE",
      "countryOfTaxation": "FR",
      "initialTaxAmount": 123.45
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

Allows submitting new initial tax amounts for the OSS filing. This endpoint supports both submitting new values as well as overwriting old values.

Please be aware that you cannot submit 2 entries with the same combination of period, reportCountry, countryOfTaxation because such entries would overwrite each other.

HTTP Request

POST /filing/oss/initial-tax-amounts

Request

Response

The response also includes fields from SimpleResponse.

GB: Retrieve filing prefill data

Example response:

{
  "status": "success",
  "prefillData": [
    {
      "period": "2022-02",
      "importTransfersPaidAtBorderNet": 100,
      "importTransfersPaidAtBorderVat": 20,
      "importTransfersPvaNet": 200,
      "importTransfersPvaVat": 40,
      "importSalesPvaNet": 50,
      "importSalesPvaVat": 60,
      "importSalesPaidAtBorderVat": 0,
      "importSalesPaidAtBorderNet": 0
    }
  ]
}

For the periodic filing on Great Britain after the Brexit a few figures are required that Taxdoo cannot determine automatically. The values need to be submitted either via the Taxdoo Dashboard, or via the Taxdoo API. You can retrieve previously saved entries via this endpoint. There will be at most one entry per month.

HTTP Request

GET /filing/gb/prefill-data

Query Parameters

Response

The response also includes fields from SimpleResponse.

GB: Submit filing prefill data

Example payload:

{
  "prefillData": [
    {
      "period": "2022-02",
      "importTransfersPaidAtBorderNet": 100,
      "importTransfersPaidAtBorderVat": 20,
      "importTransfersPvaNet": 200,
      "importTransfersPvaVat": 40,
      "importSalesPvaNet": 50,
      "importSalesPvaVat": 60,
      "importSalesPaidAtBorderVat": 0,
      "importSalesPaidAtBorderNet": 0,
      "markAsSubmitted": true
    },
    {
      "period": "2022-03",
      "importTransfersPaidAtBorderNet": 0,
      "importTransfersPaidAtBorderVat": 0,
      "importTransfersPvaNet": 10,
      "importTransfersPvaVat": 2,
      "importSalesPvaNet": 0.1,
      "importSalesPvaVat": 0.02,
      "importSalesPaidAtBorderVat": 0,
      "importSalesPaidAtBorderNet": 0
    }
  ]
}

Example response:

{
  "status": "success",
  "insertedRows": 30
}

For the periodic filing on Great Britain after the Brexit a few figures are required that Taxdoo cannot determine automatically. The values need to be submitted either via the Taxdoo Dashboard, or via the Taxdoo API.

You can save new entries with this endpoint. Once an entry is marked as submitted, it cannot be altered anymore. As of now we also use entries for the filing report creation even if they are not marked as submitted. We may change that to only use an entry if it is marked as submitted.

There must be always only one entry per period. If you transmit an entry for a period that was already saved earlier, it will get overwritten if it is not marked as submitted. The write operation will fail if for one of the supplied entries there is already an entry with the same period in our system that is marked as submitted.

HTTP Request

POST /filing/gb/prefill-data

Request

Response

The response also includes fields from SimpleResponse.

Models

Required fields are bold.

Addon

{
  "name": "datev"
}

{
  "name": "datev",
  "firstPeriod": "2020-01",
  "lastPeriod": "2020-12"
}

Addon schema

Address

{
  "fullName": "John Johnson",
  "street": "Wall Street 3",
  "zip": "12345",
  "city": "Kings Landing",
  "state": "",
  "country": "DE"
}

Represents an address.

CountryRegistrationStatus

{
  "country": "PL",
  "status": "completed",
  "vatId": "PL1234567890",
  "registrationDate": "2017-04-05T14:03:55Z"
}

Describes the vat registration status for a merchant in a country. Either vatId or taxNumber are required.

CountryTaxRate

{
  "country": "DE",
  "rateType": "standard_rate",
  "value": 19,
  "proposedRateType": "reduced_rate_1",
  "proposedValue": 7
}

Describes the currently applied tax rate on a product for a country, along with a proposal for the tax rate according to the commodity code. Objects of this type only appear inside objects to which they refer to, e.g. ProductTaxRates.

CountryThresholdStatus

{
  "country": "AT",
  "year": 2017,
  "value": 26251.32,
  "rateOfExceedance": 0.75,
  "isActive": true,
  "reason": "waiver",
  "activeFrom": "2016-04-018T12:34:56.000Z",
  "activeUntil": "9999-12-31T22:59:59.000Z"
}

Represents the current distance selling threshold status of a merchant for this country. When we consider a threshold of a country as active, all orders that are sent into the country are taxable there.

CsvProduct

{
  "description": "Sessel in rot",
  "productIdentifier": "redcouch123",
  "commodityCode": "9394240000",
  "purchasePrice": 330.3,
  "currency": "EUR"
}

Describe a product offered in your shop.

CsvTransaction

Describes the columns for a csv transaction as used in the Post Csv Transactions call. For sales, one of paymentDate and sentDate is required. For refunds, the paymentDate is required, and the sentDate is ignored.

FulfillmentCenter

{
  "type": "amazon",
  "code": "PRG1"
}

A fulfillment center

GbFilingPrefillData

{
  "period": "2022-02",
  "importTransfersPaidAtBorderNet": 100,
  "importTransfersPaidAtBorderVat": 20,
  "importTransfersPvaNet": 200,
  "importTransfersPvaVat": 40,
  "importSalesPvaNet": 50,
  "importSalesPvaVat": 60,
  "importSalesPaidAtBorderVat": 0,
  "importSalesPaidAtBorderNet": 0,
  "submittedTime": "2022-03-02T12:34:56Z"
}

{
  "period": "2022-03",
  "importTransfersPaidAtBorderNet": 0,
  "importTransfersPaidAtBorderVat": 0,
  "importTransfersPvaNet": 10,
  "importTransfersPvaVat": 2,
  "importSalesPvaNet": 0.1,
  "importSalesPvaVat": 0.02,
  "importSalesPaidAtBorderVat": 0,
  "importSalesPaidAtBorderNet": 0
}

Customer-provided data that is required for GB filing after the Brexit

IossRegistration

{
  "dateOfConfirmation": "2021-09-05T14:03:55Z",
  "id": "IM1234567890"
}

{
  "from": "2022-01",
  "dateOfConfirmation": "2022-03-05T14:03:55Z",
  "id": "IM9999999999"
}

Describes a registration for the Import One-Stop-Shop of the European Union. The country is always the country of residence of the merchant.

LogMessage

{
  "level": "error",
  "message": "unknown amazon fulfillment center code 'ABC9'",
  "code": 1010
}

A message with an error level.

Movement

{
  "sentDate": "2017-04-05T14:03:55Z",
  "arrivalDate": "2017-04-05T14:03:55Z",
  "platform": {
    "identifier": "AFN",
    "movementNumber": "12345",
    "itemNumber": "2342"
  },
  "senderAddress": {
    "amazonFulfillmentCenterId": "PRG1"
  },
  "deliveryAddress": {
    "amazonFulfillmentCenterId": "HAM1"
  },
  "quantity": 1,
  "weight": {
    "unit": "kg",
    "value": 3
  },
  "productIdentifier": "sku123",
  "commodityCode": "111111111",
  "description": "test item",
  "purchasePrice": 30,
  "purchaseCurrency": "EUR"
}

Represents a movement in general. There are 4 types of Movements: Import, Export, Transfer and Supply. Import denotes an import from a 3rd party country into the EU, export denotes an export from the EU into a 3rd party country and supply denotes a border-crossing B2B delivery inside the EU. A transfer is a movement of goods between warehouses, mostly FBA warehouses. Import, export and supply movements are created from transactions with the corresponding properties.

MovementPlatform

{
  "identifier": "EBY",
  "movementNumber": "31415926",
  "itemNumber": "1234345"
}

Describes platform-specific data that belongs to a movement. The platform can be a marketplace like Amazon, or other fulfillment providers.

MovementTaxInfo

{
  "departureCurrency": "EUR",
  "departureExchangeRate": 1,
  "departureTotalValue": 3.74,
  "arrivalCurrency": "CZK",
  "arrivalExchangeRate": 25.542,
  "arrivalTotalValue": 95.53
}

Tax Information for a movement. Note that the information in this object is calculated by us and not modifiable.

Order

{
  "type": "Sale",
  "channel": {
    "identifier": "EBY",
    "transactionNumber": "63231231"
  },
  "source": {
    "identifier": "PLTY",
    "transactionNumber": "7812372138"
  },
  "paymentDate": "2017-04-05T14:03:55Z",
  "sentDate": "2017-04-05T14:35:41Z",
  "deliveryAddress": {
    "fullName": "John Johnson",
    "street": "Wall Street 3",
    "zip": "12345",
    "city": "Kings Landing",
    "state": "",
    "country": "DE"
  },
  "senderAddress": {
    "fullName": "Mustershop24",
    "street": "Westring 32",
    "zip": "987654",
    "city": "München",
    "state": "Bayern",
    "country": "DE"
  },
  "transactionCurrency": "EUR",
  "items": [
    {
      "quantity": 5,
      "productIdentifier": "sku123",
      "description": "Green biscuits Premium",
      "itemPrice": 50.2,
      "discount": 5.2,
      "channelItemNumber": "22342",
      "sourceItemNumber": "2843928"
    },
    {
      "quantity": 1,
      "productIdentifier": "89283423",
      "description": "Charcoal 5kg",
      "itemPrice": 19.99,
      "channelItemNumber": "72384",
      "sourceItemNumber": "2843929"
    }
  ],
  "paymentChannel": "paypal",
  "paymentNumber": "123456789",
  "marketplaceCountry": "DE"
}

An order with one or multiple order items. For sales, one of paymentDate and sentDate is required. For refunds, the paymentDate is required, and the sentDate is ignored.

OrderItem

{
  "quantity": 5,
  "productIdentifier": "sku123",
  "description": "Green biscuits Premium",
  "itemPrice": 50.2,
  "channelItemNumber": "22342",
  "sourceItemNumber": "2843928",
  "marketplaceCountry": "DE"
}

An order item within an order. Either sourceItemNumber or channelItemNumber is required (please provide them accordingly to the source and channel objects on the order)

OssInitialTaxAmount

{
  "period": "2021-Q4",
  "reportCountry": "DE",
  "countryOfTaxation": "ES"
}