How to Manage Regions using Admin APIs

In this document, you’ll learn how to manage regions using the Admin APIs.

Overview

Using the region admin REST APIs, you can manage regions in your store, including creating, updating, and deleting regions.

Scenario

You want to add or use the following admin functionalities:

• List regions
• Create a region
• Update a region
• Add shipping options to a region
• Delete a Region

You can use Medusa’s Admin APIs to achieve more functionalities as well. Check out the API reference to learn more.

---

Prerequisites

Medusa Components

It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the quickstart guide to get started.

JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.

If you follow the JS Client code blocks, it’s assumed you already have Medusa’s JS Client installed and have created an instance of the client.

Medusa React

This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have Medusa React installed and have used MedusaProvider higher in your component tree.

Authenticated Admin User

You must be an authenticated admin user before following along with the steps in the tutorial.

You can learn more about authenticating as an admin user in the API reference.

---

List Regions

You can retrieve regions available on your backend using the List Regions endpoint:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.regions.list()
.then(({ regions, limit, offset, count }) => {
  console.log(regions.length)
  // display regions
})

Report Incorrect CodeCopy to Clipboard

import { Region } from "@medusajs/medusa"
import { useAdminRegions } from "medusa-react"

const Regions = () => {
  const { regions, isLoading } = useAdminRegions()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {regions && !regions.length && <span>No Regions</span>}
      {regions && regions.length > 0 && (
        <ul>
          {regions.map((region: Region) => (
            <li key={region.id}>{region.name}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default Regions

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/admin/regions`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ regions, limit, offset, count }) => {
  console.log(regions.length)
  // display regions
})

Report Incorrect CodeCopy to Clipboard

curl -L -X GET '<BACKEND_URL>/admin/regions' \
-H 'Authorization: Bearer <API_TOKEN>'

Report Incorrect CodeCopy to Clipboard

This request returns an array of regions, as well as pagination fields.

You can also pass filters and other selection query parameters to the request. Check out the API reference for more details on available query parameters.

---

Create a Region

You can create a region by sending a request to the Create a Region endpoint:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

Report Incorrect CodeCopy to Clipboard

import { useAdminCreateRegion } from "medusa-react"

const CreateRegion = () => {
  const createRegion = useAdminCreateRegion()
  // ...

  const handleCreate = () => {
    createRegion.mutate({
      name: "Europe",
      currency_code: "eur",
      tax_rate: 0,
      payment_providers: [
        "manual",
      ],
      fulfillment_providers: [
        "manual",
      ],
      countries: [
        "DK",
      ],
    })
  }

  // ...
}

export default CreateRegion

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/admin/regions`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Europe",
    currency_code: "eur",
    tax_rate: 0,
    payment_providers: [
      "manual",
    ],
    fulfillment_providers: [
      "manual",
    ],
    countries: [
      "DK",
    ],
  }),
})
.then((response) => response.json())
.then(({ region }) => {
  console.log(region.id)
})

Report Incorrect CodeCopy to Clipboard

curl -L -X POST '<BACKEND_URL>/admin/regions' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": "Europe",
    "currency_code": "eur",
    "tax_rate": 0,
    "payment_providers": [
      "manual"
    ],
    "fulfillment_providers": [
      "manual"
    ],
    "countries": [
      "DK"
    ]
}'

Report Incorrect CodeCopy to Clipboard

This request requires the following body parameters:

• nameCopy to Clipboard: The name of the region.
• currency_codeCopy to Clipboard: The 3 character ISO currency code.
• tax_rateCopy to Clipboard: The tax rate in the Region.
• payment_providersCopy to Clipboard: An array of payment processor IDs. The array must contain at least one item.
• fulfillment_providersCopy to Clipboard: An array of fulfillment provider IDs. The array must contain at least one item.
• countriesCopy to Clipboard: An array of the 2 character ISO code of the countries included in the region.

This request also accepts optional parameters, which you can view in the API reference.

The request returns the created region in the response.

---

Update a Region

You can update any of the region’s fields and configurations. The REST APIs offer different APIs for updating specific configurations, such as the Add Country endpoint.

Alternatively, you can update the details of a region using the Update a Region endpoint:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.regions.update(regionId, {
  countries: [
    "DK",
    "DE",
  ],
})
.then(({ region }) => {
  console.log(region.id)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminUpdateRegion } from "medusa-react"

const UpdateRegion = () => {
  const updateRegion = useAdminUpdateRegion(regionId)
  // ...

  const handleUpdate = () => {
    updateRegion.mutate({
      countries: [
        "DK",
        "DE",
      ],
    })
  }

  // ...
}

export default UpdateRegion

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/admin/regions/${regionId}`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    countries: [
      "DK",
      "DE",
    ],
  }),
})
.then((response) => response.json())
.then(({ region }) => {
  console.log(region.id)
})

Report Incorrect CodeCopy to Clipboard

curl -L -X POST '<BACKEND_URL>/admin/regions/<REGION_ID>' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "countries": [
      "DK",
      "DE"
    ]
}'

Report Incorrect CodeCopy to Clipboard

This request accepts in its body parameters any of the region’s fields that you want to update. In the example above, you update the list of countries that are included in that region.

You can see the list of accepted fields in the API reference.

This request returns the full object of the updated region.

In the example above, the list of countries replace any countries that were previously in the region. So, if you’re adding a country, make sure to include previously added countries as well.

---

Add a Shipping Option to a Region

You can add a shipping option to a region by sending a request to the Create Shipping Option endpoint:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.shippingOptions.create({
  name: "PostFake",
  region_id: regionId,
  provider_id: "manual",
  data: {
  },
  price_type: "flat_rate",
  amount: 1000,
})
.then(({ shipping_option }) => {
  console.log(shipping_option.id)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminCreateShippingOption } from "medusa-react"

const Region = () => {
  const createShippingOption = useAdminCreateShippingOption()
  // ...

  const handleCreate = () => {
    createShippingOption.mutate({
      name: "PostFake",
      region_id: regionId,
      provider_id: "manual",
      data: {
      },
      price_type: "flat_rate",
      amount: 1000,
    })
  }

  // ...
}

export default Region

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/admin/shipping-options`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "PostFake",
    region_id: regionId,
    provider_id: "manual",
    price_type: "flat_rate",
    data: {
    },
    amount: 1000,
  }),
})
.then((response) => response.json())
.then(({ shipping_option }) => {
  console.log(shipping_option.id)
})

Report Incorrect CodeCopy to Clipboard

curl -L -X POST '<BACKEND_URL>/admin/shipping-options' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": "PostFake",
    "region_id": "<REGION_ID>",
    "provider_id": "manual",
    "price_type": "flat_rate",
    "data": {},
    "amount": 1000
}'

Report Incorrect CodeCopy to Clipboard

This request requires the following body parameters:

• nameCopy to Clipboard: The name of the shipping option.
• region_idCopy to Clipboard: The ID of the region.
• provider_idCopy to Clipboard: The ID of the fulfillment provider. The fulfillment provider must be enabled in the region.
• dataCopy to Clipboard: An object of data needed for the fulfillment provider to handle shipping with this shipping option. If none is required, you can pass an empty object.
• price_typeCopy to Clipboard: The price type of the shipping option. Can be flat_rateCopy to Clipboard for fixed price, or calculatedCopy to Clipboard for prices that are calculated using custom logic.
• If price_typeCopy to Clipboard is flat_rateCopy to Clipboard, the amountCopy to Clipboard field is then required. It is the price of the shipping option. If price_typeCopy to Clipboard is calculatedCopy to Clipboard, amountCopy to Clipboard is not required.

The is_returnCopy to Clipboard body parameter can also be passed if the shipping option is a return shipping option. Its boolean value indicates whether the shipping option is a return option or not.

This request accepts other optional body parameters, which you can learn more about in the API reference.

This request returns the created shipping option.

You can also manage shipping options such as list, update, and delete. You can learn more in the API reference.

---

Delete a Region

You can delete a region by sending a request to the Delete a Region endpoint:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.regions.delete(regionId)
.then(({ id, object, deleted }) => {
  console.log(id)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminDeleteRegion } from "medusa-react"

const Region = () => {
  const deleteRegion = useAdminDeleteRegion(regionId)
  // ...

  const handleDelete = () => {
    deleteRegion.mutate()
  }

  // ...
}

export default Region

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/admin/regions/${regionId}`, {
  credentials: "include",
  method: "DELETE",
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
  console.log(id)
})

Report Incorrect CodeCopy to Clipboard

curl -L -X DELETE '<BACKEND_URL>/admin/regions/<REGION_ID>' \
-H 'Authorization: Bearer <API_TOKEN>'

Report Incorrect CodeCopy to Clipboard

This request requires the region ID as a path parameter. It deletes the region and returns the following fields:

• idCopy to Clipboard: The ID of the deleted region.
• objectCopy to Clipboard: The type of object that was deleted. In this case, the value will be regionCopy to Clipboard.
• deletedCopy to Clipboard: A boolean value indicating whether the region was deleted.

---

See Also

• Use regions on the storefront