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

string

required

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

string

required

Default currency code (three-letter ISO)

boolean

Whether to calculate taxes automatically (default: true)

boolean

Whether gift cards are taxable (default: true)

number

Default tax rate percentage

string

Tax code for external tax providers

Country[]

Countries in this region

string[]

Available payment provider IDs

object

Additional custom data

Country

Represents a country within a region.

string

required

Unique country identifier

string

required

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

string

required

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

number

required

Numeric country code

string

required

Country name

string

required

Display name for the country

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 })
}

CreateRegionDTO | CreateRegionDTO[]

required

Region data

string

required

Region name

string

required

Default currency (three-letter ISO code)

boolean

Enable automatic tax calculation

number

Default tax rate percentage

string[]

Country codes (two-letter ISO)

string[]

Available payment provider IDs

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" }, ...]

string

required

The ID of the region to retrieve

FindConfig

Configuration for the query

string[]

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

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"],
})

string

required

ID of the region to update

UpdateRegionDTO

required

Fields to update

string

Region name

string

Currency code

boolean

Automatic tax calculation

number

Tax rate percentage

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: "customer@example.com",
})

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"],
})

await regionModuleService.createRegions({
  name: "Europe",
  currency_code: "eur",
  automatic_taxes: true,
  tax_rate: 20,
  countries: ["de", "fr", "es", "it", "nl"],
  payment_providers: ["stripe", "paypal"],
})

await regionModuleService.createRegions({
  name: "United Kingdom",
  currency_code: "gbp",
  automatic_taxes: true,
  tax_rate: 20,
  countries: ["gb"],
  payment_providers: ["stripe"],
})

await regionModuleService.createRegions({
  name: "Asia Pacific",
  currency_code: "usd",
  automatic_taxes: false,
  countries: ["au", "nz", "sg", "jp"],
  payment_providers: ["stripe", "paypal"],
})

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

​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

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