Shipping Options

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

All hooks listed require user authentication.

A shipping option is used to define the available shipping methods during checkout or when creating a return. Admins can create an unlimited number of shipping options, each associated with a shipping profile and fulfillment provider, among other resources.

Related Guide: Shipping Option architecture.

Mutations

useAdminCreateShippingOption

This hook creates a shipping option.

Example

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

type CreateShippingOption = {
  name: string
  provider_id: string
  data: Record<string, unknown>
  price_type: string
  amount: number
}

type Props = {
  regionId: string
}

const Region = ({ regionId }: Props) => {
  const createShippingOption = useAdminCreateShippingOption()
  // ...

  const handleCreate = (
    data: CreateShippingOption
  ) => {
    createShippingOption.mutate({
      ...data,
      region_id: regionId
    }, {
      onSuccess: ({ shipping_option }) => {
        console.log(shipping_option.id)
      }
    })
  }

  // ...
}

export default Region

Mutation Function Parameters

AdminPostShippingOptionsReqAdminPostShippingOptionsReqRequired

The details of the shipping option to create.

Mutation Function Returned Data

AdminShippingOptionsResAdminShippingOptionsResRequired

The shipping option's details.

useAdminUpdateShippingOption

This hook updates a shipping option's details.

Example

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

type Props = {
  shippingOptionId: string
}

const ShippingOption = ({ shippingOptionId }: Props) => {
  const updateShippingOption = useAdminUpdateShippingOption(
    shippingOptionId
  )
  // ...

  const handleUpdate = (
    name: string,
    requirements: {
      id: string,
      type: string,
      amount: number
    }[]
  ) => {
    updateShippingOption.mutate({
      name,
      requirements
    }, {
      onSuccess: ({ shipping_option }) => {
        console.log(shipping_option.requirements)
      }
    })
  }

  // ...
}

export default ShippingOption

Hook Parameters

idstringRequired

The shipping option's ID.

Mutation Function Parameters

AdminPostShippingOptionsOptionReqAdminPostShippingOptionsOptionReqRequired

The details to update of the shipping option.

Mutation Function Returned Data

AdminShippingOptionsResAdminShippingOptionsResRequired

The shipping option's details.

useAdminDeleteShippingOption

This hook deletes a shipping option. Once deleted, it can't be used when creating orders or returns.

Example

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

type Props = {
  shippingOptionId: string
}

const ShippingOption = ({ shippingOptionId }: Props) => {
  const deleteShippingOption = useAdminDeleteShippingOption(
    shippingOptionId
  )
  // ...

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

  // ...
}

export default ShippingOption

Hook Parameters

idstringRequired

The shipping option's ID.

Mutation Function Returned Data

DeleteResponseDeleteResponseRequired

The response returned for a DELETE request.

---

Queries

useAdminShippingOptions

This hook retrieves a list of shipping options. The shipping options can be filtered by fields such as region_id or is_return passed in the query parameter.

Example

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

const ShippingOptions = () => {
  const {
    shipping_options, 
    isLoading
  } = useAdminShippingOptions()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {shipping_options && !shipping_options.length && (
        <span>No Shipping Options</span>
      )}
      {shipping_options && shipping_options.length > 0 && (
        <ul>
          {shipping_options.map((option) => (
            <li key={option.id}>{option.name}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default ShippingOptions

Hook Parameters

queryAdminGetShippingOptionsParams

Filters to apply on the retrieved shipping options.

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.

shipping_optionsShippingOption[]Required

An array of shipping options details.

useAdminShippingOption

This hook retrieves a shipping option's details.

Example

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

type Props = {
  shippingOptionId: string
}

const ShippingOption = ({ shippingOptionId }: Props) => {
  const {
    shipping_option, 
    isLoading
  } = useAdminShippingOption(
    shippingOptionId
  )

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

export default ShippingOption

Hook Parameters

idstringRequired

The shipping option's ID.

Query Returned Data

shipping_optionShippingOptionRequired

Shipping option details.