NAV Navbar
json

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, we respond with a ValidationError with more 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.

Then get an API token:

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:

Some other possible actions on our API:

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:

Our current rate limits are:

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:

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 except the login call. You can get this token from your dashboard, or by using the login call. The key has a maximum length of 1024 chars.

The token must be provided within the AuthToken header:

AuthToken: <Token>

If you use a token obtained from a login call, the token must be prefixed with SESSIONTOKEN:

AuthToken: SESSIONTOKEN <Token>

About our keys

Our API can be used with two types of keys:

Login

Example payload:

{
  "username": "user123",
  "password": "swordfish",
  "loginToken": "123456"
}

Example response:

{
  "status": "success",
  "token": "b1ea09a58035714d5ff0ea5ab439259b7854a71b5a83cebab026d7d0988c087b5bab406506923d[...]",
  "clients": [
    {
      "name": "Global Merchant GmbH",
      "identifier": "seller123",
      "permissionLevel": 3
    }
  ]
}

Use this call to obtain a short-duration API key. This is the one and only call that does not require the AuthToken header.

We use 2-factor authentication with the standard username/password combination and an additional time-based one-time password (TOTP) generated by the Time-based One-time Password Algorithm as specified in RFC 6238.

The TOTP can be generated using the Google Authenticator App which is available for free in the play store and also used by Google and Amazon for the login to some of their services.

If the 2-factor authentication is not set up yet, you can leave the loginToken field empty. The API then returns a tokenCode field, which contains a data URI for a QR Code image. Scan the image with the Google Authenticator App. Afterwards, you must confirm the 2-factor authentication on the next login with one generated TOTP provided in the loginToken field. The API returns a new QR Code image every time the loginToken field is empty until the 2-factor authentication is confirmed.

Once the 2-factor authentication is set up, you must provide a valid TOTP in the field loginToken on each call.

Only one login per account is possible at a time i.e. only one session token is valid.

HTTP Request

POST https://api.taxdoo.com/login

Payload

Field Type Description Constraints
username string The username of the authenticating user. ≥ 5 chars
password string The associated password ≥ 5 chars
loginToken string The time-based one-time password generated using the algorithm specified in RFC6238.

Response

Field Type Description Constraints
status string Status code. Can be either "success" or "fail". success, fail
token string The session token to use for the next requests. Is valid for 24 hours.
errors LogMessage[] An Array of warnings and errors that occurred during the operation.
clients ClientPermissionsInfo[] The list of clients this account has permissions on along with the permission level.
tokenCode string The QR Code as date URI the user should scan with the Google Authenticator app. Is only supplied when setup of 2-factor-authentication is necessary.

Get current account

Example response:

{
  "account": "info@sellermail.de"
}

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

HTTP Request

GET https://api.taxdoo.com/account

Payload

No parameters required.

Response

Field Type Description
account string the email of the account your token belongs to

Transactions

A transaction represents the sale or the refund of one or multiple products of one single product type. A transactions 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. And this 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.

If you provide a valid buyerVatNumber, we automatically handle the transactions as B2B and assume that all provided monetary amounts are net values. If the buyerVatNumber is empty or invalid, the monetary amounts are handled as gross values (the validation is done with a simple regular expression).

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.

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.80
    }
  ]
}

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 https://api.taxdoo.com/transactions

Payload

Field Type Description Limit
transactions Transaction[] Array of Transactions. 1000

Response

This call answers with a PostDataResponse, or a ValidationErrorResponse on validation error.

Upload Csv Transactions

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".

HTTP Request

POST https://api.taxdoo.com/transactions/csv

Query Parameters

Field Type Description
delimiter string the delimiter of your CSV file (defaults to ";")

Payload

Simple use the contents of your csv file as the payload. The columns must match the ones in the CsvTransaction model.

Response

This call answers with a PostDataResponse, or a ValidationErrorResponse on validation error.

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.80
    }
  ]
}

Retrieve transactions by filter.

HTTP Request

GET https://api.taxdoo.com/transactions

Query Parameters

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.

Field Type Description Constraints
primary_platform string The primary platform identifier, e.g. AFN/MFN for Amazon or PLTY for Plentymarkets (See Platform Abbreviations) ≤ 10 chars
primary_transaction_number string The transaction number of the primary platform only in combination with primary_platform
primary_refund_number string The refund number of the primary platform. Please use this in combination with primary_transaction_number, as it is significantly faster only in combination with primary_platform
secondary_platform string The secondary platform identifier, e.g. AFN/MFN for Amazon or EBY for eBay (See Platform Abbreviations) ≤ 10 chars
secondary_transaction_number string The transaction number of the secondary platform only in combination with secondary_platform
secondary_refund_number string The refund number of the secondary platform. Please use this in combination with secondary_transaction_number, as it is significantly faster only in combination with secondary_platform
payment_date_from string Returns only transactions which where paid after the specified date-time. Use [RFC3339] format. date-time
payment_date_until string Returns only transactions which where paid before the specified date-time. Use [RFC3339] format. date-time
sent_date_from string Returns only transactions which where sent after the specified date-time. Use [RFC3339] format. date-time
sent_date_until string Returns only transactions which where sent before the specified date-time. Use [RFC3339] format. date-time
inserted_from string Returns only transactions which where inserted after the specified date-time. Use [RFC3339] format. date-time
calculated_from string Returns only transactions for which our results were calculated exactly on or after the specified date-time (>=). Use [RFC3339] format. Only allowed in combination with the with_results param. date-time
calculated_until string Returns only transactions for which our results were calculated before the specified date-time. Use [RFC3339] format. Only allowed in combination with the with_results param. date-time
type string Filter by the transaction type. Sale or Refund
period string Only transactions where the tax date is within the specified period are returned. Only allowed in combination with the with_results param. No other date params must be set to use this param. period (like 2018-01)
tax_country string Only transactions which are taxable in the specified country are returned. Only allowed in combination with the with_results param. 2 chars
with_results boolean If true, the results of our analysis are returned true or false
valid boolean If set, only transactions with the isValid field set to this value are returned. true or false
limit int The maximum number of items to display. Smaller value results in faster response. 1-100
page int The page to retrieve. 1-1000

Response

Field Type Description
transactions Transaction[] An array of Transaction matching the filters.

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.80
    }
  ]
}

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.

HTTP Request

PUT https://api.taxdoo.com/transactions

Payload

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.

Field Type Description Limit
transactions Transaction[] Array of Transactions. 1000

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"
        }
      ]
    }
  ]
}

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 https://api.taxdoo.com/orders

Payload

Field Type Description Limit
orders Order[] An array of Order objects 1000

Response

This call answers with a PostDataResponse, or a ValidationErrorResponse on validation error.

Add Orders for invoicing

This call behaves exactly like the POST /orders, but gives you immediate information about invoicing. You can match your provided Orders with the response by the channel and source Platform, and the order items by their channelItemNumber and sourceItemNumber.

HTTP Request

POST https://api.taxdoo.com/orders/invoicing

Payload

Field Type Description Limit
orders Order[] An array of Order objects 10

Response

This call answers with a OrderInvoicingResponse, or a ValidationErrorResponse on validation error.

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,
          "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"
        }
      ]
    }
  ]
}

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 https://api.taxdoo.com/refunds

Payload

Field Type Description Limit
refunds Refund[] An array of Refund objects 1000

Response

This call answers with a PostDataResponse, or a ValidationErrorResponse on validation error.

Movements

This endpoint is used for movement handling. Movements available here were either retrieved from Amazon API or created from transactions.

We create movements from transactions in the following cases:

Movements of type TRANSFER are imported directly from Amazon and represent the border-crossing intra-community movements of goods by Amazon.

Get Movements

Example response:

{
    "status": "success",
    "movements": [
        {
            "id": 3909077,
            "type": "TRANSFER",
            "sentDate": "2017-12-01T00:00:00.000Z",
            "arrivalDate": "2017-12-05T00:00:00.000Z",
            "movementNumber": "980486868",
            "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.000",
                "unit": "kg"
            },
            "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 https://api.taxdoo.com/movements

Query Parameters

Field Type Description Constraints
sent_date_from string Returns only movements which where sent after the specified date-time. Use [RFC3339] format. date-time
sent_date_until string Returns only movements which where sent before the specified date-time. Use [RFC3339] format. date-time
arrival_date_from string Returns only movements which arrived after the specified date-time. Use [RFC3339] format. date-time
arrival_date_until string Returns only movements which arrived before the specified date-time. Use [RFC3339] format. date-time
inserted_from string Returns only transactions which where inserted after the specified date-time. Use [RFC3339] format. date-time
inserted_until string Returns only transactions which where inserted before the specified date-time. Use [RFC3339] format. date-time
type string Filter by the movement type. transfer, import, export, supply
valid boolean If set, only movements with the specified isValid value are returned. true or false
period string Only movements where the arrivalDate (for transfers) or the departureDate (for import, export, supply) is within the specified period are returned period (like 2018-01)
country string If set, only movements are returned were either the departure or the arrival country equals the provided value 2 chars
limit int The maximum number of items to display. Smaller value results in faster response. 1-100
page int The page to retrieve. 1-1000

Response

Field Type Description
movements Movement[] An array of Movement matching the filters.

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):

There are two major reasons why we need product information:

Add Products

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

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"
    }
  ]
}

HTTP Request

POST https://api.taxdoo.com/products

Payload

Field Type Description
products Product[] An array of Products

Response

This call answers with a PostDataResponse, or a ValidationErrorResponse on validation error.

Upload Csv Products

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.

HTTP Request

POST https://api.taxdoo.com/products/csv

Query Parameters

Field Type Description
delimiter string the delimiter of your CSV file (defaults to ";")

Payload

Simple use the contents of your csv file as the payload. The columns must match the ones in the Product model.

Response

This call answers with a PostDataResponse, or a ValidationErrorResponse on validation error.

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.

HTTP Request

GET https://api.taxdoo.com/products/

Query Parameters

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.

Field Type Description Constraints
description string Returns only products that contain the specified string in its description. exclusive
product_identifier string Returns only products that contain the specified string in its product identifier. exclusive
invalid_commodity_code boolean If true, only products with invalid commodity code are returned. true or false
missing_commodity_code boolean If true, only products without a commodity code are returned. true or false

Response

Field Type Description Constraints
products Product[] Array of Products

Delete Products

Example response:

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

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 https://api.taxdoo.com/products

Query Parameters

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.

Field Type Description
product_identifiers string-array Specifies the products to delete. Multiple values must be separated by comma (,). Do not forget to use URI encoding if you use special chars.

Response

This call answers with a DeleteDataResponse.

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"
        }
      ]
    }
  ]
}

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.

HTTP Request

POST https://api.taxdoo.com/products/rates

Payload

Field Type Description Constraints
products ProductTaxRates[] An array of ProductTaxRates

Response

This call answers with a PostDataResponse, or a ValidationErrorResponse on validation error. The insertedCount of the PostDataResponse may be misleading. This is the raw value returned by our underlying database. E.g. for updated rows, 2 is returned instead of 1.

Get tax rates

Example response:

{
  "productIdentifier": "sku1234",
  "commodityCode": "14569322323",
  "rates": [
    {
      "country": "DE",
      "rateType": "standard",
      "value": 19
    },
    {
      "country": "PL",
      "rateType": "standard",
      "value": 23,
      "proposedRateType": "reduced",
      "proposedValue": 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 https://api.taxdoo.com/products/rates

Response

Field Type Description Constraints
products ProductTaxRates[] Array of Products with tax rates

Client

Get client data

Example response:

{
  "status": "success",
  "legalName": "Merchant UG",
  "email": "info@bestshop.de",
  "created": "2017-04-05T14:35:41Z",
  "complianceActive": true
}

Returns information about the current client.

HTTP Request

GET https://api.taxdoo.com/client

Response fields

Field Type Description Constraints
legalName string The legal name of the client
email string The email address of the client
created string The date and time the Client was created. date-time
complianceActive boolean True if the client is an active customer. true or false

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"
    }
  ]
}

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

HTTP Request

POST https://api.taxdoo.com/warehouses

Payload

Field Type Description
warehouses SenderAddress[] An array of SenderAddress

Retrieve Warehouses

Example response:

{
  "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 https://api.taxdoo.com/warehouses

Payload

Field Type Description
warehouses SenderAddress[] An array of SenderAddress

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.

HTTP Request

GET https://api.taxdoo.com/registrations

Response

Field Type Description
registrations CountryRegistrationStatus[] An array of CountryRegistrationStatus

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.

Thresholds

Get threshold status

Example response:

 {
  "status": "success",
  "thresholds": [
    {
      "year": "2017",
      "country": "AT",
      "value": "26251.32",
      "rateOfExceedance": "0.75",
      "dateOfExceedance": null,
      "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 https://api.taxdoo.com/thresholds

Query Parameters

Field Type Description
year integer the year of the thresholds

Response

Field Type Description
thresholds CountryThresholdStatus[] An array of CountryThresholdStatus

Summary

Get Period Summary

Example response payload (shortened):

{
    "status": "success",
    "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 probably shows preliminary results.

It contains the following fields:

Field Description
createdTime The date-time where the summary was created (using [RFC3339] format).
period The period of the summary.
taxes Owed VAT and net per country, currency and VAT rate.
ecsales Intra-community supplies (either from transfers or b2b sales) per country pair and currency.
ecpurchases Intra-community purchases (from transfers) per country pair and currency.
eu_sales Sales and Refunds inside of the EU combined per delivery country. Only for statistical purposes.
export_sales Sales and Refunds leaving the EU combined per departure country.
platforms Sales and Refunds combined per currency, primary and secondary platform. Only for statistical purposes.
b2b_sales B2B Sales and Refunds per country pair and currency combined (is included in ecsales). Only for statistical purposes.

HTTP Request

GET https://api.taxdoo.com/period-summary

Query Parameters

Field Type Description Format
period string The period for which the summary is requested. Is required. YYYY-MM (e.g. 2018-05)

Response

Field Type Description
summary object The summary. The structure is not final and may be changed in the future.

Models

Required fields are bold.

Address

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

Represents an address.

Field Type Description Constraints
fullName string The full name of the address owner. ≤ 100 chars
street string Street field of the address. ≤ 200 chars
zip string Postal code ≤ 15 chars
city string City ≤ 100 chars
state string State ≤ 50 chars
country string Country as 2-letter ISO-3166 code iso-country

ClientPermissionsInfo

{
  "identifier": "seller123",
  "name": "Global Merchant GmbH",
  "permissionLevel": 2
}

Describes a client associated with permissions.

Field Type Description Constraints
name string The legal name of the client.
identifier string An unique identifier of the client.
permissionLevel number The associated permission level. 1 is the owner, 2 and 3 are more restricted. We will use the permission level more in the future.
clientId number The numeric id for the client

CountryTaxRate

{
  "country": "DE",
  "rateType": "standard",
  "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.

Field Type Description Constraints
country string Country as 2-letter ISO-3166 code iso-country
rateType string The type of the tax rate standard_rate, zero_rate, parking_rate, reduced_rate_1, reduced_rate_2, super_reduced_rate
value number The tax rate according to the rateType in the country. Ignored on any POST request.
proposedRateType string The type of the tax rate as derived from the commodity code. Ignored on any POST request. standard_rate, zero_rate, parking_rate, reduced_rate_1, reduced_rate_2, super_reduced_rate
proposedValue number The tax rate according to the proposedRateType in the country. Ignored on any POST request.

CountryThresholdStatus

{
  "country": "AT",
  "year": "2017",
  "value": "26251.32",
  "rateOfExceedance": "0.75",
  "dateOfExceedance": null,
  "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.

Field Type Description Constraints
country string Country as 2-letter ISO-3166 code ≤ 2 chars
year integer The year of the threshold level.
value number The current threshold value in the currency of the country.
rateOfExceedance number The current rate of exceedance of the distance selling threshold in the country for the current year.
dateOfExceedance string The date and time when the distance selling threshold was exceeded in the current year. That means, this property is still set if the threshold was waived or exceeded in the year before. Only set when the rateOfExceedance is equal or greater than one. date-time
isActive boolean True if the distance selling threshold is active, e.g. by exceedance or waiver. true or false
reason string Only set when isActive is true. Displays the reason why the threshold is active. waiver, exceedance, registration
activeFrom string The date and time when the distance selling threshold was activated. Only set when isActive is true. date-time
activeUntil string The date and time until the distance selling threshold is active. Only set when isActive is true. date-time

CsvTransaction

Describes the columns for a csv transaction as used in the Post Csv Transactions call.

Field Description Constraints
type The type of this transaction. Use one of the preset values. Sale, Refund
channelIdentifier The identifier of the platform. You can find possible values here. 2-8 chars
channelMerchantId ignored ≤ 100 chars
channelTransactionNumber The identifier for the transaction on this platform. If the transaction is a refund, use the id of the underlying order. ≤ 100 chars
channelRefundNumber If the transaction is a refund, put in the refund identifier here. ≤ 100 chars
channelItemNumber The number of the item within the transaction. ≤ 100 chars
sourceIdentifier The identifier of the platform. Link here 2-8 chars
sourceMerchantId The id of the merchant on this platform. Not necessary for your own Webshop. ≤ 100 chars
sourceTransactionNumber The identifier for the transaction on this platform. If the transaction is a refund, use the id of the underlying order. ≤ 100 chars
sourceRefundNumber If the transaction is a refund, put in the refund identifier here. ≤ 100 chars
sourceItemNumber The number of the item within the transaction. ≤ 100 chars
paymentDate The date and time of the payment. Use RFC3339 format. date-time
sentDate The date and time where the items were shipped. Use RFC3339 format. date-time
arrivalDate The date and time of arrival. Use RFC3339 format. date-time
deliveryFullName The full name of the address owner. ≤ 150 chars
deliveryStreet1 Street field number 1. Only the first one is required, others are optional. ≤ 100 chars
deliveryStreet2 Street field number 2 ≤ 100 chars
deliveryStreet3 Street field number 3 ≤ 100 chars
deliveryStreet4 Street field number 4 ≤ 100 chars
deliveryZip Postal code ≤ 10 chars
deliveryCity City ≤ 50 chars
deliveryState State ≤ 50 chars
deliveryCountry Country as 2-letter ISO-3166 code ≤ 2 chars
billingFullName The full name of the address owner. ≤ 100 chars
billingStreet1 Street field number 1. Only the first one is required, others are optional. ≤ 100 chars
billingStreet2 Street field number 2 ≤ 100 chars
billingStreet3 Street field number 3 ≤ 100 chars
billingStreet4 Street field number 4 ≤ 100 chars
billingZip Postal code ≤ 10 chars
billingCity City ≤ 50 chars
billingState State ≤ 50 chars
billingCountry Country as 2-letter ISO-3166 code ≤ 2 chars
senderStreet1 Street field number 1. Only the first one is required, others are optional. ≤ 100 chars
senderStreet2 Street field number 2 ≤ 100 chars
senderStreet3 Street field number 3 ≤ 100 chars
senderStreet4 Street field number 4 ≤ 100 chars
senderZip Postal code ≤ 10 chars
senderCity City ≤ 50 chars
senderState State ≤ 50 chars
senderCountry Country as 2-letter ISO-3166 code ≤ 2 chars
buyerVatNumber The VAT number of the buyer. If provided and valid (checked by regex), we process the transaction as B2B transaction. ≤ 15 chars
buyerEmail The Email address of the buyer. ≤ 50 chars
quantity The quantity of the item of this transaction.
weight The weight of the whole package.
productIdentifier An identifier that identifies the product, e.g. your SKU. You are strongly encouraged to use the same product identifier for the same product across all channels. ≤ 50 chars
description A title describing the article. ≤ 250 chars
commodityCode The Customs Tariff Number of the product. ≤ 10 chars
transactionCurrency The currency of the order as 3-digit ISO-4217 code. All monetary amounts must have this currency. ≤ 3 chars
itemPrice The total price of items of this transaction. This equals to the price per item multiplied with the quantity.
itemDiscount Total discount on items.
shipping Total shipping cost.
shippingDiscount Total discount on shipping.
giftWrap Total gift wrap cost.
giftWrapDiscount Total discount on gift wrap.
goodWillRefund Refund the merchant gave to their customer due to kindness?
trackingNumber The number to track the package. ≤ 50 chars
invoiceNumber The number of the invoice. ≤ 50 chars
invoiceDate The date and time where the invoice was sent. Use RFC3339 format. date-time

DeleteDataResponse

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

Describes the payload for an delete anything request.

Field Type Description Constraints
status string Status code. Can be either "success" or "fail". success, fail
deletedRows number The number of deleted rows.
errors LogMessage[] An Array of warnings and errors that appeared during the operation.

InvoicingResponseOrderItem

{
  "net": 100,
  "vat": 19,
  "rateType": "standard_rate",
  "vatRate": 19,
  "taxCountry": "DE",
  "sellerVatId": "DE999999999",
  "sourceItemNumber": "12345",
  "channelItemNumber": "12345"
}

Invoicing information for an order item.

Field Type Description Constraints
net number The net value of this order item.
vat number The VAT amount of this order item.
rateType string The rate type that applies to this order item.
vatRate number The actual VAT rate.
taxCountry string The country of taxation of this order item as 2-letter ISO-3166 code.
sellerVatId string The VAT ID of the seller within the taxCountry. Is empty if the seller has no VAT ID in the taxCountry.
sourceItemNumber string The source item number. Equals the sourceItemNumber on the provided OrderItem. ≤ 500 chars
channelItemNumber string The channel item number. Equals the channelItemNumber on the provided OrderItem. ≤ 500 chars

InvoicingResponseOrder

{
  "channel": {
    "identifier": "EBY",
    "transactionNumber": "63231231"
  },
  "source": {
    "identifier": "PLTY",
    "transactionNumber": "7812372138"
  },
  "items": [
    {
      "net": 100,
      "vat": 19,
      "rateType": "standard_rate",
      "vatRate": 19,
      "taxCountry": "DE",
      "sellerVatId": "DE999999999",
      "sourceItemNumber": "12345",
      "channelItemNumber": "12345"
    }
  ],
  "currency": "EUR",
  "isEUExport": false,
  "isEUImport": false,
  "isB2b": false,
  "isTargetingSpecialTerritory": false
}

Invoicing information for an order.

Field Type Description Constraints
channel Platform Channel platform of the provided order.
source Platform Source platform of the provided order.
items InvoicingResponseOrderItem[] Array of invoicing information for order items
currency string The currency of all monetary amounts in this order as 3-digit ISO-4217 code. Equals the transactionCurrency on the provided order.
isEUExport boolean True if this order's destination is outside of the EU or enters a special territory for which deliveries should be treated as an export. true or false
isEUImport boolean True if this order enters the EU from any 3rd party country. true or false
isB2B boolean True if the VAT id provided in the original order's buyerVatNumber field is valid (checked by a simple regex). true or false
isTargetingSpecialTerritory boolean True if this order's destination is a special territory. The transaction is treated as an export (e.g., Helgoland, Germany) or as a transaction liable for VAT in another EU country (e.g., Isle of Man). true or false

LogMessage

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

A message with an error level.

Field Type Description Constraints
level string The error level of this message, e.g. error, warning or info
message string The actual message.
code integer A numeric code representing the message. Only for localization purposes.

Movement

{
  "sentDate": "2017-04-05T14:03:55Z",
  "arrivalDate": "2017-04-05T14:03:55Z",
  "movementNumber": "12345",
  "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.

Field Type Description Constraints
id integer Our internal id for the movement. Do not use this param in POST /movements requests.
transactionId integer The id of the transactions from which this movement was created. We create movements for importing (to EU, type IMPORT) , exporting (from EU, type EXPORT) and border-crossing (type SUPPLY) transactions. Is ignored on POST /movements.
type string The type of this movement. The api determines the type itself, therefore this param is not settable. IMPORT, EXPORT, TRANSFER, SUPPLY
sentDate string The date and time where the items were shipped. Use RFC3339 format. date-time
arrivalDate string The date and time of arrival. Use RFC3339 format. date-time
movementNumber string A number that identifies the movement. 1-50 chars
senderAddress SenderAddressFlex The address from which the order was shipped.
deliveryAddress SenderAddressFlex The address where the order arrived.
quantity integer The quantity of the item of this movement. ≥0
weight Weight The weight of the whole package.
productIdentifier string An identifier that identifies the product, e.g. your SKU. You are strongly encouraged to use the same product identifier for the same product across all channels. ≤ 150 chars
commodityCode string The Customs Tariff Number of the product. ≤ 10 chars
description string A title describing the article. ≤ 250 chars
trackingNumber string The number to track the package. ≤ 50 chars
purchasePrice number The purchase price per item. Must be positive ≥0
purchaseCurrency string The currency of the purchasePrice as 3-digit ISO-4217 code. 3-3 chars
isValid boolean False if the movement is not taxable for the client, but should be recorded anyway. Defaults to false if the purchase price equals zero, true otherwise. true or false
inserted string The date and time where the row was inserted into our database. Only used in the GET /movements call. Has RFC3339 format. date-time
results MovementTaxInfo An object containing the results. Only appears in the response of GET /movements requests.

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.

Field Type Description Constraints
departureCurrency string Currency in the departure country.
departureExchangeRate number The exchange rate applied to the departureTotalValue.
departureTotalValue number The total value in the departure country.
arrivalCurrency string Currency in the arrival country.
arrivalExchangeRate number The exchange rate applied to the arrivalTotalValue.
arrivalTotalValue number The total value in the arrival country.

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"
    }
  ]
}

An order with one or multiple order items. One of paymentDate and sentDate is required.

Field Type Description Constraints
type string The type of this order. Sale, Refund
channel Platform The platform where the transaction was done, e.g. Amazon.
source Platform The platform from which the data originated, e.g. Plentymarkets.
paymentDate string The date and time of the payment. Use RFC3339 format. date-time
sentDate string The date and time where the items were shipped. Use RFC3339 format. date-time
arrivalDate string The date and time of arrival. Use RFC3339 format. date-time
deliveryAddress Address The delivery address.
billingAddress Address The billing address.
senderAddress SenderAddress The address from which the order was shipped
buyerVatNumber string The VAT number of the buyer. If provided and valid (checked by regex), we process the transaction as B2B transaction. ≤ 15 chars
buyerEmail string The Email address of the buyer. ≤ 50 chars
items OrderItem[] The array of OrderItems of this Order. At least one item must be provided.
transactionCurrency string The currency of the order as 3-digit ISO-4217 code. All monetary amounts must have this currency. 3-3 chars
shipping number Total shipping cost. Will be ignored if shipping is set on one of the items. Is distributed proportionally across the order items otherwise.
giftWrap number Total gift wrap cost. Will be ignored if giftWrap is set on one of the items. Is distributed proportionally across the order items otherwise.
totalDiscount number Total discount. Will be ignored if itemDiscount is set on one of the items. Is distributed proportionally across the order items otherwise. Usually negative for sales, positive for refunds.
adjustmentAmount number Any other amount that does not fit into the other field's descriptions. Is distributed proportionally across the order items.
invoiceNumber string The number of the invoice. ≤ 50 chars
invoiceDate string The date and time where the invoice was sent. Use RFC3339 format. date-time
invoiceUrl string A path were the invoice document is reachable. ≤ 100 chars

OrderItem

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

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)

Field Type Description Constraints
quantity integer The quantity of the item of this transaction. ≥0
weight number The weight of the whole package in kilograms. Must be positive. ≥0
productIdentifier string An identifier that identifies the product, e.g. your SKU. You are strongly encouraged to use the same product identifier for the same product across all channels. ≤ 50 chars
description string A title describing the article. ≤ 250 chars
commodityCode string The Customs Tariff Number of the product. ≤ 10 chars
itemPrice number The total price of items of this transaction. This equals to the price per item multiplied with the quantity.
shipping number Shipping cost for this item. The Api prefers to use item-level shipping fields. If the item-level shipping field is set on at least one item, the item-level shipping fields (including shipping discount) are used for every item.
giftWrap number Gift wrap cost for this item. The Api prefers to use item-level gift wrap fields. If the item-level gift wrap field is set on at least one item, the item-level gift wrap fields (including gift wrap discount) are used for every item.
discount number Total discount on this item. If the item-level item discount field is set on at least one item, the item-level item discount fields are used for every item. Usually negative for sales, positive for refunds.
trackingNumber string The number to track the package. ≤ 50 chars
sourceItemNumber string The number of the item from the source platform within the order, e.g. when the source platform on the order object is Plentymarkets, the sourceItemNumber is set to the ID of the OrderItem of Plentymarkets. Is ignored if the source object is unset or the source transaction number is empty. ≤ 500 chars
channelItemNumber string The number of the item from the channel platform within the order, e.g. when the channel platform on the order object is ebay, the channelItemNumber is set to the lineItemId of ebay. ≤ 500 chars
amazonFulfillmentCenterId string The code of the amazon fulfillment center for FBA orders. Use this field if the order items where sent from different FBA warehouses. If this field is provided, the order´s sender address is ignored (but still required). ≤ 4 chars
purchasePrice number The purchase price per item. Must be positive ≥0

Platform

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

Describes platform-specific data that belongs to a transaction or order. The platform can be a marketplace like Amazon, an ERP-Software you are using or your own Webshop

Field Type Description Constraints
identifier string The identifier of the platform. See Platform Abbreviations for possible values. 2-8 chars
transactionNumber string The identifier for the transaction on this platform. If the transaction is a refund, use the id of the underlying order. ≤ 100 chars
refundNumber string If the transaction is a refund, put in the refund identifier here. ≤ 100 chars
itemNumber string The number of the item within the transaction. Only applies if this platform object belongs to a transaction object. Use sourceItemNumber and channelItemNumber for orders and refunds on the item level. ≤ 100 chars
itemPosition integer An additional number to differentiate between different order items with identical ids. Use this only and only if there is no other way to differentiate two separate order items. This occurred only on Amazon so far. This field is ignored on the channel platform if a source platform is set. Only applies to POST /transactions. When using the POST /orders call, the API detects rows with the same id and assigns this field itself starting from 0. Default 0. ≥0

PostDataResponse

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

Describes the payload for an post anything request.

Field Type Description Constraints
status string Status code. Can be either "success" or "fail". success, fail
insertedRows number The number of inserted rows for checking purposes. Only occurs on POST responses.
updatedRows number The number of updated rows for checking purposes. Only occurs on PUT responses.
errors LogMessage[] An Array of warnings and errors that appeared during the operation.

PostOrdersInvoicingResponse

{
  "status": "success",
  "insertedRows": 12,
  "invoicingOrders": [
    {
      "channel": {
        "identifier": "EBY",
        "transactionNumber": "63231231"
      },
      "source": {
        "identifier": "PLTY",
        "transactionNumber": "7812372138"
      },
      "items": [
        {
          "net": 100,
          "vat": 19,
          "rateType": "standard_rate",
          "vatRate": 19,
          "taxCountry": "DE",
          "sellerVatId": "DE999999999",
          "sourceItemNumber": "12345",
          "channelItemNumber": "12345"
        }
      ],
      "currency": "EUR",
      "isEUExport": false,
      "isEUImport": false,
      "isB2B": false,
      "isTargetingSpecialTerritory": false
    }
  ]
}

Describes the response payload for a POST /orders/invoicing request.

Field Type Description Constraints
status string Status code. Can be either "success" or "fail". success, fail
insertedRows number The number of inserted rows for checking purposes.
errors LogMessage[] An Array of warnings and errors that appeared during the operation.
invoicingOrders InvoicingResponseOrder[] The invoicing information for provided orders.

Product

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

Describe a product offered in your shop.

Field Type Description Constraints
id integer An unique id for the entry issued by Taxdoo. Is ignored on POST /products requests. ≥1
productIdentifier string An identifier that identifies the product, e.g. your SKU. You are strongly encouraged to use the same product identifier for the same product across all channels. ≤ 150 chars
commodityCode string The Customs Tariff Number of the product. ≤ 10 chars
purchasePrice number The purchase price per item of this product. Must be positive ≥0
weight Weight The weight of this product
currency string The currency of the purchase_price as 3-digit ISO-4217 code. Defaults to 'EUR'. ≤ 3 chars
description string A title describing the product. ≤ 1000 chars
invalidCommodityCode boolean True if the given commodity code is invalid. Issued only by Taxdoo. true or false
updated string The time where the purchase price was updated. Only returned on GET /products date-time

ProductTaxRates

{
  "productIdentifier": "sku1234",
  "rates": [
    {
      "country": "DE",
      "rateType": "reduced_rate_1"
    }
  ]
}

Provides the tax rate for each country for a product based on the productIdentifier. The CountryTaxRate objects inside the rates array also contain proposals for tax rates based on the commodity code of the product.

Field Type Description Constraints
productIdentifier string Identifier of the Product, e.g. your SKU
commodityCode string The commodity code of the product. Ignored on any POST request.
description string A title describing the article. Ignored on any POST request. ≤ 1000 chars
rates CountryTaxRate[] Array of tax rate and country pairs.

Refund

{
  "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,
      "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"
    }
  ]
}

A refund with one or multiple refund items. Please note that monetary amounts should be negative for refunds.

Field Type Description Constraints
channel Platform The platform where the transaction was done, e.g. Amazon.
source Platform The platform from which the data originated, e.g. Plentymarkets.
paymentDate string The date and time of the payment. Use RFC3339 format. date-time
items RefundItem[] The array of RefundItems of this Refund. At least one item must be provided.
transactionCurrency string The currency of the order as 3-digit ISO-4217 code. All monetary amounts must have this currency. ≤ 3 chars
totalDiscount number Total discount. Will be ignored if itemDiscount is set on one of the items. Is distributed proportionally across the order items otherwise. Usually positive (because it reduces the refund).
shipping number Total shipping cost. Will be ignored if shipping is set on one of the items. Is distributed proportionally across the order items otherwise.
giftWrap number Total gift wrap cost. Will be ignored if giftWrap is set on one of the items. Is distributed proportionally across the order items otherwise.
adjustmentAmount number Any other amount that does not fit into the other field's descriptions.
invoiceNumber string The number of the invoice.
invoiceDate string The date and time where the invoice was sent. Use RFC3339 format. date-time
invoiceUrl string A path were the invoice document is reachable. ≤ 150 chars

RefundItem

{
  "quantity": 5,
  "description": "Green biscuits Premium",
  "itemPrice": -50.2,
  "channelItemNumber": "22342",
  "sourceItemNumber": "2843928"
}

A refund item within a refund. Either sourceItemNumber or channelItemNumber is required (please provide them accordingly to the source and channel objects on the refund). Please note that monetary amounts should be negative for refunds.

Field Type Description Constraints
quantity integer The quantity of the item of this transaction. If the quantity is zero, we will insert the order, but not use it for vat calculation. ≥0
weight Weight The weight of the item (means weight per item multiplied with quantity).
description string A title describing the article. ≤ 1000 chars
itemPrice number The total price of items of this transaction. This equals to the price per item multiplied with the quantity.
discount number Total discount on this item. If the item-level item discount field is set on at least one item, the item-level item discount fields are used for every item. Usually positive (because it reduces the refund).
shipping number Shipping cost for this item. The Api prefers to use item-level shipping fields. If the item-level shipping field is set on at least one item, the item-level shipping fields (including shipping discount) are used for every item.
giftWrap number Gift wrap cost for this item. The Api prefers to use item-level gift wrap fields. If the item-level gift wrap field is set on at least one item, the item-level gift wrap fields (including gift wrap discount) are used for every item.
trackingNumber string The number to track the package. ≤ 50 chars
sourceItemNumber string The number of the item from the source platform within the order, e.g. when the source platform on the order object is Plentymarkets, the sourceItemNumber is set to the ID of the OrderItem of Plentymarkets. Is ignored if the source object is unset or the source transaction number is empty. ≤ 500 chars
channelItemNumber string The number of the item from the channel platform within the order, e.g. when the channel platform on the order object is ebay, the channelItemNumber is set to the lineItemId of ebay. ≤ 500 chars

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.

Field Type Description Constraints
country string The country.
status string Describes the registration status in the given country. none, pending, completed
vatId string The VAT id of the merchant in the country. Some countries use the vatId, others use a tax number. vat-id
taxNumber string The tax number of the merchant in the country.
registrationDate string The date and time the registration was completed. date-time

SenderAddress

{
  "fullName": "John Doe",
  "street": "Westring 32",
  "zip": "987654",
  "city": "München",
  "state": "Bayern",
  "country": "DE"
}

Represents an address e.g. of a warehouse. Either id, amazonFulfillmentCenterId, or a set of zip, state and country are required when used as senderAddress on a /orders or /transactions resource.

Field Type Description Constraints
id integer The id of this address. Is ignored on POST /warehouses. If this is provided on /transactions or /orders, all other fields are ignored.
fullName string The full name of the address owner. ≤ 100 chars
street string Street field of the address. ≤ 200 chars
zip string Postal code 3-10 chars
city string City ≤ 100 chars
state string State ≤ 50 chars
country string Country as 2-letter ISO-3166 code iso-country
amazonFulfillmentCenterId string The code of the amazon fulfillment center for FBA orders. If this is provided on /transactions or /orders, all other fields are ignored. ≤ 4 chars
isStandard boolean True if this is set as the standard warehouse. Only one standard warehouse per merchant allowed. Is only considered on calls to /warehouses. true or false

SimpleResponse

{
  "status": "fail",
  "errors": [
    {
      "level": "error",
      "message": "unkown order id 13454589"
    }
  ]
}

Describes a simple payload for a response.

Field Type Description Constraints
status string Status of the API call. Can be either "success" or "fail". success, fail
errors LogMessage[] An Array of warnings and errors that appeared during the operation. Only appears if the API wants to tell you something.
message string Other error information. Can only appear when status is "fail".

Transaction

{
  "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
}

Describes a Transaction with one article (which can have a quantity greater than one).

Field Type Description Constraints
id integer Our internal id for the transaction. Do not use this param in POST /transactions requests.
type string The type of this transaction. Sale, Refund
channel Platform The platform where the transaction was done, e.g. Amazon.
source Platform The platform from which the data originated, e.g. Plentymarkets.
paymentDate string The date and time of the payment. Use RFC3339 format. date-time
sentDate string The date and time where the items were shipped. Use RFC3339 format. date-time
arrivalDate string The date and time of arrival. Use RFC3339 format. date-time
deliveryAddress Address The delivery address.
billingAddress Address The billing address.
senderAddress SenderAddress The address from which the order was shipped
buyerVatNumber string The VAT number of the buyer. If provided and valid (checked by regex), we process the transaction as B2B transaction. ≤ 15 chars
buyerEmail string The Email address of the buyer. ≤ 50 chars
quantity integer The quantity of the item of this transaction. ≥0
weight number The weight of the whole package in kg. Must be positive. ≥0
productIdentifier string An identifier that identifies the product, e.g. your SKU. You are strongly encouraged to use the same product identifier for the same product across all channels. ≤ 50 chars
description string A title describing the article. ≤ 250 chars
commodityCode string The Customs Tariff Number of the product. ≤ 10 chars
transactionCurrency string The currency of the order as 3-digit ISO-4217 code. All monetary amounts of this transaction must have this currency. 3-3 chars
itemPrice number The total price of items of this transaction. This equals to the price per item multiplied with the quantity.
shipping number Total shipping cost.
giftWrap number Total gift wrap cost.
totalDiscount number The total discount. Usually negative for sales, positive for refunds.
adjustmentAmount number Any other amount that does not fit into the other field's descriptions.
totalValue number The total value of this transaction. Equals the sum of all other monetary amount fields. Is returned only from the GET /transactions call. Is ignored if you provide it in any call.
purchasePrice number The purchase price per item. Must be positive ≥0
trackingNumber string The number to track the package. ≤ 50 chars
invoiceNumber string The number of the invoice. ≤ 50 chars
invoiceDate string The date and time where the invoice was sent. Use RFC3339 format. date-time
invoiceUrl string A path were the invoice document is reachable. ≤ 100 chars
inserted string The date and time where the row was inserted into our database. Only used in the GET /transactions call. Has RFC3339 format. date-time
isValid boolean Only appears in GET /transactions responses. If this field is false, the transaction is invalid and not considered in vat calculation, e.g. when the totalValue equals zero. Despite this, we keep such transactions for completeness in our database. true or false
results TransactionTaxInfo An object containing the results. Only appears in the response of GET /transactions requests when the with_results=true query param is set.

TransactionTaxInfo

{
  "country": "DE",
  "currency": "EUR",
  "time": "2018-05-31T23:45:27.000Z",
  "exchangeRate": 1,
  "rateType": "standard_rate",
  "rateValue": "19.00",
  "net": "20.96",
  "vat": "3.98"
}

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

Field Type Description Constraints
country string The country where this transaction is taxable.
currency string The currency of the tax country.
time string The tax date. date-time
exchangeRate number The applied exchange rate.
rateType string The vat rate type that was applied to this transaction.
rateValue number The applied vat rate value according to the rate type.
net number The net value.
vat number The VAT value.
calculatedTime string The date-time of the calculation. date-time

ValidationErrorResponse

{
  "status": "fail",
  "message": "validation failed",
  "errors": [
    {
      "level": "error",
      "message": "[0].invoiceDate should match format \"date-time\""
    }
  ]
}

The API returns this object on any validation error.

Field Type Description Constraints
status string always "fail"
message string An error message.
errors LogMessage[] Detailed description of the error.

Weight

{
  "value": 0.432,
  "unit": "kg"
}

Represents an weight value paired with an unit.

Field Type Description Constraints
value number The numerical value. ≥0
unit string The unit of the weight. kg, lbs

HTTP Status Codes

The Taxdoo API responds with the following HTTP status codes:

Status Code Meaning
200 OK -- Authentication and request succeeded
400 Bad Request -- Your request sucks. See errors response property for more information.
401 Unauthorized -- Authentication failed, please check if you provided the AuthToken header (and ClientIdentifier header for session tokens)
403 Forbidden -- Your API key is wrong or you do not have permissions for that operation on the given client.
404 Not found -- Your request path is wrong
405 Method not allowed -- You used a wrong HTTP method in the resource. Check the Allow response header for allowed methods.
429 Too Many Requests -- Please turn off your DOS tool.
500 Internal Server Error -- Sorry, we fucked up. Please contact us.
502 Internal Error -- Contact us.
503 Service Unavailable -- AWS is temporarily offline for maintenance. Please try again later.
504 Timeout exception -- Please try again later (and contact us).

Platform Abbreviations

You can use the following abbreviations as platform identifiers (but you are free to use your own):

Platform Abbreviation
eBay EBY
Fulfillment by Amazon AFN
Fulfillment by Merchant (Amazon) MFN
Amazon (unknown) AMZ
Paypal PYPL
Plentymarkets PLTY
Actindo ACT
JTL WaWi JTL
Own webshop WEB
Rakuten RAK
Hitmeister HIT
Allyouneed AYN
Shopgate SGT
TradeTracker TRT
guenstiger.de GST
Preisroboter PRT
fashion.de FSH
laary LAR
Newsletter NWS
Google Products GPR
doyoo DOY
Manual Input MAN
TM3 Logistiksoftware TM3
AnSyS ANS
Unicorn (JTL) UNI
Idealo IDE
Afterbuy ABY
Elmar / elm@r ELM
Lenando LEN
Point of Sale POS
Yatego YAT
Kelkoo KEL
Shopping24 S24
Ricardo RIC
Zentralverkauf.de ZEN
Otto OTTO
Gimahhot GIM
Billiger.de BIL
ShopShare SHR
Quelle QUE
Kauflux KLX
Home24 H24
Zalando ZAL
Check24 C24

Rate Types

The rate types necessary for setting the product rates.

Country (ISO-3166) Rate Type Rate Value
AT standard_rate 20.00
AT parking_rate 13.00
AT reduced_rate_1 10.00
BE standard_rate 21.00
BE parking_rate 12.00
BE reduced_rate_1 12.00
BE reduced_rate_2 6.00
BE zero_rate 0.00
BG standard_rate 20.00
BG reduced_rate_1 9.00
CY standard_rate 19.00
CY reduced_rate_1 9.00
CY reduced_rate_2 5.00
CZ standard_rate 21.00
CZ reduced_rate_1 15.00
CZ reduced_rate_2 10.00
DE standard_rate 19.00
DE reduced_rate_1 7.00
DK standard_rate 25.00
DK zero_rate 0.00
EE standard_rate 20.00
EE reduced_rate_1 9.00
ES standard_rate 21.00
ES reduced_rate_1 10.00
ES super_reduced_rate 4.00
FI standard_rate 24.00
FI reduced_rate_1 14.00
FI reduced_rate_2 10.00
FI zero_rate 0.00
FR standard_rate 20.00
FR reduced_rate_1 10.00
FR reduced_rate_2 5.50
FR super_reduced_rate 2.10
GB standard_rate 20.00
GB reduced_rate_1 5.00
GB zero_rate 0.00
GR standard_rate 24.00
GR reduced_rate_1 13.00
GR reduced_rate_2 6.00
HR standard_rate 25.00
HR reduced_rate_1 13.00
HR reduced_rate_2 5.00
HU standard_rate 27.00
HU reduced_rate_1 18.00
HU reduced_rate_2 5.00
IE standard_rate 23.00
IE reduced_rate_1 13.50
IE parking_rate 13.50
IE reduced_rate_2 9.00
IE super_reduced_rate 4.80
IE zero_rate 0.00
IT standard_rate 22.00
IT reduced_rate_1 10.00
IT reduced_rate_2 5.00
IT super_reduced_rate 4.00
LT standard_rate 21.00
LT reduced_rate_1 9.00
LT reduced_rate_2 5.00
LU standard_rate 17.00
LU parking_rate 14.00
LU reduced_rate_1 8.00
LU super_reduced_rate 3.00
LV standard_rate 21.00
LV reduced_rate_1 12.00
MT standard_rate 18.00
MT reduced_rate_1 7.00
MT reduced_rate_2 5.00
MT zero_rate 0.00
NL standard_rate 21.00
NL reduced_rate_1 6.00
PL standard_rate 23.00
PL reduced_rate_1 8.00
PL reduced_rate_2 5.00
PT standard_rate 23.00
PT parking_rate 13.00
PT reduced_rate_1 13.00
PT reduced_rate_2 6.00
RO standard_rate 20.00
RO standard_rate 19.00
RO reduced_rate_1 9.00
RO reduced_rate_2 5.00
SE standard_rate 25.00
SE reduced_rate_1 12.00
SE reduced_rate_2 6.00
SE zero_rate 0.00
SI standard_rate 22.00
SI reduced_rate_1 9.50
SK standard_rate 20.00
SK reduced_rate_1 10.00