How to Integrate HubSpot with eCommerce Websites Please note that the majority of this document is made for a technical audience. The first portions are made to help non-technical readers determine requirements of the integration. Preliminary Requirements There are a 2 pieces of information you will need before proceeding: 1. Your HubSpot product level (Small, Medium, Large) 2. The name of your shopping cart software (e.g. Volusion, Magento, Shopify, BigCommerce, osCommerce, Yahoo! Merchant Solutions, ZenCart, X-Cart, PayPal, etc.) Next, be sure you can integrate with HubSpot. This requires access to HubSpot’s API and other considerations: 1. You must be on HubSpot Medium or Large, or otherwise have the HubSpot API available. If you are on Medium or Large you have the API as a part of your HubSpot package. Don’t have HubSpot API access? Your primary HubSpot contact can assist with an upgrade; if you do not know who your primary HubSpot contact is, write to [email protected] 2. Check our HubSpot<>eCommerce integration list now and see if we already have an integration available. These are generally provided by HubSpot partners and are our recommended methods of integration. They are typically easier to set up than a fully custom integration. They may have fees associated with them to support ongoing development and maintenance. 3. If there is not an integration available for your cart yet, don’t despair! You can integrate HubSpot with any cart where you have access to the files that process your store’s checkouts. This will require a developer or someone with knowledge of your checkout processes to perform. Don’t feel comfortable looking at code? Contact a partner to perform your HubSpot integration from http://services.hubspot.com/ecommerceintegration/directory/ Lastly, please be clear on HubSpot policies regarding your future integration: 1. HubSpot's Technical Support team will NOT support or troubleshoot code you create. Do not call or query HubSpot Technical Support with specific questions about your code or integrations. Tech Support can help answer basic questions regarding API methods, but the resources below will be a better use of your time. 2. For specific questions related to your code, either contact an integration engineer at HubSpot or post your questions in HubSpot's API Google Group: http://groups.google.com/group/hubspot-api 3. HubSpot maintains its API methods for uses by HubSpot customers. HubSpot's APIs and API methods are documented at http://docs.hubapi.com/wiki/Main_Page for a technical audience. You can find non-technical HubSpot Product updates (including API updates) at: http://customers.hubspot.com/ 4. HubSpot maintains subject matter experts on eCommerce integrations and solutions inhouse. If you're not sure where to go with a specific question, there is likely someone happy to help. Reach out to your primary HubSpot point of contact or [email protected] if you do not know who your primary HubSpot contact is. We will pair you with the right person to answer your questions as quickly as possible. 5. HubSpot Inc. takes no responsibility for any damages, legal, financial or otherwise, incurred as a result of code you or a partner you employ create or use when working with any of HubSpot's APIs. Check your local laws and website's terms of service to ensure compliance, and be smart about whom you employ to do work that involves your customers' data. Performing a HubSpot<>eCommerce Integration The below explains in detail how to integrate HubSpot with your eCommerce cart software. It assumes that you have the HubSpot API available, that you can make changes to your cart’s checkout processing files, and are a technical reader. Determine the points to connect HubSpot You need to determine the 2 points in your cart at which to connect HubSpot to your platform and pass customer information into HubSpot. Think of your checkout process as a flow (home page > product detail page > add to cart > register for account > enter credit card info > confirm > checkout, for instance). These critical points in the checkout process are: 1. HubSpot Integration point 1: The first point at which your cart captures an email address. This is usually in a site registration process or the very beginning of a checkout. The goal here is to identify this point in order to alert HubSpot that you’ve captured a new email address, and then integrate to sync up HubSpot’s marketing tools and analytics with the new email addresses your cart has captured. 2. HubSpot Integration point 2: The point at which a purchase is complete and a credit card has been billed / an invoice created for you to fulfill on. This is the point at which a new order is inserted into your system, your payment processing happens, etc. If this point is not on your site or not all of your transactions are handled on-site (e.g. “30% of my customers pay through PayPal, on paypal.com) you may want to speak with an integration engineer at HubSpot to determine the precise details. Have multiple points at which order data is created? Contact HubSpot’s integration engineers for help on how to best integrate. You also may want to step through your checkout process to understand where these points are. After learning where the right points to integrate are, continue. Note: To readers with one-page checkout processes or checkout flows with emails collected simultaneously with billing information Some online stores have simplified checkout processes that do not have two points at which to integrate HubSpot. This is OK. You will integrate only at the second point, and you will pass only “customers” into HubSpot as opposed to both “leads” from point #1 and “customers” from point #2. Understand the “lead” vs. “customer” distinction in HubSpot With the two integration points in mind, it’s important to understand the difference between “leads” and “customers” in HubSpot. HubSpot’s “Leads” – site visitors whose email address you’ve captured, but have not purchased. Leads are passed in from integration point #1 above to HubSpot via API. Leads passed to HubSpot typically have information like email address and a name, but may include other info like address, phone number, etc. HubSpot’s “Customers” – site visitors who have been through your online checkout process and have completed a transaction with your store. Any data you pass into HubSpot from point #2 above should be “customer” data, meaning that you have completed a transaction. These are also passed into HubSpot via API but have a variable of closeDate (see more below) to distinguish them from other leads. Note that both “Leads” and “Customers” are passed into HubSpot via the same API calls. The major difference is in how the data is displayed and used HubSpot’s software and it’s important to ensure both leads and customers are being counted correctly. Not sure what the difference between a lead and a customer is for your business? Contact HubSpot’s integration engineers for help on how to differentiate. Executing the HubSpot<>eCommerce API Integration Step 1: Claim Your HubSpot API Key For Medium and Large HubSpot customers, you can request your API key here: https://hubapi.com/keys/get. For the two pieces of information required on this page: 1. PortalID: If you don’t know your PortalID, log into HubSpot and there on the dashboard below the info you normally look at is a gray PortalID numerical string, toward the bottom of the page. It is the string of numbers that you’re looking for here. 2. Email: Your “technical contact email” must be a registered user on your HubSpot account. The person executing the integration should use their email address here. Note: HubSpot's API key and best practices This particular integration does not strictly require an API key today, but may in the future. As of writing this document, it is a best practice to use your API key whenever working with any of HubSpot’s API. Not doing so could result in integration failure in the future, should you choose not to follow this best practice. Step 2: Learn HubSpot’s Relevant API Methods The primary method you’ll be using in HubSpot’s API is to insert a lead from your cart to HubSpot’s lead database. From here HubSpot will take over creating the appropriate records, lining up everything in HubSpot's analytics, and and managing the database items. Inserting a lead to HubSpot is performed using HubSpot’s Leads API, one of many APIs HubSpot offers. Documentation on the Leads API method: http://docs.hubapi.com/wiki/Leads_API_Methods Code samples and detailed documentation using the Insert Leads method: http://docs.hubapi.com/wiki/Inserting_Leads An example using ZenCart: http://docs.hubapi.com/wiki/ZenCart_Integration HubSpot has a Google Group for questions pertinent to the API: http://groups.google.com/group/hubspot-api. As before, note that HubSpot's standard call-in tech support line will not support or troubleshoot code you've written. They may be able to help you understand our API methods at a nonprogrammatic level but the Google Group is typically a more effective avenue for specific questions. Step 3: Create An Endpoint in HubSpot to Receive Leads via API Now that you’ve seen a few examples and understand the API method, create the endpoint necessary to receive a lead in HubSpot. To do this, log into your HubSpot and navigate to Settings, then to “HubSpot Lead API”. To create the API endpoint in HubSpot: 1. Click"Add New Form" 2. In “Form Name” enter the name for integration point #1. HubSpot users will see this Form Name when they look at users data or segment leads, so use something that will make sense to users. Suggestions include “new_registration” or “begin_checkout”. Use what makes the most sense for your business. In “Email List” enter your email address. You’ll later want to change this to the primary HubSpot users if you are not a primary HubSpot user. Keep it just to your own email for testing purposes. Do not select a lead nurturing campaign yet. Click “Save” toward the bottom of the page. 3. You’ll now be presented with the “API POST URL”. This is the first element of the string you’ll use to pass leads into HubSpot. Step 4: Passing Leads to HubSpot at Integration Point #1 In your form processing file associated with Integration Point #1, writecode to compose the URL that you will pass to HubSpot. Leverage our code samples here: http://docs.hubapi.com/wiki/Inserting_Leads. Capture the different pieces of information from your system, compose the string, then cURL the string to HubSpot using the base of the URL as the string you just received from the screen in settings (the “API POST URL”, above). You’ll probably want to pass in all the information you have available for marketing purposes. This could be limited to simply name and email, or just email, but could be as much as name, email, address, phone number, etc. The limits of this information are dependent on your cart's fields that are presented to the user. In addition to personal information, you need to pass in an IPAddress field and a UserToken field whenever using the HubSpot Leads API. Note on the HubSpot User Token (UTK) The most important part of the string is the UserToken. This is pulled from a cookie called hubspotutk by a line in your code. It is HubSpot’s best unique identifier for a given unique person. If there is no UTK available, HubSpot will fall back to an email address – but we highly recommend keeping track of the UTK and passing it in as a parameter whenever possible. Step 5: Passing Leads to HubSpot at Integration Point #2 Now that you’ve integrated HubSpot at integration point #1, registration, it’s time to integrate at the second point that HubSpot requires for full closed-loop marketing integration, the point where the transaction completes. You should already have identified the processing file for this integration point, as well as the integration point itself. If you haven’t, please backtrack to the beginning of this document and identify the proper point and related processing file or code in your cart. HubSpot recommends using a human-readable FormName here, as with integration point #1. Consider descriptive names like “purchase_complete” or “transaction_finished”. Create the endpoint in HubSpot in by navigating to HubSpot's Settings tab, then clicking to HubSPot Leads API and following the same steps as before (see above for reference as necessary). The code you add in here will be similar to your code in integration point #1, but with at least two important differences: 1. It includes “CloseDate” variable of $today (a variablized date, in MM/DD/YYYY format). This is the differentiator of “leads” and “customers” in HubSpot. 2. It uses a different FormName; integration point #1 uses the "new_registration" form name, whereas this uses the "purchase_complete" type FormName. Your specific names may vary, but the two integration points need to have two different FormNames for purposes inside HubSpot. Note: Passing non-standard data to HubSpot (SKUs, revenue, etc.) HubSpot also recommends passing in any other pertinent order info: order number, total revenue pre-tax and pre-shipping, and even SKUs, if you like. To pass in non-standard fields like order numbers and get the most out of your integration, just create new key-value pairs in your Leads API string. So if your normal call would just have a UTK, IP, and CloseDate, tack on a key like “order_number” with a value like “931”. So your key-value pair to use in your API string would be “&order_number=931”. Then if you wanted to pass in a total revenue, you could add on “&total_revenue=142.31”. Step 6: Ensure your integration is working To check your work, do the following: 1. Execute a mock transaction on your cart. If you cannot execute a full mock transaction, at least begin the checkout process on your cart. 2. Wait 5-10 minutes for HubSpot to process these data. 3. You should see an email come through to your inbox from HubSpot. If you do not, either you did not specify an email address when you configured the API endpoint in HubSpot, or your integration is not passing any info to HubSpot. If it is the latter, ensure you are pulling the IP Address and UserToken from your visitors correctly; failure to include these can cause an API call to fail entirely. 4. Verify that the right data is coming through and HubSpot is tracking it correctly. After confirming that HubSpot and your cart are communicating per the above, log into your HubSpot. Check two important places: 1. Convert Tab > Leads. Look for new lead activity from your mock transaction. Click into that lead record. Verify that page-views are tracked (if you haven’t blocked traffic from your IP in Settings) or verify that a UserToken and the proper IP have been passed through. If either you see pageviews associated with your new lead or you see a proper UTK string (looks like an MD5 hash), your integration was successful! 2. Analyze Tab > Sources. Look for evidence of your Lead and Customer entry in these data. If you saw the UTK in your lead submission above, your information will be counted in Sources. If there is no UTK information in your lead record, Sources will not display your data as a Lead or Customer record. Note: HubSpot's back-end processes and lead record management HubSpot prefers to unique database records based on the UserToken (UTK). If you pass in one record with a certain UTK and another any time later with that same UTK, the records will be joined together in HubSpot's database. If there is no UTK or a different UTK for any lead activity in HubSpot - whether the lead is created via API or otherwise - HubSpot will first attempt to match on email address to join the records. This means that even if there is no UTK from a particular lead, HubSpot can still join the records together on email address. Failing email and UTK, HubSpot looks to join records on IP Address. Due to this tiered failback system for inserting lead records, it is best to always include a UTK and IP Address, and an email for the first conversion point. For the purposes of this document, the "first conversion point" is typically at integration point #1. It is entirely possible, however, to create leads in HubSpot from sources other than the API - in these case future API-driven lead insertions would match based on UTK, email, and IP Address, in that order. Troubleshooting Common Issues in HubSpot<>eCommerce Custom API Integrations “I don’t know if I can edit my cart’s processing code” If you do not know the answer to this, you probably will need help completing the integration. That’s OK! Contact a service partner today to learn pricing and timing on an integration. “I set up the integration but am not seeing anything in HubSpot” Something is wrong with your API setup. First, ensure you’ve created the appropriate endpoints in HubSpot. Navigate to Settings > HubSPot Leads API and confirm that you have created 2 endpoints in HubSpot, and used the appropriate FormName in both API calls. If you’re trying to pass a lead to an endpoint that HubSpot does not recognize, HubSpot may reject the lead. Next, examine the code you have written to integrate. To start debugging, first ensure you have the base URL and base strings right. You can create a test string over HTTP (put it into your browser) provided you specify an IP Address and UserToken. Attempt to have this log information into HubSpot. If it does not, you may not have the right URL base; check your API endpoints in HubSpot to verify you’re using the correct hubspot.com URL to pass your leads to. Next, ensure the URL is being formed properly. You’re putting together a variety of information in your form processing field and something may be wrong there. If you have the right URL composed and know the right endpoint, ensure the cURL call is working correctly and you have appropriate permissions to send that to HubSpot from your cart. “I’m seeing info under the Convert Tab > Leads, but nothing in Sources” The UTK is not tracking correctly. HubSpot’s Sources tool relies on the presence of a UTK to determine how to attribute a new lead or customer. Ensure you have cookies enabled on your browser, and that the browser has properly created the cookie. If there are no problems with your browser creating the cookie, the UTK may not be getting pulled correctly from your HubSpot cookie. Check the line in your code that references the cookie and ensure it is working correctly. “In Analyze Tab > Sources, I see a Lead, but no Customer” Your CloseDate variable may be missing or malformed, or you did not trigger the code that runs when a checkout is completed. First ensure your CloseDate is formatted as follows: MM/DD/YYYY. You can check your CloseDate variable's format in the“closed won” field in the Convert Tab > Leads tool, and locating the appropriate record there. Still need help? Post a question in our API developers Google Group: http://groups.google.com/group/hubspot-api, contact your HubSpot representative or [email protected] and they will route your inquiry to the appropriate resource at HubSpot, or employ a certified partner to integration from http://services.hubspot.com/ecommerce-integration/directory/.
© Copyright 2018