medusajs/medusa · error · MedusaError

invalid_data

invalid_data

Error message

Gift card (${giftCard.code}) has no balance

What it means

validateGiftCardBalancesStep (used when preparing cart credit lines) throws when a gift card attached to the cart has a balance of zero or less. A gift card with no remaining balance cannot contribute to the cart total, so the flow aborts.

Source

Thrown at packages/plugins/loyalty/src/workflows/carts/steps/validate-gift-card-balances.ts:51

 *     "GC-XXXX": {
 *       balance: 100,
 *       credit: 150,
 *       debit: 50,
 *     }
 *   },
 * })
 */
export const validateGiftCardBalancesStep = createStep(
  "validate-gift-card-balances",
  async function ({
    giftCards,
    giftCardsBalanceMap,
  }: ValidateGiftCardBalancesStepInput) {
    for (const giftCard of giftCards) {
      const stats = giftCardsBalanceMap[giftCard.code];

      if (MathBN.convert(stats.balance).lte(0)) {
        throw new MedusaError(
          MedusaError.Types.INVALID_DATA,
          `Gift card (${giftCard.code}) has no balance`
        );
      }
    }
  }
);

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Remove the exhausted gift card from the cart before confirming
2. Show the customer an up-to-date gift card balance and let them pick another payment method
3. Re-fetch gift card stats at confirmation time and filter out zero-balance cards

Example fix

// before
await confirmCartCreditLinesWorkflow.run({ input: { cart_id: cart.id } })
// after
const active = giftCards.filter((gc) => stats[gc.code].balance > 0)
await removeGiftCardFromCartWorkflow.run({ input: { cart_id: cart.id, code: drainedGc.code } })
await confirmCartCreditLinesWorkflow.run({ input: { cart_id: cart.id } })

const usable = giftCards.filter((gc) => Number(stats[gc.code]?.balance ?? 0) > 0)

const hasGiftCardBalance = (gc: string) => Number(stats[gc]?.balance ?? 0) > 0

When it happens

Trigger: Confirming/validating a cart that still references a fully-redeemed gift card; giftCardsBalanceMap stats for that code show balance <= 0.

Common situations: The gift card was drained by a previous completed order but remained on a draft cart, or a shared gift card was used elsewhere between add-to-cart and checkout.

Related errors

• invalid_data
• invalid_data
• invalid_data
• invalid_data
• invalid_data

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