We’ve just released another free update to fmEcommerce Link (Shopify Edition), our FileMaker solution for integrating your FileMaker solution with the Shopify platform. This update is mainly concerned with changes that Shopify have made to their API that require integrators to make some small changes to their API requests.
API Versioning: earlier this year Shopify announced that they were introducing API Versioning which allows them to introduce new versions of the API without breaking previous versions of the API. Versions will be released on a quarterly cycle, on the first of January, April, July, and October and are named after calendar dates, such as 2019-04 for the April 2019 release.
As a result of this change they require you to include the API Version in your HTTP request URLs. For example a request to the Orders Admin API endpoint currently looks like this:
With API Versioning include it will look like this:
To support API Versioning we’ve added a new custom function – ShopifyAPIVersion – to store the API Version number which can be easily updated over time. We’ve also updated all the URLs that are generated to include this, for example:
$$fmShopifyWebsite & "/admin/api/" & ShopifyAPIVersion & "/customers/count.json"
Shopify do allow you to continue to call the Admin API with no version, and they will return with the oldest supported version. However, they strongly recommend that you start including version numbers in order to make your application version-aware and anchor your code to a specific set of features that are guaranteed to behave in the same way for the next 12 months.
If you want to read more about API Versioning we recommend the following Shopify pages:
Deprecation of Page-Based Pagination: as part of the changes to API Versioning Shopify are deprecating page-based pagination and changing to what they call cursor-based pagination. Some customers have already started receiving notification emails from Shopify about these changes warning them to update by April 1, 2020 to avoid breaking changes.
The 2019-07 and 2019-10 Release of the API include these changes and no longer support page-based pagination, and as the API version 2019-04 will be removed on April 1, 2020 you will need to update your requests to support cursor-based pagination before then. We’ve done all the hard work for you so you can copy and paste the changes across to your existing integration or simply download the latest version of the fmEcommerce Link (Shopify Edition) solution if you are using the fmEcommerce Link file without modifications.
A typical page-based pagination request looks like this:
$$fmShopifyWebsite & "/admin/customers.json?limit=" & $limit & "&page=" & $page
You can see the “page” parameter is specified here – support for this is being removed. Instead you will make an initial request specifying the “limit” as you currently do, and if there are additional pages of results Shopify will let you know by including a response header that looks like this:
Link: <https://acmecorp.myshopify.com/admin/api/2019-10/customers.json?limit=5&page_info=eyJsYXN0X2lkIjoyODYzOTIxMjM0MTIsImxhc3RfdmFsdWUiOjODAwMDAsImRpcmVjdGlvbiI6Im5leHQifQ>; rel="next"
If there is another page of results to request you can check for a “rel=”next” value and grab the associated URL to use as the URL for the next request. When there is no rel=”next” Link returned in the response headers you no longer need to make any further requests.
We’ve updated all the scripts that request multiple records from Shopify (Get All Customers, Get All Products etc) that were using page-based pagination to the new cursor-based pagination method. We’ve added a new custom function for the native branch (getNextLink) to capture the “next” URL, and for the plug-in branch we’re using the BE_HTTP_ResponseHeaders plug-in function to do this. We’ve updated these scripts to reference the “next” URL as follows:
and have added an additional variable to store the “next” URL after each request if it exists:
Finally we’ve changed the exit condition for the loop from referencing the page number to the existence of a “next” URL:
If you want to read more about cursor-based pagination we recommend the following Shopify pages:
If you don’t update to the new cursor-based pagination format and make a request to a version of the API that doesn’t support page-based pagination you will get an error like this:
User Customisable Maximum Results Setting: we’ve also added a new field in the Interface table (RecordsLimit) to allow you to specify the maximum number of results to return when downloading multiple records from Shopify. Previously we were hardcoding the $limit variable to 50 which is the Shopify default if no value is specified. They do allow a maximum of 250 which could prove more efficient when downloading large numbers of Orders, Products etc from Shopify:
The full list of changes are listed in the version history here. Existing customers can download this version from the link on your original order email (contact us if you need the link to be reset etc). As with previous updates if you are using one of the Database Design Report analysis tools like BaseElements or FMPerception you can use these to run a comparison report between your current version/integration and the new v1.5 release to identify the changes.