medusajs/medusa · error · MedusaError

application_method.max_quantity is required when application

Error message

application_method.max_quantity is required when application_method.allocation is '${allowedAllocationForQuantity.join(" OR ")}'

What it means

For allocations in allowedAllocationForQuantity (i.e., 'each'), application_method.max_quantity is required. Per-item allocation needs an explicit cap on how many items the adjustment applies to; absence throws INVALID_DATA.

Source

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

  const allAllocationTypes: string[] = Object.values(
    ApplicationMethodAllocation
  )

  if (allocation && !allAllocationTypes.includes(allocation)) {
    throw new MedusaError(
      MedusaError.Types.INVALID_DATA,
      `application_method.allocation should be one of ${allAllocationTypes.join(
        ", "
      )}`
    )
  }

  if (
    allocation &&
    allowedAllocationForQuantity.includes(allocation) &&
    !isDefined(maxQuantity)
  ) {
    throw new MedusaError(
      MedusaError.Types.INVALID_DATA,
      `application_method.max_quantity is required when application_method.allocation is '${allowedAllocationForQuantity.join(
        " OR "
      )}'`
    )
  }

  if (
    allocation === ApplicationMethodAllocation.ONCE &&
    targetType === ApplicationMethodTargetType.ORDER
  ) {
    throw new MedusaError(
      MedusaError.Types.INVALID_DATA,
      `application_method.allocation 'once' is not compatible with target_type 'order'`
    )
  }
}

View on GitHub (pinned to 5e06e544a2)

Solutions

Add max_quantity when allocation is 'each' — set it high (e.g., a large number) for effectively unlimited items
Switch to allocation 'across' if a per-item cap is not desired (and then remove max_quantity per the other rule)
Include max_quantity in every seed/import row for each-allocated methods

Example fix

// before
application_method: { type: "percentage", value: 10, target_type: "items", allocation: "each" }

// after
application_method: { type: "percentage", value: 10, target_type: "items", allocation: "each", max_quantity: 1000 }

Defensive patterns

Strategy: validation

Validate before calling

if (allocation === ApplicationMethodAllocation.EACH && !isDefined(maxQuantity)) {
  maxQuantity = 1000 // sensible unlimited-ish cap
}

Type guard

const eachAllocationHasMaxQuantity = (am: { allocation?: string; max_quantity?: number | null }): boolean => am.allocation !== "each" || am.max_quantity !== undefined && am.max_quantity !== null

Try / catch

try { await createPromotions(...) } catch (e) { if (e.type === MedusaError.Types.INVALID_DATA && /max_quantity is required when/.test(e.message)) { /* add max_quantity and resubmit */ } throw e }

Prevention

Remember 'each' allocation requires max_quantity
Default max_quantity high for effectively unlimited
Prefer 'across' when no per-item cap is wanted

When it happens

Trigger: Creating a promotion with allocation 'each' and target_type 'items' but no max_quantity (e.g., an each-allocated percentage discount).

Common situations: Assuming max_quantity only matters for buy-get, migrating promotions where the column was nullable, forms not exposing the field for 'each' allocation.

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

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