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 timeX-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
Field | Type | Description | Constraints |
---|---|---|---|
account | string | The email of the account your token belongs to. | format email |
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
Header | Value | Description |
---|---|---|
Authorization | Basic |
"clientID:clientSecret" encoded with Base64 |
Content-Type | application/x-www-form-urlencoded |
Payload
The payload must be grant_type=client_credentials
.
Response
Field | Type | Description |
---|---|---|
access_token | string | The access token |
expires_in | integer | Expiry of the access token in seconds |
token_type | string | Always "Bearer" |
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
Field | Type | Description | Constraints |
---|---|---|---|
transactions | Transaction[] | Array of transactions. | 1-1000 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
delimiter | string | the delimiter of your CSV file (defaults to ";") | length 1 |
reject_on_duplicate | boolean | If set to true, the API will reject the CSV file if it detects duplicate transactions within it. | |
reject_not_matchable_refunds | boolean | If set to true, the API will reject the CSV file if it contains refunds that can neither be matched to sales within the CSV file, or to sales within our systems. |
Request
Use the CSV as request body with rows fulfilling the schema CsvTransaction.
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
primary_platform | string | The primary platform identifier, e.g. AFN/MFN for Amazon or PLTY for Plentymarkets (See Platform Abbreviations) | length ≤10 |
primary_transaction_number | string-array | The transaction number of the primary platform | alphanumeric, underscore, hyphen, separated by comma |
primary_refund_number | string-array | The refund number of the primary platform. Please use this in combination with primary_transaction_number , as it is significantly faster. |
alphanumeric, underscore, hyphen, separated by comma |
secondary_platform | string | The secondary platform identifier, e.g. AFN/MFN for Amazon or EBY for eBay (See Platform Abbreviations) | length ≤10 |
secondary_transaction_number | string-array | The transaction number of the secondary platform | alphanumeric, underscore, hyphen, separated by comma |
secondary_refund_number | string-array | The refund number of the secondary platform. Please use this in combination with secondary_transaction_number , as it is significantly faster |
alphanumeric, underscore, hyphen, separated by comma |
payment_date_from | string | Returns only transactions which were paid after the specified date-time. | date-time in RFC3339 format |
payment_date_until | string | Returns only transactions which were paid before the specified date-time. | date-time in RFC3339 format |
sent_date_from | string | Returns only transactions which were sent after the specified date-time. | date-time in RFC3339 format |
sent_date_until | string | Returns only transactions which were sent before the specified date-time. | date-time in RFC3339 format |
inserted_from | string | Returns only transactions which were inserted after the specified date-time. | date-time in RFC3339 format |
inserted_until | string | Returns only transactions which were inserted after the specified date-time. | date-time in RFC3339 format |
calculated_from | string | Returns only transactions for which our results were calculated exactly on or after the specified date-time (>=). | date-time in RFC3339 format |
calculated_until | string | Returns only transactions for which our results were calculated before the specified date-time. | date-time in RFC3339 format |
type | string | Filter by the transaction type. | one of Sale, 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. |
YYYY-MM |
with_results | boolean | If true, the results of our analysis are returned. | |
valid | boolean | If set, only transactions with the isValid field set to this value are returned. |
|
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 | Constraints |
---|---|---|---|
transactions | Transaction[] | The result array of transactions | ≤1000 |
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
Field | Type | Description | Constraints |
---|---|---|---|
transactions | Transaction[] | The transactions to update. IDs must be provided. | 1-100 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
updatedRows | integer | The number of updated rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
ids | string | List of transaction IDs | integers ≥1, length 1-1000, separated by comma or semicolon |
Response
Field | Type | Description | Constraints |
---|---|---|---|
deletedRows | integer | The number of deleted rows. |
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
Field | Type | Description | Constraints |
---|---|---|---|
orders | Order[] | An array of order objects | 1-500 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
refunds | Refund[] | An array of refund objects | 1-500 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
sent_date_from | string | Returns only movements which were sent after the specified date-time. | date-time in RFC3339 format |
sent_date_until | string | Returns only movements which were sent before the specified date-time. | date-time in RFC3339 format |
arrival_date_from | string | Returns only movements which arrived after the specified date-time. | date-time in RFC3339 format |
arrival_date_until | string | Returns only movements which arrived before the specified date-time. | date-time in RFC3339 format |
inserted_from | string | Returns only transactions which were inserted after the specified date-time. | date-time in RFC3339 format |
inserted_until | string | Returns only transactions which were inserted before the specified date-time. | date-time in RFC3339 format |
type | string | Filter by the movement type. | one of transfer, supply, import, export |
valid | boolean | If set, only movements with the specified isValid value are returned. |
|
period | string | Only movements where the arrivalDate (for transfers) or the departureDate (for import, export, supply) is within the specified period are returned |
YYYY-MM |
country | string | If set, only movements where either the departure or the arrival country equals the provided value are returned | ISO-3166 |
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 | Constraints |
---|---|---|---|
movements | Movement[] | An array of Movement matching the filters. | ≤100 |
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
Field | Type | Description | Constraints |
---|---|---|---|
movements | Movement[] | Array of movements. | 1-500 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
products | Product[] | An array of products. | 1-1000 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
delimiter | string | the delimiter of your CSV file (defaults to ";") | length ≤1 |
Request
Use the CSV as request body with rows fulfilling the schema CsvProduct.
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
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. | |
missing_commodity_code | boolean | If true, only products without a commodity code are returned. | |
limit | int | The maximum number of items to display. Smaller value results in faster response. Defaults to 100. | 1-500 |
page | int | The page to retrieve. | 1-1000 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
products | Product[] | Array of products. | ≤500 |
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
Field | Type | Description | Constraints |
---|---|---|---|
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. | alphanumeric, umlauts, underscore, hyphen, separated by comma |
Response
Field | Type | Description | Constraints |
---|---|---|---|
deletedRows | integer | The number of deleted rows. |
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
Field | Type | Description | Constraints |
---|---|---|---|
products | ProductTaxRates[] | 1-1000 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
product_identifiers | string-array | If specified, only data for specified product identifiers are returned. If this parameter is set, all other parameters must not be set. | length 1-100, alphanumeric, umlauts, underscore, hyphen, separated by comma, exclusive |
limit | int | The maximum number of products to retrieve. Defaults to 100 | 1-100 |
page | int | The page to retrieve. Defaults to 1. | 1-1000 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
products | ProductTaxRates[] | An array of ProductTaxRates | ≤100 |
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
Field | Type | Description | Constraints |
---|---|---|---|
legalName | string | The legal name of the client | |
created | string | The date and time the Client was created. | format date-time |
complianceActive | boolean | True if the client is an active customer. | true or false |
address | Address | The client's address. |
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
Field | Type | Description | Constraints |
---|---|---|---|
client | PostClientData | The data of the client to create. |
Response
Field | Type | Description | Constraints |
---|---|---|---|
clientId | integer | The ID of the new client. |
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
Field | Type | Description | Constraints |
---|---|---|---|
platforms | string[] | The platforms for which the onboarding imports are done. | 1-20 |
importStart | string | The date-time from which the imports started. Use RFC3339 format. | format date-time |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
addons | Addon[] | The addons that are activated for the current client. |
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
Field | Type | Description | Constraints |
---|---|---|---|
addon | Addon | The addon to activate |
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
Field | Type | Description | Constraints |
---|---|---|---|
warehouses | SenderAddress[] | The warehouses to add. | 1-50 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
warehouses | SenderAddress[] | Array of SenderAddress objects |
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
Field | Type | Description | Constraints |
---|---|---|---|
registrations | CountryRegistrationStatus[] | The VAT registrations and their status for this client. | |
ossRegistrations | OssRegistration[] | Registrations for the One-Stop-Shop, if available. | |
iossRegistrations | IossRegistration[] | Registrations for the Import One-Stop-Shop, if available. |
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
Field | Type | Description | Constraints |
---|---|---|---|
year | int | the year of the thresholds |
Response
Field | Type | Description | Constraints |
---|---|---|---|
thresholds | CountryThresholdStatus[] | The threshold statuses. |
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
Field | Type | Description | Constraints |
---|---|---|---|
period | string | The period for which the summary is requested. | YYYY-MM |
Response
Field | Type | Description | Constraints |
---|---|---|---|
summary | object | The period summary. The structure is not final and will change in the future. | |
preliminary | boolean | True if the data is still preliminary. | true or false |
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
Field | Type | Description | Constraints |
---|---|---|---|
period | string | The period for which the report is requested. | YYYY-MM |
type | string | The requested report type. | |
country | string | The country to retrieve the report for. Only applies to OSS and IOSS reports. | ISO-3166 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
url | string | The URL to download the report. This URL will expire. | |
expiresIn | integer | The number of seconds the url is valid. | |
preliminary | boolean | If true the report has to be treated as preliminary. | true or false |
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
Field | Type | Description | Constraints |
---|---|---|---|
only_missing | boolean | If true, only entries where the amount is missing are returned. |
Response
Field | Type | Description | Constraints |
---|---|---|---|
amounts | OssInitialTaxAmount[] |
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
Field | Type | Description | Constraints |
---|---|---|---|
amounts | object[] | The OssInitialTaxAmount objects to store. | 1-100 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
periods | string | Filter by periods. If not set, all entries are returned. | one or multiple YYYY-MM, separated by comma |
Response
Field | Type | Description | Constraints |
---|---|---|---|
prefillData | GbFilingPrefillData[] | Contains at most one entry per month. |
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
Field | Type | Description | Constraints |
---|---|---|---|
prefillData | GbFilingPrefillData[] | The GbFilingPrefillData objects to store. | 1-100 |
Response
Field | Type | Description | Constraints |
---|---|---|---|
insertedRows | integer | The number of inserted rows for checking purposes |
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
Field | Type | Description | Constraints |
---|---|---|---|
name | string | The name of the addon | datev, pro-forma, filing-be, filing-it, filing-nl, filing-pl, filing-cz, filing-fr, filing-lu, filing-at, filing-es, filing-gb, filing-se, filing-de, intrastat-de-inbound, intrastat-de-outbound, intrastat-cz-inbound, intrastat-cz-outbound, intrastat-pl-inbound, intrastat-pl-outbound, intrastat-fr-inbound, intrastat-fr-outbound, oss, ioss |
firstPeriod | string | The first month this addon should be active. Defaults to the current month. (Example: 2021-01) | format period |
lastPeriod | string | The last month this addon should be active. Defaults to unbound (i.e. 9999-12). | format period |
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 | format iso-country and 2 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. | format vat-id |
taxNumber | string | The tax number of the merchant in the country. | |
registrationDate | string | The date and time the registration was completed. | format date-time |
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.
Field | Type | Description | Constraints |
---|---|---|---|
country | string | Country as 2-letter ISO-3166 code | format iso-country and 2 chars |
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,
"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. | format 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. | format date-time |
activeUntil | string | The date and time until the distance selling threshold is active. Only set when isActive is true. | format date-time |
CsvProduct
{
"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. | format only-printable and ≤ 50 chars |
commodityCode | string | The Customs Tariff Number of the product. | 8-10 chars |
purchasePrice | number | The purchase price per item of this product. Must be positive | ≥0 |
weightValue | number | The weight of this product | ≥0 |
weightUnit | string | The weight of this product | kg, lbs, g |
supplementaryValue | number | The numerical value of the supplementary unit. | ≥0 |
supplementaryUnit | string | The unit of the supplementary unit. | ZZZ, CTM, NCL, CCT, GRM, GFI, KGM, KCC, KNS, KPO, KPH, KMA, KGE, KSD, KNI, KSH, KPP, KUR, NAR, NPR, CEN, MIL, MWH, LTR, LPA, KLT, MTR, MTK, MTQ, MTC, TJO |
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 |
countryOfOrigin | string | The manufacturing country of the product. | 2 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 | format date-time |
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.
Field | Type | Description | Constraints |
---|---|---|---|
type | string | The type of this transaction. Use one of the preset values. | Sale, Refund |
channelIdentifier | string | The identifier of the platform. You can find possible values here. | format alphanumeric and 2-8 chars |
channelMerchantId | string | ignored | ≤ 100 chars |
channelTransactionNumber | string | The identifier for the transaction on this platform. If the transaction is a refund, use the id of the underlying order. | 1-100 chars |
channelRefundNumber | string | If the transaction is a refund, put in the refund identifier here. | ≤ 100 chars |
channelItemNumber | string | The number of the item within the transaction. Use this to differentiate between items of the same order (identifier and transactionNumber of the items are identical). | ≤ 100 chars |
channelItemPosition | string | An additional number to differentiate between order items with identical ids (identifier, transactionNumber and itemNumber of the items are identical). This field is ignored if the sourceTransactionNumber is set. Defaults to 0 if the column is missing. The maximum value is 32767. | format positive-integer-string |
sourceIdentifier | string | The identifier of the platform. Link here | format alphanumeric and 2-8 chars |
sourceMerchantId | string | The id of the merchant on this platform. Not necessary for your own Webshop. | ≤ 100 chars |
sourceTransactionNumber | string | The identifier for the transaction on this platform. If the transaction is a refund, use the id of the underlying order. | ≤ 100 chars |
sourceRefundNumber | string | If the transaction is a refund, put in the refund identifier here. | ≤ 100 chars |
sourceItemNumber | string | The number of the item within the transaction. Use this to differentiate between items of the same order (identifier and transactionNumber of the items are identical). | ≤ 100 chars |
sourceItemPosition | string | An additional number to differentiate between order items with identical ids (identifier, transactionNumber and itemNumber of the items are identical). Defaults to 0 if the column is missing. The maximum value is 32767. | format positive-integer-string |
paymentDate | string | The date and time of the payment. Use RFC3339 format. | format date-time |
sentDate | string | The date and time where the items were shipped. Use RFC3339 format. | format date-time |
arrivalDate | string | The date and time of arrival. Use RFC3339 format. | format date-time |
deliveryFullName | string | The full name of the address owner. | ≤ 150 chars |
deliveryStreet1 | string | Street field number 1. Only the first one is required, others are optional. | ≤ 100 chars |
deliveryStreet2 | string | Street field number 2 | ≤ 100 chars |
deliveryStreet3 | string | Street field number 3 | ≤ 100 chars |
deliveryStreet4 | string | Street field number 4 | ≤ 100 chars |
deliveryZip | string | Postal code | ≤ 10 chars |
deliveryCity | string | City | ≤ 50 chars |
deliveryState | string | State | ≤ 50 chars |
deliveryCountry | string | Country as 2-letter ISO-3166 code | format iso-country and ≤ 2 chars |
billingFullName | string | The full name of the address owner. | ≤ 100 chars |
billingStreet1 | string | Street field number 1. Only the first one is required, others are optional. | ≤ 100 chars |
billingStreet2 | string | Street field number 2 | ≤ 100 chars |
billingStreet3 | string | Street field number 3 | ≤ 100 chars |
billingStreet4 | string | Street field number 4 | ≤ 100 chars |
billingZip | string | Postal code | ≤ 10 chars |
billingCity | string | City | ≤ 50 chars |
billingState | string | State | ≤ 50 chars |
billingCountry | string | Country as 2-letter ISO-3166 code | format iso-country-optional and ≤ 2 chars |
senderStreet1 | string | Street field number 1. Only the first one is required, others are optional. | ≤ 100 chars |
senderStreet2 | string | Street field number 2 | ≤ 100 chars |
senderStreet3 | string | Street field number 3 | ≤ 100 chars |
senderStreet4 | string | Street field number 4 | ≤ 100 chars |
senderZip | string | Postal code | ≤ 10 chars |
senderCity | string | City | ≤ 50 chars |
senderState | string | State | ≤ 50 chars |
senderCountry | string | Country as 2-letter ISO-3166 code | format iso-country and ≤ 2 chars |
amazonFulfillmentCenterId | string | The code of the amazon fulfillment center for FBA orders. If this field is provided, the sender* fields are ignored, but must still be present as columns, and senderCountry must contain a valid ISO country code. | ≤ 4 chars |
buyerVatNumber | string | The VAT number of the buyer. If provided and valid (checked by regex), we process the transaction as B2B transaction. | ≤ 15 chars |
quantity | string | The quantity of the item of this transaction. | format positive-integer-string |
weight | string | The weight of the whole package. | format number-string-optional |
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. | format only-printable and ≤ 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 must have this currency. | 3 chars |
itemPrice | string | The total price of items of this transaction. This equals to the price per item multiplied with the quantity. | format number-string |
itemDiscount | string | Total discount on items. | format number-string |
shipping | string | Total shipping cost. | format number-string |
shippingDiscount | string | Total discount on shipping. | format number-string |
giftWrap | string | Total gift wrap cost. | format number-string |
giftWrapDiscount | string | Total discount on gift wrap. | format number-string |
goodWillRefund | string | Refund the merchant gave to their customer due to kindness? | format number-string |
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. | format date-time |
paymentChannel | string | The payment channel, e.g. paypal | ≤ 50 chars |
paymentNumber | string | The payment number. | ≤ 100 chars |
taxCollector | string | The party who collects taxes, if applicable. If empty, it is automatically determined by us. | (empty), seller, marketplace |
taxCollected | string | The amount of tax collected by the marketplace, if applicable. | format number-string-optional |
FulfillmentCenter
{
"type": "amazon",
"code": "PRG1"
}
A fulfillment center
Field | Type | Description | Constraints |
---|---|---|---|
type | string | The fulfillment center type, e.g. "amazon" | cdiscount, amazon, logoix, zalando, diha |
code | string | The fulfillment center code, e.g. PRG1. Must be an existing fulfillment center for the specified type. | ≤ 4 chars |
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
Field | Type | Description | Constraints |
---|---|---|---|
period | string | The year and month to which this data is referring to. | format period |
importTransfersPaidAtBorderNet | number | Net of cross-border shipments to warehouses in GB for which you are charged import VAT at the border. | |
importTransfersPaidAtBorderVat | number | Assessed import VAT on cross-border shipments to warehouses in GB for which you are charged import VAT at the border. | |
importTransfersPvaNet | number | Net of cross-border shipments to warehouses in GB, for which you are not immediately charged with import VAT at the border, because they are imported according to PVA ('Postponed VAT Accounting'). | |
importTransfersPvaVat | number | Assessed import VAT on cross-border shipments to warehouses in GB, for which you are not immediately charged with import VAT at the border, because they are imported according to PVA ('Postponed VAT Accounting'). | |
importSalesPvaNet | number | Net of cross-border shipments (sales minus refunds) to private or business customers in GB, with an invoice value above GBP 135, for which you were not charged with import VAT at the border, because they are imported according to PVA ('Postponed VAT Accounting'). | |
importSalesPvaVat | number | Assessed import VAT on cross-border shipments (sales minus refunds) to private or business customers in GB, with an invoice value above GBP 135, for which you were not charged with import VAT at the border, because they are imported according to PVA ('Postponed VAT Accounting') | |
importSalesPaidAtBorderNet | number | Net of cross-border shipments (sales minus refunds) to private or business customers in GB, with an invoice value above GBP 135, for which you are charged import VAT at the border. Required for periods from 2022. | |
importSalesPaidAtBorderVat | number | Assessed import VAT on cross-border shipments (sales minus refunds) to private or business customers in GB, with an invoice value above GBP 135, for which you are charged import VAT at the border. Required for periods from 2022. | |
submittedTime | string | The date and time this entry was marked as submitted. Once an entry is marked as submitted, it cannot be altered anymore. Is ignored on POST requests. | format date-time |
markAsSubmitted | boolean | If true, marks the given data as submitted. Once an entry is marked as submitted, it cannot be altered anymore. Only applicable to POST requests. | true or false |
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.
Field | Type | Description | Constraints |
---|---|---|---|
from | string | In case there are multiple registrations, this shows from when this registration is valid to be used for IOSS filing. If not provided, the lower bound is always the introduction of the IOSS (2021-07). | format period |
to | string | In case there are multiple registrations, this shows until when this registration is valid to be used for IOSS filing. | format period |
dateOfConfirmation | string | The date the IOSS registration was confirmed. | format date |
id | string | The IOSS ID. |
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. | |
path | string | Only for validation errors. Shows the path where the input validation failed. Uses Javascript property access notation preceded with a $, e.g. "$.orders[10]" or "$" for the root object. | |
context | string | Only for invalid input errors. Shows the context of the input validation error, such as platform and primary_transaction_number. |
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.
Field | Type | Description | Constraints |
---|---|---|---|
id | integer | Our internal id for the movement. Do not use this param in POST /movements requests. | |
sentDate | string | The date and time where the items were shipped. Use RFC3339 format. | format date-time |
arrivalDate | string | The date and time of arrival. Use RFC3339 format. | format date-time |
platform | MovementPlatform | Information about platform where the movement originated from. | |
senderAddress | SenderAddress | The address from which the order was shipped. | |
deliveryAddress | SenderAddress | 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. | format only-printable and ≤ 50 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 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. | format date-time |
results | MovementTaxInfo | An object containing the results. Only appears in the response of GET /movements requests. | |
transportMode | integer | Mode of Transport for Intrastat. You can find possible values here: https://www-idev.destatis.de/idev/doc/intra/doc/Intrahandel_Leitfaden.pdf (Section 5.1 field 11). | 1 - 9 |
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.
Field | Type | Description | Constraints |
---|---|---|---|
identifier | string | The identifier of the platform. See Platform Abbreviations for possible values. | format alphanumeric and 2-10 chars |
movementNumber | string | The identifier for the movement on this platform. | 1-100 chars |
itemNumber | string | An additional number to different rows with the same movementNumber. | ≤ 100 chars |
itemPosition | integer | An additional number to differentiate between different items with identical ids. Use this only and only if there is no other way to differentiate two separate movement rows. Default 0. | ≥0 |
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"
}
],
"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.
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. | format date-time |
sentDate | string | The date and time where the items were shipped. Use RFC3339 format. | format date-time |
arrivalDate | string | The date and time of arrival. Use RFC3339 format. | 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 |
items | OrderItem[] | The array of OrderItems of this Order. At least one item must be provided. | ≥1 |
transactionCurrency | string | The currency of the order as 3-digit ISO-4217 code. All monetary amounts must have this currency. | 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. | -999999 - 999999 |
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. | -999999 - 999999 |
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. | -999999 - 999999 |
adjustmentAmount | number | Any other amount that does not fit into the other field's descriptions. Is distributed proportionally across the order items. | -999999 - 999999 |
invoiceNumber | string | The number of the invoice. | ≤ 50 chars |
invoiceDate | string | The date and time where the invoice was sent. Use RFC3339 format. | format date-time |
invoiceUrl | string | A path were the invoice document is reachable. | ≤ 100 chars |
paymentChannel | string | The payment channel, e.g. paypal | ≤ 50 chars |
paymentNumber | string | The payment number. | ≤ 100 chars |
taxCollector | string | The party who collects taxes, if applicable. If empty, it is automatically determined by us. | seller, marketplace |
taxCollected | number | The amount of tax collected by the marketplace, if applicable. The API prefers item-level fields. If the item-level value is set on one of the items, the order-level value is ignored. Usually positive for sales, and negative for refunds. | -999999 - 999999 |
marketplaceCountry | string | The country of the marketplace in ISO 3166-1 alpha-2 format | format iso-country and 2 chars |
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)
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. | format only-printable and ≤ 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. | -9999999 - 9999999 |
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. | -999999 - 999999 |
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. | -999999 - 999999 |
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. | -999999 - 999999 |
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). This field is deprecated, please use senderAddress. | ≤ 4 chars |
fulfillmentCenter | FulfillmentCenter | The fulfillment center. 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). This field is deprecated, please use senderAddress. | |
senderAddress | SenderAddress | The address from which the order item was shipped. Is preferred over the order-level sender address. | |
purchasePrice | number | The purchase price per item. Must be positive | ≥0 |
sentDate | string | The date and time where the items were shipped. Use RFC3339 format. Is used in preference of the order-level sentDate. | format date-time |
taxCollected | number | The amount of tax collected by the marketplace, if applicable. The API prefers item-level fields. If the item-level value is set on one of the items, the order-level value is ignored. Usually positive for sales, and negative for refunds. | -999999 - 999999 |
invoiceNumber | string | The number of the invoice. Is preferred over the order-level invoice. Only supply if there are multiple invoices for an order. | ≤ 50 chars |
invoiceDate | string | The date and time where the invoice was sent. Use RFC3339 format. Is preferred over the order-level invoice date. Only supply if there are multiple invoices for an order. | format date-time |
marketplaceCountry | string | The country of the marketplace in ISO 3166-1 alpha-2 format. Is preferred over the order-level marketplace country. | format iso-country and 2 chars |
OssInitialTaxAmount
{
"period": "2021-Q4",
"reportCountry": "DE",
"countryOfTaxation": "ES"
}
{
"period": "2021-Q4",
"reportCountry": "DE",
"countryOfTaxation": "FR",
"initialTaxAmount": 123.45
}
Describes a single entry of an initial tax amount for OSS corrections.
Field | Type | Description | Constraints |
---|---|---|---|
period | string | The year and quarter to which this amount is referring to. | format year-quarter |
reportCountry | string | The country for which the OSS report this entry refers to is generated. | format vat-id-country |
countryOfTaxation | string | The country of taxation to which this particular amount is referring to | format vat-id-country |
initialTaxAmount | number | The latest reported tax amount for the given countryOfTaxation. If missing in the GET request, this amount is missing and you should populate it. Required for POST requests. | -9999999 - 9999999 |
OssRegistration
{
"dateOfApplication": "2021-08-05T14:03:55Z"
}
{
"from": "2022-01",
"dateOfApplication": "2022-01-05T14:03:55Z"
}
Describes a registration for the One-Stop-Shop of the European Union. The country is always the country of residence of the merchant.
Field | Type | Description | Constraints |
---|---|---|---|
from | string | In case there are multiple registrations, this shows from when this registration is valid to be used for OSS filing. If not provided, the lower bound is always the introduction of the OSS (2021-07). | format period |
to | string | In case there are multiple registrations, this shows until when this registration is valid to be used for OSS filing. | format period |
dateOfApplication | string | The date of application to use the OSS. | format date |
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. | format alphanumeric and 2-10 chars |
transactionNumber | string | The identifier for the transaction on this platform. If the transaction is a refund or return, use the id of the underlying order. | 1-100 chars |
refundNumber | string | If the transaction is a refund, put in the refund identifier here. | ≤ 100 chars |
returnNumber | string | If the transaction is a return, put in the return 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 - 32767 |
PostClientAccount
An account to be linked to the client to create. Either email or id must be provided.
Field | Type | Description | Constraints |
---|---|---|---|
id | integer | The ID of an existing account. | ≥1 |
string | The email address of the account to create. | format email | |
language | string | The language of the account. Defaults to de. Only considered if the account needs to be created, i.e. id being absent. | en, de |
permissionLevel | string | The permission level of the new link. There must be exactly one owner account per client. Owner accounts have the same permissions as employee accounts, but can additionally manage permissions. Taxadvisor accounts have a reduced set of permissions. | owner, employee, taxadvisor |
PostClientAddress
The company address type for the create client request
Field | Type | Description | Constraints |
---|---|---|---|
street | string | Street field of the address. | 3-200 chars |
zip | string | Postal code | 2-15 chars |
city | string | City | 3-100 chars |
state | string | State | 0-50 chars |
country | string | Country as 2-letter ISO-3166 code | format iso-country and 2 chars |
PostClientData
Data about the client to create
Field | Type | Description | Constraints |
---|---|---|---|
legalName | string | The legal name of the new client. | 5-500 chars |
alternativeClientNumber | string | An alternative client number that identifies that client in your system. | 1-200 chars |
companyAddress | PostClientAddress | The residence address of the company. | |
entityType | string | The company type. For german companies, examples are: "GmbH" and "UG" for legal entities, "KG" and "GbR" for partnership and "e.K." for natural. | natural, legal, partnership, partnership_complementary |
countryOfBirth | string | The country of birth of the natural person as 2-letter ISO-3166 code. Should be provided if the entityType is "natural". | format iso-country and 2 chars |
dateOfBirth | string | The date of birth of the natural person. Should be provided if the entityType is "natural". | format date |
firstName | string | The first name of the natural person. Is required if the entityType is "natural". | 2-500 chars |
lastName | string | The last name of the natural person. Is required if the entityType is "natural". | 2-500 chars |
phoneNumber | string | The contact phone number of the new client. | 5-50 chars |
gender | string | The gender of the natural person. Is required if the entityType is "natural". | male, female, other |
addons | Addon[] | The addons that should be activated from the start. | ≤50 |
requestedRegistrations | RequestedRegistration[] | The VAT registrations that Taxdoo should perform. | ≤20 |
registrations | PostClientRegistration[] | The VAT registrations of this client. | 0-100 |
accounts | PostClientAccount[] | The (login-)accounts the new client should be linked to. To link an existing account, supply the id of it. To create a new account, supply an email address. This array must contain exactly one account with the permission level owner. | 1-50 |
warehouses | PostClientWarehouse[] | The warehouse addresses of this client. Must contain exactly one warehouse with isStandard set to true. | 1-10 |
estimatedMonthlyGmv | integer | The estimated monthly GMV (Gross Merchandise Volume) in EUR. Is used as a fallback to determine the base package size. If not provided, a value of 100.000 is assumed. | 1000 - 999999999 |
basePackage | string | The base package for the new client. If not provided, the professional package is used. | starter, professional, premium |
PostClientRegistration
Information about a financial registration in an EU country.
Field | Type | Description | Constraints |
---|---|---|---|
country | string | The country code of the country the registration belongs to. | format iso-country |
vatId | string | The VAT ID in this country | format vat-id |
taxNumber | string | The tax number. | 3-50 chars |
registrationDate | string | The date of registration. | format date |
taxOfficeNumber | string | A number identifying the responsible tax office in this country. | |
intrastatMaterialNumber | string | The Intrastat material number. Currently only applies to Germany. | 2-20 chars |
intrastatDistinctionNumber | string | The Intrastat distinction number. Currently only applies to Germany. | 2-20 chars |
eoriNumber | string | The EORI number of the client. Is issued for customs purposes, and sometimes required for Intrastat. See https://en.wikipedia.org/wiki/EORI_number. | 4-17 chars |
PostClientWarehouse
Warehouse address for creating a client.
Field | Type | Description | Constraints |
---|---|---|---|
street | string | Street field of the address. | 3-200 chars |
zip | string | Postal code | 2-15 chars |
city | string | City | 3-100 chars |
state | string | State | 0-50 chars |
country | string | Country as 2-letter ISO-3166 code | format iso-country and 2 chars |
isStandard | boolean | True if this warehouse address should be used as the standard (fallback) warehouse. Every client must have exactly 1 standard warehouse. This warehouse is used as fallback address for inbound movements into FBA warehouses and for sales transactions where we cannot get warehouse information (e.g. from ebay). | true or false |
Product
{
"description": "Sessel in rot",
"productIdentifier": "redcouch123",
"commodityCode": "9394240000",
"purchasePrice": 330.3,
"currency": "EUR"
}
Describes 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. | format only-printable and ≤ 50 chars |
commodityCode | string | The Customs Tariff Number of the product. | 8-10 chars |
purchasePrice | number | The purchase price per item of this product. Must be positive | ≥0 |
weight | Weight | The weight of this product | |
supplementaryUnit | SupplementaryUnit | The supplementary unit for Intrastat. | |
currency | string | The currency of the purchase_price as 3-digit ISO-4217 code. Defaults to 'EUR'. We only support currencies for which the European Central Bank provides reference exchange rates. See https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html. | EUR, AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR |
description | string | A title describing the product. | ≤ 1000 chars |
countryOfOrigin | string | The manufacturing country of the product. | format iso-country-optional and 2 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 | format 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 | format only-printable and ≤ 50 chars |
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. | 1-100 |
Refund
{
"channel": {
"identifier": "EBY",
"transactionNumber": "63231231",
"refundNumber": "112344"
},
"source": {
"identifier": "PLTY",
"transactionNumber": "7812372138",
"refundNumber": "65831122"
},
"paymentDate": "2017-04-05T14:03:55Z",
"transactionCurrency": "EUR",
"marketplaceCountry": "DE",
"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"
}
]
}
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. | format date-time |
items | RefundItem[] | The array of RefundItems of this Refund. At least one item must be provided. | ≥1 |
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). | -999999 - 999999 |
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. | -999999 - 999999 |
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. | -999999 - 999999 |
adjustmentAmount | number | Any other amount that does not fit into the other field's descriptions. | -999999 - 999999 |
invoiceNumber | string | The number of the invoice. | ≤ 50 chars |
invoiceDate | string | The date and time where the invoice was sent. Use RFC3339 format. | format date-time |
invoiceUrl | string | A path were the invoice document is reachable. | ≤ 150 chars |
paymentChannel | string | The payment channel, e.g. paypal | ≤ 50 chars |
paymentNumber | string | The payment number. | ≤ 100 chars |
taxCollector | string | The party who collects taxes, if applicable. If empty, it is automatically determined by us. | seller, marketplace |
taxCollected | number | The amount of tax collected by the marketplace, if applicable. The API prefers item-level fields. If the item-level value is set on one of the items, the refund-level value is ignored. Usually negative. | -999999 - 999999 |
marketplaceCountry | string | The country of the marketplace in ISO 3166-1 alpha-2 format | format iso-country and 2 chars |
RefundItem
{
"quantity": 5,
"description": "Green biscuits Premium",
"itemPrice": -50.2,
"channelItemNumber": "22342",
"sourceItemNumber": "2843928",
"marketplaceCountry": "DE"
}
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. | -9999999 - 9999999 |
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). | -999999 - 999999 |
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. | -999999 - 999999 |
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. | -999999 - 999999 |
taxCollected | number | The amount of tax collected by the marketplace, if applicable. The API prefers item-level fields. If the item-level value is set on one of the items, the refund-level value is ignored. Usually negative. | -999999 - 999999 |
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 |
itemPosition | integer | An additional number to differentiate between different items with identical ids. Use this only and only if there is no other way to differentiate two separate refund items. Default 0. | ≥0 |
invoiceNumber | string | The number of the invoice. Is preferred over the refund-level invoice. Only supply if there are multiple documents for a refund. | ≤ 50 chars |
invoiceDate | string | The date and time where the invoice was sent. Use RFC3339 format. Is preferred over the refund-level invoice date. Only supply if there are multiple documents for a refund. | format date-time |
marketplaceCountry | string | The country of the marketplace in ISO 3166-1 alpha-2 format. Is preferred over the refund-level marketplace country. | format iso-country and 2 chars |
RequestedRegistration
Information about a requested registration.
Field | Type | Description | Constraints |
---|---|---|---|
country | string | The country for this registration | PL, CZ, AT, IT, BE, NL, FR, LU, ES, GB, SE, DE |
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, fulfillmentCenter, 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 | format iso-country and 2 chars |
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. Will be deprecated in the future in favor of fulfillmentCenter. | ≤ 4 chars |
fulfillmentCenter | FulfillmentCenter | The fulfillment center. 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). This field is the successor of amazonFulfillmentCenterId. | |
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": "success"
}
{
"status": "fail",
"errors": [
{
"level": "error",
"message": "unknown 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". |
SupplementaryUnit
{
"value": 0.7,
"unit": "LTR"
}
Represents a supplementary unit for Intrastat along with its value.
Field | Type | Description | Constraints |
---|---|---|---|
value | number | The numerical value. | ≥0 |
unit | string | The unit of the supplementary unit. | ZZZ, CTM, NCL, CCT, GRM, GFI, KGM, KCC, KNS, KPO, KPH, KMA, KGE, KSD, KNI, KSH, KPP, KUR, NAR, NPR, CEN, MIL, MWH, LTR, LPA, KLT, MTR, MTK, MTQ, MTC, TJO |
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,
"paymentChannel": "paypal",
"paymentNumber": "123456789",
"marketplaceCountry": "DE"
}
Describes a Transaction with one article (which can have a quantity greater than one). For sales, one of paymentDate and sentDate is required. For refunds, the paymentDate is required, and the sentDate is ignored.
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. | format date-time |
sentDate | string | The date and time where the items were shipped. Use RFC3339 format. | format date-time |
arrivalDate | string | The date and time of arrival. Use RFC3339 format. | 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 |
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. | format only-printable and ≤ 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 chars |
itemPrice | number | The total price of items of this transaction. This equals to the price per item multiplied with the quantity. | -9999999 - 9999999 |
shipping | number | Total shipping cost. | -999999 - 999999 |
giftWrap | number | Total gift wrap cost. | -999999 - 999999 |
totalDiscount | number | The total discount. Usually negative for sales, positive for refunds. | -999999 - 999999 |
adjustmentAmount | number | Any other amount that does not fit into the other field's descriptions. | -999999 - 999999 |
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. | 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. | 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. |
|
transportMode | integer | Mode of Transport for Intrastat. You can find possible values here: https://www-idev.destatis.de/idev/doc/intra/doc/Intrahandel_Leitfaden.pdf (Section 5.1 field 11). | 1 - 9 |
paymentChannel | string | The payment channel, e.g. paypal | ≤ 50 chars |
paymentNumber | string | The payment number. | ≤ 100 chars |
taxCollector | string | The party who collects taxes, if applicable. If empty, it is automatically determined by us. | seller, marketplace |
taxCollected | number | The amount of tax collected by the marketplace, if applicable. | -999999 - 999999 |
marketplaceCountry | string | The country of the marketplace in ISO 3166-1 alpha-2 format | format iso-country and 2 chars |
TransactionTaxInfo
{
"country": "DE",
"currency": "EUR",
"time": "2018-05-31T23:45:27.000Z",
"exchangeRate": 1,
"rateType": "standard_rate",
"rateValue": 19,
"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. | format 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. | format date-time |
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, g |
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. Inspect the response for more information. |
401 | Unauthorized - Authentication failed, please check if you provided the AuthToken header. |
403 | Forbidden - Please check the API key, the URL and your permissions. |
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 or adjust it to respect our rate limits. |
500 | Internal Server Error - Sorry, something went wrong. Usually transient errors. Contact us if this happens too often. |
502 | Internal Error - Contact us if this happens too often. |
503 | Service Unavailable - Our API is temporarily unavailable. Please try again later. |
504 | Gateway Timeout - Please try again later. |
Platform Abbreviations
For Taxdoo to correctly evaluate marketplace transactions, it is mandatory that you provide our specified abbreviations for the platforms marked as marketplaces as platform identifier. If you want to provide transactions for a marketplace that is not listed below, please leave us a message under support@taxdoo.com. For all non-marketplace transactions, you can use our suggestions or chose your own abbreviations.
Platform | Abbreviation | Marketplace |
---|---|---|
AbeBooks | ABE | yes |
Actindo | ACT | |
Afterbuy | ABY | |
Allegro | ALG | yes |
Allyouneed | AYN | |
Amazon (unknown fulfillment) | AMZ | yes |
Amazon Commingling | AFN_C | yes |
AnSyS | ANS | |
Billbee | BLB | |
Billiger.de | BIL | |
Bol.com | BOL | yes |
Cdiscount | CDIS | yes |
Check24 | C24 | yes |
doyoo | DOY | |
DreamRobot | DR | |
eBay | EBY | yes |
Elmar / elm@r | ELM | |
Etsy | ETSY | yes |
fashion.de | FSH | |
For Vegans | FVE | yes |
Fulfillment by Amazon | AFN | yes |
Fulfillment by Merchant (Amazon) | MFN | yes |
Galaxus.de | GALAX | |
Gimahhot | GIM | |
Google Products | GPR | |
guenstiger.de | GST | |
Hitmeister | HIT | |
Home24 | H24 | |
Idealo | IDE | yes |
Immaculate Vegan | IMV | yes |
JTL WaWi | JTL | |
Kaufland | KAUF | yes |
Kauflux | KLX | yes |
Kelkoo | KEL | |
laary | LAR | |
Lenando | LEN | yes |
Manomano.de | MANO | |
Manual Input | MAN | |
MyToys | MYTOYS | |
Newsletter | NWS | |
Onbuy | ONB | yes |
Otto | OTTO | yes |
Own webshop | WEB | |
Paypal | PYPL | |
Plentymarkets | PLTY | |
Point of Sale | POS | |
Preisroboter | PRT | |
Quelle | QUE | |
Rakuten | RAK | |
Real.de | REAL | yes |
Ricardo | RIC | yes |
Shopgate | SGT | |
Shopify | SFY | |
Shop like you give a damn | SLGD | yes |
Shopping24 | S24 | |
ShopShare | SHR | |
Shopware5 | SWR5 | |
Shopware6 | SWR6 | |
TM3 Logistiksoftware | TM3 | |
TradeTracker | TRT | |
Unicorn (JTL) | UNI | |
Xentral | XENTRAL | |
Yatego | YAT | yes |
Zalando | ZAL | yes |
Zentralverkauf.de | ZEN |
Rate Types
The rate types necessary for setting the product rates. Please keep in mind that this list may not be up to date.
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 |
LV | reduced_rate_2 | 5.00 |
LV | zero_rate | 0.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 | 9.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 | 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 |