Skip to main content
Skip to main content
You're viewing the documentation for v1, which isn't the latest Medusa version.Latest documentation

IRegionModuleService

The main service interface for the Region Module.

Methods​

create​

**create**(data, sharedContext?): Promise<[RegionDTO](types.RegionDTO.mdx)[]>

This method creates regions.

Example​

const region = await regionModuleService.create([
  {
    name: "Europe",
    currency_code: "eur",
    countries: ["dk", "de", "fr"],
  },
  {
    name: "United States of America",
    currency_code: "usd",
    countries: ["us"],
  },
])

Parameters​

dataCreateRegionDTO[]Required
The regions to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionDTO[]>Required
The created regions.

**create**(data, sharedContext?): Promise&#60;[RegionDTO](types.RegionDTO.mdx)&#62;

This method creates a region.

Example​

const region = await regionModuleService.create({
  name: "Europe",
  currency_code: "eur",
  countries: ["dk", "de", "fr"],
})

Parameters​

dataCreateRegionDTORequired
The region to be created.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionDTO>Required
The created region.

upsert​

**upsert**(data, sharedContext?): Promise&#60;[RegionDTO](types.RegionDTO.mdx)[]&#62;

This method updates or creates regions if they don't exist.

Example​

const region = await regionModuleService.upsert([
  {
    id: "reg_123",
    automatic_taxes: false,
  },
  {
    name: "Europe",
    currency_code: "eur",
  },
])

Parameters​

dataUpsertRegionDTO[]Required
The attributes in the regions to be created or updated.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionDTO[]>Required
The created or updated regions.

**upsert**(data, sharedContext?): Promise&#60;[RegionDTO](types.RegionDTO.mdx)&#62;

This method updates or creates a region if it doesn't exist.

Example​

const region = await regionModuleService.upsert({
  id: "reg_123",
  automatic_taxes: false,
})

Parameters​

dataUpsertRegionDTORequired
The attributes in the region to be created or updated.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionDTO>Required
The created or updated region.

update​

**update**(id, data, sharedContext?): Promise&#60;[RegionDTO](types.RegionDTO.mdx)&#62;

This method updates an existing region.

Example​

const region = await regionModuleService.update("reg_123", {
  automatic_taxes: false,
})

Parameters​

idstringRequired
The ID of the region.
dataUpdateRegionDTORequired
The attributes to update in the region.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionDTO>Required
The updated region.

**update**(selector, data, sharedContext?): Promise&#60;[RegionDTO](types.RegionDTO.mdx)[]&#62;

This method updates existing regions.

Example​

const region = await regionModuleService.update(
  {
    name: "Europe",
  },
  {
    automatic_taxes: false,
  }
)

Parameters​

selectorFilterableRegionPropsRequired
The filters to apply on the retrieved regions.
dataUpdateRegionDTORequired
The attributes to update in the region.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionDTO[]>Required
The updated regions.

delete​

**delete**(ids, sharedContext?): Promise&#60;void&#62;

This method deletes regions by their IDs.

Example​

await regionModuleService.delete(["reg_123", "reg_321"])

Parameters​

idsstring[]Required
The IDs of the region.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the regions are deleted.

**delete**(id, sharedContext?): Promise&#60;void&#62;

This method deletes a region by its ID.

Example​

await regionModuleService.delete("reg_123")

Parameters​

idstringRequired
The ID of the region.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void>Required
Resolves when the region is deleted.

retrieve​

This method retrieves a region by its ID.

Example​

A simple example that retrieves a region by its ID:

const region = await regionModuleService.retrieve("reg_123")

To specify relations that should be retrieved:

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

Parameters​

idstringRequired
The ID of the region.
configFindConfig<RegionDTO>
The configurations determining how the region is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a region.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionDTO>Required
The retrieved region.

list​

This method retrieves a paginated list of regions based on optional filters and configuration.

Example​

To retrieve a list of regions using their IDs:

const regions = await regionModuleService.list({
  id: ["reg_123", "reg_321"],
})

To specify relations that should be retrieved within the regions:

const regions = await regionModuleService.list(
  {
    id: ["reg_123", "reg_321"],
  },
  {
    relations: ["countries"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const regions = await regionModuleService.list(
  {
    id: ["reg_123", "reg_321"],
  },
  {
    relations: ["countries"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableRegionProps
The filters to apply on the retrieved regions.
configFindConfig<RegionDTO>
The configurations determining how the region is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a region.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionDTO[]>Required
The list of regions.

listAndCount​

This method retrieves a paginated list of regions along with the total count of available regions satisfying the provided filters.

Example​

To retrieve a list of regions using their IDs:

const [regions, count] =
  await regionModuleService.listAndCount({
    id: ["reg_123", "reg_321"],
  })

To specify relations that should be retrieved within the regions:

const [regions, count] =
  await regionModuleService.listAndCount(
    {
      id: ["reg_123", "reg_321"],
    },
    {
      relations: ["countries"],
    }
  )

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const [regions, count] =
await regionModuleService.listAndCount(
  {
    id: ["reg_123", "reg_321"],
  },
  {
    relations: ["countries"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableRegionProps
The filters to apply on the retrieved regions.
configFindConfig<RegionDTO>
The configurations determining how the region is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a region.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<[RegionDTO[], number]>Required
The list of regions along with their total count.

retrieveCountry​

This method retrieves a country by its 2 character ISO code.

Example​

A simple example that retrieves a country by its 2 character ISO code:

const country =
  await regionModuleService.retrieveCountry("us")

To specify relations that should be retrieved:

const country = await regionModuleService.retrieveCountry(
  "us",
  {
    relations: ["region"],
  }
)

Parameters​

countryIdstringRequired
The country's ID, which is the 2 character ISO code.
configFindConfig<RegionCountryDTO>
The configurations determining how the country is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a country.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionCountryDTO>Required
The retrieved country.

listCountries​

This method retrieves a paginated list of countries based on optional filters and configuration.

Example​

To retrieve a list of countries using their IDs:

const countries = await regionModuleService.listCountries({
  iso_2: ["us", "eur"],
})

To specify relations that should be retrieved within the countries:

const countries = await regionModuleService.listCountries(
  {
    iso_2: ["us", "eur"],
  },
  {
    relations: ["region"],
  }
)

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const countries = await regionModuleService.listCountries(
  {
    iso_2: ["us", "eur"],
  },
  {
    relations: ["region"],
    take: 20,
    skip: 2,
  }
)

Parameters​

filtersFilterableRegionCountryProps
The filters to apply on the retrieved countries.
configFindConfig<RegionCountryDTO>
The configurations determining how the country is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a country.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<RegionCountryDTO[]>Required
The list of countries.

listAndCountCountries​

This method retrieves a paginated list of countries along with the total count of available countries satisfying the provided filters.

Example​

To retrieve a list of countries using their IDs:

const [countries, count] =
  await regionModuleService.listAndCountCountries({
    iso_2: ["us", "eur"],
  })

To specify relations that should be retrieved within the countries:

const [countries, count] =
  await regionModuleService.listAndCountCountries(
    {
      iso_2: ["us", "eur"],
    },
    {
      relations: ["region"],
    }
  )

By default, only the first 15 records are retrieved. You can control pagination by specifying the skip and take properties of the config parameter:

const [countries, count] =
  await regionModuleService.listAndCountCountries(
    {
      iso_2: ["us", "eur"],
    },
    {
      relations: ["region"],
      take: 20,
      skip: 2,
    }
  )

Parameters​

filtersFilterableRegionCountryProps
The filters to apply on the retrieved countries.
configFindConfig<RegionCountryDTO>
The configurations determining how the country is retrieved. Its properties, such as select or relations, accept the attributes or relations associated with a country.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<[RegionCountryDTO[], number]>Required
The list of countries along with their total count.

softDelete​

This method soft deletes a region by its IDs.

Example​

await regionModuleService.softDelete(["reg_123", "reg_321"], {
  returnLinkableKeys: ["country_id"],
})

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

regionIdsstring[]Required
The regions' IDs.
configSoftDeleteReturn<TReturnableLinkableKeys>
An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated country. The object's keys are the ID attribute names of the region entity's relations, such as country_id, and its value is an array of strings, each being the ID of a record associated with the region through this relation, such as the IDs of associated countries. If there are no related records, the promise resolves to void.

restore​

This method restores soft deleted regions by their IDs.

Example​

await regionModuleService.restore(["reg_123", "reg_321"], {
  returnLinkableKeys: ["country_id"],
})

Type Parameters​

TReturnableLinkableKeysstringRequired

Parameters​

regionIdsstring[]Required
The regions' IDs.
configRestoreReturn<TReturnableLinkableKeys>
Configurations determining which relations to restore along with each of the region. You can pass to its returnLinkableKeys property any of the region's relation attribute names, such as countries.
sharedContextContext
A context used to share resources, such as transaction manager, between the application and the module.

Returns​

PromisePromise<void | Record<string, string[]>>Required
An object that includes the IDs of related records that were restored, such as the ID of associated countries. The object's keys are the ID attribute names of the region entity's relations, such as country_id, and its value is an array of strings, each being the ID of the record associated with the region through this relation, such as the IDs of associated countries. If there are no related records restored, the promise resolves to void.
Was this section helpful?
© 2025 Medusa, Inc. All rights reserved.