Orders

Use the orders API to create and manage data related to ecommerce purchases in HubSpot. This can be especially useful for keeping HubSpot data synced with external ecommerce platforms, such as Shopify and NetSuite.

For example, when a buyer adds a set of products to their cart and makes a purchase, store that purchase as an individual order. You can then update that order with tracking information once the shipping label has been printed. Because this information is stored in a property, you can reference it in emails that you send to notify customers that their package is on the way. 

To create an order, make a POST request to crm/v3/objects/order.

In the request body, you can include the properties and associations objects to set property values and associate the order with other CRM objects (e.g., contacts and line items). Learn more about order properties and associations below.

Order details are stored in order properties. HubSpot provides a set of default order properties, but you can also create your own custom properties using the properties API.

To include properties when creating an order, add them as fields in a properties object in the request body. For example, the request body below would create an order with some basic order and shipping details based on the information provided by the buyer at checkout.

The response will include the information you provided during creation along with a few other default properties.

You can associate the order with other HubSpot CRM objects at creation by including an associations array. You can also use the associations API to update existing orders after creation.

In the associations array, include an object for each associated record using the following fields:

For example, the POST request body below would create an order that's associated with a specific contact and two line items. Properties are also included below the associations for setting initial order information.

Depending on the information you need, there are a few ways to retrieve orders:

• To retrieve all orders, make a GET request to /crm/v3/objects/order.
• To retrieve a specific order, make a GET request to the above URL and specify an order ID. For example: /crm/v3/objects/order/44446244097.
• To retrieve orders that meet a specific set of criteria, you can make a POST request to the search endpoint and include filters in the request body. Learn more about searching the CRM.

The response will include a few default properties, including the create date, last modified date.

To return specific properties, include a properties query parameter in the request URL along with comma-separated property names. For example, making a GET request to the following URL would result in the response below:

/crm/v3/objects/order?properties=hs_order_name,hs_source_store

To view all available order properties, you can query the properties API by making a GET request to crm/v3/properties/order.

Learn more about order properties.

You can use the search endpoint to retrieve orders that meet a specific set of filter criteria. This will be a POST request that includes your filter criteria in the request body.

For example, to search for all orders placed at a specific store, you would make a POST request to crm/v3/objects/order/search with the following request body:

Note that the filters array specifies the search criteria, while the properties array specifies which properties to return.

To update an order, make a PATCH request to /crm/v3/objects/order/{orderId}. In the request body, include a properties object containing the properties that you want to update. 

For example, if you wanted to update an order with the shipping tracking number, you could send the following request body:

The response will include a set of default properties along with the property that you just set.

To update the associations for an existing order, make a PUT request to /crm/v3/objects/order/{orderId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. You can also use the associations API.

For example, to associate an existing order with an existing payment, you would make a PUT request to the following URL:

/crm/v3/objects/order/{orderId}/associations/commerce_payments/{paymentId}/523

The response will return a set of default properties along with an associations object containing information about the association that you set.

To remove an association from an existing order, make a DELETE request to the following URL:

/crm/v3/objects/order/{orderId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

For example, if you wanted to remove an associated payment from an order, your request URL would be the following:

/crm/v3/objects/order/{orderId}/associations/commerce_payments/{paymentId}/523

When managing your order data, you may want to use some of the common properties in the table below. To get all order properties, make a GET request to /crm/v3/properties/order. Learn more about using the properties API.

To track an order's progress, you can create pipelines with defined stages for each step of the fulfillment process. For example, you could create a pipeline for online orders with stages for when the order has been opened, paid, processed, shipped, cancelled, and refunded.

Using the pipelines API, you can create an order pipeline by making a POST request to crm/v3/pipelines/order.  In the request body, you'll include a label for the pipeline, displayOrder for the display in HubSpot, and a stages array with objects for each stage.