(almost) Everything they don’t tell you in the API docs!
If you’re like me, you jump into the API documentation of a new service with excitement and trepidation. Will I find what I need- code examples, requirements, troubleshooting, robust help docs, OR will I find a basic schema and no actual requirements for how to make the darn thing function? Well in the case of SharpSpring, it’s a bit of both. They have schemas and basic function documentation, but unfortunately they never really spell out where and how you can and can’t perform the various functions of their Shopping Cart Integration.
For the purposes of this article I’m assuming that you are in the thick of integrating your shopping cart with SharpSpring, have at least skimmed the documentation, and are trying to figure out why things aren’t working the way you expect them to.
Before I get started outlining what I learned through my own trial and error, here are some key links you’ll need in your journey:
- SharpSpring Shopping Cart Integration Help Docs
- SharpSpring API Documentation (login required)
- SharpSpring API Wrapper on GitHub (not necessarily, but helpful)
I like to use some kind of API wrapper when I can— they just make initiating the connection and performing basic tasks easier and less repetitive to code.
Familiarize yourself with the basic, often contradictory, API needs
- Tracking code MUST be present on the page– and before the shopping cart tracking code because sends over your account #. In the Tracking Code documentation it says to place it before the closing </body> tag, but in the Shopping Cart Tracking documentation it says the tracking code should go in the <head>. I moved mine to the <head> and it worked, so lets just stick with that for now.
- When do I put in the setTransaction piece of the API call? It says you put it in more than once to continually update the order, but what exactly does that mean? Well I’ll tell you!
- First you use it to start the whole process- setting the transaction key is what ties the whole thing together
- Then you NEED to include it before you add any products/services to the transaction. If you don’t while they may add to the Products in SharpSpring, they won’t be part of the transaction. You only need to include it once if you are adding more than one product at a time.
- You do NOT need to include it when you complete the transaction.
Are you trying to include your addProduct call into an AJAX request or other JS? Sorry no dice.
One of the most interesting things I found was that you cannot include any of this in AJAX requests or inside of other JS. When I did this it added the products to the product database in SharpSpring, but not to the transaction, which doesn’t do me any good.
Setting transaction, adding products, or completing the transaction MUST be done towards the top of your page and happen as part of the normal page load- no (document).ready, no AJAX requests, no nothin’.
So basically the most reliable way to add anything to the transaction is via PHP variables, which when you’re dealing with a custom shopping cart, isn’t always the way you want to do it. But sorry, that’s how it is. Don’t waste your time trying to make it work, it will only end in heartbreak.
But wait, there’s more!
So you’ve gotten this all sorted out and your transactions are going into SharpSpring successfully, congrats! High five!
But wait, you probably want to take that data and use it to insert customers into workflows right? I mean cart abandonment is why we’re here right? Well tough nuggets, SharpSpring doesn’t let you access anything in the transaction to use in workflows (as of 11/2016). At the very least we’d want to know what sort of products they were interested in before they jumped ship right?
Here’s what I did:
- Create a custom field in SharpSpring- I used a checkbox one because I’d want to have multiple values selected.
- Name the values for the field after the name you’ll be able to pass from your shopping cart, that’ll make your life easier 🙂
- You’ll be using the “updateLeads” function in the API. Use the wrapper I linked earlier to make life a little easier when it comes to setting up the API connection.
- You will need to do a getFields API query to retrieve the systemName of the field you want to tie into- it’s a pain, but it seems to be the only way to get it.
- Secondly- I couldn’t get the ID of the Lead to work, so I had to tie in to the Email Address. But this is okay because there isn’t anything for our workflows to do if they have no email address anyway. Hoping to improve this in the future!
- Add this code in around the same spot that you do your addTransaction calls from earlier- you’re using the same data so it’s probably an intuitive spot to do it.
- Test! Test it with a single product added, test it with multiple products added, test it until the cows come home!
Shopping cart abandonment is an artform.
As always lots of folks promise a painless integration (some more than others) but even integration that seems simple is going to have some hiccups and nuances that make it trickier. Add in using a custom shopping cart system like I was and it can cause all kinds of fun edge case problems! Either way, I hope this helps you get past some of the sticking points I can into.