Deal splits (BETA)

Please note: this API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer TermsDeveloper Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API.

If your HubSpot account has a Sales Hub Enterprise subscription, you can set up deal splits to split credit for deal amounts between multiple users. Once deal splits are turned on in your HubSpot account, you can use the deal splits API to create new deal splits or view and update existing splits.

Create or update deal splits

To add new splits or update existing splits for deals, make a POST request to crm/v3/objects/deals/splits/batch/upsert.

In your request, include the following fields for each deal:

Use this table to describe parameters / fields
The ID of the deal. You can retrieve this via the deals API.

An array that contains the user to assign a split to, and the percentage of the deal amount to assign. In the array, include the following fields:

ownerId: the owner ID assigned to the HubSpot user.

percentage: the percentage of the deal amount to assign to the owner.

When adding deal splits, the deal's owner must be included as a split owner, the split percentages must add up to 1.0, and you must meet the limits for the split user maximum and split percentage minimum set in your deal split settings.If any deals included in the batch request fail validation for these requirements, the request will result in an error. 

For example, to assign even deal credit to two users on a deal, your request would look like:

///Example request body { "inputs": [ { "id": 5315919905, "splits": [ { "ownerId": 41629779, "percentage": 0.5 }, { "ownerId": 60158084, "percentage": 0.5 } ] } ] }

If a deal didn't have existing splits, the splits will appear on the deal record following your request. If the deal had existing splits, they will be replaced by the splits you created in your request.

Retrieve deal splits

To view split information for deals, make a POST request to crm/v3/objects/deals/splits/batch/read. In your request, include the id values of the deals with splits you want to view. You can retrieve a deal's id via the deals API.

For example, to retrieve deal splits for two deals, your request could look like:

///Example request body { "inputs": [ { "id": "5315919905" }, { "id": "17137567105" } ] }

For each deal, the response will include the date and time the splits were created or updated, the IDs of users splitting the deal, and the percentage of the deal amount assigned to each user.

For two deals, the response would look similar to:

///Example response { "status": "COMPLETE", "results": [ { "id": "17137567105", "splits": [ { "id": "311226010924", "properties": { "hs_deal_split_percentage": "0.5", "hubspot_owner_id": "41629779" }, "createdAt": "2024-03-11T19:55:26.219Z", "updatedAt": "2024-03-11T19:55:26.219Z", "archived": false }, { "id": "311226010925", "properties": { "hs_deal_split_percentage": "0.25", "hubspot_owner_id": "60158084" }, "createdAt": "2024-03-11T19:55:26.219Z", "updatedAt": "2024-03-11T19:55:26.219Z", "archived": false }, { "id": "311226010926", "properties": { "hs_deal_split_percentage": "0.25", "hubspot_owner_id": "61891281" }, "createdAt": "2024-03-11T19:55:26.219Z", "updatedAt": "2024-03-11T19:55:26.219Z", "archived": false } ] }, { "id": "5315919905", "splits": [ { "id": "57675010822", "properties": { "hs_deal_split_percentage": "0.3333", "hubspot_owner_id": "81538190" }, "createdAt": "2021-06-16T21:04:09.264Z", "updatedAt": "2021-06-16T21:04:09.264Z", "archived": false }, { "id": "57675010821", "properties": { "hs_deal_split_percentage": "0.3333", "hubspot_owner_id": "81426347" }, "createdAt": "2021-06-16T21:04:09.264Z", "updatedAt": "2021-06-16T21:04:09.264Z", "archived": false }, { "id": "57675010820", "properties": { "hs_deal_split_percentage": "0.3334", "hubspot_owner_id": "60158084" }, "createdAt": "2021-06-16T21:04:09.264Z", "updatedAt": "2021-06-16T21:04:09.264Z", "archived": false } ] } ], "startedAt": "2024-03-11T19:56:42.555Z", "completedAt": "2024-03-11T19:56:42.596Z" }

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.