Last modified: August 22, 2025
Use the subscriptions API to fetch information about an account’s commerce subscriptions. This is a read-only API, so it cannot be used for creating new or managing existing subscriptions. If you’re looking to manage marketing email subscriptions instead, check out the subscription preferences API. For example, use this API to fetch all currently active subscriptions.

​
Requirements

To use this API, the account must be set up to collect payments through either HubSpot payments or Stripe payment processing.

​
Retrieve subscriptions

Depending on the information you need, there are a few ways to retrieve subscriptions:
  • To retrieve all subscriptions, make a GET request to crm/v3/objects/subscriptions.
  • To retrieve a specific subscription, make a GET request to the above URL and specify a subscription ID. For example: crm/v3/objects/subscriptions/41112146008.
  • To retrieve subscriptions that meet a specific set of criteria, you can make a POST request to the search endpoint and include filters in the request body. See an example of using the search endpoint below.
The response will include a few default properties, including the create date, last modified date. 
{
  "id": "41112146008",
  "properties": {
    "hs_createdate": "2023-03-08T14:54:17.333Z",
    "hs_lastmodifieddate": "2024-03-01T22:33:09.011Z",
    "hs_object_id": "44446244097"
  },
  "createdAt": "2023-03-08T14:54:17.333Z",
  "updatedAt": "2024-03-01T22:33:09.011Z",
  "archived": false
}

​
Properties

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/subscriptions?properties=hs_status,hs_last_payment_amount 
{
  "id": "41112146008",
  "properties": {
    "hs_createdate": "2022-09-02T15:03:40.828Z",
    "hs_last_payment_amount": "200.00",
    "hs_lastmodifieddate": "2024-02-27T15:03:53.620Z",
    "hs_object_id": "41112146008",
    "hs_status": "active"
  },
  "createdAt": "2022-09-02T15:03:40.828Z",
  "updatedAt": "2024-02-27T15:03:53.620Z",
  "archived": false
}
To view all available subscription properties, make a GET request to crm/v3/properties/subscriptions. Learn more about using the properties API. Below are some common subscription properties that you may want to query.
Property nameLabel in UIDescription
hs_statusStatusThe current status of the subscription. Values include:
  • active
  • past_due
  • canceled
  • expired
  • scheduled
hs_recurring_billing_start_dateStart dateThe date that the subscription is scheduled to start.
hs_last_payment_amountLast payment amountThe amount that was charged during the most recent billing period.
hs_next_payment_amountNext payment amountThe amount that will be charged at the start of the next billing period.
hs_next_payment_due_dateNext payment due dateThe date that the next payment is due.

​
Search for subscriptions by properties

You can use the search endpoint to retrieve subscriptions 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 currently active subscriptions, you would make a POST request to crm/v3/objects/subscriptions/search with the following request body: 
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hs_status",
          "value": "active",
          "operator": "EQ"
        }
      ]
    }
  ],
  "properties": ["hs_status", "hs_last_payment_amount"]
}
Note that the filters array specifies the search criteria, while the properties array specifies which properties to return.

​
Associations

While you cannot set associations using this API, you can retrieve association information by making a GET request to the following URL: crm/v3/objects/subscriptions/{hs_object_id}/associations/{associatedObjectName} Associated objects can include contacts, companies, deals, quotes, line items, payments, discounts, fees, and taxes. These associations are typically set by the payment link or quote associated with the initial subscription payment. To manage these associations, you can update the subscription in HubSpot. Below is an example of how you might use this API combined with another API to get a specific set of association information.

​
Please note:

Line items belong to one single parent object. For example, if retrieving line items from a subscription, the line item ID’s will be different to those on a deal, or a quote.

​
Retrieving a subscription with associated line items

To retrieve a subscription and the line items associated with it, make a GET request to: crm/v3/objects/subscription/{hs_object_id}/associations/line_items This will return the IDs of the currently associated line items, along with meta information about the association type. 
{
  "results": [
    {
      "id": "1459694380",
      "type": "subscription_to_line_item"
    },
    {
      "id": "1459694381",
      "type": "subscription_to_line_item"
    }
  ]
}
You can then use the returned IDs to request more information about the line items through the line items API. For example, you could batch retrieve line items by ID with the following POST request: crm/v3/objects/line_items/batch/read 
{
  "inputs": [{ "id": "1459694380" }, { "id": "1459694381" }],
  "properties": ["name", "amount"]
}
The response would be formatted as follows: 
{
  "status": "COMPLETE",
  "results": [
    {
      "id": "1459694381",
      "properties": {
        "amount": "100.00",
        "createdate": "2023-11-08T18:23:06.361Z",
        "hs_lastmodifieddate": "2023-11-08T18:23:06.361Z",
        "hs_object_id": "1459694381",
        "name": "Recurring line item 2"
      },
      "createdAt": "2023-11-08T18:23:06.361Z",
      "updatedAt": "2023-11-08T18:23:06.361Z",
      "archived": false
    },
    {
      "id": "1459694380",
      "properties": {
        "amount": "100.00",
        "createdate": "2023-11-08T18:23:06.361Z",
        "hs_lastmodifieddate": "2023-11-08T18:23:06.361Z",
        "hs_object_id": "1459694380",
        "name": "Recurring line item 1"
      },
      "createdAt": "2023-11-08T18:23:06.361Z",
      "updatedAt": "2023-11-08T18:23:06.361Z",
      "archived": false
    }
  ],
  "startedAt": "2024-03-14T15:43:53.179Z",
  "completedAt": "2024-03-14T15:43:53.186Z"
}