Carts API

REST API endpoints for managing shopping carts.

Add to Cart / Create Cart

POST /api/v1/carts

Creates a new cart or updates an existing one. To create a new cart, omit cartId. To add to an existing cart, include it. Setting quantity to 0 removes the item.

Request Body

# Create a new cart
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "variantId": "0191abc0-0000-7000-8000-000000000100",
    "quantity": 1
  }' \
  https://your-store.yns.store/api/v1/carts

# Add to existing cart
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cartId": "0191abc0-1234-7def-8000-000000000001",
    "variantId": "0191abc0-0000-7000-8000-000000000200",
    "quantity": 2
  }' \
  https://your-store.yns.store/api/v1/carts

Response

Returns the complete cart with all line items:

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "lineItems": [
    {
      "variantId": "0191abc0-0000-7000-8000-000000000100",
      "quantity": 1,
      "price": "2500",
      "product": {
        "name": "Classic Tee",
        "slug": "classic-tee"
      }
    }
  ]
}

Get Cart

GET /api/v1/carts/:id

Returns the full cart with all line items, product details, and computed totals.

Delete Cart

DELETE /api/v1/carts/:id

Permanently deletes a cart and all its line items.

Checkout Redirect

GET /api/v1/carts/:id/checkout

Redirects (HTTP 308) to the store's hosted checkout page for the given cart. Useful for headless integrations that need to hand off to the YNS checkout flow.

308 → https://your-store.yns.store/checkout/r/{cartId}

Remove Line Item

DELETE /api/v1/carts/:id/line-items/:variantId

Removes a specific variant from the cart. Returns the updated cart.

Query Parameters

For subscription items, include the subscriptionPlanId to identify the correct line item.