This guide will assist you in preparing your WooCommerce shop so that ReturnPilot can connect to it and import your orders and products.

Do not connect your shop before reading this guide in full.

Introduction

Before you begin, please note that WooCommerce and ReturnPilot are distinct platforms that operate and manage data differently. As such, you will need to ensure that your shop meets the integration requirements contained in this guide. Failure to do so will lead to import errors.

Please also note that no import process is guaranteed to be perfect as we do not set the requirements on data that you provide to WooCommerce.

ReturnPilot may encounter data that is missing, invalid or incompatible. In these situations, ReturnPilot may make some changes in order to attempt a successful import. To learn more this, see the import disclaimer below.

Availability

The WooCommerce integration is now in public beta. You may occasionally encounter issues that prevent ReturnPilot from importing your orders and products. If you encounter any issues, then please contact us.

Hosting requirements

Your website / WooCommerce shop should not be hosted using a "shared hosting" plan as these are slow and unreliable.

Instead, use a dedicated provider, such as WordPress.com, Pressable, or WordPress VIP. Alternatively, ensure that you are hosting your website / WooCommerce shop using a virtual private server (VPS).

Technical requirements

• Your website must be served over HTTPS e.g. https://acme.com
• Your WooCommerce version must be 3.5 or higher.
• Your WordPress version must be 4.4 or higher.
• Ensure that any third-party security plugins you are using do not block high-frequency API requests.
• WordPress permalinks must be set to something that is easily human-readable at: Settings > Permalinks. "Day and name" is a great default, but anything aside from "Plain" should work.

Granting ReturnPilot access

The WooCommerce REST API uses a key system to control access. These keys are linked to a WordPress user on your site. To create a key for a user:

1. Go to: WooCommerce > Settings > Advanced > REST API.
2. Select "Create an API" key OR "Add Key". You’ll be taken to the "Key Details" screen.
3. Add a "Description" for the key e.g. ReturnPilot.
4. Select the User you would like to generate a key for in the dropdown.
5. Select a level of access. "Read access" is sufficient for ReturnPilot.
6. Select "Generate API Key", and WooCommerce will create API keys.
7. You should see "Consumer Key" and "Consumer Secret" keys. Use them to connect ReturnPilot via the WooCommerce panel on your organization's integrations page.

If you delete the user associated with the API key, then the key will also be deleted. In order to prevent this from happening, you might want to create a separate WordPress user that is used solely for ReturnPilot's API access.

In addition, if you revoke an API key it can no longer be used by ReturnPilot.

How it works (data synchronization)

In order for ReturnPilot to provide return support to your customers, it will import the following data from your WooCommerce shop:

• Order information (including line items and addresses).
• Product information (including variants, dimensions and weight).

No other data is imported.

In addition, ReturnPilot does not synchronize any new data it creates back to WooCommerce, this is because such an action is not necessary in order for ReturnPilot to provide its required functionality.

In other words, data transfer is only one-way (from WooCommerce to ReturnPilot).

Products

This section is divided into three sub-sections:

• Simple Requirements (the fields and data your product without variants must have).
• Variable Requirements (the fields and data your products with variants must have).
• Information (additional product details to be mindful of).

Simple requirements

All simple physical (non-digital) products must have the following:

• A unique SKU (less than 30 characters long).
• A name.
• A price.
• At least one category.
• A length (between 4 and 50 inches).
• A width (between 4 and 50 inches).
• A height (between 1 and 50 inches).
• A weight (between 1 and 50 pounds).

ReturnPilot will use the measurement system (imperial or metric) that you specify when connecting your shop, so you don't need to specify this for dimensions and weight. Simply provide the numbers for these fields.

Variable requirements

All variable physical (non-digital) products must have the following:

• A unique SKU (less than 30 characters long).
• A name.
• A price.
• At least one category.
• At least one attribute.
• A length (between 4 and 50 inches).
• A width (between 4 and 50 inches).
• A height (between 1 and 50 inches).
• A weight (between 1 and 50 pounds).
• No more than 100 variations.

Understanding the 100 variation limit

100 variations may sound like a large number, however it is important to note that each variation you add is exponential.

For example, 'size' (small, medium, large) and 'color' (red, green, blue), will result in 9 variations (3x3).

However, if you add another variation, such as 'material' (cotton, polyester, blend), you're now looking at (3x3x3), which is 27 variations.

Make sure to calculate the total number of variations for a product and that this total does not exceed 100.

Information

• Returns are not supported for digital products.
• Products or variations marked "virtual" or "downloadable" are ignored.
• Dimensions or weights that exceed the above limits will be changed to the max limits in order to be imported. Since this data is only used to make package size recommendations to the customer, this should not be a problem. The customer still retains the right to make an informed decision about the number and size of packages that they are returning.
• WooCommerce doesn't allow you to indicate whether a product can be returned. Therefore, ReturnPilot assumes that all physical products can be returned. If you have products that cannot be returned, add them to ReturnPilot via the website (either one at a item or via CSV import). Make sure to do this before publishing the products on your WooCommerce shop.

Orders

This section is divided into two sub-sections:

• Requirements (the fields and data your orders must have).
• Information (additional order details to be mindful of).

Requirements

All orders must have the following:

• A created / creation date.
• A unique order number / reference.
• A billing address customer email address.
• A shipping address first and last name.
• A shipping address first line.
• A shipping address town or city.
• A shipping address region (state or province).
• A shipping address post or zip code.
• A shipping address country.
• One or more line items, each of which must have a product SKU.

Information

• Order numbers are prefixed with "WC-" in order to differentiate them from other channels e.g. website, API, or another integration.
• Orders containing only non-physical products will be ignored.
• Orders containing a mix of physical and non-physical products will be processed, however only physical products will be imported.
• ReturnPilot will only import the first 100 line items (that correspond to physical products) within an order.

Import disclaimer

Sometimes, imported data may exceed the maximum size that a certain field permits. In these situations, ReturnPilot will trim the excess to ensure that it fits. This will usually not impact how ReturnPilot operates.