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.

Send ecommerce sync messages

Last updated July 13, 2020

PUT /extensions/ecomm/v2/sync/messages

Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?





Marketing & CRM

Required Scope:


Send a group of sync messages for a specific object type. Sync messages would be notifications of creates, updates, or deletes of ecommerce objects.

Up to 200 sync messages can be included in a single request.


Required Parameters How to use Description
OAuth Access Token or API Key Authorization: Bearer {token} header or hapikey={key} query parameter. Used to authenticate the request. Please see this page for more details about authentication.
Object Type "objectType": xxxx
Used in the request body
The object type that the updates are for. One of CONTACT, DEAL, PRODUCT, or LINE_ITEM.
Store Id

Used in the request body

The ID of the store that the objects are being synced for.
Messages "messages":[ ...]
Used in the request body 
Array of message objects - up to 200 messages can be submitted in the same batch

The request will be a list of sync messages. Each message must include the following fields.

Field name  Field type Description
externalObjectId String, max length 100 characters, ascii-only The ID, in your system, of the object that is being created, updated, or deleted.

The type of action this message describes. One of UPSERT or DELETE. Please note: that the DELETE action type will not remove the object from HubSpot, it will prevent it from syncing in the future.

In addition, sync messages will not restore or recreate deleted object records with the same externalObjectId value.

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. Please note: Once created with a sync message, a Contacts email property cannot be updated with an additional sync message.  

associations Map

Map of associated object type to associated external IDs.