Skip to main content

​
Build Commerce Experiences Across Multiple Merchants

Satsuma provides developers with a unified API to search products, manage carts, and place orders across hundreds of merchants. One API, consistent data format, real-time inventory.

Search Products

Query inventory across all merchants with filters for location, category, and availability

Manage Carts

Create merchant-specific carts and manage items before checkout

Place Orders

Submit orders with tokenized payments and receive real-time status updates

​
Quick Start

# Search products
curl 'https://api.satsuma.ai/product?query=wireless+headphones&latitude=37.7749&longitude=-122.4194&distance=10mi' \
  -H 'Authorization: sk_live_your_api_key'

# Create cart
curl -X POST 'https://api.satsuma.ai/cart' \
  -H 'Authorization: sk_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"location_id": "loc_abc123", "user_id": "user_xyz789", "status": "Active"}'

# Add items to cart
curl -X POST 'https://api.satsuma.ai/cart/{cart_id}/item' \
  -H 'Authorization: sk_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"product_id": "prod_123", "product_name": "Wireless Headphones", "quantity": 2}'

# Place order
curl -X POST 'https://api.satsuma.ai/order' \
  -H 'Authorization: sk_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"location_id": "loc_abc123", "fulfillment_method": "Delivery", "customer": {"id": "user_xyz789", "name": "John Doe", "address": {"street_address": "123 Main St", "city": "San Francisco", "region": "CA", "postal_code": "94105", "country": "US"}}, "items": [{"product_id": "prod_123", "quantity": 2}]}'

​
Core Concepts

​
Multi-Merchant Architecture

  • Product Search: Query across all merchants simultaneously
  • Merchant-Specific Carts: Each cart belongs to a single merchant
  • Independent Orders: Orders are placed with individual merchants
  • Unified Response Format: Consistent data structure across all merchants

​
Key Constraints

  • Carts cannot contain items from multiple merchants
  • Each order is submitted to a single merchant

​
What You Can Build

AI Shopping Assistants

Help users find products and complete purchases through natural conversation

Local Discovery Apps

Find products available near users with location-based search

Automated Purchasing

Build systems that reorder products automatically based on rules

​
API Capabilities

curl 'https://api.satsuma.ai/product?query=coffee&merchantId=merch_123&category=Beverages&latitude=37.7749&longitude=-122.4194&distance=5mi' \
  -H 'Authorization: your-api-key'

​
Cart Management

# Create cart for specific location
curl -X POST 'https://api.satsuma.ai/cart' \
  -H 'Authorization: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"location_id": "loc_123", "user_id": "user_456", "status": "Active"}'

# Add items to cart
curl -X POST 'https://api.satsuma.ai/cart/{cart_id}/item' \
  -H 'Authorization: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"product_id": "prod_789", "product_name": "Premium Coffee", "quantity": 3}'

# Update item quantity
curl -X PUT 'https://api.satsuma.ai/cart/{cart_id}/item/{item_id}' \
  -H 'Authorization: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"quantity": 5}'

​
Order Processing

# Create order directly
curl -X POST 'https://api.satsuma.ai/order' \
  -H 'Authorization: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"location_id": "loc_123", "fulfillment_method": "Delivery", "dropoff_instructions": "Leave at door", "customer": {"id": "user_456", "name": "Jane Doe", "address": {"street_address": "456 Oak St", "city": "San Francisco", "region": "CA", "postal_code": "94105", "country": "US"}}, "items": [{"product_id": "prod_789", "quantity": 3}]}'

# Get payment intent for order
curl 'https://api.satsuma.ai/order/{order_id}/payment-intent' \
  -H 'Authorization: your-api-key'

​
Authentication

All API requests require authentication via API key: 
curl https://api.satsuma.ai/product?latitude=37.7749&longitude=-122.4194 \
  -H "Authorization: sk_live_your_api_key"
Get your API key from the developer dashboard.

​
Rate Limits

Development

Free Tier
  • 1,000 requests/month
  • 5 requests/second
  • Sandbox environment

Production

Paid Plans
  • 50K-500K requests/month
  • 25-100 requests/second
  • Production access

​
Next Steps

API Reference

Explore all endpoints and parameters

SDKs

JavaScript, Python, and Go libraries

​
Need Help?

⌘I