Cart & Wishlist

Add to cart

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

Auth / key type: publishable or secret key. This is a storefront write that is deliberately pk-accessible (it originates in the browser). Anonymous carts need only the key + X-Session-Id; authenticated carts (customer_id in the body) also require the customer session token (x-auth-token).

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": "9a47e047-b1b6-4c35-9617-820629e22e04",
  "quantity": 2
}

Authenticated Cart Example:

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

{
  "variant_id": "9a47e047-b1b6-4c35-9617-820629e22e04",
  "quantity": 2,
  "customer_id": "650e8400-e29b-41d4-a716-446655440000"
}

SDK example (adds the Sony WH-1000XM4 default variant, $349.99):

POST

cart

items

Add to cart

curl --request POST \
  --url https://api.tybritelabs.com/v1/cart/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "variant_id": "9a47e047-b1b6-4c35-9617-820629e22e04",
  "quantity": 2,
  "customer_id": "650e8400-e29b-41d4-a716-446655440000"
}
'

import requests

url = "https://api.tybritelabs.com/v1/cart/items"

payload = {
    "variant_id": "9a47e047-b1b6-4c35-9617-820629e22e04",
    "quantity": 2,
    "customer_id": "650e8400-e29b-41d4-a716-446655440000"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    variant_id: '9a47e047-b1b6-4c35-9617-820629e22e04',
    quantity: 2,
    customer_id: '650e8400-e29b-41d4-a716-446655440000'
  })
};

fetch('https://api.tybritelabs.com/v1/cart/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/cart/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'variant_id' => '9a47e047-b1b6-4c35-9617-820629e22e04',
    'quantity' => 2,
    'customer_id' => '650e8400-e29b-41d4-a716-446655440000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/cart/items"

	payload := strings.NewReader("{\n  \"variant_id\": \"9a47e047-b1b6-4c35-9617-820629e22e04\",\n  \"quantity\": 2,\n  \"customer_id\": \"650e8400-e29b-41d4-a716-446655440000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/cart/items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"variant_id\": \"9a47e047-b1b6-4c35-9617-820629e22e04\",\n  \"quantity\": 2,\n  \"customer_id\": \"650e8400-e29b-41d4-a716-446655440000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/cart/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"variant_id\": \"9a47e047-b1b6-4c35-9617-820629e22e04\",\n  \"quantity\": 2,\n  \"customer_id\": \"650e8400-e29b-41d4-a716-446655440000\"\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "6d2d55ff-d0ea-48b7-8c9c-6c6ef841c6d6",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "product_name": "Samsung Galaxy Watch 6",
      "variant_name": "Default",
      "variant_attributes": {},
      "product_sku": "SAM-WATCH-6-44-0186",
      "thumbnail_url": "https://media.tybritelabs.com/samsung-galaxy-watch-6.jpg",
      "media": [
        {
          "id": "dd630f03-fff1-455e-a927-46ddf36fde72",
          "url": "https://media.tybritelabs.com/samsung-galaxy-watch-6.jpg",
          "type": "image",
          "alt_text": "Samsung Galaxy Watch 6",
          "position": 0,
          "is_primary": true
        }
      ],
      "quantity": 2,
      "unit_price": 299,
      "selling_price": 299,
      "total_price": 598,
      "stock_available": 179,
      "has_variants": false,
      "created_at": "2026-06-20T13:49:14.603382+00:00",
      "updated_at": "2026-06-20T13:49:14.603382+00:00"
    }
  ],
  "total_items": 2,
  "subtotal": 598,
  "session_id": "session-abc123-xyz789",
  "customer_id": null
}

{
  "error": {
    "code": "insufficient_stock",
    "message": "Only 5 items available in stock",
    "available_stock": 5
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Variant not found or not available"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

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-external-auth

string

Bring-your-own-auth assertion for stores that manage authentication in an external identity provider (Auth0, Clerk, Cognito, Firebase, NextAuth, SSO). Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.

Format: <base64url(JSON)>.<base64url(HMAC-SHA256(JSON))> where the JSON is { "external_id": "...", "iat": <unix>, "exp": <unix> } and the HMAC is keyed on the store's signing secret. Claim lifetime capped at 300 seconds.

x-idp-token

string

A raw token from the store's own identity provider (e.g. a Firebase ID token). Galactic Core forwards it to the store's configured Auth verifier, which validates it and returns the identity.

Verification is fail-closed: if the verifier rejects the token or is unreachable, the request is unauthenticated (401). Requires an Auth verifier to be configured for the store. Provide exactly one of x-auth-token, x-external-auth, or x-idp-token.

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:

"9a47e047-b1b6-4c35-9617-820629e22e04"

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"

Response

Item added (returns refreshed cart)

items

object[]

Show child attributes

total_items

integer

subtotal

number

session_id

string | null

customer_id

string | null

Add to cart

curl --request POST \
  --url https://api.tybritelabs.com/v1/cart/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "variant_id": "9a47e047-b1b6-4c35-9617-820629e22e04",
  "quantity": 2,
  "customer_id": "650e8400-e29b-41d4-a716-446655440000"
}
'

import requests

url = "https://api.tybritelabs.com/v1/cart/items"

payload = {
    "variant_id": "9a47e047-b1b6-4c35-9617-820629e22e04",
    "quantity": 2,
    "customer_id": "650e8400-e29b-41d4-a716-446655440000"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    variant_id: '9a47e047-b1b6-4c35-9617-820629e22e04',
    quantity: 2,
    customer_id: '650e8400-e29b-41d4-a716-446655440000'
  })
};

fetch('https://api.tybritelabs.com/v1/cart/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/cart/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'variant_id' => '9a47e047-b1b6-4c35-9617-820629e22e04',
    'quantity' => 2,
    'customer_id' => '650e8400-e29b-41d4-a716-446655440000'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/cart/items"

	payload := strings.NewReader("{\n  \"variant_id\": \"9a47e047-b1b6-4c35-9617-820629e22e04\",\n  \"quantity\": 2,\n  \"customer_id\": \"650e8400-e29b-41d4-a716-446655440000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/cart/items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"variant_id\": \"9a47e047-b1b6-4c35-9617-820629e22e04\",\n  \"quantity\": 2,\n  \"customer_id\": \"650e8400-e29b-41d4-a716-446655440000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/cart/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"variant_id\": \"9a47e047-b1b6-4c35-9617-820629e22e04\",\n  \"quantity\": 2,\n  \"customer_id\": \"650e8400-e29b-41d4-a716-446655440000\"\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "6d2d55ff-d0ea-48b7-8c9c-6c6ef841c6d6",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "product_name": "Samsung Galaxy Watch 6",
      "variant_name": "Default",
      "variant_attributes": {},
      "product_sku": "SAM-WATCH-6-44-0186",
      "thumbnail_url": "https://media.tybritelabs.com/samsung-galaxy-watch-6.jpg",
      "media": [
        {
          "id": "dd630f03-fff1-455e-a927-46ddf36fde72",
          "url": "https://media.tybritelabs.com/samsung-galaxy-watch-6.jpg",
          "type": "image",
          "alt_text": "Samsung Galaxy Watch 6",
          "position": 0,
          "is_primary": true
        }
      ],
      "quantity": 2,
      "unit_price": 299,
      "selling_price": 299,
      "total_price": 598,
      "stock_available": 179,
      "has_variants": false,
      "created_at": "2026-06-20T13:49:14.603382+00:00",
      "updated_at": "2026-06-20T13:49:14.603382+00:00"
    }
  ],
  "total_items": 2,
  "subtotal": 598,
  "session_id": "session-abc123-xyz789",
  "customer_id": null
}

{
  "error": {
    "code": "insufficient_stock",
    "message": "Only 5 items available in stock",
    "available_stock": 5
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Variant not found or not available"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Add to cart

Authorizations

Headers

Body

Response