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.

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.

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 endpoint:

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

Report Incorrect CodeCopy to Clipboard

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

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

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

  // ...
}

export default CreateDiscount

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

curl -L -X POST '<BACKEND_URL>/admin/discounts' \
-H 'Authorization: Bearer <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
}'

Report Incorrect CodeCopy to Clipboard

This request accepts many request-body parameters including:

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

This request returns the full discountCopy to Clipboard object.

---

Update Discount

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

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

Report Incorrect CodeCopy to Clipboard

import { useAdminUpdateDiscount } from "medusa-react"

const UpdateDiscount = () => {
  const updateDiscount = useAdminUpdateDiscount(discount_id)
  // ...

  const handleUpdate = () => {
    // ...
    updateDiscount.mutate({
      is_disabled: true,
    })
  }

  // ...
}

export default UpdateDiscount

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

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 discountCopy to Clipboard object in the response.

---

Manage Conditions

Create a Condition

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

You can send a request to the Create Condition endpoint 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)
})

Report Incorrect CodeCopy to Clipboard

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

const Discount = () => {
  const createCondition = useAdminDiscountCreateCondition(
    discount_id
  )
  // ...

  const handleCreateCondition = (
    operator: DiscountConditionOperator, 
    productId: string
  ) => {
    // ...
    createCondition.mutate({
      operator,
      products: [
        productId,
      ],
    })
  }

  // ...
}

export default Discount

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

This request accepts the discount ID as a path parameter.

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

• inCopy to Clipboard indicates that the discount should be applied to the specified resources in this condition. When using the Medusa JS Client, DiscountConditionOperator.INCopy to Clipboard must be used as the value.
• not_inCopy to Clipboard indicates that the discount should be applied to all resources except those specified in this condition. When using the Medusa JS Client, DiscountConditionOperator.NOT_INCopy to Clipboard 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 productsCopy to Clipboard is required.

The additional required parameter must be an array of IDs of the resources. For the previous example, productsCopy to Clipboard 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 discountCopy to Clipboard object in the response which includes all conditions under discount.rule.conditionsCopy to Clipboard.

Retrieve Condition

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

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

Report Incorrect CodeCopy to Clipboard

import { useAdminGetDiscountCondition } from "medusa-react"
import { Product } from "@medusajs/medusa"

const DiscountCondition = () => {
  const { 
    discount_condition, 
    isLoading, 
  } = useAdminGetDiscountCondition(
    discount_id, 
    conditionId
  )
  // ...

  return (
    <div>
      {isLoading && <span>Loading</span>}
      {discount_condition && (
        <>
          <span>{discount_condition.id}</span>
          <ul>
            {discount_condition.products.map(
              (product: Product) => (
                <li key={product.id}>{product.title}</li>
              )
            )}
          </ul>
        </>
      )}
    </div>
  )
}

export default DiscountCondition

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

curl -L -X GET '<BACKEND_URL>/admin/discounts/<DISCOUNT_ID>/conditions/<CONDITION_ID>&expand=products' \
-H 'Authorization: Bearer <API_TOKEN>'

Report Incorrect CodeCopy to Clipboard

This request accepts as path parameters the discount ID and the condition ID. You can optionally pass a query parameter expandCopy to Clipboard 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 expandCopy to Clipboard query parameter.

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

Update Condition

You can update a condition’s resources using the Update Condition endpoint. 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)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminDiscountUpdateCondition } from "medusa-react"
import { Product } from "@medusajs/medusa"

const DiscountCondition = () => {
  const updateCondition = useAdminDiscountUpdateCondition(
    discount_id, 
    conditionId
  )
  // ...

  const handleUpdateCondition = (productIds: string[]) => {
    updateCondition.mutate({
      products: productIds,
    })
  }

  // ...
}

export default DiscountCondition

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

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 productsCopy to Clipboard, you can’t pass in the update request product_collectionsCopy to Clipboard. You must pass in the update request a productsCopy to Clipboard array as well.

This request returns the full discountCopy to Clipboard object with the updated condition in the response.

Delete Condition

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

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

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

Report Incorrect CodeCopy to Clipboard

import { useAdminDiscountRemoveCondition } from "medusa-react"

const Discount = () => {
  const deleteCondition = useAdminDiscountRemoveCondition(
    discount_id
  )
  // ...

  const handleUpdateCondition = (conditionId: string) => {
    deleteCondition.mutate(conditionId)
  }

  // ...
}

export default Discount

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

curl -L -X DELETE '<BACKEND_URL>/admin/discounts/<DISCOUNT_ID>/conditions/<CONDITION_ID>' \
-H 'Authorization: Bearer <API_TOKEN>'

Report Incorrect CodeCopy to Clipboard

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

It returns the discountCopy to Clipboard object in the response.

---

Delete Discount

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

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

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

Report Incorrect CodeCopy to Clipboard

import { useAdminDeleteDiscount } from "medusa-react"

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

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

  // ...
}

export default Discount

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

This request accepts the discount ID as a path parameter.

It returns in the response the following fields:

• idCopy to Clipboard: The ID of the deleted discount.
• objectCopy to Clipboard: A string indicating the type of object deleted. By default, its value is discountCopy to Clipboard.
• deletedCopy to Clipboard: A boolean value indicating whether the discount was deleted or not.

---

See Also

• Use Discounts on the storefront