Region Module

Overview

The Region Module manages geographic regions and their configurations including currencies, countries, tax settings, and payment/fulfillment provider availability. Regions are essential for multi-market commerce. Key Features:

Multi-region support
Currency configuration per region
Country associations
Tax settings and rates
Payment provider availability
Fulfillment provider availability
Automatic tax calculation settings

When to Use

Use the Region Module when you need to:

Support multiple geographic markets
Configure different currencies per market
Manage country-specific settings
Set region tax configurations
Control payment provider availability
Control fulfillment options per region
Handle multi-currency commerce

Data Models

Region

Represents a geographic market with specific settings.

string

required

Unique region identifier

name

string

required

Region name (e.g., “North America”, “Europe”)

currency_code

string

required

Default currency code (three-letter ISO)

automatic_taxes

boolean

Whether to calculate taxes automatically (default: true)

gift_cards_taxable

boolean

Whether gift cards are taxable (default: true)

tax_rate

number

Default tax rate percentage

tax_code

string

Tax code for external tax providers

countries

Country[]

Countries in this region

payment_providers

string[]

Available payment provider IDs

metadata

object

Additional custom data

Country

Represents a country within a region.

string

required

Unique country identifier

iso_2

string

required

Two-letter ISO country code (e.g., “US”, “GB”)

iso_3

string

required

Three-letter ISO country code (e.g., “USA”, “GBR”)

num_code

number

required

Numeric country code

name

string

required

Country name

display_name

string

required

Display name for the country

region_id

string

ID of the associated region

Service Interface

The Region Module service is available at @medusajs/medusa/region.

Create Region

Create a new region.

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IRegionModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"

export async function POST(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const regionModuleService: IRegionModuleService = req.scope.resolve(
    Modules.REGION
  )

  const region = await regionModuleService.createRegions({
    name: "North America",
    currency_code: "usd",
    automatic_taxes: true,
    tax_rate: 10,
    countries: ["us", "ca"],
    payment_providers: ["stripe", "paypal"],
  })

  res.json({ region })
}

data

CreateRegionDTO | CreateRegionDTO[]

required

Region data

name

string

required

Region name

currency_code

string

required

Default currency (three-letter ISO code)

automatic_taxes

boolean

Enable automatic tax calculation

tax_rate

number

Default tax rate percentage

countries

string[]

Country codes (two-letter ISO)

payment_providers

string[]

Available payment provider IDs

region

RegionDTO | RegionDTO[]

The created region(s)

Retrieve Region

Get a region with its configuration.

const region = await regionModuleService.retrieveRegion("reg_us", {
  relations: ["countries"],
})

console.log(region.currency_code) // "usd"
console.log(region.countries) // [{ iso_2: "us", name: "United States" }, ...]

regionId

string

required

The ID of the region to retrieve

config

FindConfig

Configuration for the query

relations

string[]

Relations to load (e.g., ["countries"])

region

RegionDTO

The retrieved region

List Regions

List all regions.

const regions = await regionModuleService.listRegions(
  {},
  {
    relations: ["countries"],
  }
)

Update Region

Modify region configuration.

const region = await regionModuleService.updateRegions("reg_us", {
  tax_rate: 8.5,
  automatic_taxes: false,
  payment_providers: ["stripe", "paypal", "manual"],
})

regionId

string

required

ID of the region to update

data

UpdateRegionDTO

required

Fields to update

name

string

Region name

currency_code

string

Currency code

automatic_taxes

boolean

Automatic tax calculation

tax_rate

number

Tax rate percentage

payment_providers

string[]

Payment provider IDs

Add Countries to Region

Associate countries with a region.

const region = await regionModuleService.updateRegions("reg_eu", {
  countries: ["de", "fr", "es", "it"],
})

Remove Countries from Region

Disassociate countries from a region.

// Get current countries
const region = await regionModuleService.retrieveRegion("reg_eu", {
  relations: ["countries"],
})

// Remove specific country
const remainingCountries = region.countries
  .filter(c => c.iso_2 !== "gb")
  .map(c => c.iso_2)

await regionModuleService.updateRegions("reg_eu", {
  countries: remainingCountries,
})

List Countries

Retrieve available countries.

const countries = await regionModuleService.listCountries()

// Find specific country
const us = countries.find(c => c.iso_2 === "us")
console.log(us.name) // "United States"

Integration Examples

With Cart Module

Set cart region.

import { Modules } from "@medusajs/framework/utils"

const regionModule = container.resolve(Modules.REGION)
const cartModule = container.resolve(Modules.CART)

// Get region
const region = await regionModule.retrieveRegion("reg_us")

// Create cart with region
const cart = await cartModule.createCarts({
  region_id: region.id,
  currency_code: region.currency_code,
  email: "[email protected]",
})

With Pricing Module

Region-based pricing.

import { Modules } from "@medusajs/framework/utils"

const regionModule = container.resolve(Modules.REGION)
const pricingModule = container.resolve(Modules.PRICING)

// Get region
const region = await regionModule.retrieveRegion("reg_eu")

// Add region-specific price
await pricingModule.addPrices({
  priceSetId: "pset_123",
  prices: [
    {
      amount: 2000,
      currency_code: region.currency_code,
      rules: {
        region_id: region.id,
      },
    },
  ],
})

With Payment Module

Configure payment providers per region.

import { Modules } from "@medusajs/framework/utils"

const regionModule = container.resolve(Modules.REGION)

// US region - Stripe only
await regionModule.updateRegions("reg_us", {
  payment_providers: ["stripe"],
})

// EU region - Stripe and PayPal
await regionModule.updateRegions("reg_eu", {
  payment_providers: ["stripe", "paypal"],
})

// Retrieve region to check available providers
const region = await regionModule.retrieveRegion("reg_us")
console.log(region.payment_providers) // ["stripe"]

With Fulfillment Module

Region-specific fulfillment.

import { Modules } from "@medusajs/framework/utils"

const regionModule = container.resolve(Modules.REGION)
const fulfillmentModule = container.resolve(Modules.FULFILLMENT)

// Get region
const region = await regionModule.retrieveRegion("reg_us", {
  relations: ["countries"],
})

// Create service zone for region countries
const serviceZone = await fulfillmentModule.createServiceZones({
  name: region.name,
  geo_zones: region.countries.map(country => ({
    type: "country",
    country_code: country.iso_2,
  })),
})

With Tax Module

Region tax configuration.

import { Modules } from "@medusajs/framework/utils"

const regionModule = container.resolve(Modules.REGION)
const taxModule = container.resolve(Modules.TAX)

// Get region
const region = await regionModule.retrieveRegion("reg_us")

if (region.automatic_taxes) {
  // Calculate taxes using region's tax rate
  const taxLines = await taxModule.getTaxLines(
    items,
    {
      tax_rate: region.tax_rate,
    }
  )
}

Multi-Region Setup

Example Configuration

await regionModuleService.createRegions({
  name: "North America",
  currency_code: "usd",
  automatic_taxes: true,
  tax_rate: 0,
  countries: ["us", "ca"],
  payment_providers: ["stripe"],
})

Best Practices

Region Design: Structure regions based on:
- Currency zones (Euro zone, USD zone, etc.)
- Tax jurisdictions
- Fulfillment/shipping areas
- Payment provider availability
Currency Codes: Always use lowercase three-letter ISO currency codes (“usd”, “eur”, “gbp”).
Country Associations: Each country should belong to only one region. Carefully plan country-to-region mappings.
Tax Configuration:
- Set automatic_taxes: true for regions with simple tax calculations
- Set automatic_taxes: false for complex tax scenarios requiring external providers
Payment Providers: Only list payment providers that:
- Support the region’s currency
- Are legally available in the region’s countries
- Have been properly configured in your Medusa instance
Default Region: Create a default region for your primary market to handle cases where region detection fails.

Cart Module - Region-based cart creation
Pricing Module - Region-specific pricing
Payment Module - Payment provider availability
Fulfillment Module - Region fulfillment

Get Started

Core Concepts

Commerce Modules

Building with Medusa

Providers

Admin Dashboard

Deployment

Overview

When to Use

Data Models

Region

Country

Service Interface

Create Region

Retrieve Region

List Regions

Update Region

Add Countries to Region

Remove Countries from Region

List Countries

Integration Examples

With Cart Module

With Pricing Module

With Payment Module

With Fulfillment Module

With Tax Module

Multi-Region Setup

Example Configuration

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Commerce Modules

Building with Medusa

Providers

Admin Dashboard

Deployment

​Overview

​When to Use

​Data Models

​Region

​Country

​Service Interface

​Create Region

​Retrieve Region

​List Regions

​Update Region

​Add Countries to Region

​Remove Countries from Region

​List Countries

​Integration Examples

​With Cart Module

​With Pricing Module

​With Payment Module

​With Fulfillment Module

​With Tax Module

​Multi-Region Setup

​Example Configuration

​Best Practices

​Related Modules

Build docs developers (and LLMs) love

Overview

When to Use

Data Models

Region

Country

Service Interface

Create Region

Retrieve Region

List Regions

Update Region

Add Countries to Region

Remove Countries from Region

List Countries

Integration Examples

With Cart Module

With Pricing Module

With Payment Module

With Fulfillment Module

With Tax Module

Multi-Region Setup

Example Configuration

Best Practices

Related Modules