How to Manage Price Lists

In this document, you’ll learn how to use the PriceList Admin APIs to create, update, and manage prices in a price list.

Note

This document doesn't cover what price lists are and their basics. If you’re interested to learn about that, check out this documentation instead.

Prerequisites

Medusa Components

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

JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, JavaScript’s Fetch API, or cURL.

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.

Create Price List

When you create a price list, you can specify different conditions to control when the price list can be applied.

In the body of your request, aside from the required fields, you can send the following fields to apply different conditions:

{
  prices: [
    {
      region_id,
      currency_code,
      min_quantity,
      max_quantity
    }
  ],
  customer_groups: [
    {
      id
    }
  ]
}

Info

You can learn more about what the conditions you can apply on a price list and its prices in this documentation.

For example, sending the following request creates a price list with two prices: one that is applied when the maximum quantity of the product variant in the cart is 3; another is applied when the minimum quantity of the same variant in the cart is 4:

Medusa JS Client
Medusa React
Fetch API
cURL

import { 
  PriceListStatus, 
  PriceListType, 
} from "@medusajs/medusa"

medusa.admin.priceLists.create({
  name: "New Price List",
  description: "A new price list",
  type: PriceListType.SALE,
  status: PriceListStatus.ACTIVE,
  prices: [
    {
      amount: 1000,
      variant_id,
      currency_code: "eur",
      max_quantity: 3,
    },
    {
      amount: 1500,
      variant_id,
      currency_code: "eur",
      min_quantity: 4,
    },
  ],
})
.then(({ price_list }) => {
  console.log(price_list.id)
})

import { useAdminCreatePriceList } from "medusa-react"
import { 
  PriceListStatus, 
  PriceListType, 
} from "@medusajs/medusa"

type CreateData = {
  name: string
  description: string
  type: PriceListType
  status: PriceListStatus
  prices: {
    amount: number
    variant_id: string
    currency_code: string
    max_quantity: number
  }[]
}

const CreatePriceList = () => {
  const createPriceList = useAdminCreatePriceList()
  // ...

  const handleCreate = (
    data: CreateData
  ) => {
    createPriceList.mutate(data, {
      onSuccess: ({ price_list }) => {
        console.log(price_list.id)
      }
    })
  }

  // ...
}

export default CreatePriceList

fetch(`<BACKEND_URL>/admin/price-lists`, {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "New Price List",
    description: "A new price list",
    type: "sale",
    status: "active",
    prices: [
      {
        amount: 1000,
        variant_id,
        currency_code: "eur",
        max_quantity: 3,
      },
      {
        amount: 1500,
        variant_id,
        currency_code: "eur",
        min_quantity: 4,
      },
    ],
  }),
})
.then((response) => response.json())
.then(({ price_list }) => {
  console.log(price_list.id)
})

curl -L -X POST '<YOUR_BACKEND_URL>/admin/price-lists' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": "New Price List",
    "description": "A new price list",
    "type": "sale",
    "status": "active",
    "prices": [
        {
            "amount": 1500,
            "variant_id": "<VARIANT_ID>",
            "max_quantity": 3,
            "currency_code": "eur"
        },
        {
            "amount": 1000,
            "variant_id": "<VARIANT_ID>",
            "currency_code": "eur",
            "min_quantity": 4
        }
    ]
}'

This request returns the created price list.

You can check the full list of request body parameters in the API reference.

Get Price List’s Details

You can retrieve all of a price list’s details using the Get a Price List API Route:

Medusa JS Client
Medusa React
Fetch API
cURL

medusa.admin.priceLists.retrieve(priceListId)
.then(({ price_list }) => {
  console.log(price_list.id)
})

import { useAdminPriceList } from "medusa-react"

type Props = {
  priceListId: string
}

const PriceList = ({
  priceListId
}: Props) => {
  const { 
    price_list, 
    isLoading, 
  } = useAdminPriceList(priceListId)

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

export default PriceList

fetch(`<BACKEND_URL>/admin/price-lists/${priceListId}`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ price_list }) => {
  console.log(price_list.id)
})

curl -L -X GET '<BACKEND_URL>/admin/price-lists/{id}' \
-H 'x-medusa-access-token: <API_TOKEN>'

Update a Price List

After creating a price list, you can update all of its fields including its status, prices, and more using the Update Price List API Route.

For example, by sending the following request the end date of the price list will be updated:

Medusa JS Client
Medusa React
Fetch API
cURL

medusa.admin.priceLists.update(priceListId, {
  ends_at: "2022-10-11",
})
.then(({ price_list }) => {
  console.log(price_list.id)
})

import { useAdminUpdatePriceList } from "medusa-react"

type Props = {
  priceListId: string
}

const PriceList = ({
  priceListId
}: Props) => {
  const updatePriceList = useAdminUpdatePriceList(priceListId)
  // ...

  const handleUpdate = (
    endsAt: Date
  ) => {
    updatePriceList.mutate({
      ends_at: endsAt,
    }, {
      onSuccess: ({ price_list }) => {
        console.log(price_list.ends_at)
      }
    })
  }

  // ...
}

export default PriceList

fetch(`<BACKEND_URL>/admin/price-lists/${priceListId}`, {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ends_at: "2022-10-11",
  }),
})
.then((response) => response.json())
.then(({ price_list }) => {
  console.log(price_list.id)
})

curl -L -X POST '<BACKEND_URL>/admin/price-lists/<PRICE_LIST_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "ends_at": "2022-10-11"
}'

This request returns the updated price list.

For a full list of request body parameters, check out the API reference.

Manage Prices

Add Prices

You can add prices to your price list after creating it using the Update Prices API Route.

You can also set the override request body parameter to true to replace the existing prices in the price list.

For example, sending the following request adds a new price to the price list:

Medusa JS Client
Medusa React
Fetch API
cURL

medusa.admin.priceLists.addPrices(priceListId, {
  prices: [
    {
      amount: 1200,
      variant_id,
      currency_code: "eur",
    },
  ],
})
.then(({ price_list }) => {
  console.log(price_list.id)
})

import { useAdminCreatePriceListPrices } from "medusa-react"

type PriceData = {
  amount: number
  variant_id: string
  currency_code: string
}

type Props = {
  priceListId: string
}

const PriceList = ({
  priceListId
}: Props) => {
  const addPrices = useAdminCreatePriceListPrices(priceListId)
  // ...

  const handleAddPrices = (prices: PriceData[]) => {
    addPrices.mutate({
      prices
    }, {
      onSuccess: ({ price_list }) => {
        console.log(price_list.prices)
      }
    })
  }

  // ...
}

export default PriceList

fetch(`<BACKEND_URL>/admin/price-lists/${priceListId}/prices/batch`, {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prices: [
      {
        amount: 1200,
        variant_id,
        currency_code: "eur",
      },
    ],
  }),
})
.then((response) => response.json())
.then(({ price_list }) => {
  console.log(price_list.id)
})

curl -L -X POST '<BACKEND_URL>/admin/price-lists/<PRICE_LIST_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "prices": [
        {
            "amount": 1200,
            "variant_id": "<VARIANT_ID>",
            "currency_code": "eur"
        }
    ]
}'

This request returns the price list with the updated prices.

For a full list of request body parameters, check out the API reference.

Delete a Product’s Prices

You can delete all the prices of a product’s variants using the Delete Product Prices API Route:

Medusa JS Client
Medusa React
Fetch API
cURL

medusa
  .admin
  .priceLists
  .deleteProductPrices(priceListId, productId)
  .then(({ ids, object, deleted }) => {
    console.log(ids.length)
  })

import { 
  useAdminDeletePriceListProductPrices
} from "medusa-react"

type Props = {
  priceListId: string
  productId: string
}

const PriceListProduct = ({
  priceListId,
  productId
}: Props) => {
  const deleteProductPrices = useAdminDeletePriceListProductPrices(
    priceListId,
    productId
  )
  // ...

  const handleDeleteProductPrices = () => {
    deleteProductPrices.mutate(void 0, {
      onSuccess: ({ ids, deleted, object }) => {
        console.log(ids)
      }
    })
  }

  // ...
}

export default PriceListProduct

fetch(
  `<BACKEND_URL>/admin/price-lists/${priceListId}/products/${productId}/prices`,
  {
    method: "DELETE",
    credentials: "include",
  }
)
.then((response) => response.json())
.then(({ ids, object, deleted }) => {
  console.log(ids.length)
})

curl -L -X DELETE '<BACKEND_URL>/admin/price-lists/<PRICE_LIST_ID>/products/<PRODUCT_ID>/prices' \
-H 'x-medusa-access-token: <API_TOKEN>'

This request returns the IDs of the deleted prices.

Delete a Variant’s Prices

You can delete all the prices of a variant using the Delete Variant Prices API Route:

Medusa JS Client
Medusa React
Fetch API
cURL

medusa
  .admin
  .priceLists
  .deleteVariantPrices(priceListId, variantId)
  .then(({ ids, object, deleted }) => {
    console.log(ids)
  })

import { 
  useAdminDeletePriceListVariantPrices
} from "medusa-react"

type Props = {
  priceListId: string
  variantId: string
}

const PriceListVariant = ({
  priceListId,
  variantId
}: Props) => {
  const deleteVariantPrices = useAdminDeletePriceListVariantPrices(
    priceListId,
    variantId
  )
  // ...

  const handleDeleteVariantPrices = () => {
    deleteVariantPrices.mutate(void 0, {
      onSuccess: ({ ids, deleted, object }) => {
        console.log(ids)
      }
    })
  }

  // ...
}

export default PriceListVariant

fetch(
  `<BACKEND_URL>/admin/price-lists/${priceListId}/variants/${variantId}/prices`,
  {
    method: "DELETE",
    credentials: "include",
  }
)
.then((response) => response.json())
.then(({ ids, object, deleted }) => {
  console.log(ids.length)
})

curl -L -X DELETE '<BACKEND_URL>/admin/price-lists/<PRICE_LIST_ID>/variants/<VARIANT_ID>/prices' \
-H 'x-medusa-access-token: <API_TOKEN>'

This request returns the IDs of the deleted prices.

Delete Price List

You can delete a price list, and subsequently all prices defined in it, using the Delete Price List API Route:

Medusa JS Client
Medusa React
Fetch API
cURL

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

import { useAdminDeletePriceList } from "medusa-react"

type Props = {
  priceListId: string
}

const PriceList = ({
  priceListId
}: Props) => {
  const deletePriceList = useAdminDeletePriceList(priceListId)
  // ...

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

  // ...
}

export default PriceList

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

curl -L -X DELETE '<BACKEND_URL>/admin/price-lists/<PRICE_LIST_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

This request returns the ID of the deleted price list.

Was this section helpful?

Prerequisites​

Medusa Components​

JS Client​

Medusa React​

Authenticated Admin User​

Create Price List​

Get Price List’s Details​

Update a Price List​

Manage Prices​

Add Prices​

Delete a Product’s Prices​

Delete a Variant’s Prices​

Delete Price List​