Skip to main content

Regions Overview

In this document, you’ll learn about Regions and their importance in your Medusa server.

Introduction​

Regions represent at least one country on your Medusa server. They're used to define different business logic and configurations for a set of countries.

For example, you can enable one payment provider for region A, and a different payment provider for region B. Customers can then use the payment provider enabled in their region.

This applies to other relations and entities in your store such as different currencies, fulfillment providers, and tax providers.

Region Configurations​

The following configurations can be set for each region:

  1. The currency used.
  2. The tax provider and rates.
  3. The countries that belong to that region. A country can only belong to one region.
  4. The enabled payment providers.
  5. The enabled fulfillment providers.
  6. The shipping and return shipping options.

One vs Multiple Regions​

Your store needs at least one region so that your customers can place orders.

If you serve customers in different countries that use the same configurations, such as the same currency and payment providers, then you can include more countries in the same region.

If you serve customers in different countries that have at least one different configuration, such as different payment providers, you need to create a new region for those countries.

There is no limit on how many regions you can create, and regions can share similar configurations.

Region Entity Overview​

A region is stored in the database as a Region entity. Some of its important attributes are:

  • name: The name of the region. Customers will see this name on the storefront.
  • tax_rate: A number that indicates the tax rate. The tax rate is a percentage.
  • tax_code: An optional string that is used as the code for the default tax rate.
  • gift_cards_taxable: A boolean value that indicates whether gift cards in a region are taxable or not.
  • automatic_taxes: A boolean value that indicates whether taxes should be calculated during checkout automatically or manually for that region. You can learn more about manually calculating taxes in this documentation.

Relations to Other Entities​

As regions are a core part of your Medusa server, there are many relations to other entities.

This section covers relations to entities that make up the configurations of a region.

Regions Relations Overview

Country​

A region must have at least one country. A country can belong to only one region.

The relation between the Region and Country entities is available on both entities:

  • You can access the countries that belong to a region by expanding the countries relation and accessing region.countries.
  • You can access the region of a country by expanding the region relation and accessing country.region. Also, you can access the ID of the region through country.region_id.

Currency​

A region must have one currency. A currency can be used for more than one region.

The relation is available on a region by expanding the currency relation and accessing region.currency. The 3 character currency code can also be accessed through region.currency_code.

FulfillmentProvider​

A region must have at least one fulfillment provider. A fulfillment provider can be used in more than one region.

The relation is available on a region by expanding the fulfillment_providers relation and accessing region.fulfillment_providers.

PaymentProvider​

A region must have at least one payment provider. A payment provider can be used in more than one region.

The relation is available on a region by expanding the payment_providers relation and accessing region.payment_providers.

ShippingOption​

Both shipping options and return shipping options are represented by the ShippingOption entity. You can learn more in the Shipping Architecture documentation.

More than one shipping option can belong to a region. The relation is available on a shipping option by expanding the region relation and accessing shipping_option.region.

TaxProvider​

A region can have one tax provider. A tax provider can be used for more than one region.

The relation is available on a region by expanding the tax_provider relation and accessing region.tax_provider. You can also access the ID of the tax provider through region.tax_provider_id.

TaxRate​

A region can have more than one tax rate, and a tax rate belongs to one region.

The relation between the Region and TaxRate entities is available on both entities:

  • You can access the tax rates of a region by expanding the tax_rates relation and accessing region.tax_rates.
  • You can access the region of a tax rate by expanding the region relation and accessing tax_rate.region. You can also access the ID of the region through tax_rate.region_id.

See Also​