Manage Subscriptions

This guide explains how to use the Care Portals Patient API to retrieve and manage a patient's existing product subscriptions. You will learn how to do the following:

View Subscriptions
Update a Subscription Renewal Date
Pause a Subscription

The following sections provide a detailed walkthrough of each action.

Prerequisites

Before you begin, ensure you have the following:

Patient JSON Web Token (JWT): An authenticated patient is required to access subscription information. All requests in this guide must include the patient's JWT in the Authorization header.
Organization ID (<ORG_ID>): If you are using a custom domain, you must send the Organization ID (<ORG_ID>) in the request header. For requests made from a CarePortals subdomain, this header is not required, as the ID is retrieved from the domain itself.

View Subscriptions

To display subscription details in your custom patient portal, you first need to retrieve a list of all subscriptions associated with the authenticated patient by calling the List Subscriptions endpoint with a GET request.

This endpoint returns an array of subscription objects, which you can use to populate a user interface where patients can view their subscription history and details.

curl -X GET 'https://patient-api.portals.care/patient/subscriptions' \
-H 'organization: <ORG_ID>' \
-H 'Authorization: Bearer <YOUR_JWT>'

[
  {
    "_id": "sub_1m2n3o4p5q6r7s8t",
    "organization": "<ORG_ID>",
    "customer": {
      "_id": "a1b2c3d4e5f6a1b2c3d4e5f6",
      "firstName": "John",
      "lastName": "Doe"
    },
    "status": "Active",
    "nextCycleDate": "2025-09-28T00:00:00.000Z",
    "lineItems": [
      {
        "name": "Ozempic Weight Loss Plan",
        "productId": "67913a49df75bdf65ad795f3",
        "quantity": 1,
        "price": 85.00
      }
    ]
  }
]

📘
Retrieve a Specific Subscription
You can add a subscription's _id as query param to retrieve the data for that specific subscription. For example: /patient/subscriptions/12345 will return the data of the subscription with the ID 12345.

Update a Subscription Renewal Date

To change the renewal date of a subscription, you can use the Update Subscription endpoint with a PUT request. You will need the subscriptionId of the subscription you wish to modify. In the request body, provide the new nextCycleDate in ISO 8601 format.

curl -X PUT 'https://patient-api.portals.care/patient/subscriptions/<subscriptionId>' \
-H 'organization: <ORG_ID>' \\
--header 'Authorization: Bearer <YOUR_JWT>' \
--header 'Content-Type: application/json' \
--data '{ "nextCycleDate": "2025-09-10T22:19:31.744Z" }'

{
  "_id": "68ae25b35e032cf8c396b1d0",
  "organization": "<ORG_ID>",
  "customer": {
    "_id": "67b4751a88fcbf517941f3b1",
    "email": "[email protected]",
    "phone": "+11231231231",
    "firstName": "John",
    "lastName": "Doe"
  },
  "product": {
    "_id": "68ae2064e3a586248c49ec1d",
    "organization": "<ORG_ID>",
    "label": "Ozempic",
    "subLabel": "",
    "description": null,
    "listPrice": 299,
    "price": 299,
    "cost": 299,
    "currency": "USD",
    "status": "active",
    "type": "physical",
    "images": [],
    "isSubscription": true
  },
  "status": "active",
  "stripePriceId": null,
  "stripeSubscriptionId": "sub_1S2tJ8KeCoUxIkZxbClPRf5u",
  "nextCycleDate": "2025-09-10T22:19:31.744Z",
  "createdAt": "2025-08-26T21:22:59.441Z",
  "updatedAt": "2025-08-26T21:28:01.151Z",
  "__v": 0
}

The API will then update the subscription and return the updated subscription object in the response.

Pause a Subscription

To pause a patient's subscription, you can use the Update Subscription endpoint with a PUT request. To use this endpoint, you'll need the subscriptionId of the subscription you want to pause. You'll include this ID in the URL and set the status to paused in the request body.

📘
To resume a subscription, use the same endpoint with the status parameter set to active

curl -X PUT 'https://patient-api.portals.care/patient/subscriptions/<subscriptionId>' \
-H 'organization: <ORG_ID>' \\
--header 'Authorization: Bearer <YOUR_JWT>' \
--header 'Content-Type: application/json' \
--data '{ "status": "paused" }'

{
  "_id": "<subscriptionId>",
  "organization": "<ORG_ID>",
  "customer": {
    "_id": "67b4751a88fcbf517941f3b1",
    "email": "[email protected]",
    "phone": "+11231231231",
    "firstName": "John",
    "lastName": "Doe"
  },
  "product": {
    "_id": "68ae2064e3a586248c49ec1d",
    "organization": "<ORG_ID>",
    "label": "Ozempic",
    "subLabel": "",
    "description": null,
    "listPrice": 299,
    "price": 299,
    "cost": 299,
    "currency": "USD",
    "status": "active",
    "type": "physical",
    "images": [],
    "isSubscription": true
 },
  "status": "paused",
  "statusHistory": [
        {
            "prevStatus": "active",
            "newStatus": "paused",
            "updatedAt": "2025-08-26T21:28:01.150Z",
            "userId": "685a8973d64feeb776922a97"
        } ],
"stripePriceId": null,
  "stripeSubscriptionId": "sub_1S2tJ8KeCoUxIkZxbClPRf5u",
  "nextCycleDate": "2025-09-10T22:19:31.744Z",
  "createdAt": "2025-08-26T21:22:59.441Z",
  "updatedAt": "2025-08-26T21:28:01.151Z",
  "__v": 0
}

Once the request is successfully processed, the API returns the updated subscription object, which will show the new status as paused.