Settings help you to model how you want your sellers and marketplace to be configured. For example, you can use the settings to allow a seller to only be liable for tax in the specified countries where you want them to.

Settings are defined in 2 categories, for the marketplace and its sellers. Depending on the specific use case or setting, you may need to define settings in both categories or you may not. This depends on the use case and your business circumstances. For example, where the marketplace or seller is registered.

Marketplace Settings: Here you can define whether tax is enabled for a specified region or country. You can also specify whether tax is calculated for physical goods or services. You can specify settings for regional schemes like IOSS and OSS.
Seller Settings: Here you can set many similar settings to the marketplace except these are for individual sellers in your marketplace.

Initially, your marketplace settings are set during the implementation project. You cannot create a new Marketplace, you can only update an existing one.

Settings Groups

Each of the seller and marketplace settings are divided into a four groups:

General Settings for Seller or Marketplace: Settings at this level are applied to the seller or marketplace in all contexts unless specified otherwise in a lower level setting. It is usually basic identification information for the seller or marketplace. For more information, see General Settings for a Seller and General Settings for a Marketplace
Region: A region is a collection of countries that share settings. For example, the European Union (EU). The settings here apply to all the countries in the region unless specified otherwise in the country or subdivision settings. Some settings are inter-related.
Country: A country is an entity that can be associated with a region in the hierarchy. To enable your sellers in a specific country, you need to include the required settings for the goods that they sell.
Country Subdivision: A country sub-division is a level below a country in the hierarchy. It is analogous to a province or state in the United States. For example, California (CA) is a country subdivision of the United States (US).

For example, you need to specify the IOSS number at the regional level of your Marketplace settings.

See Regions, Countries and Country Subdivisions.

Setting Examples

The following are some examples of how you might use these settings to meet different needs:

Locations and Registrations

You use the is_seller_located_within_region field in your marketplace's settings to indicate if they are located in the specified region. This is used for liability determination.

For example, the "is_seller_located_within_region": false setting indicates that the Marketplace is not located in the EU.

However, the marketplace is registered in Poland as a seller. This means that they can bear liability for certain transactions sent to Poland:

"settings": [
        
        {
            "effective_from": "2021-12-17",
            "value": {           
                "regions": {
                   
                    "EU": {
                        "taxation": {
                            "physical": {
                                "is_seller_located_within_region": false
                            }
                        }
                    }
},                    
                "countries": {
                    "PL": {
                        "taxation": {
                            "physical": {
                                "is_seller_registered": true,
                                "is_physical_tax_enabled": true,
                                "seller_tax_number": "ABC1234"
                            }
                        }
                    }                                 
            }
        }
        }
    ],

You can also use the same setting in the region in the seller's settings. Here, you specify both the country and region settings to match the marketplace's settings. Note the following:

The seller is set as located in the EU in the region settings ("is_seller_located_within_region": true).
This seller is registered to pay tax in Poland (is_seller_registered).
They are also enabled to pay physical tax in Poland (is_physical_tax_enabled": true).

{
     "settings": [
          {
                    "countries": {
                         "PL": {
                              "is_domestic": true,
                              "taxation": {
                                   "physical": {
                                        "is_seller_registered": true,
                                        "is_physical_tax_enabled": true,
                                        "seller_tax_number": "DE456778",
                                        "tax_obligation_country_code_override": "IT"
                                   }
                              },
                    "regions": {
                         "EU": {
                              "taxation": {
                                   "physical": {
                                        "is_seller_located_within_region": true,
                                        "use_marketplace_as_intermediary": false,
                                        "ioss_member_state_of_identification": "GB",
                                        "ioss_registration_number": "GB454949",
                                        "oss_member_state_of_identification": "FR",
                                        "oss_registration_number": "FR458686"
                                   },
                              }
                         }
                    },
                    "timezone": "GMT"
               },
               "effective_from": "1999-01-01"
          }
     ],
     "country": "IE",
     "postal_code": "XC12134",
     "business_name": "Test Widgets",
     "email": "[email protected]",
     "postal_address_line3": "Building 5",
     "postal_address_line2": "Main Street",
     "last_name": "Murphy",
     "first_name": "Audey",
     "seller_code": "XCV123",
     "postal_address_line1": "Wessex Town",
     "middle_name": "Humphrey"
}
'

Depending on the circumstance, this can change tax and liability determination. For example, if (like in the example) the marketplace is not registered to pay tax in a country but the seller is, then the seller may be liable for goods in certain circumstances.

Liability Rule Overrides for Sellers

You can use the physical.tax_obligation_country_code_override setting to change how liability is assigned in a specific country for a specific Seller. You can set it to one of the following

seller_country: Liability is assigned to the seller's country.
ship_from: Liability is assigned to the country that the goods are shipped from
country_code: Liability is assigned to the specified country code. For example, IE for Ireland.

For example, the following seller setting uses Germany for all physical sales in Germany:

{
     "settings": [
          {
                    "countries": {
                         "DE": {
                              "is_domestic": false,
                              "taxation": {
                                   "services": {
                                        "use_marketplace_as_intermediary": true
                                   },
                                   "physical": {
                                        "is_seller_registered": true,
                                        "is_physical_tax_enabled": true,
                                        "seller_tax_number": "DE456778",
                                        "tax_obligation_country_code_override": "DE"
                                   }
                              },
                    "regions": {
                         "EU": {
                              "taxation": {
                                   "physical": {
                                        "is_seller_located_within_region": true,
                                        "use_marketplace_as_intermediary": false,
                                        "ioss_member_state_of_identification": "GB",
                                        "ioss_registration_number": "GB454949",
                                        "oss_member_state_of_identification": "FR",
                                        "oss_registration_number": "FR458686"
                                   },
                                   "services": {
                                        "use_marketplace_as_intermediary": false
                                   }
                              }
                         }
                    },
                    "timezone": "GMT"
               },
               "effective_from": "1999-01-01"
          }
     ],
     "country": "IE",
     "postal_code": "XC12134",
     "business_name": "Test Widgets",
     "email": "[email protected]",
     "postal_address_line3": "Building 5",
     "postal_address_line2": "Main Street",
     "last_name": "Murphy",
     "first_name": "Audey",
     "seller_code": "XCV123",
     "postal_address_line1": "Wessex Town",
     "middle_name": "Humphrey"
}
'

In this Section

Topic	Description
Start and Block Dates for Settings	You can set starting dates for settings and also dates from which settings are blocked.
2-Party Sales Mode	Read about how to configure the service for sales with 2 possibly liable parties.
Regions, Countries and Country Subdivisions	Regions, countries and subdivisions can be defined in your marketplace and seller settings.
Marketplace Settings Overview	Marketplace settings control how the marketplace functions.
Seller Settings Overview	This section lists the settings for sellers.
Regional Tax Variations	This section lists configurations that are required for various countries and special tax schemes.