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.

The endpoint supports two mutually exclusive modes: variant add (variantId + quantity) and bundle add (bundleId + selections).

Variant Add

Add a single product variant to the cart. Setting quantity to 0 removes the item.

# 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

Bundle Add

Add a configured bundle as one line item. Get the available groups and choices from the bundle field on GET /api/v1/products/:idOrSlug for bundle-type products.

Each entry in selections:

Always-included (forced) items may be omitted from selections — the server fills them in automatically. Choices are validated server-side against the bundle's groups (per-group count, allow-duplicates, stock).

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "bundleId": "0191abc0-1234-7def-8000-000000000001",
    "selections": [
      {
        "variantId": "0191abc0-0000-7000-8000-000000000100",
        "groupId": "0191abc0-0000-7000-8000-000000000300",
        "quantity": 1
      }
    ]
  }' \
  https://your-store.yns.store/api/v1/carts

A 400 response with details is returned when the selections are invalid (wrong group count, disallowed duplicates, etc.).

Re-adding a bundle: If the same bundle is already in the cart with identical selections, the line quantity increments by one (capped by constituent stock). If the same bundle is already in the cart with different selections, the API returns 409 Conflict with a bundle_conflict code — remove the existing bundle from the cart first to change its options.

{
  "error": "Bundle already in cart with a different configuration",
  "details": ["This bundle is already in the cart with a different configuration. Remove it from the cart to change its options."]
}

Stock Overflow (409)

When the requested quantity exceeds the variant's available stock, the API returns 409 Conflict:

{
  "error": "Insufficient stock",
  "available": 5,
  "requested": 10
}

Available stock accounts for units reserved by other active carts when stock hold is enabled.

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}

Apply Coupon to Cart

POST /api/v1/carts/:id/coupon

Applies a discount code to a cart. The coupon is validated against its date range, usage cap, product count requirements, and product/collection/category/brand scope before being applied.

Request Body

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"code": "WELCOME10"}' \
  https://your-store.yns.store/api/v1/carts/0191abc0-1234-7def-8000-000000000001/coupon

Response (200)

Returns the full updated cart object with the coupon applied.

Validation Error (422)

When the coupon cannot be applied, a 422 is returned with a machine-readable reason:

{
  "error": "Coupon cannot be applied",
  "reason": "couponHasExpired"
}

Remove Coupon from Cart

DELETE /api/v1/carts/:id/coupon

Removes the applied coupon from a cart.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/carts/0191abc0-1234-7def-8000-000000000001/coupon

Response (200)

{
  "ok": true
}

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.