Keeping Your Customers up to date.
Learn how you can leverage some new API features when syncing your customers with Square’s APIs.
Heads up, we’ve moved! If you’d like to continue keeping up with the latest technical content from Square please visit us at our new home https://developer.squareup.com/blog
Square customer management can usually meet all your needs, but at times you might need to keep your customer directory in sync with another customer database or order management system. Luckily some new changes to our APIs make that easier than ever.
In this post we will cover the use case of nightly syncs between a customer directory in Square and a different database. We’ll use a local SQLite database as the other database to sync customers to and Node.js for all of our programming. At a high level, we will use the SearchCustomers endpoint to find recently updated and added customers from our customer directory and then insert them into our SQLite database. Then we will do the same thing on the other side to sync customers back to Square that might have been added into our other database independently through other means. Remember, if you are using OAuth to access data belonging to a Square seller, you must have their permission to access or sync any data associated with their Square account to a different database.
Setup: Initializing the local database and getting API credentials.
Setting up my local database only needs a couple lines of Node.js thanks to the
sqlite3 package. I am using a local file (
database.db) to store my database and a table structure similar to the response bodies of the customer objects.
npm install square-connect and
require()ing it in my app.
Getting recently added & updated customers from Square.
There are two types of information changes that we might want to sync from our Square customer directory to our other database: new customers and customers who have had their information updated. Luckily the new SearchCustomers endpoint makes it easy to get both of those groups of customers with as few of API calls as possible.
To get the customers that were recently created, we’ll use the
created_at filter with SearchCustomers. This allows us to filter all of the returned results to only those that were created within a window of times that we specify. This code looks for the customers that were created within the last day, but it could just as easily poll for customers made within the last 5 minutes, or use a timestamp that the directories were last successfully synced to be the start of the window. We could also use the ListCustomers endpoint with the
sort_field parameter to list our customers by their creation date, and then just go through that list until we reach our last synced date. Search customers is a better choice since it has the ability to return more customer entries as well as only the ones within a specified window of time.
Getting customers that were recently update is just as easy. We’ll swap out the
created_at parameter for
updated_at in our request body and specify the same time window. This is a big improvement over using the ListCustomers endpoint and having to sync the entire customer directory to find any updates.
This approach is somewhat naive, and doesn’t handle paging. If you are syncing more than 1000 newly created or updated customers for a given time window, you will get back a
cursor parameter that you will need to use to get the next page of results. You can learn more about pagination in my previous post Tips and Tricks for API Pagination.
Syncing customers to Square
The base case here is pretty simple as well, but in practice it will probably be a little more complex for your own database. We can select the rows that are not in our Square Customer Directory and then run them through the CreateCustomer endpoint. We could identify these customers in many different ways, a
source field, entries that don’t have a Square id yet, or looking at customers that were created since the last time the databases have been synced.
This is just a taste of some of the useful situations the new features in our Customers APIs can be used for. Remember, you will likely need to consider some of the trade offs when implementing this with your own system. Should you sync every day, week, hour? How will your data models be translated between systems? Your implementation will differ depending on how many customers you have, where you sync them to, and what you want to do with that customer information. If you have any questions, or want to share examples of how are syncing customers, feel free to respond to this post, tell us on twitter or our slack community, and sign up for our newsletter to stay up to date with new releases.