Why Ecommerce Bridge?

The Ecommerce Bridge API (EB) provides a way for integrators to sync ecommerce data into HubSpot. It also facilitates creating a set of out-of-box ecommerce features for HubSpot users. These features include:

• Workflows that send emails to welcome new customers and recover abandoned carts (taking advantage of HubSpot's email send infrastructure and email performance tracking)
• An ecommerce reporting dashboard and several report templates to use in custom dashboards
• Contact and Deal property mapping to power list segmentation based on customer and order activity

To begin using Ecommerce Bridge, you'll need to know how ecommerce data is structured in HubSpot and how to take advantage of the features that build on our ecommerce framework.

How to use the Ecommerce Bridge

To use EB you need to:

1. Set up mappings that translate ecommerce data in your system to native objects in HubSpot
2. Define the ecommerce store(s) that will be connected to a HubSpot account
3. Send sync messages to HubSpot, through EB, when there is a change to ecommerce data in your system

1. Mapping data onto HubSpot

In order to use EB you must describe how the structure of data in your system maps to native objects in HubSpot.

HubSpot Ecommerce Objects

EB allows you to map to properties of the following native HubSpot objects:

• Contacts: Contacts can represent anyone who has a relationship with your company.
  Note: For more information about contacts in HubSpot see the user guide and developer guide.
• Products: Products represent the goods or services being sold.
• Deals: Deals represent a potential or completed transaction. Typically, one customer order in a store will map to one HubSpot Deal.
• Line Items: Line items represent a single line on a transaction record. They can be thought of as an instance of a Product that a customer has begun or completed purchasing. They are associated with both Deals and Products.
  Note: Sales Professional is NOT needed to create line items on deals when using EB.

HubSpot Properties

Properties store all information about objects in HubSpot. For more information about using properties in HubSpot see this blog post and the developer guide.

Your ecommerce data can be mapped to HubSpot object properties in several ways:

• Default properties that are guaranteed to be present in every HubSpot account.
  Note: For more information about default properties see the contact defaults, deal defaults, and developer guide.
• Custom properties that your integration has defined.
• Properties created by EB in every account specific to ecommerce. These include:

Creating property mappings

Once you've decided how to map your ecommerce data to HubSpot, you can create property mappings that EB will use to sync. A property mapping is simply the name of a property in your system, the internal name of a HubSpot property, and optionally a data type that describes the format of the property. They are modified through settings.

Your settings have the following fields:

Example property mapping scenario

Let's say your ecommerce platform represents a shopper by name, email, and phone number. You might also represent unique orders with a name, status, URL, and a timestamp for when the order was completed. You could then define your EB settings as follows:

PUT https://api.hubapi.com/extensions/ecomm/v2/settings?appId={yourAppId}&hapikey={yourDeveloperAccountHapikey}

{
  "enabled": true,
  "webhookUri": null,
  "mappings": {
    "CONTACT": {
      "properties": [
        {
          "externalPropertyName": "firstname",
          "hubspotPropertyName": "firstname",
          "dataType": "STRING"
        },
        {
          "externalPropertyName": "familyname",
          "hubspotPropertyName": "lastname",
          "dataType": "STRING"
        },
        {
          "externalPropertyName": "customer_email",
          "hubspotPropertyName": "email",
          "dataType": "STRING"
        },
        {
          "externalPropertyName": "phone_number",
          "hubspotPropertyName": "mobilephone",
          "dataType": "STRING"
        }
      ]
    },
    "DEAL": {
      "properties": [
        {
          "externalPropertyName": "purchase_date",
          "hubspotPropertyName": "closedate",
          "dataType": "STRING"
        },
        {
          "externalPropertyName": "name",
          "hubspotPropertyName": "dealname",
          "dataType": "STRING"
        },
        {
          "externalPropertyName": "stage",
          "hubspotPropertyName": "dealstage",
          "dataType": "STRING"
        },
        {
          "externalPropertyName": "abandoned_cart_url",
          "hubspotPropertyName": "ip__ecomm_bridge__abandoned_cart_url",
          "dataType": "STRING"
        }
      ]
    },
    "PRODUCT": {
      "properties": [
        {
          "externalPropertyName": "product_description",
          "hubspotPropertyName": "description",
          "dataType": "STRING"
        },
        {
          "externalPropertyName": "price",
          "hubspotPropertyName": "price",
          "dataType": "NUMBER"
        },
        {
          "externalPropertyName": "product_name",
          "hubspotPropertyName": "name",
          "dataType": "STRING"
        }
      ]
    },
    "LINE_ITEM": {
      "properties": [
        {
          "externalPropertyName": "tax_amount",
          "hubspotPropertyName": "tax",
          "dataType": "NUMBER"
        },
        {
          "externalPropertyName": "num_items",
          "hubspotPropertyName": "quantity",
          "dataType": "NUMBER"
        },
        {
          "externalPropertyName": "price",
          "hubspotPropertyName": "price",
          "dataType": "NUMBER"
        },
        {
          "externalPropertyName": "discount_amount",
          "hubspotPropertyName": "discount",
          "dataType": "NUMBER"
        }
      ]
    }
  }
}

Note: When developing a custom solution for an individual HubSpot account, the appId can be omitted and the API key for that account should be used instead.

The above request does not create any properties in HubSpot. But whenever your integration references a contact phone_number, EB will modify the contact's mobilephone property. This means that when sending ecommerce data to HubSpot through EB you can continue to use your own terminology and property names. HubSpot will handle the conversion.

Note: The property mapping for a Product image URL should be defined as a AVATAR_IMAGE dataType.

{
  "externalPropertyName": "product_image",
  "hubspotPropertyName": "ip__ecomm_bridge__image_url",
  "dataType": "AVATAR_IMAGE"
}

More information about how to set up your property mappings is in the Settings API documentation.

Required Properties

Some properties are required to create an object in the HubSpot CRM. Because of this, all required properties must be mapped to and must be included when attempting to create an object. Below are a list of required properties. Mappings for these properties must be provided before you can enable your Ecommerce Bridge settings.

Required Contact Properties:

• email -- Only contacts with valid email addresses will be created.

Required Deal Properties:

• dealstage -- Only deals with a valid deal stage in the ecommerce Pipeline will be created.

Required Line Item Properties:

• hs_assoc__deal_id - Only line items associated to a deal will be created.

• hs_assoc__product_id - Only line items associated to a product will be created.

Required Product Properties:

None

2. Defining stores

An ecommerce store is not currently represented as a native object in HubSpot. Instead, defining a store through EB is a way to organize and manage data, and all data sent through EB will be attributed to a store.

Users will be able to segment data based on the store it came from, and will be able to see separate overviews and import tools for each store.

A store has the following fields:

For example, when a user connects your integration to their HubSpot account you can create a store as follows:

PUT https://api.hubapi.com/extensions/ecomm/v2/stores

{
  "id": "ecommercebridge-test-store",
  "label": "Ecommerce Bridge Test Store",
  "adminUri": "ecommercebridge-test-store.myshopify.com"
}

With OAuth token in the Authorization header, see OAuth 2.0.
Note: When developing a custom solution for an individual HubSpot account, the OAuth token can be omitted and the API key for that account should be used instead.

Automatic account setup

The first time a store is defined in a HubSpot account, we do some additional setup.

• A reporting dashboard with premade reports is added.
• Ecommerce specific properties (listed above) are created under the property group "ECommerce".
• A deal pipeline labeled "Ecommerce Pipeline" is created with 6 stages: checkout_abandoned, checkout_pending, checkout_completed, processed, shipped, cancelled. All deals created through EB must have a dealstage that is a part of this pipeline.
  Note: Sales Professional is NOT needed to add this pipeline to an account.

Note:
The ecommerce pipeline should not be modified. This pipeline is used by all integrations using the Ecommerce Bridge, and any updates to any store will revert this pipeline to its default label and stages.

If any of those setup items fail, then the store will not be created.

Uninstalling your app will automatically delete any stores created by your app. This will also disable any workflows that are based on the store.

3. Syncing data

After you've defined how to translate your data into HubSpot, and defined at least one store, you're ready to notify HubSpot of changes to ecommerce objects in that store. Sync messages represent a creation, update, or deletion of an object in your system that should be reflected in HubSpot.

Sync messages have the following fields:

Messages have the following fields:

For all objects synced by the Ecommerce Bridge, HubSpot will maintain a link between the externalObjectId you provide and the corresponding HubSpot object. If a new externalObjectId is used then a new HubSpot object will be created.

Note: 

• Sync messages will not restore or recreate deleted object records with the same externalObjectId value.
  
• UPSERT messages for the same externalObjectId will update the same object in HubSpot, with the most recent changedAt value taking precedence.
• Once created with a sync message, a Contacts email property cannot be updated with an additional sync message.
  
  

Associations

EB supports the following associations between objects:

*Note: Since contact associations are not required to create a deal, invalid contact associations will be ignored and will not cause sync errors.

Example product and purchase scenario

Say a user has connected your integration to their HubSpot account, and you've defined an Ecommerce Bridge Test Store. When a vendor creates a product in your ecommerce system, you can then create that product in HubSpot:

PUT https://api.hubapi.com/extensions/ecomm/v2/sync/messages

{
  "storeId": "ecommercebridge-test-store",
  "objectType": "PRODUCT",
  "messages": [
    {
      "action": "UPSERT",
      "externalObjectId": "orange_widget",
      "properties": {
        "price": "100",
        "product_name": "Orange Widget",
        "product_description": "The orange widget is a wonder of modern technology."
      }
    }
  ]
}

With oauth token in the Authorization header, see OAuth 2.0.
Note: When developing a custom solution for an individual HubSpot account, the OAuth token can be omitted and the API key for that account should be used instead.

This product will be created in the HubSpot account's Product Library (visible under Sales settings).

If a customer then makes a purchase from that same store, you can sync the corresponding contact, deal, and line items representing that transaction:

PUT https://api.hubapi.com/extensions/ecomm/v2/sync/messages

{
  "storeId": "ecommercebridge-test-store",
  "objectType": "CONTACT",
  "messages": [
    {
      "action": "UPSERT",
      "changedAt": "1542092841947",
      "externalObjectId": "daniel452834529",
      "properties": {
        "firstname": "Daniel",
        "lastname": "Smith",
        "customer_email": "danielsmith@gmail.com",
        "phone_number": "123-456-7890"
      }
    }
  ]
}

PUT https://api.hubapi.com/extensions/ecomm/v2/sync/messages

{
  "storeId": "ecommercebridge-test-store",
  "objectType": "DEAL",
  "messages": [
    {
      "action": "UPSERT",
      "changedAt": "1542092841947",
      "externalObjectId": "1000",
      "properties": {
        "name": "1000",
        "stage": "processed",
        "purchase_date": "1542092841947"
      },
      "associations": {
        "CONTACT": [
          "daniel452834529"
        ]
      }
    }
  ]
}

PUT https://api.hubapi.com/extensions/ecomm/v2/sync/messages

{
  "storeId": "ecommercebridge-test-store",
  "objectType": "LINE_ITEM",
  "messages": [
    {
      "action": "UPSERT",
      "changedAt": "1542092841947",
      "externalObjectId": "abcdef",
      "properties": {
        "price": "100",
        "num_items": "2",
        "tax_amount": "7"
      },
      "associations": {
        "DEAL": [
          "1000"
        ],
        "PRODUCT": [
          "orange_widget"
        ]
      }
    }
  ]
}

The above calls will create a contact with one deal visible on the contact record. That deal will reflect the line item and show that two (2) Orange Widgets were purchased. If multiple products were purchased in the same deal, then multiple line items should be created.

Note: A customer order will have a deal stage of Checkout Abandoned in HubSpot if the order is created and not completed within 24 hours. After 24 hours pass, the order will move from Checkout Pending to Checkout Abandoned.

Sync Status

EB will asynchronously apply changes from these sync messages to HubSpot. This process involves translating messages using the property mappings, validating against the current state of the user's properties, and then applying property changes to users' accounts.

A successful response from the API does not mean that a change was made to a HubSpot object, just that the message was successfully enqueued. There are two endpoints you should use to monitor the success status of your sync messages.

This first, /sync/status, returns the status of the sync for a specific external object.

GET https://api.hubapi.com/extensions/ecomm/v2/sync/status/ecommercebridge-test-store/CONTACT/daniel452834529

{
  "lastProcessedAt": "1542094119555",
  "hubspotId": 5402,
  "errors": [],
  "objectType": "CONTACT",
  "storeId": "ecommercebridge-test-store",
  "externalObjectId": "daniel452834529"
}

But, for example, say you did not include customer_email as a property when syncing information about Daniel. Since email is required to create a contact through EB, the processing would fail and you would see:

GET https://api.hubapi.com/extensions/ecomm/v2/sync/status/ecommercebridge-test-store/CONTACT/daniel452834529

{
  "lastProcessedAt": null,
  "hubspotId": null,
  "errors": [{
    "portalId": 9999999,
    "storeId": "ecommercebridge-test-store",
    "objectType": "CONTACT",
    "externalObjectId": "daniel452834529",
    "changedAt": "1542092841947",
    "erroredAt": "1542092843000",
    "type": "MISSING_REQUIRED_PROPERTY",
    "details": "more details about the error",
    "status": "OPEN"
  }],
  "objectType": "CONTACT",
  "storeId": "ecommercebridge-test-store",
  "externalObjectId": "daniel452834529"
}

The second endpoint you should use to monitor the status of sync is /sync/errors/. This will return all the existing errors for a specific application or account.

GET https://api.hubapi.com/extensions/ecomm/v2/sync/errors/app/{appId}?hapikey={yourDeveloperAccountHapikey}

or

GET https://api.hubapi.com/extensions/ecomm/v2/sync/errors/portal/{portalId}={yourCustomerAccountHapikey}

The API reference page describes the details of this API in more detail.