Add to Cart

Add a product to the cart with quantity and variant.

Updated September 29, 2026

On this page

Overview

Add a product size to the cart. If no cart exists yet, one is created automatically.

SDK Usage

typescript

import dash from "@/lib/dash"

const { cart_id, item } = await dash.cart.add({
  productId: "prod_abc123",
  sizeId: "size_1g",
  quantity: 1,
})

Parameters

Parameter	Type	Required	Description
`productId`	string	Yes	The product ID
`sizeId`	string	Yes	The specific size/variant ID
`quantity`	number	No	Quantity to add (default: 1)
`freestyleSelections`	array	No	Custom selections for freestyle/bundle products
`subscriptionPlanId`	string	No	Start a subscription instead of buying once. A plan id from `size.subscription_plans`; see Subscription Cart Lines

Important: You must pass a sizeId, not just a product ID. Every purchasable item is a specific size within a product. Get available sizes from the product variations endpoint.

Add to Cart Button Example

typescript

"use client"
import { useState } from "react"
import dash from "@/lib/dash"

export function AddToCartButton({ productId, sizeId }: {
  productId: string
  sizeId: string
}) {
  const [loading, setLoading] = useState(false)
  const [added, setAdded] = useState(false)

  async function handleAdd() {
    setLoading(true)
    try {
      await dash.cart.add({ productId, sizeId, quantity: 1 })
      setAdded(true)
      setTimeout(() => setAdded(false), 2000)
    } catch (err) {
      alert(err.message)
    }
    setLoading(false)
  }

  return (
    <button onClick={handleAdd} disabled={loading}>
      {added ? "Added!" : loading ? "Adding..." : "Add to Cart"}
    </button>
  )
}

REST API

shell

POST /storefront/cart/add
X-API-Key: pk_live_your_key
Content-Type: application/json

{
  "product_id": "prod_abc123",
  "size_id": "size_1g",
  "quantity": 1,
  "cart_id": "cart_xyz"  // optional — omit to create new cart
}

Error Handling

Common errors when adding to cart:

Out of stock — The size has no inventory left
Invalid size — The size ID doesn't belong to the product
Quantity exceeds stock — Requested more than available

typescript

try {
  await dash.cart.add({ productId, sizeId, quantity: 5 })
} catch (err) {
  if (err.message.includes("stock")) {
    // Show stock warning
  }
}

Next Steps

Update Cart Item — Change quantities
Remove from Cart — Remove items
Recipe: Build a Cart Drawer — Full cart UI walkthrough

Add to Cart

Add a product to the cart with quantity and variant.

Updated September 29, 2026

On this page

Overview

Add a product size to the cart. If no cart exists yet, one is created automatically.

SDK Usage

typescript

import dash from "@/lib/dash"

const { cart_id, item } = await dash.cart.add({
  productId: "prod_abc123",
  sizeId: "size_1g",
  quantity: 1,
})

Parameters

Parameter	Type	Required	Description
`productId`	string	Yes	The product ID
`sizeId`	string	Yes	The specific size/variant ID
`quantity`	number	No	Quantity to add (default: 1)
`freestyleSelections`	array	No	Custom selections for freestyle/bundle products
`subscriptionPlanId`	string	No	Start a subscription instead of buying once. A plan id from `size.subscription_plans`; see Subscription Cart Lines

Important: You must pass a sizeId, not just a product ID. Every purchasable item is a specific size within a product. Get available sizes from the product variations endpoint.

Add to Cart Button Example

typescript

"use client"
import { useState } from "react"
import dash from "@/lib/dash"

export function AddToCartButton({ productId, sizeId }: {
  productId: string
  sizeId: string
}) {
  const [loading, setLoading] = useState(false)
  const [added, setAdded] = useState(false)

  async function handleAdd() {
    setLoading(true)
    try {
      await dash.cart.add({ productId, sizeId, quantity: 1 })
      setAdded(true)
      setTimeout(() => setAdded(false), 2000)
    } catch (err) {
      alert(err.message)
    }
    setLoading(false)
  }

  return (
    <button onClick={handleAdd} disabled={loading}>
      {added ? "Added!" : loading ? "Adding..." : "Add to Cart"}
    </button>
  )
}

REST API

shell

POST /storefront/cart/add
X-API-Key: pk_live_your_key
Content-Type: application/json

{
  "product_id": "prod_abc123",
  "size_id": "size_1g",
  "quantity": 1,
  "cart_id": "cart_xyz"  // optional — omit to create new cart
}

Error Handling

Common errors when adding to cart:

Out of stock — The size has no inventory left
Invalid size — The size ID doesn't belong to the product
Quantity exceeds stock — Requested more than available

typescript

try {
  await dash.cart.add({ productId, sizeId, quantity: 5 })
} catch (err) {
  if (err.message.includes("stock")) {
    // Show stock warning
  }
}

Next Steps

Update Cart Item — Change quantities
Remove from Cart — Remove items
Recipe: Build a Cart Drawer — Full cart UI walkthrough