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

PropertyMapping Fields

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

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:

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

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

Messages have the following fields:

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/{storeId}/{objectType}/{externalObjectId}

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

Sync status fields

Get sync errors

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

Optional Query Parameters

Sync Error Fields

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.