Ecommerce Bridge documentation and walkthrough

Highlighted
Community Manager

Ecommerce Bridge Motivations and Walkthrough

Why Ecommerce Bridge

The Ecommerce Bridge provides a process for syncing ecommerce data into HubSpot. The Ecommerce Bridge handles much of the work of syncing data. It does the work of applying the property mappings, validating the incoming data against the customer's specific setup and applying the changes appropriately. Using the Ecommerce Bridge API you avoid all the little gotchas encountered when writing data directly to Contacts and the CRM objects.

The Ecommerce Bridge allows HubSpot to provide common ecommerce functionality. Because we're now working from a common understanding of how ecommerce data is structured, HubSpot can add new features that automatically work for all Ecommerce Bridge applications. For example, users of Ecommerce Bridge applications will have the ability to send marketing emails for new customer welcome and abandoned cart recovery -- allowing them to take advantage of HubSpot's email send infrastructure and email performance tracking. Users will also have the ability to build ecommerce reporting dashboards and use ecommerce data to build fine-tuned contact lists.

How to use the Ecommerce Bridge

To implement an Ecommerce Bridge application you need to:

  • set up property mappings from your domain to HubSpot properties
  • send messages to HubSpot when ecommerce data changes
  • implement the import process

To use the Ecommerce Bridge API with a HubSpot portal you need to:

  • call the install endpoint
  • set up property mappings from your domain to HubSpot properties
  • send messages to HubSpot when your ecommerce data changes

Property Mappings

The first step of implementing the Ecommerce Bridge is mapping properties from your ecommerce domain into HubSpot. The Ecommerce Bridge allows you to map to properties of the following objects:

  • Contacts: Standard HubSpot contacts.
  • Deals: HubSpot deals used in the CRM
  • Products: A new object in the CRM. This allows customers to define their product catalog in the CRM.
  • Line Items: A new object in the CRM. This object represents a line-item of a deal. It is associated with a deal and a product.

To implement the Ecommerce Bridge you need to provide property mappings for each of these objects. More information about how to set up your field mappings is in the Settings API documentation.

Sync Messages

After you've defined how your system's properties map into HubSpot, and after a user has installed your integration, you're ready to send sync messages to HubSpot notifying HubSpot of changes to ecommerce objects. The Sync Messages section describes the details of this API.

When sending these messages, you use your system's property names. The reason for this is that HubSpot stores each of these messages in an immutable data store. This allows efficient handling of property mapping changes. When you change your property mappings, HubSpot can reapply field mappings to our full history of sync messages -- without having to reimport data from your system.

The Ecommerce Bridge API will apply changes from sync messages to HubSpot. This process involves applying the property mappings, validation against the current state of the user's properties, and the efficient bulk application of property changes to customer portals.

The Ecommerce Bridge will also be adding performance and reliability monitoring to this process as well as giving customers troubleshooting capabilities for sync issues.

Imports

The Ecommerce Bridge defines a process to allow customers to import their ecommerce data into HubSpot. Imports only apply to and are only available for application development, not development on an individual portal.

The import process is as follows:

  • The customer initiates an import and the HubSpot sends your API an import initialization webhook. (See: Import Initialization Webhook) This is your notification to start sending HubSpot import data for this customer.

  • You use the import pages endpoint to send import data. (See: Import Pages Endpoint) These import pages are similar to sync messages in that they use your property names.

  • When you're done sending HubSpot import data for a particular object type, you send an import-end request to HubSpot. This tells HubSpot that we have all the data for this object type. In order for an import to complete successfully, HubSpot must receive import-end notifications for each object type: Contacts, Deals, Line Items, and Products. (See: Import Page End Endpoint)

Cross-Object Associations

To support cross-object associations, like associating a deal to a contact, the Ecommerce Bridge provides some special properties. Using a cross-object association requires two steps:

  1. Setup the association by defining a mapping from a property in your domain to a special HubSpot-defined association property.
  2. Associate objects by sending sync messages that use this property to create the association.

For example, the Ecommerce Bridge provides deal property called hs_assoc__contact_ids. You can set up a mapping to this property. The following example maps an example external property customerIds to hs_assoc__contact_ids:

{
  "propertyName": "customerIds",
  "dataType": "STRING",
  "targetHubspotProperty": "hs_assoc__contact_ids"
}

Next, you can send a sync message via the Sync Messages endpoint like:

POST /extensions/ecomm/v1/sync-messages/DEAL
[
  {
    "integratorObjectId": "111",
    "action": "UPSERT",
    "changeOccurredTimestamp": 1507642200000,
    "propertyNameToValues" : {
      "customerIds": "222,333"
    }
  }
]

This sync message maps a deal, that your system identifies as "111", to customers that your system identifies as "222" and "333". HubSpot looks for contacts created via sync messages with the integratorObjectId set to "222" and "333" to find the contacts to associate to this deal. So you can manage these associations without ever having to know the dealId or vid that HubSpot assigns to these deals and contacts.

As Ecommerce Bridge development continues, more of these special-purpose properties will be added to the system to enable richer ecommerce functionality.

Ecommerce Bridge API Reference

Install

Warning: While the Ecommerce Bridge is in Beta, you should not install an app (using OAuth) that uses the Ecommerce Bridge alongside a custom app (using a hapikey). This behavior is not supported during the beta, as you may have sync messages crossed between the two separate installs. Also, you will not be allowed to install a second app using the Ecommerce Bridge in a portal that already has an Ecommerce Bridge app installed, of if the portal is already using the HubSpot Shopify integration. This will be fixed by the official launch.

Manually installing the Ecommerce Bridge API only applies to and is only available for development on an individual portal, not application development. For an ecommerce application, these install steps will happen when a customer installs the application.

To take full advantage of the functionality that Ecommerce Bridge provides, certain things need to be added to your portal. For example, this includes ecommerce specific properties and an ecommerce reporting dashboard. To add these things, use the installs endpoint.

POST /extensions/ecomm/v1/installs

Before you are able to sync data using the /sync-messages endpoint, you must have installed and you must have settings enabled. To check the status of your setup, use the installs status endpoint.

GET /extensions/ecomm/v1/installs/status

Settings API

The Settings API is where you set up the field mappings for your use of the Ecommerce Bridge API.

When developing an application, use your developer portal's hapikey to authenticate for these settings requests. When developing for an individual portal, use that portal's hapikey to authenticate.

Upsert settings

PUT /extensions/ecomm/v1/settings?appId={appId}

Example request body:

{
  "enabled": false,
  "importOnInstall": true,
  "productSyncSettings": {
    "properties": [
      {
        "propertyName": "my_name_field",
        "dataType": "STRING",
        "targetHubspotProperty": "name"
      },
      {
        "propertyName": "image",
        "dataType": "STRING",
        "targetHubspotProperty": "ip__ecomm_bridge__product_image"
      }
    ]
  },
  "dealSyncSettings" : {
    "properties": [ ]
  },
  "lineItemSyncSettings": {
    "properties": [ ]
  },
  "contactSyncSettings": {
    "properties": [ ]
  }
}

This PUT operation is an update-replace. Blank values will clear out existing data.

Retrieve settings

GET /extensions/ecomm/v1/settings?appId={appId}

Example response:

{
  "enabled": false,
  "importOnInstall": true,
  "productSyncSettings": {
    "properties": [
      {
        "propertyName": "my_name_field",
        "dataType": "STRING",
        "targetHubspotProperty": "name"
      },
      {
        "propertyName": "image",
        "dataType": "STRING",
        "targetHubspotProperty": "ip__ecomm_bridge__product_image"
      }
    ]
  },
  "dealSyncSettings" : {
    "properties": [ ]
  },
  "lineItemSyncSettings": {
    "properties": [ ]
  },
  "contactSyncSettings": {
    "properties": [ ]
  }
}

The PUT and GET are completely symmetric. You can copy the response from the GET and use it as the body of the PUT.

HubSpot provides some additional property mappings to all Ecommerce Bridge settings. They are not editable, but there is an optional boolean query param showProvidedProperties that can be used with both the PUT and GET endpoints to retrieve those as well. Note that doing so will prevent the responses from being symmetric.

Settings Properties

Property name Property type Description
enabled boolean Whether or not this application is "turned on" or actively syncing data. Setting this property to "false" enables you to build up your settings and only turn your sync on once you're comfortable that you have all the necessary data set up. When setting enabled to true the Settings API checks your field mappings to ensure that you've specified all fields required for the Ecommerce Bridge sync process, see Required Properties
importOnInstall boolean Whether or not to automatically kick off the import process once a user has installed your application. This field does not apply to settings for direct use of the API.
productSyncSettings.properties Array of PropertyMapping objects Field mappings for the Product object.
dealSyncSettings.properties Array of PropertyMapping objects Field mappings for the Deal object.
lineItemSyncSettings.properties Array of PropertyMapping objects Field mappings for the Line Item object.
contactSyncSettings.properties Array of PropertyMapping objects Field mappings for the Contact object.

PropertyMapping Properties

The FieldMapping defines how we map properties defined in your system to properties defined in HubSpot.

Property name Property type Description
propertyName String The name of the property in your system.
dataType "STRING", "NUMBER", "DATETIME", "AVATAR_IMAGE" The type of value we can expect for this property. "AVATAR_IMAGE" is expected to be a url for an image. Note that only one property mapping per object type can have the dataType "AVATAR_IMAGE", and currently this dataType is only available for use in productSyncSettings.
targetHubspotProperty String The name of the field defined in HubSpot. This can be the name of a default HubSpot field or a custom property.

Association Properties

The Ecommerce Bridge supports the following associations between objects:

object associations

Deal Properties:

  • hs_assoc__contact_ids - A comma-delimited list of external ids to use to associate contacts to the current deal.

Line Item Properties:

  • hs_assoc__deal_id - A single ID to use to associate this line item to a deal. A value for this property is required for the successful creation of a line item.

  • hs_assoc__product_id - A single ID to use to associate this line item to a product. A value for this property is required for the successful creation of a line item.

Required Properties

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.
    These include "checkout_abandoned", "checkout_pending", "checkout_completed", "processed", "shipped", "cancelled".

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.

Sync Messages

Use the Sync Messages API to send HubSpot notifications of all creates, updates, and deletes of ecommerce objects.

An application should use the OAuth token for a specific customer to send these sync message requests, and a portal using the api directly should include its hapikey to send these sync message requests.

Example request:

POST /extensions/ecomm/v1/sync-messages/{objectType}

Where {objectType} is one of: CONTACT, DEAL, PRODUCT, or LINE_ITEM

With body:

[
  {
    "integratorObjectId": "001",
    "action": "UPSERT",
    "changeOccurredTimestamp": 1507642200000,
    "propertyNameToValues" : {
      "my_name_field": "Example Product",
      "image": "https://url.to.image/image.png"
    }
  }
]

Note that this API allows you to send multiple sync messages for a single object-type. These messages can be for multiple objects of that object-type.

Sync Message Properties

Property name Property type Description
integratorObjectId String, max length 100 characters, ascii-only The ID, in your system, of the object that is being created/updated/deleted.
action UPSERT or DELETE The type of action this describes
changeOccurredTimestamp long The epoch millisecond timestamp when the change that this message describes occurred.
propertyNameToValues Map This is a map of your property names to the values for this object. These are the values that we will sync into corresponding HubSpot object.

Imports

Imports only apply to and are only available for application development, not development on an individual portal.

The import process works as follows:

  1. The customer initiates an import, and HubSpot sends your system the Import Initialization Webhook.

  2. Your system sends all the relevent data for this customers store to HubSpot via the Import Pages Endpoint.

  3. Your system uses the Import Page End Endpoint to indicate that you're done sending the import data for a particular object-type.

  4. When HubSpot receives import page end requests for all object types: CONTACT, DEAL, PRODUCT, and LINE_ITEMS the import processing will apply all changes to HubSpot and the import will complete.

Import Settings API

The import settings API is where you set the URI for the Import Initialization Webhook.

Use your developer account's hapikey to authenticate for these settings requests.

Settings Import Settings:

PUT /extensions/ecomm/v1/import-settings?appId={appId}

Example body:

{
  "importTriggerUri": "https://example.com"
}

Retrieving Import Settings:

GET /extensions/ecomm/v1/import-settings?appId={appId}
{
  "importTriggerUri": "https://example.com"
}

Import Initialization Webhook

When a user initiates an import, HubSpot will send the following request to the URI set via the Import Settings API.

POST /your-uri

Example request body:

{
  "portalId": 2345,
  "importStartedAt": 1505590751000,
  "settingsToImport": [
    {
      "settingsId": 51,
      "objectType": "CONTACT"
    },
    {
      "settingsId": 52,
      "objectType": "DEAL"
    },
    {
      "settingsId": 53,
      "objectType": "LINE_ITEM"
    },
    {
      "settingsId": 54,
      "objectType": "PRODUCT"
    },
  ]
}

Example expected reponses:

{
  "importCounts": [
    {
      "settingsId": 51,
      "count": 1022
    },
    {
      "settingsId": 52,
      "count": 1044
    },
    {
      "settingsId": 53,
      "count": null
    },
    {
      "settingsId": 54,
      "count": 349
    }
  ]
}

Initialization Webhook Request Properties

Property name Property type Description
portalId Number The portalId of the customer requesting the import. This will be one of the customers that have installed your application.
importStartedAt Number, epoch milliseconds The time the customer requested the import. This timestamp identifies this specific import, and you'll use this value in the import pages endpoints.
settingsToImport Array This specifies which object types the customer has requested to import. Imports of a subset of object-types may be possible.
settingsToImport.settingsId Number An internal ID for the sync settings of a specific object-type. You don't need to worry about this idea except to generate the response for this request.
settingsToImport.objectType String, one of CONTACT, DEAL, LINE_ITEM or PRODUCT The objectType this specific ID corresponds to.

Initialization Webhook Response Properties

Property name Property type Description
importCounts Array Objects that return the number of items to expect for each object type. The response must contain an element for each settingsToImport in the request.
importCounts.settingsId Number The corresponding settingsToImport.settingsId from the request.
count Number or null The number of items that you're planning to import. This is for progress-estimation purposes. This can be an estimate. If this value cannot be reasonably estimated it can be set to null.

Security

This webhook request will contain a signature in the X-HubSpot-Signature header. See the Webhooks documentation for instruction on how to validate this request based on the signature.

Import Pages Endpoint

Once you've received an import initialization request you can send batches of items to HubSpot via this Import Paged Endpoint.

Use the OAuth token for a specific customer to send these import pages requests.

PUT /import-pages/{importStartedAt}/{objectType}/{pageNumber}

Url params:

  • importStartedAt : The importStartedAt timestamp from the import intialization request.
  • objectType: The object type this data corresponds to. (CONTACT, DEAL, LINE_ITEM, or PRODUCT)
  • pageNumber: A numeric page number that identifies this page of data. Must be unique within this import.

Example request body:

[
  {
    "integratorObjectId": "001",
    "propertyNameToValues" : {
      "my_name_field": "Example Product",
      "image": "https://url.to.image/image.png"
    }
  },
  {
    "integratorObjectId": "002",
    "propertyNameToValues" : {
      "my_name_field": "Example Product 2",
      "image": "https://url.to.image/image-2.png"
    }
  }
]

The request body should consist of an array of Import Messages. You can specify up to 500 Import Messages per request.

Import Message Properties

Property name Property type Description
integratorObjectId String, max length 100 characters, ascii-only The ID, in your system, of the object that is being created/updated/deleted.
propertyNameToValues Map This is a map of your property names to the values for this object. These are the values that we will sync into corresponding HubSpot object.

Import Message are the same thing as Sync Messages, just without the action property. (All import messages are UPSERTs.)

Import Page End Endpoint

One you're done sending all import-pages for a specific object type you need to send an import page end request. In order for an import to complete successfully, HubSpot must receive import-end notifications for each object type: Contacts, Deals, Line Items, and Products.

Use the OAuth token for a specific customer to send these import page end requests.

PUT /import-pages/{importStartedAt}/{objectType}/end

Url params:

  • importStartedAt : The importStartedAt timestamp from the import intialization request.
  • objectType: The object type this data corresponds to. (CONTACT, DEAL, LINE_ITEM, or PRODUCT)

Example request body:

{
  "pageCount": 12,
  "itemCount": 5762
}

Request properties:

Property name Property type Description
pageCount Number The number of pages you sent via the import pages endpoint.
itemCount Number The total number of items you sent via the import pages endpoint.

This request will return a 400 error if the number of pages or items do not match what we actually received.

Object Creation and De-duplication

For all objects synced via the Ecommerce Bridge API we store a mapping from integratorObjectId to the corresponding HubSpot ID. Upserts for the same integratorObjectId will update the same object in HubSpot. If the Ecommerce Bridge API sees a new integratorObjectId it will create a new object in HubSpot.

One exception to this rule is if we see a new integratorObjectId for a Contact, we will first check to see if any contact exists with the same email address. If so, we will associate the new integratorObjectId to the matching contact and update the contact's properties. If a contact does not exist with a matching email address, we will create a new Contact.

6 Replies
Regular Contributor

@dadams Thanks for the walkthrough. Is this document up to date?

Reply
0 Upvotes
HubSpot Product Team

Hey @udayapitchika - this document is up to date! Any changes to the doc will be announced through this private forum.

Feel free to let us know if you have any other questions.

Reply
0 Upvotes
HubSpot Product Team

Hi all,
We just made some changes to the documentation posted above.

The new doc includes:

  • Language specific to developers using the api directly with their portal rather than through an application
  • A new property dataType (AVATAR_IMAGE) that is used to sync image urls
  • A new required Deal property (dealstage)
  • Clarification about the properties returned by /settings endpoints

A detailed diff can be viewed in the history of the post.

Community Manager

Hi all

The documentation was just updated with a warning about multiple installs.

While the ECommerce Bridge is in Beta, you should not install an app (using OAuth) that uses the ECommerce Bridge alongside a custom app (using a hapikey). This behavior is not supported during the beta, as you may have sync messages crossed between the two separate installs. Also, you will not be allowed to install a second app using the ECommerce Bridge in a portal that already has an ECommerce Bridge app installed, of if the portal is already using the HubSpot Shopify integration.

This will be fixed by the official launch.

Occasional Contributor

Thanks for the update @dadams

Reply
0 Upvotes
Not applicable

I have a consultant who needs access to this topic. How do I get him access?

Reply
0 Upvotes