Troubleshooting Wix Pricing Plans API: Resolving "INVALID_PATCH" Errors During Plan Updates

Understanding the "INVALID_PATCH" Error in Wix Pricing Plans API Updates

The Wix Pricing Plans V3 REST API allows developers to programmatically manage pricing plans for Wix stores. However, developers sometimes encounter the "INVALID_PATCH" error when attempting to update existing plans. This article analyzes a recent Wix Studio community forum discussion about this error and provides insights and solutions for store owners and developers.

The Problem: "Missing Hierarchies" During Plan Updates

According to the Wix Studio community forum, a developer encountered an "INVALID_PATCH" error with the message "Missing Hierarchies" when using the Pricing Plans V3 REST API to update a pricing plan. The developer stated they were sending a complete payload, not a partial update, and were strictly following the API documentation. The payload included the following fields:

id
revision
name
description
pricingVariants (Array of 1)
pricingVariants[0].fees (Array, empty or filled)
pricingVariants[0].billingTerms (Complete object)
image (tried both String URI and Object)

Despite including all these fields, the API returned the "INVALID_PATCH" error, indicating a discrepancy between the provided data and the expected structure.

Possible Causes and Solutions

The "INVALID_PATCH" error often arises from inconsistencies between the data being sent in the update request and the existing data structure of the pricing plan. Here's a breakdown of potential causes and corresponding solutions:

1. Data Type Mismatch: Ensure that the data types of all fields in your payload match the expected data types defined in the Wix Pricing Plans API documentation. For example, if a field is expected to be a number, ensure that you are not sending a string.
2. Missing Required Fields: Even if you are sending a complete payload, double-check that all required fields, including nested fields within objects and arrays, are present and correctly formatted. Refer to the Wix API documentation for a comprehensive list of required fields for the pricingVariants and billingTerms objects.
3. Incorrect Field Mask (if used): While the developer in the forum explicitly stated that they were not using a fieldMask, it's crucial to understand its purpose. If you intend to update only specific fields, you must use the fieldMask to specify which fields are being updated. An incorrect or missing fieldMask can lead to the "INVALID_PATCH" error. If providing a fieldMask, make sure all the fields you are patching are included.
4. Revision Mismatch: The revision field is crucial for ensuring that you are updating the correct version of the pricing plan. If the revision value in your request does not match the current revision of the plan in the Wix database, the update will fail. Always fetch the latest plan details before attempting an update and use the revision value from the fetched data in your update request.
5. Image Field Issues: The developer mentioned trying both a String URI and an Object for the image field. Ensure that the format of the image data (either URI or object) conforms precisely to the Wix API documentation. If using an object, verify that all required properties within the object (e.g., src, alt) are present and correctly formatted. Consider using the Media Manager API to upload images and obtain the correct URI or object representation.

Step-by-Step Troubleshooting Guide

Follow these steps to troubleshoot the "INVALID_PATCH" error:

1. Fetch the Latest Plan Data: Before attempting any update, use the GET endpoint of the Pricing Plans API to retrieve the current state of the pricing plan you want to modify. This ensures you have the correct revision and the latest data structure.
2. Validate Your Payload: Compare your update payload with the data you retrieved in step 1. Pay close attention to data types, required fields, and the structure of nested objects and arrays.
3. Examine API Documentation: Carefully review the Wix Pricing Plans API documentation for the specific endpoint you are using (update plan). Verify that you are including all required fields and that your data is formatted correctly.
4. Test with Minimal Changes: Start by making a small, incremental change to the plan (e.g., updating the plan name). If the update succeeds, gradually add more changes until you identify the specific field or data structure causing the error.
5. Inspect API Responses: Carefully examine the API response for detailed error messages. The response may provide clues about the specific field or data structure causing the "INVALID_PATCH" error.

Conclusion

The "INVALID_PATCH" error when updating Wix Pricing Plans can be frustrating, but by carefully examining your payload, referring to the API documentation, and following the troubleshooting steps outlined above, you can identify and resolve the issue. Remember to always fetch the latest plan data before attempting an update and to pay close attention to data types, required fields, and the structure of nested objects and arrays.