v1 — Stable

Cart API

E-commerce intelligence API for agents and developers. Discover stores, products, ads, and trends across the entire e-commerce landscape.

Get API Key Quick Start

Quick Start #

Get up and running with the Cart API in under a minute.

1. Get your API key

2. Install the SDK

$ npm install @usecart/sdk

$ pip install usecart

3. Make your first request

TypeScript
import { CartClient } from '@usecart/sdk';

const cart = new CartClient('cart_sk_YOUR_KEY');

const stores = await cart.stores.search({
  keyword: 'fitness',
  platform: 'shopify',
  min_traffic: 10000
});

console.log(stores.data);
// [{ domain: "gymshark.com", traffic: 4200000, ... }, ...]

Python
from usecart import Cart

cart = Cart("cart_sk_YOUR_KEY")

stores = cart.stores.search(
    keyword="fitness",
    platform="shopify",
    min_traffic=10000
)

print(stores.data)
# [{"domain": "gymshark.com", "traffic": 4200000, ...}, ...]

Bash
curl "https://api.usecart.com/v1/stores?keyword=fitness&platform=shopify&min_traffic=10000" \
  -H "Authorization: Bearer cart_sk_YOUR_KEY"

Authentication #

All API requests require authentication via an API key sent as a Bearer token.

HTTP Header
Authorization: Bearer cart_sk_...

ℹ️

Get your API key at usecart.com/developers. Keys begin with cart_sk_ and should be kept secret.

Rate Limits & Pricing

Each API key has a daily request limit based on your plan tier.

Tier	Daily Limit	Price
Free	100 requests	$0
Pro	10,000 requests	$49/mo
Business	100,000 requests	$199/mo
Enterprise	1,000,000 requests	Custom

⚠️

When you exceed your rate limit, the API returns a 429 status with a rate_limit_exceeded error. The response includes a Retry-After header indicating when you can resume.

Response Format #

All successful responses follow a consistent envelope structure.

JSON
{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": 1234567890
  },
  "usage": {
    "requests_today": 42,
    "limit": 100
  }
}

Field	Type	Description
data	object \| array	The requested resource(s)
meta	object	Request metadata including unique ID and timestamp
usage	object	Current usage against your daily limit

Paginated endpoints include additional fields in meta:

JSON
{
  "meta": {
    "request_id": "req_abc123",
    "timestamp": 1234567890,
    "page": 1,
    "per_page": 20,
    "total": 1483,
    "total_pages": 75
  }
}

Stores #

Discover, analyze, and compare e-commerce stores across every major platform.

GET /v1/stores Search stores

Search and filter across millions of e-commerce stores.

Query Parameters

Parameter	Type	Description
keyword	string	Search term to match against store name, description, and niche
platform	string	Filter by platform: `shopify`, `woocommerce`, `bigcommerce`, `magento`, `custom`
language	string	ISO 639-1 language code (e.g., `en`, `fr`)
currency	string	ISO 4217 currency code (e.g., `USD`, `EUR`)
biz_model	string	Business model: `dropshipping`, `private_label`, `wholesale`, `print_on_demand`
has_ads	boolean	Filter stores currently running paid ads
status	string	Store status: `active`, `inactive`, `new`
min_traffic	integer	Minimum estimated monthly visitors
sort	string	Sort by: `relevance`, `traffic`, `products`, `created`
page	integer	Page number (default: `1`)
per_page	integer	Results per page, 1–100 (default: `20`)

Example Response

JSON
{
  "data": [
    {
      "domain": "pawsome-pets.com",
      "name": "Pawsome Pets",
      "platform": "shopify",
      "language": "en",
      "currency": "USD",
      "biz_model": "dropshipping",
      "monthly_traffic": 45200,
      "product_count": 312,
      "has_ads": true,
      "status": "active",
      "created_at": "2024-03-15T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_s1a2b3",
    "page": 1,
    "per_page": 20,
    "total": 1483
  }
}

GET /v1/stores/:domain Get store details

Retrieve full details for a single store by its domain.

Path Parameters

Parameter	Type	Description
domain required	string	The store domain (e.g., `pawsome-pets.com`)

Example Response

JSON
{
  "data": {
    "domain": "pawsome-pets.com",
    "name": "Pawsome Pets",
    "description": "Premium pet supplies and accessories",
    "platform": "shopify",
    "language": "en",
    "currency": "USD",
    "biz_model": "dropshipping",
    "monthly_traffic": 45200,
    "product_count": 312,
    "avg_price": 29.95,
    "has_ads": true,
    "status": "active",
    "social": {
      "facebook": "https://facebook.com/pawsomepets",
      "instagram": "https://instagram.com/pawsomepets"
    },
    "created_at": "2024-03-15T00:00:00Z",
    "last_checked": "2025-01-20T12:00:00Z"
  }
}

GET /v1/stores/:domain/products Get store products

List all products from a specific store.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: `1`)
per_page	integer	Results per page, 1–100 (default: `20`)
sort	string	Sort by: `price_asc`, `price_desc`, `newest`, `best_selling`

Example Response

JSON
{
  "data": [
    {
      "id": "prod_8f3k2j",
      "title": "Organic Dog Treats - Chicken",
      "price": 14.99,
      "currency": "USD",
      "image_url": "https://cdn.pawsome-pets.com/treats.jpg",
      "url": "https://pawsome-pets.com/products/organic-dog-treats"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 312 }
}

GET /v1/stores/:domain/traffic Get traffic data

Retrieve estimated traffic data and visitor sources for a store.

Example Response

JSON
{
  "data": {
    "domain": "pawsome-pets.com",
    "monthly_visitors": 45200,
    "trend": "growing",
    "growth_pct": 12.5,
    "sources": {
      "organic": 0.45,
      "paid": 0.25,
      "social": 0.18,
      "direct": 0.08,
      "referral": 0.04
    },
    "top_countries": [
      { "code": "US", "share": 0.62 },
      { "code": "CA", "share": 0.15 },
      { "code": "GB", "share": 0.09 }
    ]
  }
}

GET /v1/stores/:domain/tech Get tech stack

Identify the technologies, apps, and integrations used by a store.

Example Response

JSON
{
  "data": {
    "domain": "pawsome-pets.com",
    "platform": "shopify",
    "theme": "Dawn 12.0",
    "technologies": [
      { "name": "Klaviyo", "category": "email_marketing" },
      { "name": "Loox", "category": "reviews" },
      { "name": "Google Analytics", "category": "analytics" },
      { "name": "Meta Pixel", "category": "advertising" }
    ],
    "payment_processors": ["shopify_payments", "paypal"]
  }
}

GET /v1/stores/:domain/ads Get store ads

Retrieve all tracked advertisements for a specific store.

Example Response

JSON
{
  "data": [
    {
      "id": "ad_9x8k2m",
      "platform": "facebook",
      "type": "image",
      "headline": "Your Dog Deserves the Best",
      "cta": "Shop Now",
      "landing_url": "https://pawsome-pets.com/collections/premium",
      "first_seen": "2025-01-10T00:00:00Z",
      "last_seen": "2025-01-20T00:00:00Z",
      "days_running": 10
    }
  ]
}

GET /v1/stores/compare Compare stores

Compare key metrics side-by-side for 2–10 stores.

Query Parameters

Parameter	Type	Description
domains required	string	Comma-separated list of 2–10 store domains

Example Request

Bash
curl "https://api.usecart.com/v1/stores/compare?domains=pawsome-pets.com,petco.com" \
  -H "Authorization: Bearer cart_sk_..."

Example Response

JSON
{
  "data": [
    {
      "domain": "pawsome-pets.com",
      "monthly_traffic": 45200,
      "product_count": 312,
      "avg_price": 29.95,
      "platform": "shopify"
    },
    {
      "domain": "petco.com",
      "monthly_traffic": 8200000,
      "product_count": 14520,
      "avg_price": 22.50,
      "platform": "custom"
    }
  ]
}

Products #

Search, discover, and track products across the e-commerce ecosystem.

GET /v1/products Search products

Search across millions of products from tracked stores.

Query Parameters

Parameter	Type	Description
keyword	string	Search term to match against product title and description
min_price	number	Minimum price filter
max_price	number	Maximum price filter
currency	string	ISO 4217 currency code (default: `USD`)
sort	string	Sort by: `relevance`, `price_asc`, `price_desc`, `newest`
page	integer	Page number (default: `1`)
per_page	integer	Results per page, 1–100 (default: `20`)

Example Response

JSON
{
  "data": [
    {
      "id": "prod_8f3k2j",
      "title": "Organic Dog Treats - Chicken",
      "price": 14.99,
      "currency": "USD",
      "store_domain": "pawsome-pets.com",
      "image_url": "https://cdn.pawsome-pets.com/treats.jpg",
      "url": "https://pawsome-pets.com/products/organic-dog-treats"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 892 }
}

GET /v1/products/:id Get product

Retrieve full details for a single product.

Path Parameters

Parameter	Type	Description
id required	string	The product ID (e.g., `prod_8f3k2j`)

Example Response

JSON
{
  "data": {
    "id": "prod_8f3k2j",
    "title": "Organic Dog Treats - Chicken",
    "description": "All-natural chicken treats for dogs of all sizes.",
    "price": 14.99,
    "compare_at_price": 19.99,
    "currency": "USD",
    "store_domain": "pawsome-pets.com",
    "images": [
      "https://cdn.pawsome-pets.com/treats-1.jpg",
      "https://cdn.pawsome-pets.com/treats-2.jpg"
    ],
    "variants": [
      { "title": "Small Bag", "price": 14.99 },
      { "title": "Large Bag", "price": 24.99 }
    ],
    "created_at": "2024-06-10T00:00:00Z"
  }
}

Ads #

Track and analyze paid advertising across e-commerce stores.

GET /v1/ads Search ads

Search across tracked advertisements from e-commerce stores.

Query Parameters

Parameter	Type	Description
keyword	string	Search ad headlines and copy
domain	string	Filter ads by store domain

Example Response

JSON
{
  "data": [
    {
      "id": "ad_9x8k2m",
      "store_domain": "pawsome-pets.com",
      "platform": "facebook",
      "type": "video",
      "headline": "Your Dog Deserves the Best",
      "body": "Premium organic treats, delivered to your door.",
      "cta": "Shop Now",
      "days_running": 10,
      "first_seen": "2025-01-10T00:00:00Z"
    }
  ]
}

GET /v1/ads/:id Get ad

Retrieve full details for a single advertisement.

Path Parameters

Parameter	Type	Description
id required	string	The ad ID (e.g., `ad_9x8k2m`)

Example Response

JSON
{
  "data": {
    "id": "ad_9x8k2m",
    "store_domain": "pawsome-pets.com",
    "platform": "facebook",
    "type": "video",
    "headline": "Your Dog Deserves the Best",
    "body": "Premium organic treats, delivered to your door.",
    "cta": "Shop Now",
    "landing_url": "https://pawsome-pets.com/collections/premium",
    "media_url": "https://cdn.usecart.com/ads/ad_9x8k2m.mp4",
    "first_seen": "2025-01-10T00:00:00Z",
    "last_seen": "2025-01-20T00:00:00Z",
    "days_running": 10,
    "is_active": true
  }
}

Suppliers, Niches & More #

Additional endpoints for supplier discovery, niche analysis, and account management.

GET /v1/suppliers Search suppliers

Search for product suppliers and manufacturers.

Query Parameters

Parameter	Type	Description
keyword	string	Search term for supplier name or product category
min_products	integer	Minimum number of products offered
sort	string	Sort by: `relevance`, `products`, `stores`
page	integer	Page number (default: `1`)
per_page	integer	Results per page, 1–100 (default: `20`)

Example Response

JSON
{
  "data": [
    {
      "id": "sup_4f2a1x",
      "name": "PetGoods Direct",
      "product_count": 1240,
      "store_count": 89,
      "avg_price": 8.50,
      "categories": ["pet_supplies", "pet_food"]
    }
  ]
}

GET /v1/niches/:keyword Niche overview

Get a comprehensive overview of a niche including competition, market size, and trends.

Path Parameters

Parameter	Type	Description
keyword required	string	The niche keyword (e.g., `pet-supplies`)

Example Response

JSON
{
  "data": {
    "keyword": "pet supplies",
    "store_count": 3420,
    "avg_monthly_traffic": 28500,
    "avg_product_count": 185,
    "avg_price": 24.99,
    "competition": "high",
    "trend": "growing",
    "top_platforms": [
      { "name": "shopify", "share": 0.68 },
      { "name": "woocommerce", "share": 0.22 }
    ],
    "top_biz_models": [
      { "name": "dropshipping", "share": 0.45 },
      { "name": "private_label", "share": 0.35 }
    ]
  }
}

GET /v1/account Account info

Retrieve your account details, current plan, and usage statistics.

Example Response

JSON
{
  "data": {
    "email": "[email protected]",
    "plan": "pro",
    "requests_today": 42,
    "daily_limit": 10000,
    "key_prefix": "cart_sk_a1b2...",
    "created_at": "2024-11-01T00:00:00Z"
  }
}

Node.js SDK #

The official Node.js SDK provides a typed, ergonomic interface to the Cart API. View on npm

Installation

$ npm install @usecart/sdk

Initialization

TypeScript
import { CartClient } from '@usecart/sdk';

const cart = new CartClient('cart_sk_...');

Resource Namespaces

The SDK organizes methods under resource namespaces that mirror the API structure.

Namespace	Methods
cart.stores	`.search()`, `.get()`, `.products()`, `.traffic()`, `.tech()`, `.ads()`, `.compare()`
cart.products	`.search()`, `.get()`
cart.ads	`.search()`, `.get()`
cart.suppliers	`.search()`
cart.niches	`.get()`

Examples

TypeScript
// Search stores with filters
const stores = await cart.stores.search({
  keyword: 'pet supplies',
  platform: 'shopify',
  min_traffic: 10000,
  sort: 'traffic'
});

// Get store details
const store = await cart.stores.get('pawsome-pets.com');

// Analyze a niche
const niche = await cart.niches.get('pet-supplies');

Error Handling

The SDK throws typed errors that you can catch and handle individually.

TypeScript
import {
  CartApiError,
  CartAuthError,
  CartRateLimitError
} from '@usecart/sdk';

try {
  const store = await cart.stores.get('example.com');
} catch (err) {
  if (err instanceof CartAuthError) {
    // Invalid or missing API key
    console.error('Auth failed:', err.message);
  } else if (err instanceof CartRateLimitError) {
    // Rate limit exceeded - check err.retryAfter
    console.log(`Retry in ${err.retryAfter}s`);
  } else if (err instanceof CartApiError) {
    // General API error
    console.error(err.status, err.code, err.message);
  }
}

Python SDK #

The official Python SDK provides a zero-dependency interface to the Cart API. Python 3.9+. View on PyPI

Installation

$ pip install usecart

Initialization

Python
from usecart import Cart

cart = Cart('cart_sk_...')

Examples

Python
# Search stores with filters
stores = cart.stores.search(
    keyword="pet supplies",
    platform="shopify",
    min_traffic=10000
)

# Get store details
store = cart.stores.get("pawsome-pets.com")

# Analyze a niche
niche = cart.niches.get("pet-supplies")

# Access response data
print(stores.data)    # list of store dicts
print(stores.meta)    # request_id, page, total_results
print(stores.usage)   # requests_today, limit

Error Handling

Python
from usecart import Cart, CartAuthError, CartRateLimitError, CartApiError

try:
    store = cart.stores.get("example.com")
except CartAuthError as e:
    print(f"Auth failed: {e}")
except CartRateLimitError as e:
    print(f"Retry in {e.retry_after}s")
except CartApiError as e:
    print(f"{e.status}: {e.message}")

MCP Server #

The Cart MCP server lets AI assistants like Claude access the Cart API through the Model Context Protocol, a standard for connecting AI models to external tools and data. View on npm

Installation

Add the Cart MCP server to your Claude Desktop configuration file:

JSON — claude_desktop_config.json
{
  "mcpServers": {
    "cart": {
      "command": "npx",
      "args": ["@usecart/mcp-server"],
      "env": {
        "CART_API_KEY": "cart_sk_..."
      }
    }
  }
}

Available Tools

Once connected, the following tools become available to Claude:

Tool	Description
search_stores	Search and filter e-commerce stores
get_store	Get full details for a store by domain
get_store_products	List products from a specific store
get_store_traffic	Get traffic data for a store
get_store_tech	Identify a store's tech stack
get_store_ads	Get ads from a specific store
compare_stores	Compare metrics for multiple stores
search_products	Search across all tracked products
get_product	Get full details for a product
search_ads	Search tracked advertisements
search_suppliers	Search for product suppliers
niche_overview	Get niche analysis and competition data

Skills Pack #

Pre-built Claude Code slash commands for common e-commerce research tasks. Install once and get instant access to Cart data from your terminal. View on GitHub

Installation

Clone the skills into your project's .claude/skills/ directory:

$ git clone https://github.com/usecart/cart-skills .claude/skills/cart

Available Commands

Command	Description
/store-lookup	Get a full profile for any e-commerce store by domain
/niche-research	Analyze a niche market with competition data, top stores, and trending products
/competitor-report	Generate a side-by-side competitor comparison for a set of stores
/find-suppliers	Search for manufacturers and wholesalers by product type and location

CLI #

A command-line interface for quick lookups and scripting. No installation required with npx.

Usage

Shell
# Search stores in a niche
$ npx cart-cli search stores --niche fitness
# Returns top stores matching "fitness" sorted by traffic

# Get a store profile
$ npx cart-cli store allbirds.com
# Returns full store profile with traffic, revenue, tech stack

# Compare stores
$ npx cart-cli compare allbirds.com greats.com

# Search ads
$ npx cart-cli ads --keyword "protein powder" --platform facebook

Set your API key as an environment variable:

Shell
export CART_API_KEY="cart_sk_live_a1b2c3d4e5f6"

Use Cases #

Examples of what developers and AI agents are building with the Cart API.

Competitor Analysis Agent

Build an agent that takes a store URL and automatically generates a competitive landscape report with traffic, pricing, and ad strategy analysis.

TypeScript
import { CartClient } from '@usecart/sdk';

const cart = new CartClient(process.env.CART_API_KEY);

async function analyzeCompetitors(domain: string) {
  // Get the store's profile and top categories
  const store = await cart.stores.get(domain);
  const niche = await cart.niches.get(store.data.top_categories[0]);

  // Pull the top competitors by traffic
  const competitors = niche.data.top_stores
    .filter(s => s.domain !== domain)
    .slice(0, 3);

  // Compare side by side
  const domains = [domain, ...competitors.map(c => c.domain)];
  const comparison = await cart.stores.compare(domains);

  return {
    store: store.data,
    niche_overview: niche.data,
    comparison: comparison.data
  };
}

const report = await analyzeCompetitors('gymshark.com');

Store Monitor

A background service that tracks changes to a list of stores and sends alerts when traffic, pricing, or ad activity shifts significantly.

TypeScript
import { CartClient } from '@usecart/sdk';

const cart = new CartClient(process.env.CART_API_KEY);
const watchlist = ['allbirds.com', 'gymshark.com', 'glossier.com'];

async function checkForChanges(previousData: Record<string, any>) {
  const alerts = [];

  for (const domain of watchlist) {
    const traffic = await cart.stores.traffic(domain);
    const ads = await cart.stores.ads(domain);
    const prev = previousData[domain];
    if (!prev) continue;

    // Alert on traffic drops greater than 15%
    const change = (traffic.data.monthly_visits - prev.traffic) / prev.traffic;
    if (change < -0.15) {
      alerts.push({
        domain,
        type: 'traffic_drop',
        change: `${(change * 100).toFixed(1)}%`
      });
    }

    // Alert on new ad campaigns
    const newAds = ads.data.filter(ad => ad.first_seen > prev.last_check);
    if (newAds.length > 0) {
      alerts.push({
        domain,
        type: 'new_ads',
        count: newAds.length
      });
    }
  }

  return alerts;
}

Errors #

The API uses conventional HTTP status codes and returns structured error responses.

Error Response Format

JSON
{
  "error": {
    "code": "not_found",
    "message": "Store 'nonexistent.com' was not found.",
    "request_id": "req_xyz789"
  }
}

Error Codes

HTTP Status	Code	Description
401	authentication_required	No API key was provided in the request.
403	invalid_api_key	The provided API key is invalid or has been revoked.
429	rate_limit_exceeded	You have exceeded your daily request limit. Check the `Retry-After` header.
404	not_found	The requested resource does not exist.
400	missing_parameter	A required parameter is missing from the request.
400	invalid_parameter	A parameter value is invalid or out of range.
500	internal_error	An unexpected error occurred. Please retry or contact support.