Skip to main content

Universal Cart

Manage shopping carts with real-time pricing from merchants. Get accurate tax and shipping costs before checkout by creating a cart, adding items from multiple stores, and providing a shipping address. The cart handles multi-merchant complexity automatically, giving you a unified view of all costs.

See API Reference for complete endpoint documentation.

Quick Start​

import requests

headers = {"api-key": "YOUR_API_KEY"}

# 1. Create cart
cart = requests.post(
    "https://api.simplecheckout.ai/v0/carts",
    headers=headers
).json()

# 2. Add items (from Catalog search or direct variant IDs)
requests.post(
    f"https://api.simplecheckout.ai/v0/carts/{cart['id']}/lines",
    headers=headers,
    json={"product_variant_id": "variant_id_here", "quantity": 1}
)

# 3. Update address to get real pricing
cart = requests.patch(
    f"https://api.simplecheckout.ai/v0/carts/{cart['id']}",
    headers=headers,
    json={
        "shipping_address": {
            "first_name": "John", 
            "last_name": "Doe",
            "email": "[email protected]", 
            "phone": "+1234567890",
            "line1": "123 Main St", 
            "city": "Austin",
            "region": "TX", 
            "postal_code": "78701", 
            "country": "US"
        }
    }
).json()

# 4. See final pricing
print(f"Total: ${cart['total_price']}")

Key Concepts​

Universal Cart: Contains items from multiple merchants in a single cart. You work with one cart ID, the API handles the complexity.

Price Synchronization: Adding a shipping address triggers real-time pricing updates from merchants, giving you accurate tax and shipping costs.

Cart Status:

  • open - Can be modified
  • locked - Finalized, cannot be modified
  • converted - Purchase completed
  • abandoned - Inactive

How It Works​

Create a cart, add items from multiple merchants, and update the shipping address to trigger real-time pricing with accurate tax and shipping costs.

Cart Structure​

When you add a shipping address, the cart response includes:

  • Cart details - ID, status, and shipping address
  • Line items - Individual products with pricing and merchant information
  • Merchant breakdown - Per-merchant pricing including subtotal, shipping, tax, and total
  • Unified totals - Overall cart totals across all merchants

Key response features:

  • Real-time pricing updates when shipping address is added
  • Multi-merchant support with per-merchant pricing breakdown
  • Line items grouped by merchant for easy processing
  • All prices returned as strings with 2 decimal places

Important Details​

Address Requirements: All fields required except line2. Format: first_name, last_name, email, phone, line1, line2 (optional), city, region (state code like "CA" or "TX"), postal_code, country (currently only "US").

Multi-Merchant Support: Add items from different merchants to a single cart. The API handles the complexity and returns unified pricing.

Price Updates: Without a shipping address, tax_price and shipping_price are "0.00". Adding an address triggers real-time calculation from merchants.

Catalog Integration: Use variant IDs from Product Search results directly in the product_variant_id field.

Next Steps​