AdminRegionsResource

This class is used to send requests to Admin Region API Routes. All its method are available in the JS Client under the medusa.admin.regions property.

All methods in this class require user authentication.

Regions are different countries or geographical regions that the commerce store serves customers in. Admins can manage these regions, their providers, and more.

Related Guide: How to manage regions.

Methods

create

Create a region.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.create({
  name: "Europe",
  currency_code: "eur",
  tax_rate: 0,
  payment_providers: [
    "manual"
  ],
  fulfillment_providers: [
    "manual"
  ],
  countries: [
    "DK"
  ]
})
.then(({ region }) => {
  console.log(region.id);
})

Parameters

payloadAdminPostRegionsReqRequired

The region to create.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.

update

Update a region's details.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.update(regionId, {
  name: "Europe"
})
.then(({ region }) => {
  console.log(region.id);
})

Parameters

idstringRequired

The region's ID.

payloadAdminPostRegionsRegionReqRequired

The attributes to update in the region.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.

delete

Delete a region. Associated resources, such as providers or currencies are not deleted. Associated tax rates are deleted.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.delete(regionId)
.then(({ id, object, deleted }) => {
  console.log(id);
})

Parameters

idstringRequired

The region's ID.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<DeleteResponse>Required

Resolves to the deletion operation's details.

retrieve

Retrieve a region's details.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.retrieve(regionId)
.then(({ region }) => {
  console.log(region.id);
})

Parameters

idstringRequired

The region's ID.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.

list

Retrieve a list of Regions. The regions can be filtered by fields such as created_at passed in the query parameter. The regions can also be paginated.

Example

To list regions:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.list()
.then(({ regions, limit, offset, count }) => {
  console.log(regions.length);
})

By default, only the first 50 records are retrieved. You can control pagination by specifying the limit and offset properties:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.list({
  limit,
  offset
})
.then(({ regions, limit, offset, count }) => {
  console.log(regions.length);
})

Parameters

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

queryAdminGetRegionsParams

Filters and pagination configurations to apply on the retrieved regions.

Returns

ResponsePromiseResponsePromise<AdminRegionsListRes>Required

Resolves to the list of regions with pagination fields.

addCountry

Add a country to the list of countries in a region.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.addCountry(regionId, {
  country_code: "dk"
})
.then(({ region }) => {
  console.log(region.id);
})

Parameters

idstringRequired

The region's ID.

payloadAdminPostRegionsRegionCountriesReqRequired

The country to add.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.

deleteCountry

Delete a country from the list of countries in a region. The country will still be available in the system, and it can be used in other regions.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.deleteCountry(regionId, "dk")
.then(({ region }) => {
  console.log(region.id);
})

Parameters

idstringRequired

The region's ID.

country_codestringRequired

The code of the country to delete from the region.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.

addFulfillmentProvider

Add a fulfillment provider to the list of fulfullment providers in a region.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.addFulfillmentProvider(regionId, {
  provider_id: "manual"
})
.then(({ region }) => {
  console.log(region.id);
})

Parameters

idstringRequired

The region's ID.

payloadAdminPostRegionsRegionFulfillmentProvidersReqRequired

The fulfillment provider to add.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.

deleteFulfillmentProvider

Delete a fulfillment provider from a region. The fulfillment provider will still be available for usage in other regions.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.deleteFulfillmentProvider(regionId, "manual")
.then(({ region }) => {
  console.log(region.id);
})

Parameters

idstringRequired

The region's ID.

provider_idstringRequired

The ID of the fulfillment provider to delete from the region.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.

retrieveFulfillmentOptions

Retrieve a list of fulfillment options available in a region.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.retrieveFulfillmentOptions(regionId)
.then(({ fulfillment_options }) => {
  console.log(fulfillment_options.length);
})

Parameters

idstringRequired

The region's ID.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminGetRegionsRegionFulfillmentOptionsRes>Required

Resolves to the list of fulfillment options.

addPaymentProvider

Add a payment provider to the list of payment providers in a region.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.addPaymentProvider(regionId, {
  provider_id: "manual"
})
.then(({ region }) => {
  console.log(region.id);
})

Parameters

idstringRequired

The region's ID.

payloadAdminPostRegionsRegionPaymentProvidersReqRequired

The payment provider to add.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.

deletePaymentProvider

Delete a payment provider from a region. The payment provider will still be available for usage in other regions.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.regions.deletePaymentProvider(regionId, "manual")
.then(({ region }) => {
  console.log(region.id);
})

Parameters

idstringRequired

The region's ID.

provider_idstringRequired

The ID of the payment provider to delete from the region.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<AdminRegionsRes>Required

Resolves to the region's details.