Create and Handle Carts

This tutorial guides you through creating and managing a shopping cart using the Care Portals Public API. You will learn how to create a cart, add items, and update or remove them before proceeding to the next stage of the purchase process.

This guide is designed for developers who are building a custom e-commerce or product selection experience and need to manage the state of a shopping cart before a user is authenticated and enters the final checkout flow.

Prerequisites

Before you begin, make sure you have the following:

Configured Products: Ensure you have products available and configured for ordering within your organization's catalog.
Organization ID (<ORG_ID>): You must include your unique Organization ID in the header of every request to the Public API.

📘
Organization ID (<ORG_ID>)

For a CarePortals subdomain: You don’t need to send the Organization ID (<ORG_ID>) in the request header since it’s retrieved from the domain.

For a custom domain configuration: If you are hosting the checkout on a custom domain, you must send the Organization ID (<ORG_ID>) in the request header.

Flow Overview

Here's a high-level overview of the cart management flow:

Create a Cart: Initialize a new shopping cart and add the first item(s).
Add Items to the Cart: Add more items to the newly created cart.
Update an Item in the Cart (Optional): Modify the quantity of an item already in the cart.
Remove an Item from the Cart (Optional): Delete an item from the cart.
Proceed to Checkout: Transition from cart management to the final checkout workflow.

Step 1: Create a Cart

The first step is to create a shopping cart for the user. To do this, use the Create a Cart endpoint with a POST request. You can add initial items to the cart by including their productId and quantity in the request body. The response will contain the full cart object, including the _id, which we'll refer to as the <CART_ID>.

curl -X POST 'https://public-api.portals.care/public/v2/carts' \
-H 'organization: <ORG_ID>' \
-H 'Content-Type: application/json' \
-d '[
  {
    "productId": "67913a49df75bdf65ad795f3",
    "quantity": 1
  }
]'

{
    "_id": "<CART_ID>",
    "organization": "<ORG_ID>",
    "lineItems": [
        {
            "id": "<ITEM_ID>",
            "name": "Sample Product A",
            "productId": "67913a49df75bdf65ad795f3",
            "sku": "SP-A-001",
            "price": 25,
            "listPrice": 25,
            "quantity": 1,
            "isSubscription": false,
            "type": "physical"
        }
    ],
    "totalAmount": 25,
    "discountAmount": 0,
    "baseAmount": 25,
    "createdAt": "2025-09-19T14:00:00.000Z",
    "updatedAt": "2025-09-19T14:00:00.000Z"
}

The API will respond with the newly created cart object. You must save the _id from this response, as you'll need it for all subsequent cart operations.

📘
Anytime you modify the cart (add, update, or remove an item), the API returns the latest cart state. Always use the most recent response as your application's source of truth to avoid state drift.

Step 2: Add Items to the Cart

To add more products to an existing cart, call the Add Item to Cart endpoint with a POST request. You must include the <CART_ID> from the previous step in the URL path. The request body should contain an array of the new items you want to add.

curl -X POST 'https://public-api.portals.care/public/v2/carts/<CART_ID>/items' \
-H 'organization: <ORG_ID>' \
-H 'Content-Type: application/json' \
-d '[
  {
    "productId": "84524b51ef89acg76be826g4",
    "quantity": 2
  }
]'

{
    "_id": "<CART_ID>",
    "organization": "<ORG_ID>",
    "lineItems": [
        {
            "id": "<ITEM_ID>",
            "name": "Sample Product A",
            "productId": "67913a49df75bdf65ad795f3",
            "sku": "SP-A-001",
            "price": 25,
            "listPrice": 25,
            "quantity": 1,
            "isSubscription": false,
            "type": "physical"
        },
        {
            "id": "f3b2c1a0-e9d8-c7b6-a5b4-c3d2e1f0a9b8",
            "name": "Sample Product B",
            "productId": "84524b51ef89acg76be826g4",
            "sku": "SP-B-002",
            "price": 10,
            "listPrice": 10,
            "quantity": 2,
            "isSubscription": false,
            "type": "physical"
        }
    ],
    "totalAmount": 45,
    "discountAmount": 0,
    "baseAmount": 45,
    "createdAt": "2025-09-19T14:00:00.000Z",
    "updatedAt": "2025-09-19T14:02:00.000Z"
}

A successful request returns the updated cart object, which now includes the new item and revised totals.

Step 3 (Optional): Update an Item in the Cart

If you need to change the quantity of an item that is already in the cart, use the Update Item in Cart endpoint with a PUT request. This request requires both the <CART_ID> and the specific <ITEM_ID> of the product you wish to modify in the URL path.

curl -X PUT 'https://public-api.portals.care/public/v2/carts/<CART_ID>/items/<ITEM_ID>' \
-H 'organization: <ORG_ID>' \
-H 'Content-Type: application/json' \
-d '{
  "productId": "67913a49df75bdf65ad795f3",
  "quantity": 3
}'

{
    "_id": "<CART_ID>",
    "organization": "<ORG_ID>",
    "lineItems": [
        {
            "id": "<ITEM_ID>",
            "name": "Sample Product A",
            "productId": "67913a49df75bdf65ad795f3",
            "sku": "SP-A-001",
            "price": 25,
            "listPrice": 25,
            "quantity": 3,
            "isSubscription": false,
            "type": "physical"
        },
        {
            "id": "<ITEM_ID>",
            "name": "Sample Product B",
            "productId": "84524b51ef89acg76be826g4",
            "sku": "SP-B-002",
            "price": 10,
            "listPrice": 10,
            "quantity": 2,
            "isSubscription": false,
            "type": "physical"
        }
    ],
    "totalAmount": 95,
    "discountAmount": 0,
    "baseAmount": 95,
    "createdAt": "2025-09-19T14:00:00.000Z",
    "updatedAt": "2025-09-19T14:05:00.000Z"
}

The response returns the complete cart object with the updated quantity for the specified item and the new grand total.

Step 4 (Optional): Remove an Item from the Cart

To completely remove an item from the cart, make a DELETE request to the Delete Item in Cart endpoint. This action also requires both the <CART_ID> and the <ITEM_ID> in the URL path.

curl -X DELETE 'https://public-api.portals.care/public/v2/carts/<CART_ID>/items/<ITEM_ID>' \
-H 'organization: <ORG_ID>'

{
    "_id": "<CART_ID>",
    "organization": "<ORG_ID>",
    "lineItems": [
        {
            "id": "<ITEM_ID>",
            "name": "Sample Product B",
            "productId": "84524b51ef89acg76be826g4",
            "sku": "SP-B-002",
            "price": 10,
            "listPrice": 10,
            "quantity": 2,
            "isSubscription": false,
            "type": "physical"
        }
    ],
    "totalAmount": 20,
    "discountAmount": 0,
    "baseAmount": 20,
    "createdAt": "2025-09-19T14:00:00.000Z",
    "updatedAt": "2025-09-19T14:08:00.000Z"
}

The response contains the final cart details and an array of saved paymentMethods. If the array is empty, you'll need to prompt the user to add a new payment method.

Step 5: Proceed to Checkout

Once the cart is configured with the desired items, the next step is to hand off the cart to an authenticated user to complete the purchase.

For detailed instructions on this process, see the Build a Custom Checkout guide.