There's a new version of the HubSpot API
As of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. Your API Keys could be deactivated at any time after Nov. 30th, and we recommend that you migrate to Private Apps as soon as possible so you do not lose business-critical functionality.
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.
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
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. |
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 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 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.
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. |
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.
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. |
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 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 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.
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
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.
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 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 externalObjectId
you 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.
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" }
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 https://api.hubapi.com/extensions/ecomm/v2/sync/errors
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. |
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 ). |
INACTIVE_PORTAL
- the HubSpot account to be modified by the sync message has been disabledNO_SYNC_SETTINGS
- there are no EB sync settings found for your application or accountSETTINGS_NOT_ENABLED
- the EB settings for your application or account are not enabledNO_MAPPINGS_DEFINED
- the EB settings for your application or account did not define property mappings for any properties in the sync messageMISSING_REQUIRED_PROPERTY
- an object to be created is missing a required propertyNO_PROPERTIES_DEFINED
- the account to be modified by the sync message did not have any of the mapped properties defined on itINVALID_ASSOCIATION_PROPERTY
- the ID provided for an association does not correspond to any existing objectINVALID_ENUM_PROPERTY
- a value was provided for an enumerated property without a corresponding optionINVALID_DEAL_STAGE
- a deal update includes a deal stage that is not part of the ecommerce pipelineINVALID_EMAIL_ADDRESS
- a contact update includes an email address that is not validUNKNOWN_ERROR
- there was an unexpected problem trying to update object data in HubSpotNote: 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:
When a user initiates an import from HubSpot, HubSpot will send your system the initial import webhook.
Your system can then send all the relevent data for this customer's store to HubSpot via import pages
.
Your system uses the import end
endpoint to indicate that you are done sending data for a particular object-type.
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.
The import is complete.