Marketplace Settings - Tax

You can create settings for tax in both the marketplace and seller settings.

The settings are very similar for each to allow you to decide where and how to set rules. They govern how tax is calculated and where the liability is assigned.

You can configure settings that are applied to the entire marketplace or seller. You can also fine-tune your settings by creating settings that apply only to a specific country or seller or even for a specific country and seller.

Apart from some general settings, tax is arranged in the following categories at each level:

  • Physical: Settings for taxes relating to physical goods.
  • Shipping: Settings for taxes relating to shipping.

Marketplace Settings

You can configure the following settings for tax for an entire marketplace.

FieldDescription
taxation.back_to_back_transaction_templates.transactionUse this to create custom fields and values for back-to-back, digital transactions. You can create these fields at the transaction or transaction line level.
taxation.back_to_back_transaction_tax_country_codeThe code for the country that will be used for paying tax for back-to-back transactions.

For example:

{
     "settings": [
          {
               "value": {
                    "taxation": {
                         "digital": {
                              "back_to_back_transaction_templates": {
                                   "transaction": {
                                        "Test": "tplate",
                                   }
                              },
                              "accept_all_countries_during_autodetection": true
                         },
                         "back_to_back_transaction_tax_country_code": "IE"
                    },
                    "invoicing": {
                         "detect_currency_from_tax_country": true,
                         "invoice_email_subject": "[email protected]",
                         "refund_note_email_subject": "{{refund_note_number}}",
                         "invoice_number_format": "{{territory}}{{year}}-{{index}}",
                         "generate_optional_invoices": true,
                         "is_invoice_delivery_enabled": true,
                         "invoice_email_from_address": "[email protected]",
                         "invoice_footer_text": "Thank You",
                         "invoice_logo_url": "example.com/test.jpg"
                    },
                    "timezone": "GMT"
               },
               "effective_from": "1970-01-01"
          }
     ],
     "country": "IE",
     "marketplace_code": "XYZ"
}
'

Regional Settings

The following categories of tax settings for each region in a marketplace:

  • Tax Validation Settings: The settings for Vertex Validator govern how Tax IDs are validated. These are explained in the API-based Settings topic.
  • Services: Settings for how services are taxed and assigned liability.
  • Physical: Settings for how physical goods are taxed and assigned liability.

The following settings are available for tax in a region in a marketplace:

FieldDescription
services.service_owner_liability_ruleThis setting determines whether the consignment or service rule is used for liability determination for services.
If the service rule is used, the liability is determined using the Ship To country configuration for sellers in this region.
physical.is_seller_located_within_regionThis setting allows you to later enable seller's location settings in that region. If set to true, sellers with the same settings are treated as being located in the region (assuming this is configured in the seller's settings).
physical.ioss_member_state_of_identificationSpecify the member state country where the IOSS number is registered.
physical.ioss_registration_numberSpecify the IOSS number, if any, that will be used by the marketplace. If the Marketplace is liable for an IOSS qualifying transaction, the value here will be used as the IOSS number.
physical.oss_member_state_of_identificationSpecify the member state country where the OSS number is registered.
physical.oss_registration_numberSpecify the OSS number, if any, that will be used by the marketplace. If the Marketplace is liable for an OSS qualifying transaction, the value here will be used as the OSS number.

For example:

{
     "settings": [
          {

                    "regions": {
                         "EU": {
                              "taxation": {
                                   "services": {
                                        "service_owner_liability_rule": "consignment"
                                   },
                                   "physical": {
                                        "is_seller_located_within_region": true,
                                        "ioss_member_state_of_identification": "DE",
                                        "ioss_registration_number": "234234234",
                                        "oss_member_state_of_identification": "GB",
                                        "oss_registration_number": "32e3ref4",
                                        "special_tax_registration": "VOEC",
                                        "liability_for_high_value_goods_in_mixed_value_consignment": true
                                   }
                              }
                         }
                    },
                    "timezone": "GMT"
               },
               "effective_from": "1970-01-01"
          }
     ],
     "country": "IE",
     "marketplace_code": "XYZ"
}
'

Country Settings

FieldDescription
is_domesticIf this is set to true, transactions where the liability is determined to reside in this country are treated as domestic transactions.
tax_number_validation.validation_request_timeout_msSee API-based Settings.
tax_number_validation.cache_expiry_timeout_daysSee API-based Settings .
service.service_owner_liability_ruleThis setting determines whether the consignment or service rule is used for liability determination for services.
If the consignment rule is used,
If the service rule is used, the liability is determined using the Ship To country configuration for sellers in this country.
is_seller_registeredIf this is set to trues, it indicates that all the sellers in this country can be later modelled as being registered to pay tax in this country, in their settings. This affects liability determination.
physical.is_physical_tax_enabledThis setting allows you to enable tax for Sellers in this country. If set to true, you can later make the same setting in the Seller's settings.
seller_tax_numberThe Tax ID number that will be used for all sales from the marketplace to this country.

For example:

{
     "settings": [
          {
                    "countries": {
                         "IE": {
                              "is_domestic": true,
                              "tax_number_validation": {
                                   "validation_request_timeout_ms": 45,
                                   "cache_expiry_timeout_days": 60
                              },
                              "taxation": {
                                   "services": {
                                        "service_owner_liability_rule": "consignment"
                                   },
                                   "physical": {
                                        "is_seller_registered": true,
                                        "is_physical_tax_enabled": true,
                                        "seller_tax_number": "123456"
                                   }
                              },'

Country Subdivision Settings

Country subdivisions are representations of bodies that exist within a country in the hierarchy of settings. For example, you might define the United States as country code US and this might have subdivisions within it for each state like CA for California.

FieldDescription
taxation.is_enabledIf set to true, taxation is enabled for this subdivision.

For example

{
     "settings": [
          {
               "value": {
                    "countries": {
                         "US": {
                              "is_domestic": true,
                              "taxation": {
                                   "services": {
                                        "service_owner_liability_rule": "consignment"
                                   },
                                   "physical": {
                                        "is_seller_registered": true,
                                        "is_physical_tax_enabled": true,
                                        "seller_tax_number": "12345"
                                   }
                              },
                              "country_subdivisions": {
                                   "US-CA": {
                                        "taxation": {
                                             "is_enabled": true
                                        }