Regions

Queries and Mutations listed here are used to send requests to the Admin Region API Routes.

All hooks listed require 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.

Mutations

useAdminCreateRegion

This hook creates a region.

Example

import React from "react"
import { useAdminCreateRegion } from "medusa-react"

type CreateData = {
  name: string
  currency_code: string
  tax_rate: number
  payment_providers: string[]
  fulfillment_providers: string[]
  countries: string[]
}

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

  const handleCreate = (regionData: CreateData) => {
    createRegion.mutate(regionData, {
      onSuccess: ({ region }) => {
        console.log(region.id)
      }
    })
  }

  // ...
}

export default CreateRegion

Mutation Function Parameters

AdminPostRegionsReqAdminPostRegionsReqRequired

The details of the region to create.

Mutation Function Returned Data

AdminRegionsResAdminRegionsResRequired

The region's details.

useAdminUpdateRegion

This hook updates a region's details.

Example

import React from "react"
import { useAdminUpdateRegion } from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const updateRegion = useAdminUpdateRegion(regionId)
  // ...

  const handleUpdate = (
    countries: string[]
  ) => {
    updateRegion.mutate({
      countries,
    }, {
      onSuccess: ({ region }) => {
        console.log(region.id)
      }
    })
  }

  // ...
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Mutation Function Parameters

AdminPostRegionsRegionReqAdminPostRegionsRegionReqRequired

The details to update of the regions.

Mutation Function Returned Data

AdminRegionsResAdminRegionsResRequired

The region's details.

useAdminDeleteRegion

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

Example

import React from "react"
import { useAdminDeleteRegion } from "medusa-react"

type Props = {
  regionId: string
}

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

  const handleDelete = () => {
    deleteRegion.mutate(void 0, {
      onSuccess: ({ id, object, deleted }) => {
        console.log(id)
      }
    })
  }

  // ...
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Mutation Function Returned Data

DeleteResponseDeleteResponseRequired

The response returned for a DELETE request.

useAdminRegionAddCountry

This hook adds a country to the list of countries in a region.

Example

import React from "react"
import { useAdminRegionAddCountry } from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const addCountry = useAdminRegionAddCountry(regionId)
  // ...

  const handleAddCountry = (
    countryCode: string
  ) => {
    addCountry.mutate({
      country_code: countryCode
    }, {
      onSuccess: ({ region }) => {
        console.log(region.countries)
      }
    })
  }

  // ...
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Mutation Function Parameters

AdminPostRegionsRegionCountriesReqAdminPostRegionsRegionCountriesReqRequired

The details of the country to add to the region.

Mutation Function Returned Data

AdminRegionsResAdminRegionsResRequired

The region's details.

useAdminRegionRemoveCountry

This hook deletes 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 React from "react"
import { useAdminRegionRemoveCountry } from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const removeCountry = useAdminRegionRemoveCountry(regionId)
  // ...

  const handleRemoveCountry = (
    countryCode: string
  ) => {
    removeCountry.mutate(countryCode, {
      onSuccess: ({ region }) => {
        console.log(region.countries)
      }
    })
  }

  // ...
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Mutation Function Parameters

stringstringRequired

The code of the country to delete from the region.

Mutation Function Returned Data

AdminRegionsResAdminRegionsResRequired

The region's details.

useAdminRegionAddFulfillmentProvider

This hook adds a fulfillment provider to the list of fulfullment providers in a region.

Example

import React from "react"
import { 
  useAdminRegionAddFulfillmentProvider
} from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const addFulfillmentProvider = 
    useAdminRegionAddFulfillmentProvider(regionId)
  // ...

  const handleAddFulfillmentProvider = (
    providerId: string
  ) => {
    addFulfillmentProvider.mutate({
      provider_id: providerId
    }, {
      onSuccess: ({ region }) => {
        console.log(region.fulfillment_providers)
      }
    })
  }

  // ...
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Mutation Function Parameters

AdminPostRegionsRegionFulfillmentProvidersReqAdminPostRegionsRegionFulfillmentProvidersReqRequired

The details of the fulfillment provider to add to the region.

Mutation Function Returned Data

AdminRegionsResAdminRegionsResRequired

The region's details.

useAdminRegionDeleteFulfillmentProvider

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

Example

import React from "react"
import { 
  useAdminRegionDeleteFulfillmentProvider
} from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const removeFulfillmentProvider = 
    useAdminRegionDeleteFulfillmentProvider(regionId)
  // ...

  const handleRemoveFulfillmentProvider = (
    providerId: string
  ) => {
    removeFulfillmentProvider.mutate(providerId, {
      onSuccess: ({ region }) => {
        console.log(region.fulfillment_providers)
      }
    })
  }

  // ...
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Mutation Function Parameters

stringstringRequired

The fulfillment provider's ID to delete from the region.

Mutation Function Returned Data

AdminRegionsResAdminRegionsResRequired

The region's details.

useAdminRegionAddPaymentProvider

This hook adds a payment provider to the list of payment providers in a region.

Example

import React from "react"
import { 
  useAdminRegionAddPaymentProvider
} from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const addPaymentProvider = 
    useAdminRegionAddPaymentProvider(regionId)
  // ...

  const handleAddPaymentProvider = (
    providerId: string
  ) => {
    addPaymentProvider.mutate({
      provider_id: providerId
    }, {
      onSuccess: ({ region }) => {
        console.log(region.payment_providers)
      }
    })
  }

  // ...
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Mutation Function Parameters

AdminPostRegionsRegionPaymentProvidersReqAdminPostRegionsRegionPaymentProvidersReqRequired

The details of the payment provider to add to the region.

Mutation Function Returned Data

AdminRegionsResAdminRegionsResRequired

The region's details.

useAdminRegionDeletePaymentProvider

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

Example

import React from "react"
import { 
  useAdminRegionDeletePaymentProvider
} from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const removePaymentProvider = 
    useAdminRegionDeletePaymentProvider(regionId)
  // ...

  const handleRemovePaymentProvider = (
    providerId: string
  ) => {
    removePaymentProvider.mutate(providerId, {
      onSuccess: ({ region }) => {
        console.log(region.payment_providers)
      }
    })
  }

  // ...
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Mutation Function Parameters

stringstringRequired

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

Mutation Function Returned Data

AdminRegionsResAdminRegionsResRequired

The region's details.

---

Queries

useAdminRegions

This hook retrieves 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 React from "react"
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) => (
            <li key={region.id}>{region.name}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default Regions

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

import React from "react"
import { useAdminRegions } from "medusa-react"

const Regions = () => {
  const { 
    regions, 
    limit,
    offset,
    isLoading
  } = useAdminRegions({
    limit: 20,
    offset: 0
  })

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

export default Regions

Hook Parameters

queryAdminGetRegionsParams

Filters and pagination configurations to apply on the retrieved regions.

Query Returned Data

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

countnumberRequired

The total number of items available.

regionsRegion[]Required

An array of regions details.

useAdminRegion

This hook retrieves a region's details.

Example

import React from "react"
import { useAdminRegion } from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const { region, isLoading } = useAdminRegion(
    regionId
  )

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {region && <span>{region.name}</span>}
    </div>
  )
}

export default Region

Hook Parameters

idstringRequired

The region's ID.

Query Returned Data

regionRegionRequired

Region details.

useAdminRegionFulfillmentOptions

This hook retrieves a list of fulfillment options available in a region.

Example

import React from "react"
import { 
  useAdminRegionFulfillmentOptions
} from "medusa-react"

type Props = {
  regionId: string
}

const Region = ({
  regionId
}: Props) => {
  const { 
    fulfillment_options, 
    isLoading
  } = useAdminRegionFulfillmentOptions(
    regionId
  )

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {fulfillment_options && !fulfillment_options.length && (
        <span>No Regions</span>
      )}
      {fulfillment_options && 
        fulfillment_options.length > 0 && (
        <ul>
          {fulfillment_options.map((option) => (
            <li key={option.provider_id}>
              {option.provider_id}
            </li>
          ))}
        </ul>
          )}
    </div>
  )
}

export default Region

Hook Parameters

regionIdstringRequired

The region's ID.

Query Returned Data

fulfillment_optionsFulfillmentOption[]Required

Fulfillment providers details.