> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# Region Module

> Learn about the Region Module and how to configure regions, countries, and regional settings in Medusa.

## 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.

<ResponseField name="id" type="string" required>
  Unique region identifier
</ResponseField>

<ResponseField name="name" type="string" required>
  Region name (e.g., "North America", "Europe")
</ResponseField>

<ResponseField name="currency_code" type="string" required>
  Default currency code (three-letter ISO)
</ResponseField>

<ResponseField name="automatic_taxes" type="boolean">
  Whether to calculate taxes automatically (default: true)
</ResponseField>

<ResponseField name="gift_cards_taxable" type="boolean">
  Whether gift cards are taxable (default: true)
</ResponseField>

<ResponseField name="tax_rate" type="number">
  Default tax rate percentage
</ResponseField>

<ResponseField name="tax_code" type="string">
  Tax code for external tax providers
</ResponseField>

<ResponseField name="countries" type="Country[]">
  Countries in this region
</ResponseField>

<ResponseField name="payment_providers" type="string[]">
  Available payment provider IDs
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

### Country

Represents a country within a region.

<ResponseField name="id" type="string" required>
  Unique country identifier
</ResponseField>

<ResponseField name="iso_2" type="string" required>
  Two-letter ISO country code (e.g., "US", "GB")
</ResponseField>

<ResponseField name="iso_3" type="string" required>
  Three-letter ISO country code (e.g., "USA", "GBR")
</ResponseField>

<ResponseField name="num_code" type="number" required>
  Numeric country code
</ResponseField>

<ResponseField name="name" type="string" required>
  Country name
</ResponseField>

<ResponseField name="display_name" type="string" required>
  Display name for the country
</ResponseField>

<ResponseField name="region_id" type="string">
  ID of the associated region
</ResponseField>

## Service Interface

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

### Create Region

Create a new region.

<CodeGroup>
  ```typescript Example theme={null}
  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 })
  }
  ```
</CodeGroup>

<ParamField path="data" type="CreateRegionDTO | CreateRegionDTO[]" required>
  Region data

  <ParamField path="name" type="string" required>
    Region name
  </ParamField>

  <ParamField path="currency_code" type="string" required>
    Default currency (three-letter ISO code)
  </ParamField>

  <ParamField path="automatic_taxes" type="boolean">
    Enable automatic tax calculation
  </ParamField>

  <ParamField path="tax_rate" type="number">
    Default tax rate percentage
  </ParamField>

  <ParamField path="countries" type="string[]">
    Country codes (two-letter ISO)
  </ParamField>

  <ParamField path="payment_providers" type="string[]">
    Available payment provider IDs
  </ParamField>
</ParamField>

<ResponseField name="region" type="RegionDTO | RegionDTO[]">
  The created region(s)
</ResponseField>

### Retrieve Region

Get a region with its configuration.

<CodeGroup>
  ```typescript Example theme={null}
  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" }, ...]
  ```
</CodeGroup>

<ParamField path="regionId" type="string" required>
  The ID of the region to retrieve
</ParamField>

<ParamField path="config" type="FindConfig">
  Configuration for the query

  <ParamField path="relations" type="string[]">
    Relations to load (e.g., `["countries"]`)
  </ParamField>
</ParamField>

<ResponseField name="region" type="RegionDTO">
  The retrieved region
</ResponseField>

### List Regions

List all regions.

<CodeGroup>
  ```typescript Example theme={null}
  const regions = await regionModuleService.listRegions(
    {},
    {
      relations: ["countries"],
    }
  )
  ```
</CodeGroup>

### Update Region

Modify region configuration.

<CodeGroup>
  ```typescript Example theme={null}
  const region = await regionModuleService.updateRegions("reg_us", {
    tax_rate: 8.5,
    automatic_taxes: false,
    payment_providers: ["stripe", "paypal", "manual"],
  })
  ```
</CodeGroup>

<ParamField path="regionId" type="string" required>
  ID of the region to update
</ParamField>

<ParamField path="data" type="UpdateRegionDTO" required>
  Fields to update

  <ParamField path="name" type="string">
    Region name
  </ParamField>

  <ParamField path="currency_code" type="string">
    Currency code
  </ParamField>

  <ParamField path="automatic_taxes" type="boolean">
    Automatic tax calculation
  </ParamField>

  <ParamField path="tax_rate" type="number">
    Tax rate percentage
  </ParamField>

  <ParamField path="payment_providers" type="string[]">
    Payment provider IDs
  </ParamField>
</ParamField>

### Add Countries to Region

Associate countries with a region.

<CodeGroup>
  ```typescript Example theme={null}
  const region = await regionModuleService.updateRegions("reg_eu", {
    countries: ["de", "fr", "es", "it"],
  })
  ```
</CodeGroup>

### Remove Countries from Region

Disassociate countries from a region.

<CodeGroup>
  ```typescript Example theme={null}
  // 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,
  })
  ```
</CodeGroup>

### List Countries

Retrieve available countries.

<CodeGroup>
  ```typescript Example theme={null}
  const countries = await regionModuleService.listCountries()

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

## Integration Examples

### With Cart Module

Set cart region.

<CodeGroup>
  ```typescript Example theme={null}
  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",
  })
  ```
</CodeGroup>

### With Pricing Module

Region-based pricing.

<CodeGroup>
  ```typescript Example theme={null}
  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,
        },
      },
    ],
  })
  ```
</CodeGroup>

### With Payment Module

Configure payment providers per region.

<CodeGroup>
  ```typescript Example theme={null}
  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"]
  ```
</CodeGroup>

### With Fulfillment Module

Region-specific fulfillment.

<CodeGroup>
  ```typescript Example theme={null}
  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,
    })),
  })
  ```
</CodeGroup>

### With Tax Module

Region tax configuration.

<CodeGroup>
  ```typescript Example theme={null}
  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,
      }
    )
  }
  ```
</CodeGroup>

## Multi-Region Setup

### Example Configuration

<CodeGroup>
  ```typescript North America theme={null}
  await regionModuleService.createRegions({
    name: "North America",
    currency_code: "usd",
    automatic_taxes: true,
    tax_rate: 0,
    countries: ["us", "ca"],
    payment_providers: ["stripe"],
  })
  ```

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

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

  ```typescript Asia Pacific theme={null}
  await regionModuleService.createRegions({
    name: "Asia Pacific",
    currency_code: "usd",
    automatic_taxes: false,
    countries: ["au", "nz", "sg", "jp"],
    payment_providers: ["stripe", "paypal"],
  })
  ```
</CodeGroup>

## Best Practices

1. **Region Design**: Structure regions based on:
   * Currency zones (Euro zone, USD zone, etc.)
   * Tax jurisdictions
   * Fulfillment/shipping areas
   * Payment provider availability

2. **Currency Codes**: Always use lowercase three-letter ISO currency codes ("usd", "eur", "gbp").

3. **Country Associations**: Each country should belong to only one region. Carefully plan country-to-region mappings.

4. **Tax Configuration**:
   * Set `automatic_taxes: true` for regions with simple tax calculations
   * Set `automatic_taxes: false` for complex tax scenarios requiring external providers

5. **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

6. **Default Region**: Create a default region for your primary market to handle cases where region detection fails.

## Related Modules

* [Cart Module](/modules/cart) - Region-based cart creation
* [Pricing Module](/modules/pricing) - Region-specific pricing
* [Payment Module](/modules/payment) - Payment provider availability
* [Fulfillment Module](/modules/fulfillment) - Region fulfillment