Add to cart

Add item to cart with automatic stock checking. If the same variant already exists in the cart, the quantity is incremented.

Variant Selection:

• variant_id is required to specify which variant to add (e.g., Black vs Blue color)
• For simple products (no variants), use the default variant’s ID
• Stock validation is performed against the specific variant

Cart Association:

• Provide X-Session-Id header for anonymous carts (before customer login)
• Provide customer_id in request body for authenticated customer carts
• If both provided, customer_id takes precedence
• If neither provided, returns 400 error

Key Type Support:

• Publishable keys (tybrite_pk_*) — fully supported (browser/storefront)
• Secret keys (tybrite_sk_*) — also supported (server-side)

Anonymous Cart Example:

POST /v1/cart/items
Authorization: Bearer tybrite_pk_live_YOUR_API_KEY
X-Session-Id: session-abc123-xyz789
Content-Type: application/json

{
  "variant_id": "83b6a47e-4f5c-4090-b8d3-4b606b78f1b4",
  "quantity": 2
}

Authenticated Cart Example:

POST /v1/cart/items
Authorization: Bearer tybrite_pk_live_YOUR_API_KEY
Content-Type: application/json

{
  "variant_id": "83b6a47e-4f5c-4090-b8d3-4b606b78f1b4",
  "quantity": 2,
  "customer_id": "650e8400-e29b-41d4-a716-446655440000"
}

POST /v1/cart/items

Add to cart

cURL

curl --request POST \
  --url https://api.tybritelabs.com/v1/cart/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "variant_id": "83b6a47e-4f5c-4090-b8d3-4b606b78f1b4",
  "quantity": 2,
  "customer_id": "650e8400-e29b-41d4-a716-446655440000",
  "product_id": "770e8400-e29b-41d4-a716-446655440000"
}
'

200

{
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "product_name": "Sony WH-1000XM4",
      "variant_name": "Black",
      "variant_attributes": {
        "color": "Black"
      },
      "product_sku": "SNY-WH1002",
      "thumbnail_url": "https://pub-41977a...r2.dev/.../primary-image.jpg",
      "media": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "url": "<string>",
          "position": 123,
          "alt_text": "<string>",
          "is_primary": true
        }
      ],
      "quantity": 2,
      "unit_price": 34999,
      "selling_price": 34999,
      "total_price": 69998,
      "stock_available": 10,
      "has_variants": true,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "total_items": 123,
  "subtotal": 123,
  "session_id": "<string>",
  "customer_id": "<string>"
}

Authorizations

Authorization · string · header · required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

• Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
• Full read/write access to all endpoints
• ⚠️ NEVER expose in client-side code or public repositories
• Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

• Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
• Read-only access (GET requests only, plus POST semantic search)
• ✅ Safe for client-side JavaScript, mobile apps, and public code
• Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

• Authentication endpoints (/v1/auth/*): Secret key required
• Payment verification (POST /v1/payments/verify): Secret key required
• AI Recommendations (POST /v1/recommendations): Secret key required
• Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
• All write operations: Secret key required
• All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Headers

x-auth-token · string

Customer session access_token from /v1/auth/login or /v1/auth/verify-otp. Required whenever customer_id is supplied so the gateway can prove the caller owns that customer record. Anonymous (session-only) carts may omit it.

X-Session-Id · string

Session ID for anonymous carts (UUID or random string stored in localStorage). Optional if customer_id is provided in the body.

Body

application/json

variant_id · string<uuid> · required

Specific product variant UUID (required for multi-variant products)

Example:

"83b6a47e-4f5c-4090-b8d3-4b606b78f1b4"

quantity · integer · required

Quantity to add

Required range: x >= 1

Example:

2

customer_id · string<uuid>

Customer UUID for authenticated carts (optional if using X-Session-Id)

Example:

"650e8400-e29b-41d4-a716-446655440000"

product_id · string<uuid>

Legacy/optional online product UUID. Ignored when variant_id is provided; included for backwards compatibility.

Example:

"770e8400-e29b-41d4-a716-446655440000"

Response

200

application/json

Item added (returns refreshed cart)

items · object[]

Show child attributes

total_items · integer

subtotal · number

session_id · string | null

customer_id · string | null