How to Integrate HubSpot with eCommerce Websites

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/.