CRM API | Deal splits - HubSpot docs

Scope requirements

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:

Field	Description
`id`	The ID of the deal. You can retrieve this via the deals API.
`splits`	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"
}

​Create or update deal splits

​Retrieve deal splits

Create or update deal splits

Retrieve deal splits