Ecommerce Bridge API Reference

The Ecommerce Bridge v2 is part of our developer preview program, and should be considered as a non-stable release that will be subject to bugs and breaking changes while under development. Please take this into account as you build against a release. Please subscribe to our changelog for updates.
Looking for the original version of the Ecommerce Bridge? Find the docs for v1 here.
Check out the Ecommerce Bridge V2 API docs in the preview version of our API Explorer and let us know what you think in our forums!

Settings

The Settings API is used to configure how object properties will map between HubSpot and your ecommerce system.

When configuring these settings for an integration, use your developer account's HAPIkey along with the unique appId for your integration to authenticate for these calls.

When configuring these settings for an individual HubSpot account, no appId is needed. Use that account's unique API key to authenticate instead.

Settings Fields

Field name Field type Description
enabled Boolean Whether or not this application can sync data. Set this false to pause the sync from your application for maintenance or other reasons.
webhookUri String, URI Optional. The URI that HubSpot should use to start an import of an account's data. Learn more about imports.
mappings Map Map of ecommerce object type (CONTACT, PRODUCT, DEAL, LINE_ITEM) to property mappings for that object type.

PropertyMapping Fields

PropertyMapping describes how properties defined in your ecommerce system will map to properties defined in HubSpot.

Field name Field type Description
externalPropertyName String The name of the property in your system.
hubspotPropertyName String The name of the property in HubSpot.
dataType STRING, NUMBER, DATETIME, AVATAR_IMAGE Optional. The type of value expected for this property. Note:AVATAR_IMAGE is expected to be a url for an image. Only PRODUCT mappings can have dataType set to AVATAR_IMAGE, and only one mapping of this type can exist.

Create or update settings

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_bride__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"
        }
      ]
    }
  }
}

This PUT operation is an update-replace. Blank values will clear out existing data. On successful creation or update, your current settings will be returned as the response.

Get settings

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

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

{
  "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_bride__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"
        }
      ]
    }
  }
}

Delete settings

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

Note: This DELETE operation cannot be undone. If you'd like to disable sync messages from being applied using your property mappings, you should use the enabled field instead.

Provided mappings

HubSpot provides some additional required property mappings to all Ecommerce Bridge integrations. These are used by HubSpot to properly set source and association between contacts, companies, and deals. These required mappings are not editable, but showProvidedMappings is an optional boolean parameter that can be used with both the PUT and GET endpoints to retrieve them for reference. Note that doing so will prevent the responses from being symmetric.

Mappings provided on all object types:

Property name Type Description
ip__ecomm_bridge__ecomm_synced Boolean This will be set to true for all objects synced by EB.
ip__ecomm_bridge__source_app_id list of integers The unique IDs of all the apps that have synced data to the object. Only contacts can have multiple source app IDs. All other objects will always have a single value.
ip__ecomm_bridge__source_store_id list of strings The unique store IDs that have synced data to the object. Only contacts can have multiple source stores. All other objects will have a single value.

Stores

When developing for an integration, use an OAuth token in the Authorization header to authenticate these requests (see the OAuth 2.0 documentation for more details).

When developing for an individual HubSpot account, the OAuth token can be omitted and the API key for that account should be used instead.

Store Fields

Field name Field type Description
id String The identifier you use for your store.
label String A human readable title for the store. This will be used in several places in the HubSpot UI. It should clearly and uniquely identify this store for users.
adminUri String, valid URI Optional. An address to the website where a user can manage their store in your ecommerce system. This will allow a user to get there directly from the HubSpot UI.

Create or update a store

PUT https://api.hubapi.com/extensions/ecomm/v2/stores
{
  "id": "ecommercebridge-test-store",
  "label": "Ecommerce Bridge Test Store",
  "adminUri": "ecommercebridge-test-store.myshopify.com"
}

This PUT operation is an update-replace. Blank values will clear out existing data. On successful creation or update, the current store will be returned as the response.

Get a store

GET https://api.hubapi.com/extensions/ecomm/v2/stores/ecommercebridge-test-store
{
  "id": "ecommercebridge-test-store",
  "label": "Ecommerce Bridge Test Store",
  "adminUri": "ecommercebridge-test-store.myshopify.com"
}

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

Get all stores

GET https://api.hubapi.com/extensions/ecomm/v2/stores
{
  "results" : [
    {
      "id": "ecommercebridge-test-store",
      "label": "Ecommerce Bridge Test Store",
      "adminUri": "ecommercebridge-test-store.myshopify.com"
    }, 
    {
      "id": "ecommercebridge-test-store-2",
      "label": "Another Ecommerce Bridge Test Store",
      "adminUri": "ecommercebridge-test-store-2.myshopify.com"
    }
  ]
}

This endpoint will return all stores that your application has defined on the HubSpot account.

Delete a store

Use this endpoint to delete stores from the HubSpot account when a user disconnects a single store or your entire application. This will not delete or corrupt any data in the account.

DELETE https://api.hubapi.com/extensions/ecomm/v2/stores/ecommercebridge-test-store

Sync Messages

Use the Sync Messages API to send create, update, and delete events to HubSpot when ecommerce objects in your system have changed.

When developing for an integration, use the OAuth token for a specific customer to send these Sync Message requests. When developing for an individual HubSpot account, use that account's API key.

Sync Message Fields

Field name Field type Description
objectType CONTACT, PRODUCT, DEAL, LINE_ITEM The type of the object being changed.
storeId String The ID of the store being changed.
messages Array of message objects Note: Up to 200 messages can be submitted in the same batch. They can be for different objects of the same type.

Messages have the following fields:

Field name Field type Description
externalObjectId String, max length 100 characters, must be in ASCII format The ID in your system for the object being modified.
action UPSERT or DELETE The type of change this describes.
changedAt long Optional. The epoch millisecond timestamp when the change that this message describes occurred in your ecommerce system. Providing this value is optional, but strongly recommended. If not provided, the time the message was received by HubSpot will be used instead.
properties Map Map of external property names and values for this object. These are the values that we will sync into the corresponding HubSpot object.
associations Map Map of associated object type to associated external IDs.

Put sync messages

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"
        ]
      }
    }
  ]
}

Note: This endpoint is not subject to our per-second or per-day API rate limits.

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

UPSERT messages for the same externalObjectId will update the same object in HubSpot, with the most recent changedAt value taking precedence.

One exception to this rule is if a new externalObjectId is used for a contact. In this case, HubSpot will first check to see if any contact exists with the same email address. If so, the new externalObjectId will be associated with that contact instead. If a contact does not exist with a matching email address, we will create a new contact.

Email is a required property for all contacts created through the Ecommerce Bridge, and we do not support changing contact email addresses at this time.

Get sync status

Because sync messages are processed asynchronously, problems with processing are not surfaced at the time of submission. Instead, you can use the following Sync Status and Sync Errors endpoints to monitor the state of your sync messages and retrieve errors related to the processing of ecommerce data.

GET https://api.hubapi.com/extensions/ecomm/v2/sync/status/{objectType}/{storeId}/{externalObjectId}
{
  "lastProcessedAt": "1542094119555",
  "hubspotId": 5402,
  "errors": [],
  "objectType": "CONTACT",
  "storeId": "ecommercebridge-test-store",
  "externalObjectId": "daniel452834529"
}

Sync status fields

Field name Field type Description
lastProcessedAt long Epoch millisecond timestamp of the last time a sync message was successfully processed for the given object. Possibly null.
hubspotId long The ID of the HubSpot object that the given external object is linked to. Possibly null.
errors Array of Sync Error objects A list of any errors that occurred when processing a sync message for the given object.
objectType CONTACT, PRODUCT, DEAL, LINE_ITEM Type of the object
storeId String Store ID of the object
externalObjectId String External ID of the object

Get sync errors

GET https://api.hubapi.com/extensions/ecomm/v2/sync/errors

Optional Query Parameters

Param name Param type Default value Description
objectType CONTACT, PRODUCT, DEAL, LINE_ITEM none Filter to return only errors for objects of the given type.
errorType String, Enum none Filter to return only errors of the given type.
showResolvedErrors boolean false Specifies whether errors that have been resolved should be returned.
limit integer, max 200 200 The maximum number of errors to be returned.
offset integer 0 The index of the first error to be returned.

Sync Error Fields

Field name Field type Description
portalId integer The ID of the HubSpot account in which the error(s) occurred.
storeId String The numeric ID of the store for which the error(s) occurred.
objectType CONTACT, PRODUCT, DEAL, LINE_ITEM The type of the object for which the error(s) occurred.
externalObjectId String, max length 100 characters, must be in ASCII format The unique ID in your ecommerce system of the object that has one or more sync errors.
changedAt long The epoch millisecond timestamp for the sync message that caused an error.
erroredAt long The epoch millisecond timestamp when the error happened.
type Enum Described below
details String More information about the error that happened.
status OPEN or RESOLVED Tells whether the errored object has been successfully synced since this error occurred (erroredAt).

Error Types

  • INACTIVE_PORTAL - the HubSpot account to be modified by the sync message has been disabled
  • NO_SYNC_SETTINGS - there are no EB sync settings found for your application or account
  • SETTINGS_NOT_ENABLED - the EB settings for your application or account are not enabled
  • NO_MAPPINGS_DEFINED - the EB settings for your application or account did not define property mappings for any properties in the sync message
  • MISSING_REQUIRED_PROPERTY - an object to be created is missing a required property
  • NO_PROPERTIES_DEFINED - the account to be modified by the sync message did not have any of the mapped properties defined on it
  • INVALID_ASSOCIATION_PROPERTY - the ID provided for an association does not correspond to any existing object
  • INVALID_ENUM_PROPERTY - a value was provided for an enumerated property without a corresponding option
  • INVALID_DEAL_STAGE - a deal update includes a deal stage that is not part of the ecommerce pipeline
  • INVALID_EMAIL_ADDRESS - a contact update includes an email address that is not valid
  • UNKNOWN_ERROR - there was an unexpected problem trying to update object data in HubSpot

Imports

Note: This section of the API is under construction.

Imports are only available for application development, not when development for an individual HubSpot account.

The import process is an optional contract that we provide to allow for entering historical ecommerce data into HubSpot. Sync messages work well for keeping HubSpot up to date, but a user might request to import all previous customer and order data from your system as well.

It works as follows:

  1. When a user initiates an import from HubSpot, HubSpot will send your system the initial import webhook.

  2. Your system can then send all the relevent data for this customer's store to HubSpot via import pages.

  3. Your system uses the import end endpoint to indicate that you are done sending data for a particular object-type.

  4. When HubSpot receives import end requests for all object types (CONTACT, DEAL, PRODUCT, and LINE_ITEM), the import will being processing all the data and apply all the requested changes to HubSpot.

  5. The import is complete.