All tutorials
Installing the what3words Ecwid app
The what3words Free API plan will no longer include convert-to-coordinate requests. To continue using this feature, please upgrade to one of our paid plans starting from £7.99/month. Learn more about our API plans here.
As a reminder, emergency services can make use of the what3words API for free, and we have a dedicated plan for NGOs and registered charities. If your organisation falls within these categories, please get in touch.
For any questions or assistance, feel free to reach out to support@what3words.com.
The Ecwid App adds a what3words address field to your store’s checkout page allowing your customers to easily enter and validate a what3words address when placing an order. what3words addresses can then be converted to GPS coordinates, which can then be passed onto delivery drivers allowing deliveries to arrive at right place and on time, giving a more reliable delivery experience for your customers.
To use this extension, you will need to log in/sign up to:
Visit the what3words Ecwid App in the Ecwid marketplace and select “GET” (or “INSTALL” from within your store apps page).
You will then need to authorise our app to finalise the install process.
The next step is to log in/sign up to your what3words account which will allow you to administer the app.
Once logged on to your what3words account you wil be able to access the app settings.
You will need a what3words API key to use this plugin, as it authenticates and interacts with the what3words API.
If you don’t already have a what3words API key, a message will pop up on your screen requesting you to “Get an API key”.
If you already have one or more what3words API keys, you can simply select the API key that you will be using for your Ecwid store.
If you don’t have an API key you can click the popup and follow the steps to create a new API key.
Once you have create an API key you can return to the settings screen and select the key.
The basic settings allow you to customise how the what3words Address Field is configured on your site.
The app can automatically add an address field for shipping information, allowing your customer to specify a what3words address for shipping address to help you locate your customers. Select the Add what3words Address Field to my checkout pages option for the field to appear.
A new field should now be appearing on your checkout under the shipping address. When a what3words address is captured in this field, it will be saved alongside your order details and will be visible on order preview and shipping label screens.
In Ecwid, the what3words address attributes are stored as extraFields and orderExtraFields in the Orders endpoints of the Ecwid Orders REST API.
Please follow this guide to be able to access the Ecwid API.
The API request to make to the Ecwid Orders REST API should be:
GET https://app.ecwid.com/api/v3/{{store_id}}/orders/{{order_id}}, e.g. GET https://app.ecwid.com/api/v3/75142703/orders/10POS
The API response should be:
{ "id": "10POS", ... "extraFields": { "w3w_address": "///filled.count.slap", "w3w_nearest": "Wednesfield, West Midlands", "w3w_lat": "52.599329", "w3w_lng": "-2.083533" }, "orderExtraFields": [ { "id": "w3w_address", "value": "///filled.count.slap", "customerInputType": "", "title": "what3words address", "orderDetailsDisplaySection": "shipping_info", "orderBy": "3", "showInNotifications": true, "showInInvoice": true }, { "id": "w3w_nearest", "value": "Wednesfield, West Midlands", "customerInputType": "", "title": "what3words nearest place", "orderDetailsDisplaySection": "shipping_info", "orderBy": "4", "showInNotifications": true, "showInInvoice": true }, { "id": "w3w_lat", "value": "52.599329", "customerInputType": "", "title": "what3words latitude", "orderDetailsDisplaySection": "shipping_info", "orderBy": "5", "showInNotifications": true, "showInInvoice": true }, { "id": "w3w_lng", "value": "-2.083533", "customerInputType": "", "title": "what3words longitude", "orderDetailsDisplaySection": "shipping_info", "orderBy": "6", "showInNotifications": true, "showInInvoice": true } ], ... }
If you are using the Free plan and have enabled the save coordinates feature in your plugin settings, you are making convert-to-coordinate requests, which are not supported under the Free plan. You might encounter the following errors:
- You should see an error message:
Transport errorunder the what3words address field at the checkout page. - In the network panel, look for
Error 402: Payment Required. The response to this error is:
{ "error": { "code": "QuotaExceeded", "message": "Quota Exceeded. Please upgrade your usage plan, or contact support@what3words.com" } }
We are actively working on updating our plugins to prevent this error by disabling the save coordinates feature when the API key is registered under a Free plan.
For more information, visit our API plans page. If you need further assistance, contact support@what3words.com.
Additional settings
It is possible to the coordinates for the what3words address by selecting Save coordinates checkbox.
The coordinates will be added to your order and visible in your Sales page on Ecwid.
Note: this uses an additional what3words API call to convert the what3words address to coordinates. Please ensure the tier you have signed up to covers the amount of usage you intend to do to avoid interruption of service.
It is possible to store a nearby place by selecting Save nearest place checkbox.
The nearest place info will be added to your order and visible in your Sales page on Ecwid.
You can override the default label for the address field by selecting this option and specifying the label text. We recommend using the default label with “(optional)” text where possible.
You can override the default placeholder for the address field by selecting this option and specifying the placeholder text. We recommend you use the default placeholder value, as it provides your customers with an example of how to use the what3words Address Field but it is also useful to change the address to a location in your market.
In order to provide guidance explaining what3words to the customer, you can display a tooltip explainer and its question mark icon next to the what3words field.
This message will be displayed on the tooltip explainer:
By entering your 3 word address you make it much easier for our delivery partners to find you first time. To discover your 3 word address, visit what3words.com.
We provide a number of options for clipping the AutoSuggest results, limiting the addresses that can be validated and captured. You can clip suggestions to a number of countries by providing comma separated 2 digit ISO codes for each country you wish to clip to. This will ensure suggestions provided are clipped within the countries specified. You can also clip within a circle, a bounding box or a polygon.
N.B. – When providing multiple clippings the intersection of each polygon is what forms the suggestions provided when using the what3words Address Field.
For most checkouts we recommend skipping these options as the clip to country is automatically set when a user selects a country for their billing and/or shipping information as they select a country from the dropdown menu options in the checkout form.