---
displayed_sidebar: jsClientSidebar
slug: /references/js-client/RegionsResource
---

import ParameterTypes from "@site/src/components/ParameterTypes"

# RegionsResource

This class is used to send requests to [Store Region API Routes](https://docs.medusajs.com/api/store#regions\_getregions). All its method
are available in the JS Client under the `medusa.regions` property.

Regions are different countries or geographical regions that the commerce store serves customers in.
Customers can choose what region they're in, which can be used to change the prices shown based on the region and its currency.

Related Guide: [How to use regions in a storefront](https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions)

## Methods

### list

Retrieve a list of regions. This method is useful to show the customer all available regions to choose from.

#### Example

```ts
import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.regions.list()
.then(({ regions, count, limit, offset }) => {
  console.log(regions.length);
})
```

#### Parameters

<ParameterTypes parameters={[
  {
    "name": "customHeaders",
    "type": "`Record<string, any>`",
    "description": "Custom headers to attach to the request.",
    "optional": false,
    "defaultValue": "{}",
    "expandable": false,
    "children": []
  }
]} expandUrl="https://docs.medusajs.com/js-client/overview#expanding-fields"/>

#### Returns

<ParameterTypes parameters={[
  {
    "name": "ResponsePromise",
    "type": "ResponsePromise&#60;StoreRegionsListRes&#62;",
    "optional": false,
    "defaultValue": "",
    "description": "Resolves to the list of regions with pagination fields.",
    "expandable": false,
    "children": [
      {
        "name": "StoreRegionsListRes",
        "type": "[PaginatedResponse](../../medusa/types/medusa.PaginatedResponse-1.mdx) & `object`",
        "description": "The list of regions with pagination fields.",
        "optional": false,
        "defaultValue": "",
        "expandable": false,
        "children": [
          {
            "name": "count",
            "type": "`number`",
            "description": "",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "limit",
            "type": "`number`",
            "description": "",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "offset",
            "type": "`number`",
            "description": "",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "regions",
            "type": "[Region](../../entities/classes/entities.Region.mdx)[]",
            "description": "An array of regions details.",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": [
              {
                "name": "automatic_taxes",
                "type": "`boolean`",
                "description": "Whether taxes should be automated in this region.",
                "optional": false,
                "defaultValue": "true",
                "expandable": false,
                "children": []
              },
              {
                "name": "countries",
                "type": "[Country](../../entities/classes/entities.Country.mdx)[]",
                "description": "The details of the countries included in this region.",
                "optional": false,
                "defaultValue": "",
                "expandable": true,
                "children": []
              },
              {
                "name": "created_at",
                "type": "`Date`",
                "description": "The date with timezone at which the resource was created.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "currency",
                "type": "[Currency](../../entities/classes/entities.Currency.mdx)",
                "description": "The details of the currency used in the region.",
                "optional": false,
                "defaultValue": "",
                "expandable": true,
                "children": []
              },
              {
                "name": "currency_code",
                "type": "`string`",
                "description": "The three character currency code used in the region.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "deleted_at",
                "type": "`null` \\| `Date`",
                "description": "The date with timezone at which the resource was deleted.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "fulfillment_providers",
                "type": "[FulfillmentProvider](../../entities/classes/entities.FulfillmentProvider.mdx)[]",
                "description": "The details of the fulfillment providers that can be used to fulfill items of orders and similar resources in the region.",
                "optional": false,
                "defaultValue": "",
                "expandable": true,
                "children": []
              },
              {
                "name": "gift_cards_taxable",
                "type": "`boolean`",
                "description": "Whether the gift cards are taxable or not in this region.",
                "optional": false,
                "defaultValue": "true",
                "expandable": false,
                "children": []
              },
              {
                "name": "id",
                "type": "`string`",
                "description": "The region's ID",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "includes_tax",
                "type": "`boolean`",
                "description": "Whether the prices for the region include tax",
                "optional": false,
                "defaultValue": "false",
                "expandable": false,
                "featureFlag": "tax_inclusive_pricing",
                "children": []
              },
              {
                "name": "metadata",
                "type": "`Record<string, unknown>`",
                "description": "An optional key-value map with additional details",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "name",
                "type": "`string`",
                "description": "The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "payment_providers",
                "type": "[PaymentProvider](../../entities/classes/entities.PaymentProvider.mdx)[]",
                "description": "The details of the payment providers that can be used to process payments in the region.",
                "optional": false,
                "defaultValue": "",
                "expandable": true,
                "children": []
              },
              {
                "name": "tax_code",
                "type": "`string`",
                "description": "The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "tax_provider",
                "type": "[TaxProvider](../../entities/classes/entities.TaxProvider.mdx)",
                "description": "The details of the tax provider used in the region.",
                "optional": false,
                "defaultValue": "",
                "expandable": true,
                "children": []
              },
              {
                "name": "tax_provider_id",
                "type": "`null` \\| `string`",
                "description": "The ID of the tax provider used in this region",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "tax_rate",
                "type": "`number`",
                "description": "The tax rate that should be charged on purchases in the Region.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "tax_rates",
                "type": "`null` \\| [TaxRate](../../entities/classes/entities.TaxRate.mdx)[]",
                "description": "The details of the tax rates used in the region, aside from the default rate.",
                "optional": false,
                "defaultValue": "",
                "expandable": true,
                "children": []
              },
              {
                "name": "updated_at",
                "type": "`Date`",
                "description": "The date with timezone at which the resource was updated.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              }
            ]
          }
        ]
      }
    ]
  }
]} />

___

### retrieve

Retrieve a Region's details.

#### Example

```ts
import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.regions.retrieve(regionId)
.then(({ region }) => {
  console.log(region.id);
})
```

#### Parameters

<ParameterTypes parameters={[
  {
    "name": "id",
    "type": "`string`",
    "description": "The region's ID.",
    "optional": false,
    "defaultValue": "",
    "expandable": false,
    "children": []
  },
  {
    "name": "customHeaders",
    "type": "`Record<string, any>`",
    "description": "Custom headers to attach to the request.",
    "optional": false,
    "defaultValue": "{}",
    "expandable": false,
    "children": []
  }
]} expandUrl="https://docs.medusajs.com/js-client/overview#expanding-fields"/>

#### Returns

<ParameterTypes parameters={[
  {
    "name": "ResponsePromise",
    "type": "ResponsePromise&#60;StoreRegionsRes&#62;",
    "optional": false,
    "defaultValue": "",
    "description": "Resolves to the region's details.",
    "expandable": false,
    "children": [
      {
        "name": "region",
        "type": "[Region](../../entities/classes/entities.Region.mdx)",
        "description": "Region details.",
        "optional": false,
        "defaultValue": "",
        "expandable": false,
        "children": [
          {
            "name": "automatic_taxes",
            "type": "`boolean`",
            "description": "Whether taxes should be automated in this region.",
            "optional": false,
            "defaultValue": "true",
            "expandable": false,
            "children": []
          },
          {
            "name": "countries",
            "type": "[Country](../../entities/classes/entities.Country.mdx)[]",
            "description": "The details of the countries included in this region.",
            "optional": false,
            "defaultValue": "",
            "expandable": true,
            "children": [
              {
                "name": "display_name",
                "type": "`string`",
                "description": "The country name appropriate for display.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "id",
                "type": "`number`",
                "description": "The country's ID",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "iso_2",
                "type": "`string`",
                "description": "The 2 character ISO code of the country in lower case",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "iso_3",
                "type": "`string`",
                "description": "The 2 character ISO code of the country in lower case",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "name",
                "type": "`string`",
                "description": "The normalized country name in upper case.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "num_code",
                "type": "`number`",
                "description": "The numerical ISO code for the country.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "region",
                "type": "[Region](../../entities/classes/entities.Region.mdx)",
                "description": "The details of the region the country is associated with.",
                "optional": false,
                "defaultValue": "",
                "expandable": true,
                "children": []
              },
              {
                "name": "region_id",
                "type": "`null` \\| `string`",
                "description": "The region ID this country is associated with.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              }
            ]
          },
          {
            "name": "created_at",
            "type": "`Date`",
            "description": "The date with timezone at which the resource was created.",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "currency",
            "type": "[Currency](../../entities/classes/entities.Currency.mdx)",
            "description": "The details of the currency used in the region.",
            "optional": false,
            "defaultValue": "",
            "expandable": true,
            "children": [
              {
                "name": "code",
                "type": "`string`",
                "description": "The 3 character ISO code for the currency.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "includes_tax",
                "type": "`boolean`",
                "description": "Whether the currency prices include tax",
                "optional": true,
                "defaultValue": "false",
                "expandable": false,
                "featureFlag": "tax_inclusive_pricing",
                "children": []
              },
              {
                "name": "name",
                "type": "`string`",
                "description": "The written name of the currency",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "symbol",
                "type": "`string`",
                "description": "The symbol used to indicate the currency.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "symbol_native",
                "type": "`string`",
                "description": "The native symbol used to indicate the currency.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              }
            ]
          },
          {
            "name": "currency_code",
            "type": "`string`",
            "description": "The three character currency code used in the region.",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "deleted_at",
            "type": "`null` \\| `Date`",
            "description": "The date with timezone at which the resource was deleted.",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "fulfillment_providers",
            "type": "[FulfillmentProvider](../../entities/classes/entities.FulfillmentProvider.mdx)[]",
            "description": "The details of the fulfillment providers that can be used to fulfill items of orders and similar resources in the region.",
            "optional": false,
            "defaultValue": "",
            "expandable": true,
            "children": [
              {
                "name": "id",
                "type": "`string`",
                "description": "The ID of the fulfillment provider as given by the fulfillment service.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "is_installed",
                "type": "`boolean`",
                "description": "Whether the fulfillment service is installed in the current version. If a fulfillment service is no longer installed, the `is\\_installed` attribute is set to `false`.",
                "optional": false,
                "defaultValue": "true",
                "expandable": false,
                "children": []
              }
            ]
          },
          {
            "name": "gift_cards_taxable",
            "type": "`boolean`",
            "description": "Whether the gift cards are taxable or not in this region.",
            "optional": false,
            "defaultValue": "true",
            "expandable": false,
            "children": []
          },
          {
            "name": "id",
            "type": "`string`",
            "description": "The region's ID",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "includes_tax",
            "type": "`boolean`",
            "description": "Whether the prices for the region include tax",
            "optional": false,
            "defaultValue": "false",
            "expandable": false,
            "featureFlag": "tax_inclusive_pricing",
            "children": []
          },
          {
            "name": "metadata",
            "type": "`Record<string, unknown>`",
            "description": "An optional key-value map with additional details",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "name",
            "type": "`string`",
            "description": "The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "payment_providers",
            "type": "[PaymentProvider](../../entities/classes/entities.PaymentProvider.mdx)[]",
            "description": "The details of the payment providers that can be used to process payments in the region.",
            "optional": false,
            "defaultValue": "",
            "expandable": true,
            "children": [
              {
                "name": "id",
                "type": "`string`",
                "description": "The ID of the payment provider as given by the payment service.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "is_installed",
                "type": "`boolean`",
                "description": "Whether the payment service is installed in the current version. If a payment service is no longer installed, the `is\\_installed` attribute is set to `false`.",
                "optional": false,
                "defaultValue": "true",
                "expandable": false,
                "children": []
              }
            ]
          },
          {
            "name": "tax_code",
            "type": "`string`",
            "description": "The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "tax_provider",
            "type": "[TaxProvider](../../entities/classes/entities.TaxProvider.mdx)",
            "description": "The details of the tax provider used in the region.",
            "optional": false,
            "defaultValue": "",
            "expandable": true,
            "children": [
              {
                "name": "id",
                "type": "`string`",
                "description": "The ID of the tax provider as given by the tax service.",
                "optional": false,
                "defaultValue": "",
                "expandable": false,
                "children": []
              },
              {
                "name": "is_installed",
                "type": "`boolean`",
                "description": "Whether the tax service is installed in the current version. If a tax service is no longer installed, the `is\\_installed` attribute is set to `false`.",
                "optional": false,
                "defaultValue": "true",
                "expandable": false,
                "children": []
              }
            ]
          },
          {
            "name": "tax_provider_id",
            "type": "`null` \\| `string`",
            "description": "The ID of the tax provider used in this region",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "tax_rate",
            "type": "`number`",
            "description": "The tax rate that should be charged on purchases in the Region.",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          },
          {
            "name": "tax_rates",
            "type": "`null` \\| [TaxRate](../../entities/classes/entities.TaxRate.mdx)[]",
            "description": "The details of the tax rates used in the region, aside from the default rate.",
            "optional": false,
            "defaultValue": "",
            "expandable": true,
            "children": []
          },
          {
            "name": "updated_at",
            "type": "`Date`",
            "description": "The date with timezone at which the resource was updated.",
            "optional": false,
            "defaultValue": "",
            "expandable": false,
            "children": []
          }
        ]
      }
    ]
  }
]} />
