How to Manage Discounts using Admin APIs

In this document, you’ll learn how to use the Admin’s Discount APIs to manage discounts, discount conditions, and more.

Tip

If you want to learn about the Discount architecture in-depth, check out the Discount Architecture documentation instead.

Overview

Using Medusa’s Discount Admin APIs, you can manage discounts, their conditions, status, rules, and more. You can also manage dynamic discounts and their discount codes.

Scenario

You want to add or use general admin functionalities related to:

• Creating discounts of different types, configurations, and rules.
• Updating and deleting discounts.
• Managing conditions in that discount, including adding, retrieving, updating, and removing conditions.

Tip

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, 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 a Discount

You can create a discount by sending a request to the Create Discount API Route:

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

import { 
  AllocationType,
  DiscountRuleType,
} from "@medusajs/medusa"
// ...
medusa.admin.discounts.create({
  code,
  rule: {
    type: DiscountRuleType.FIXED,
    value: 10,
    allocation: AllocationType.ITEM,
  },
  regions: [
    regionId,
  ],
  is_dynamic: false,
  is_disabled: false,
})
.then(({ discount }) => {
  console.log(discount.id)
})

import { 
  useAdminCreateDiscount,
} from "medusa-react"
import { 
  AllocationType, 
  DiscountRuleType,
} from "@medusajs/medusa"

const CreateDiscount = () => {
  const createDiscount = useAdminCreateDiscount()
  // ...

  const handleCreate = (
    currencyCode: string,
    regionId: string
  ) => {
    // ...
    createDiscount.mutate({
      code: currencyCode,
      rule: {
        type: DiscountRuleType.FIXED,
        value: 10,
        allocation: AllocationType.ITEM,
      },
      regions: [
          regionId,
      ],
      is_dynamic: false,
      is_disabled: false,
    })
  }

  // ...
}

export default CreateDiscount

fetch(`<BACKEND_URL>/admin/discounts`, {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    code,
    rule: {
      type: "fixed",
      value: 10,
      allocation: "item",
    },
    regions: [
      regionId,
    ],
    is_dynamic: false,
    is_disabled: false,
  }),
})
.then((response) => response.json())
.then(({ discount }) => {
  console.log(discount.id)
})

curl -L -X POST '<BACKEND_URL>/admin/discounts' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "code": "<CODE>",
    "rule": {
      "type": "fixed",
      "value": 10,
      "allocation": "item"
    },
    "regions": [
      "<REGION_ID>"
    ],
    "is_dynamic": false,
    "is_disabled": false
}'

This request accepts many request-body parameters including:

• code: This parameter is required. It is a unique code. The customer redeems the discount using this code.
• rule: This parameter is required. It is an object having at least the following fields:
  • type: A string indicating the type of discount. It can be fixed, percentage, or free_shipping. When using the Medusa JS Client, you must use the enum type DiscountRuleType for the value.
  • value: A number indicating the value of the discount. If the discount type is fixed, then it will be the fixed amount to discount from the cart’s totals or its items. If the discount type is percentage, then it will be the percentage to discount from the items in the cart. If the type is free_shipping, it has no effect and can be set to 0.
  • allocation: A string indicating how the discount should be applied. Can be item or total. If the type is not fixed, then this has no effect. When using the Medusa JS Client, you must use the enum type AllocationType for the value.
• regions: An array of region IDs this discount can be used in. If the type of discount is fixed, only one region can be passed.

This request returns the full discount object.

---

Update Discount

You can update any of the discount’s information, configurations, and conditions by sending a request to the Update Discount API Route.

For example, you can update the discount’s description and status by sending the following request:

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

medusa.admin.discounts.update(discountId, {
  is_disabled: true,
})
.then(({ discount }) => {
  console.log(discount.id)
})

import { useAdminUpdateDiscount } from "medusa-react"

type Props = {
  discountId: string
}

const Discount = ({ discountId }: Props) => {
  const updateDiscount = useAdminUpdateDiscount(discountId)
  // ...

  const handleUpdate = (isDisabled: boolean) => {
    updateDiscount.mutate({
      is_disabled: isDisabled,
    })
  }

  // ...
}

export default Discount

fetch(`<BACKEND_URL>/admin/discounts/${discountId}`, {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    is_disabled: true,
  }),
})
.then((response) => response.json())
.then(({ discount }) => {
  console.log(discount.id)
})

curl -L -X POST '<BACKEND_URL>/admin/discounts/<DISCOUNT_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
  "is_disabled": true
}'

This request accepts the discount ID as a path parameter. You can pass the parameters you want to update in the request body. In the example above, is_disabled` parameter to update it.

You can check the API reference for all the accepted parameters to update the discount.

This updates the discount’s information and returns the full updated discount object in the response.

---

Manage Conditions

Create a Condition

Tip

You can learn more about conditions and conditions types in the Discount Architecture documentation.

You can send a request to the Create Condition API Route to create a condition in a discount:

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

import { DiscountConditionOperator } from "@medusajs/medusa"
// ...
medusa.admin.discounts.createCondition(discount_id, {
  operator: DiscountConditionOperator.IN,
  products: [
    productId,
  ],
})
.then(({ discount }) => {
  console.log(discount.id)
})

import { DiscountConditionOperator } from "@medusajs/medusa"
import { useAdminDiscountCreateCondition } from "medusa-react"

type Props = {
  discountId: string
}

const Discount = ({ discountId }: Props) => {
  const createCondition = useAdminDiscountCreateCondition(discountId)
  // ...

  const handleCreateCondition = (
    operator: DiscountConditionOperator,
    products: string[]
  ) => {
    createCondition.mutate({
      operator,
      products
    }, {
      onSuccess: ({ discount }) => {
        console.log(discount.id)
      }
    })
  }

  // ...
}

export default Discount

fetch(`<BACKEND_URL>/admin/discounts/${discountId}/conditions`,
  {
    method: "POST",
    credentials: "include",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operator: "in",
      products: [
        productId,
      ],
    }),
  }
)
.then((response) => response.json())
.then(({ discount }) => {
  console.log(discount.id)
})

curl -L -X POST '<BACKEND_URL>/admin/discounts/<DISCOUNT_ID>/conditions' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
  "operator": "in",
  "products": [
    "<PRODUCT_ID>"
  ]
}'

This request accepts the discount ID as a path parameter.

It also requires the request-body parameter operator which can have one of the following values:

• in indicates that the discount should be applied to the specified resources in this condition. When using the Medusa JS Client, DiscountConditionOperator.IN must be used as the value.
• not_in indicates that the discount should be applied to all resources except those specified in this condition. When using the Medusa JS Client, DiscountConditionOperator.NOT_IN must be used as the value.

In addition, every condition has a condition type. Based on that condition type, a different additional parameter is required for the request.

For example, if the condition type is product, meaning that the condition specifies which products this discount apply/doesn’t apply for, the parameter products is required.

The additional required parameter must be an array of IDs of the resources. For the previous example, products would be an array of product IDs.

You can check the API reference for a full list of accepted parameters based on the condition type.

This request returns the full discount object in the response which includes all conditions under discount.rule.conditions.

Retrieve Condition

You can retrieve a condition and its resources by sending a request to the Get Condition API Route:

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

medusa.admin.discounts.getCondition(
  discountId, 
  conditionId,
  {
    expand: "products",
  }
)
.then(({ discount_condition }) => {
  console.log(
    discount_condition.id,
    discount_condition.products
  )
})

import { useAdminGetDiscountCondition } from "medusa-react"

type Props = {
  discountId: string
  discountConditionId: string
}

const DiscountCondition = ({
  discountId,
  discountConditionId
}: Props) => {
  const { 
    discount_condition, 
    isLoading
  } = useAdminGetDiscountCondition(
    discountId,
    discountConditionId
  )

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {discount_condition && (
        <span>{discount_condition.type}</span>
      )}
    </div>
  )
}

export default DiscountCondition

fetch(
  `<BACKEND_URL>/admin/discounts/${discountId}` + 
  `/conditions/${conditionId}&expand=products`,
  {
    credentials: "include",
  }
)
.then((response) => response.json())
.then(({ discount_condition }) => {
  console.log(
    discount_condition.id,
    discount_condition.products
  )
})

curl -L -X GET '<BACKEND_URL>/admin/discounts/<DISCOUNT_ID>/conditions/<CONDITION_ID>&expand=products' \
-H 'x-medusa-access-token: <API_TOKEN>'

This request accepts as path parameters the discount ID and the condition ID. You can optionally pass a query parameter expand which specifies which relations to include in the returned object.

By default, this request returns the discount condition object without any of its resources (In the previous example the resources are the products). To ensure the resources are included in the returned object, you must pass the name of the condition’s type as a value to the expand query parameter.

In the previous example, you pass expand=products as a query parameter, which returns inside the discount_condition object a products attribute. The value of products is an array of products that belong to this condition.

Update Condition

You can update a condition’s resources using the Update Condition API Route. You can’t update a condition’s operator.

For example, to update the products in a condition:

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

medusa.admin.discounts.updateCondition(
  discountId, 
  conditionId, {
    products: [
      productId1,
      productId2,
    ],
  }
)
.then(({ discount }) => {
  console.log(discount.id)
})

import { useAdminDiscountUpdateCondition } from "medusa-react"

type Props = {
  discountId: string
  conditionId: string
}

const DiscountCondition = ({
  discountId,
  conditionId
}: Props) => {
  const update = useAdminDiscountUpdateCondition(
    discountId,
    conditionId
  )
  // ...

  const handleUpdate = (
    products: string[]
  ) => {
    update.mutate({
      products
    }, {
      onSuccess: ({ discount }) => {
        console.log(discount.id)
      }
    })
  }

  // ...
}

export default DiscountCondition

fetch(
  `<BACKEND_URL>/admin/discounts/${discountId}/conditions/${conditionId}`,
  {
    method: "POST",
    credentials: "include",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      products: [
        productId1,
        productId2,
      ],
    }),
  }
)
.then((response) => response.json())
.then(({ discount }) => {
  console.log(discount.id)
})

curl -L -X POST '<BACKEND_URL>/admin/discounts/<DISCOUNT_ID>/conditions/<CONDITION_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "products": [
      "<PRODUCT_ID_1>",
      "<PRODUCT_ID_2>"
    ]
}'

This request accepts as a path parameter the discount ID and the condition ID. In its body, it accepts the resources of the same type that were used when the condition was created.

For example, if a condition was created for products, you can’t pass in the update request product_collections. You must pass in the update request a products array as well.

This request returns the full discount object with the updated condition in the response.

Delete Condition

You can delete a condition by sending a request to the Delete Condition API Route:

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

medusa.admin.discounts.deleteCondition(
  discountId, 
  conditionId
)
.then(({ discount }) => {
  console.log(discount)
})

import { useAdminDiscountRemoveCondition } from "medusa-react"

type Props = {
  discountId: string
}

const Discount = ({ discountId }: Props) => {
  const deleteCondition = useAdminDiscountRemoveCondition(
    discountId
  )
  // ...

  const handleDelete = (
    conditionId: string
  ) => {
    deleteCondition.mutate(conditionId, {
      onSuccess: ({ id, object, deleted }) => {
        console.log(deleted)
      }
    })
  }

  // ...
}

export default Discount

fetch(
  `<BACKEND_URL>/admin/discounts/${discountId}/conditions/${conditionId}`,
  {
    method: "DELETE",
    credentials: "include",
  }
)
.then((response) => response.json())
.then(({ discount }) => {
  console.log(discount.id)
})

curl -L -X DELETE '<BACKEND_URL>/admin/discounts/<DISCOUNT_ID>/conditions/<CONDITION_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

This request accepts as a path parameter the discount ID and the condition ID.

It returns the discount object in the response.

---

Delete Discount

You can delete a discount by sending a request to the Delete Discount API Route:

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

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

import { useAdminDeleteDiscount } from "medusa-react"

const Discount = () => {
  const deleteDiscount = useAdminDeleteDiscount(discount_id)
  // ...

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

  // ...
}

export default Discount

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

curl -L -X DELETE '<BACKEND_URL>/admin/discounts/<DISCOUNT_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

This request accepts the discount ID as a path parameter.

It returns in the response the following fields:

• id: The ID of the deleted discount.
• object: A string indicating the type of object deleted. By default, its value is discount.
• deleted: A boolean value indicating whether the discount was deleted or not.

---

See Also

• Use Discounts on the storefront