[WooCommerce] API Healthiness

Table Of Contents

  1. How QPilot Makes API Requests
  2. Connecting QPilot to the WooCommerce Rest API
  3. Common Error Responses
  4. Advanced Troubleshooting
    1. Testing the WooCommerce REST API
      1. Manually Testing QPilot Integration with Postman
    2. Configuring Permalinks
    3. Clearing Existing Values & Reconnecting

The Autoship Cloud plugin integrates your WooCommerce site with QPilot using the WooCommerce REST API (version 2).

While the Autoship Cloud plugin does not add to, change or modify your site's REST API, it is very important that your site's WooCommerce REST API is enabled and fully functional to ensure a successful connection with QPilot.
If you are experiencing issues connecting Autoship Cloud to QPilot, it's a good idea to test the WooCommerce API to ensure it is accessible and healthy.

Note: The REST API is a feature of WooCommerce and you may test your site's REST API with or without the Autoship Cloud powered by QPilot plugin being active on your site at any time by following WooCommerce's documentation here.

How QPilot Makes API Requests

Requirements 

  • Site Title
    • Your site must have a title as set in WP-Admin > Settings > General >> Site Title in order to successfully connect to QPilot.
  • Ability to make GET / POST / PUT requests over the WooCommerce REST API on your site. 

GET Request

Used to securely pass (GET) Data from WooCommerce to QPilot to keep data synchronized, including:

  • Order Data
  • Product Data
  • Customer Data
  • Tokenized Payment Data

POST Request

Used to securely create data in WooCommerce Orders when processing a Scheduled Order over WooCommerce REST API

PUT Request

Used to securely update WooCommerce Order data when processing a Scheduled Order over the REST API.
Also used to securely update product availability data for WooCommerce Products and add QPilot data to Reports and Notifications in WordPress.

Connecting QPilot to the WooCommerce Rest API

In order to ensure your site is ready to process Scheduled Orders, you need to connect QPilot to the WooCommerce Rest API. See the following article for a step-by-step guide: Connecting the WooCommerce API. When successfully connected you should see a healthy connection as shown below. 

Learn more about connecting Autoship Cloud Here: Why and How Do I connect Autoship Cloud to QPilot?

How to Update the URL of a Site Already or Previously Connected to QPilot

This is common during site migrations as outlined here: Migrating Existing Scheduled Orders to a New Site. 

  1. Go to QPilot > Sites > Edit
  2. Update the site URL in the General Settings tab
  3. Go to WP-Admin > Autoship Cloud > Settings > Connection Settings and select the "Disconnect" button
  4. Clear the values for QPilot Client Id & QPilot Client Secret then select "Update"
  5. Enter your QPilot Client Id and Client Secret from QPilot > My Account > Apps > WooCommerce and select "Connect" 
  6. Go through the connection steps as outlined here: Connecting the WooCommerce API

How to Connect a Site Copied from an Existing QPilot Site

This is common when creating staging sites (which are usually copies of the live environment). 

  1. Go to WP-Admin > Autoship Cloud > Settings > Connection Settings and select the "Disconnect" button
  2. Clear the values for QPilot Client Id & QPilot Client Secret then select "Update"
  3. Enter your QPilot Client Id and Client Secret from QPilot > My Account > Apps > WooCommerce and select "Connect" 
  4. Go through the connection steps as outlined here: Connecting the WooCommerce API

Common Error Responses

If your connection is showing as "Unhealthy" or displaying errors, you will need to isolate the issue and resolve it in order to successfully connect. Common errors and the best troubleshooting steps are outlined below. 

When reviewing an unhealthy connection status in  Autoship Cloud > Settings, you will often see an HTTP error code. If an HTTP error code does not display, check your Autoship Cloud Error Logs for a detailed error message with the HTTP code. 

400 Bad Request

The 400 error code indicates that the request is invalid, e.g. using an unsupported HTTP method.  

The error is most common with staging sites using an insecure URL ("http" instead of "https"). This is error is documented by WooCommerce's REST API docs here: https://woocommerce.github.io/woocommerce-rest-api-docs/#errors.

If this is the case, you may want to ask your hosting provider to enable your staging site to be a secure URL (use " https://mysite.staging.myhost.com" instead of "http"), so you can then connect your site's API without using the secure URL.

401 Unauthorized / 403 Forbidden

  1. First, make sure that you have met the API requirements as outlined in How QPilot Makes API Requests. 
    1. For example, if you have not set a Site Title in WordPress your site may return a HTTP 401 error. 
    2. You will also get a connection error if the WooCommerce API is not enabled on the site.
  2. Check that there is a valid WooCommerce API key for "Autoship - QPilot". The API keys are listed under WP-Admin > WooCommerce > Settings > Advanced (tab) >> REST API.
    1. If there is no API key for "Autoship - QPilot", follow the guide to Connect Autoship Cloud.
    2. Ensure that the associated user account for this API key is a site administrator with full privileges to manage WooCommerce.
  3. Ensure you have not password protected access to your site using settings on your WordPress Site or using .htaccess rules. Passwords are problematic for incoming requests and is common on some staging sites. 
    1. Note: In some cases, you can still connect a password-protected site by whitelisting QPilot IP's addresses. Learn more here: Whitelisting QPilot IP Addresses With Firewalls
  4. Disable any plugins that are blocking access to the site. Some security plugins can block incoming requests to your site and causes connection errors. 
    1. To learn more see here: Deactivating Plugins for WooCommerce Site Troubleshooting
    2. Learn more about security plugins there: Will My Security Plugin Work With Autoship Cloud?
  5. Whitelist QPilot IP Addresses in your firewall to ensure you server is not blocking incoming QPilot requests.  Learn more here: Whitelisting QPilot IP Addresses With Firewalls
  6. In some cases, invalid permalinks can cause Http 401 errors. See "Configuring Permalinks" for more information and the best next steps. 

You can learn more about 401 errors here.

401 Sorry You Are Not Allowed To Create Resources

If you are receiving this error, please see our documentation for the best next steps and more details: Error 401: Sorry You Are Not Allowed To Create Resources. You can learn more about 401 errors here.

404 Error Resources Not Found

The 404 error indicates that the request reached the server, however, the information requested was not found. If the HTTP error code error does not display on the test results for API Healthiness, it can be found in the Autoship Log. 

Examples of common redirects resulting in a 404 Error:

  • Secure to insecure site redirect ("https" redirecting to "http" protocol) 
  • A site URL that redirects to a different URL  (configured within your site's .htaccess or DNS).
  • Misconfigured Permalinks on your site (See this helpful article from WP-Beginner regarding 404 errors related to Permalinks). 
  • TLS version for your site's SSL certificate: QPilot supports up to version 1.2). If your site uses TLS version greater than 1.2 for its SSL certificate, you may experience a connection error with QPilot. 

Resolving a redirect issue:

  1. Navigate to your QPilot Merchant Account and edit your connected site's settings.
  2. Within the "General Settings" tab, edit the url of your connected site to the url your site is redirecting to. 
  3. Select "Update" to confirm your changes.
  4. After updating your url, within your WordPress Admin, visit WP-Admin > Autoship Cloud > Settings and then select "Test Integration". This will attempt to test your site's connection to QPilot and result in a healthy connection status if the issue is fixed.

500 Internal Server Error

The 500 error indicates a fatal exception has been thrown on the server. This type of error can be caused by many different types of issues, and the source of the error must be tracked down. Often times since the error is on the server, your hosting provider can be used to help with troubleshooting and fixing 500 errors.

Common Causes

  • Another plugin or theme 
  • Database or server errors (such as running out of memory)
  • Browser cache
  • WordPress Permalinks 
  • Corrupted core database files 
  • Invalid site or folder permissions 
  • Invalid permalinks (usually an HTTP 520 error)

To learn more about HTTP 500 errors see here: How to Fix a 500 Internal Server Error on Your WordPress Site.

How To Resolve an HTTP 500 Error

  1. Check your Autoship Cloud Error Logs. These logs can be accessed and reviewed in Autoship Cloud > Settings > Logs. 
  2. Check your server error logs for any obvious errors. Contact your site administrator to correct these errors then try again. 
    1. If you don't have access to your server logs, you can ask your hosting provider or site administrator. 
  3. De-activate plugins and then test the API and activate additional plugins one at a time until the source of the error is found.
    1. If you find a plugin is causing the connection error, contact the plugin author and include the error message. 
    2. Learn more here: Deactivating Plugins for WooCommerce Site Troubleshooting
  4. Change the current theme to a basic theme (for example: WooCommerce's Storefront) then test the API.  
    1. If the issue is resolved after updating your theme, then contact the theme author for assistance.  
    2. Learn more here: Switch to a "Basic" Theme for WooCommerce Site Troubleshooting
  5. If you are still getting a 500 error, the issue may be caused by invalid permalinks. See "Configuring Permalinks" for more information and the best next steps. 

Learn more about troubleshooting 500 errors here.

Healthy Connection Result with Errors Displaying

Sometimes you may see errors appear within a healthy API test response. See the example screenshot below where a 500 error is returned within a successful API test response: 

This means that it is possible to connect with the URLs (the "endpoints") for your site and successfully test your API, but your site is responding to an API request with "other" errors  (for example returning a non-standard error message or one that is not a common API response). 

This does not necessarily mean that the connection with your site is unhealthy or that Autoship Cloud's connection with QPilot is not working. Instead, it means that your site may have errors within its code. Typically, this type of situation is caused when another plugin installed on your site is causing an unexpected or fatal error. 

Suggested Steps to Resolve This Type of Error

  1. Run the "test connection" action again. 
    1. This helps clear any notices and asks QPilot to retest URLs.
    2. In some cases, the error message clears on its own. If so, this could be that the cause of this issue was resolved (with a plugin update for example) and is no longer causing the notice. 
  2. If the error persists, you'll want to debug this as you would any error within WordPress. Learn more here: What Are the Best Steps to Troubleshoot Errors With My WooCommerce Site?
    1. Enable the WP Error log ( https://wordpress.org/support/article/debugging-in-wordpress/ ). 
    2. The Error log can then be used to troubleshoot which file installed on your site might be causing the problematic response to the API Health Check. 
    3. Pro Tip! You may also configure the WP Error Log to not display to customers and provide additional error details.
PHP Warnings and Errors

Sometimes the WooCommerce API can produce PHP error messages in the response instead of properly formatted JSON.

  1. De-activate all plugins on the site except for WooCommerce and then test the API and activate additional plugins one at a time until the source of the error is found.
  2. Change the current theme to the default WordPress theme (for example, Storefront or the default "2017" WordPress theme) then test the API. These default themes should not produce any errors. 
  3. These steps are outlined here: What Are the Best Steps to Troubleshoot Errors With My WooCommerce Site?

Product Sync Related Errors

Sometimes your firewall will block HTTP requests to endpoints used by QPilot to update your product availability during product synchronization. If you are having product sync errors regarding product availability, be sure the following HTTP requests and their endpoints are not being blocked:

  1. GET: /wp-json/wc/v2/products/<id> 

  2. PUT: autoshipcloud/v1/product

After Connecting to QPilot, Connection Settings Display "Not Connected"

If the display "Not Connected" is shown after going through the connection process and QPilot redirects you back to your site, this usually indicates there was an error in authenticating your site with QPilot. If our QPilot Client Secret created in  QPilot > My Account > Apps > WooCommerce is copied incorrectly or is altered before connecting, your site will fail to be authenticated with QPilot. 

How to Verify a QPilot Site Authentication Error 

From   WP-Admin > Autoship Cloud > Settings > Connection Settings, select the Logs tab and download your Autoship Logs. An Authentication error will look like the entry below if your site failed to authenticate with QPilot. 

[12-04-2021 @ 17:01:19] Autoship Oauth Exception - An 401 Exception Occurred when attempting Oauth connection to QPilot. Additional Details: Unauthorized

See the site displaying the "Not Connected" status after going through the connection process in QPilot and where to locate your Autoship Logs in the image below

How to Resolve this Type of Connection Error

As a WordPress Administrator, log in to  QPilot Merchant Center > My Account > Apps > WooCommerce, create a new QPilot Client Secret and retry connecting the site using the new QPilot Client Secret copied to its field on the site's Connection Settings page. For detailed steps for how to connect your site to QPilot see our doc Connecting the WooCommerce API.

Advanced Troubleshooting

Testing the WooCommerce REST API

  1. Navigate to WooCommerce > Settings >> Advanced >> REST API.
  2. In older versions of WooCommerce, you may need to select "Enable the REST API" and Save Changes before proceeding.

  3. In the REST API tab, add a new API Key with the settings below:

    Description: "Test Key" (or any description you choose)
    User: Select a user who has Administrator User privileges for the Wordpress site
    Permissions: Read/Write
  4. Manually test the REST API by Making a Basic Request to test the WooCommerce API with your site.

Manually Testing QPilot Integration with Postman

Sometimes manually testing the API Healthiness with a client like Postman can assist in troubleshooting. Some hosting providers restrict access to sites, preventing site visitors (including HTTP requests from external sources like the QPilot API) from getting appropriate responses (for instance: html log in instead of the expected JSON object). Some hosting providers restrict certain HTTP requests (commonly seen: PUT or update requests). Testing the API Healthiness manually will give additional details to a failed HTTP request including request type, status, and the response body.

This is a similar test to that outlined in WooCommerce's documentation: Making a Basic Request. We use the WooCommerce API keys to authenticate make the following 3 requests:

  • GET- {your site url}/wp-json/wc/v3/products/
  • POST- {your site url}/wp-json/autoshipcloud/v1/statuscheck/post
  • PUT- {your site url}/wp-json/autoshipcloud/v1/statuscheck/put

Any failure response should be recorded to share with your hosting provider.

What if I get a different response? 

The response body will vary depending on the request URL and if there are any errors. In the example above, the response body shows a successful request. However, you may also get a response that shows a detailed error message or even code from your site. 

  • If you get an error response, find the HTTP error above for more information on common causes and troubleshooting steps. 
  • If the response body contains code from your site, you will need to contact your hosting provider for further assistance. Common causes may include Permalinks or server security. 

Permalinks can cause connection HTTP 400 and 500 errors on your site. If you suspect Permalinks are an issue, please follow and review the following: 

  1. Contact your hosting provider with the error you are experiencing.
  2. You can learn more about how to format WordPress Permalinks for WooCommerce here.
  3. To learn more about how Permalinks work with WooCommerce REST API see here.
Common Permalink Structure

A common permalink structure is shown below. If you suspect permalinks are the issue, we recommend attempting this combination and then attempting to reconnect (as outlined here). However, not all sites are the same and you may need a different setup than in this example. 

  • Set "Common Settings" to "Post Name" (https://yoursite.com/sample-post/) 

  • Set "Optional" settings to blank values except "Product category base" which can be set to "product-category" and "Product tag base" which can be set to "product-tag"

  • Set "Product permalinks" to "Custom base" and then "/shop/"

Clearing Existing Autoship Connection Setting Values & Reconnecting to QPilot

When copying a site to a staging site or when changing an existing connected site's URL, values stored by the Autoship Cloud plugin for its Connection Settings need to be updated to ensure that the site connection in QPilot is correct. Values may need to be reset during troubleshooting common connections errors as well. 

Though the steps are similar, when updating a connected site's URL in QPilot, an extra step is needed to ensure the intended connected site is updated (rather than a new site being created). QPilot connects to sites based on unique URLs, so it's important to keep an eye on your connected sites in your QPilot Merchant Center and follow the outlined steps during this process. See here for more details: Connecting QPilot to the WooCommerce Rest API

When to Try Clearing QPilot Connection Values & Reconnecting

  • When updating a site's URL
  • When a site connected to QPilot is cloned and needs to be connected as a new QPilot site
  • When an existing QPilot connected Site Id does not match the Id in the Autoship Settings Connection Settings.