These field references describe settings for a marketplace in a specific country, region, or subdivision.

General marketplace settings

The following general marketplace settings are available:

Field	Type	Description
`country`	String	The two-letter ISO country code.
`settings`	Object	Groups information about settings.
`business_name`	String	The seller's business name. The service displays this value on invoices.
`email`	String	The email address of the seller's legal representative.
`postal_address_line1`	String	The seller's first address line. The service displays this value on invoices when the seller is liable.
`postal_address_line2`	String	The seller's second address line. The service displays this value on invoices when the seller is liable.
`postal_address_line3`	String	The seller's third address line. The service displays this value on invoices when the seller is liable.
`first_name`	String	The first name of the seller's legal representative.
`middle_name`	String	The middle name of the seller's legal representative.
`last_name`	String	The last name of the seller's legal representative.
`marketplace_description`	String	The marketplace's description.
`marketplace_code`	String	The marketplace's unique identifier.

Time zone settings

The following time zone settings are available:

Field	Type	Description
`settings`	Object	Groups information about settings.
`settings.block_transactions_before`	String	The timestamp before which transactions targeting the marketplace are not accepted.
`settings.timezone`	String	The marketplace's time zone for all time-based operations. For example, if a tax is configured to apply on a specific date, the system uses the date in this time zone.

Tax number validation settings

The following tax number validation settings are available:

Field	Type	Description
`tax_number_validation`	Object	Groups information about tax number validation settings.
`tax_number_validation.validation_request_timeout_ms`	Integer	The number of milliseconds to wait before a request to the validation service times out.
`tax_number_validation.cache_expiry_timeout_days`	Integer	Specifies how long a tax number validation result remains in the cache before the service refreshes it. For example, if a tax number was validated within the last 24 hours and this setting is `1`, the validation service returns the cached result when it checks the tax number again. Lower values can affect service performance.

Tax settings

The following tax settings are available:

Field	Type	Description
`taxation.{key}`	Object	Groups information about taxation settings.
`taxation.physical`	Object	Groups information about physical goods.
`taxation.physical.back_to_back_transaction_templates`	Object	The transaction templates for back-to-back transactions involving physical goods. The service creates a back-to-back transaction based on the original transaction and overrides its fields with values provided in these templates. To provide the correct address data for back-to-back (self-billed) invoices, set the `billing_address` field in the transaction template.
`taxation.physical.back_to_back_transaction_templates.transaction`	String	The custom value for the transaction.
`taxation.physical.back_to_back_transaction_templates.transaction_line`	String	The custom value for the transaction line.
`taxation.physical.back_to_back_transaction_tax_country_code`	String	The tax country code used for back-to-back transactions.

Invoicing settings

The following invoice settings are available:

Field	Type	Pattern	Description
`settings.invoicing`	Object	—	Groups information about invoice settings.
`invoicing.detect_currency_from_tax_country`	Boolean	—	Specifies whether to determine the invoice currency code from the country where the tax liability lies.
`invoicing.invoice_email_subject`	String	—	The subject line of the email sent when an invoice is generated. Use `{{invoice_number}}` as a placeholder for the invoice number.
`invoicing.refund_note_email_subject`	String	—	The subject line of the email sent when a credit note is generated for a refund. Use `{{refund_note_number}}` as a placeholder for the refund note number.
`invoicing.invoice_number_format`	String	—	The format string used to generate invoice numbers. You can use the following placeholders: `{territory}` for the country code `{year}` for the year `{month}` for the month `{day}` for the day `{index}` for a number one greater than the index used for the previous invoice The default value is `{territory}{year}-{index}`.
`invoicing.generate_optional_invoices`	Boolean	—	Specifies whether to generate an invoice when the applicable tax rule does not specify whether an invoice is required. If the tax rule does not specify this, the service generates an invoice only when this setting is enabled.
`invoicing.is_invoice_delivery_enabled`	Boolean	—	Specifies whether to send invoices and refund notes to the buyer's email address specified in the transaction request.
`invoicing.invoice_email_from_address`	String	`[^@]+@[^@]+`	The email address used in the "reply-to" field when the service sends an invoice or refund note to the buyer.
`invoicing.invoice_footer_text`	String	—	The custom text that the service adds to the footer of generated invoices.
`invoicing.invoice_logo_url`	String	`^https?:\/\/.\*`	The URL of the image to display on invoices.

Country settings

The following country settings are available:

Field	Type	Description
`countries.{key}`	String	The two-letter ISO country code.
`is_domestic`	Boolean	If `true`, transactions for digital goods with tax liability in this country are treated as domestic transactions.
`countries.{key}.taxation`	Object	Groups information about country taxation settings.
`country_subdivisions.{key}`	Object	Groups information about country subdivision settings.

Country tax settings

The following tax settings for countries and regions are available:

Field	Type	Description
`taxation.services.{key}`	Object	Groups information about taxation on services.
`taxation.services.service_owner_liability_rule`	String	Specifies how to determine the liability assignment for services such as shipping and insurance. If not provided, the service defaults to the `consignment` rule. For the `service` rule, the service applies tax based on the ship-to country settings.
Taxation settings for physical goods	—	—
`taxation.physical`	Object	Groups information about taxation settings on physical goods in this country.
`taxation.physical.is_seller_registered`	Boolean	Specifies whether the seller is configured to collect tax in this country.
`taxation.physical.is_physical_tax_enabled`	Boolean	Specifies whether tax collection for physical goods is enabled in this country.
`taxation.physical.seller_tax_number`	String	The tax number for this country.

Country subdivision settings

The following subdivision settings for countries and regions are available:

Field	Type	Description
`country_subdivisions.{key}`	String	The two-letter country subdivision code. For example, specify `CA` for California.
Taxation settings	—	—
`taxation.is_enabled`	Boolean	Specifies whether taxation is enabled for the country subdivision. Defaults to `true`.

Region settings

A region is a group of one or more countries that share common behavior. For example, many tax rules and rates apply across European Union member states, so that service defines a region for it.

The following region settings are available:

Field	Type	Description
`region.{key}`	String	The two-letter ISO code for the region.
Tax number validation settings	—	—
`tax_number_validation`	Object	Groups information about tax number validation settings across the region.
`tax_number_validation.validation_request_timeout_ms`	Number	The number of milliseconds to wait before a request to the validation service times out.
`tax_number_validation.cache_expiry_timeout_days`	Number	The number of days to retain a verified tax number in the cache. After this period, the validation service must verify the tax number online again, such as through an external validation service.
`taxation.validation_rule`	String	Specifies how the service validates tax numbers. Possible values: `valid-when-syntax-ok`—Uses the tax number valid unless the country has a configured tax number pattern that the number does not match. `valid-when-external-service-ok`—Uses an external validation service, such as VIES in the EU, to determine whether the tax number is valid. `ignored`—Ignores the tax number and processes the transaction as if no tax number was provided. Defaults to `valid-when-external-service-ok`.
Taxation settings	—	—
`taxation.{key}`	Object	Groups information about taxation settings across the region.
Tax settings for services	—	—
`taxation.services`	Object	Groups information about taxation on services, such as postage and insurance.
`taxation.services.service_owner_liability_rule`	String	Specifies how the service determines tax liability for services such as shipping and insurance. If you do not provide a value, the service follows the `consignment` rule. With the `service` rule, the service applies tax based on the ship-to country's configuration.
Tax settings for physical goods	—	—
`taxation.physical`	Object	Groups information about physical goods across the region.
`taxation.physical.is_seller_located_within_region`	Boolean	Specifies whether the seller has a presence in the region.
`taxation.physical.ioss_member_state_of_identification`	String	The IOSS Member State of identification.
`taxation.physical.ioss_registration_number`	String	The IOSS registration number.
`taxation.physical.oss_member_state_of_identification`	String	The OSS Member State of identification.
`taxation.physical.oss_registration_number`	String	The IOSS registration number.