Shopify has introduced a new error code, FREE_GIFT_CARD_NOT_ALLOWED, to the SubscriptionBillingAttemptErrorCode enum. This error is triggered when a subscription contract includes a gift card product with a purchase price of $0, which violates Shopify's business rules. While uncommon, this situation can arise through edge cases in dynamic pricing scenarios, such as when bundles or cart transformations inadvertently set a gift card's price to zero within a subscription contract.
For developers building subscription features on Shopify, this new error code provides clearer visibility into billing failures and their root causes. Previously, gift card pricing issues in subscriptions might have triggered generic error responses, making debugging difficult. Now, developers can specifically identify when a free gift card is the culprit and handle it appropriately in their applications. This is particularly important for apps that implement dynamic pricing, bundling, or custom cart transformation logic.