Managing variant not found errors
Issue
Recharge uses the variant ID to connect the subscription item on Recharge with the product on your ecommerce platform. If you have recently updated your products or made changes that impact your products on your ecommerce platform the variant ID associated with the subscription item may need to be updated to ensure that orders do not run into errors when they are processed. If the variant ID is not updated the system cannot reference the product associated with the subscription and cannot process the order.
If the variant ID is not updated, Recharge will return a missing variant, variant not found or variant removed error message.
Environment
- This issue may appear on all platforms but is most likely on Shopify if you use product-based apps or import products to update.
Resolution
For subscription products
To resolve the variant error swap the existing product to the latest version on the customer's profile.
If you would like to process immediately, once the product has been swapped, retry the order by clicking Actions and selecting Retry beside the error charge.
If you have many missing variant errors to update, you can adjust in bulk.
For one-time products
For one-time products, the swap function is not available. To resolve the variant error, you must delete the one-time product from the customer's subscription and then manually re-add the product to the customer's account.
If you would like to process immediately once the product has been re-added, retry the order by clicking Actions and selecting Retry beside the error charge.
For free gifts added via flows
Free gift products that are automatically added through flows do not appear as one-time products in the customer’s subscription profile. Instead, they are only visible within the order details.
If a free gift product is the cause of a variant not found error on a charge, you’ll need to remove the gift item and then re-add it using the Import Tool. This ensures the correct variant is properly associated moving forward.
For step-by-step instructions, please refer to our guide How to bulk add or remove free gifts using the Import tool.
Identifying potential variant errors
The Charges - Errors export only includes charges that have already encountered an error when Recharge attempted to process them. It does not include upcoming charges that may still contain outdated or invalid variant IDs.
To proactively prevent future variant not found errors, it is recommended to:
- Download the Charges - Queued export and set the date range up to one year in the future.
- Review and filter the export for any charges associated with variants that no longer exist in Shopify.
- Perform a bulk product swap to update those variant IDs before the charges are processed.
The Charges - Queued export includes all scheduled charges within your selected timeframe, allowing you to identify and resolve potential issues before they result in failed orders.
Taking this proactive approach can help reduce order errors and ensure a smoother customer experience.
Preventing future errors
The most common cause for a variant change is an update to the product on Shopify. This can include, but is not limited to:
- Adding a new variant option.
- Adding variants to a product that didn't originally have variants.
- Installing applications that interact with your products.
- Removing variant options.
To avoid making changes to your variant IDs, follow these best practices:
- When you update products in Shopify, don't delete the product and create a similar one. Always edit the original product to ensure that the variant ID remains the same.
- When importing products in bulk on Shopify, select Replace any current products that have the same handle to maintain the same variant IDs for your products.
- Review third-party apps that impact products.
