medusajs/medusa · error · MedusaError

application_method.max_quantity is a required field for Prom

Error message

application_method.max_quantity is a required field for Promotion type of ${PromotionType.BUYGET}

What it means

For buy-get promotions, application_method.max_quantity (the cap on discounted items) is required. The BUYGET validation chain throws INVALID_DATA when maxQuantity is not present.

Source

Thrown at packages/modules/promotion/src/utils/validations/application-method.ts:75

  }

  if (promotion?.type === PromotionType.BUYGET) {
    if (!isPresent(applyToQuantity)) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `apply_to_quantity is a required field for Promotion type of ${PromotionType.BUYGET}`
      )
    }

    if (!isPresent(buyRulesMinQuantity)) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `buy_rules_min_quantity is a required field for Promotion type of ${PromotionType.BUYGET}`
      )
    }

    if (!isPresent(maxQuantity)) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `application_method.max_quantity is a required field for Promotion type of ${PromotionType.BUYGET}`
      )
    }

    if (!isPresent(applyToQuantity)) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `application_method.apply_to_quantity is a required field for Promotion type of ${PromotionType.BUYGET}`
      )
    }

    if (MathBN.lt(maxQuantity!, applyToQuantity!)) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `max_quantity (${maxQuantity}) must be greater than or equal to apply_to_quantity (${applyToQuantity}) for BUYGET promotions.`
      )
    }

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Add max_quantity to the buy-get application method; commonly equal to apply_to_quantity
2. Remember max_quantity >= apply_to_quantity is separately enforced — set it consistently
3. Include the field in seeds and imports for all buyget promotions

Example fix

// before
application_method: { ..., apply_to_quantity: 1, buy_rules_min_quantity: 2 }

// after
application_method: { ..., apply_to_quantity: 1, buy_rules_min_quantity: 2, max_quantity: 1 }

if (type === "buyget" && !isDefined(applicationMethod.max_quantity)) {
  applicationMethod.max_quantity = applicationMethod.apply_to_quantity ?? 1
}

const hasMaxQuantity = (am: { max_quantity?: number | null }): boolean => am.max_quantity !== undefined && am.max_quantity !== null

try { await updatePromotions(...) } catch (e) { if (e.type === MedusaError.Types.INVALID_DATA && /max_quantity is a required field/.test(e.message)) { /* default max_quantity = apply_to_quantity and retry */ } throw e }

When it happens

Trigger: Creating/updating a buyget promotion whose application_method lacks max_quantity (after apply_to_quantity and buy_rules_min_quantity passed).

Common situations: Assuming max_quantity is optional (it is optional for other types but mandatory for buyget), migration scripts copying non-buyget payloads, UI hiding the field by default.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• apply_to_quantity is a required field for Promotion type of
• buy_rules_min_quantity is a required field for Promotion typ
• application_method.apply_to_quantity is a required field for
• max_quantity (${maxQuantity}) must be greater than or equal
• Cannot add promotions to campaign where currency_code don't

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/9cc7f33257da34d0. Report an issue: GitHub.