# Cart

> E-commerce intelligence API for AI agents and developers.

Cart provides e-commerce data (stores, products, ads, traffic, and sales) through a REST API, TypeScript SDK, MCP server, and Claude Code skills. 100K+ stores monitored, 1M+ products tracked. Indie-built since 2019.

## Docs

- [API Documentation](https://docs.usecart.com): Full endpoint reference, authentication, and usage guides
- [GitHub](https://github.com/FlatNineOrg): Open-source SDK, MCP server, and skills

## API

Base URL: `https://api.usecart.com/v1`

Authentication: Bearer token in the `Authorization` header. API keys use the format `cart_sk_` followed by 48 hex characters. Get your key from the [Developer Portal](https://usecart.com/developers).

All endpoints are GET requests. Responses return JSON with `data`, `meta` (pagination), and `usage` (request counts) fields.

### Stores

- `GET /v1/stores` - Search stores. Params: `keyword`, `platform`, `language`, `currency`, `biz_model`, `has_ads`, `status`, `min_traffic`, `sort`, `page`, `per_page`
- `GET /v1/stores/:domain` - Get full store profile by domain (e.g., `allbirds.com`)
- `GET /v1/stores/:domain/products` - Get a store's products
- `GET /v1/stores/:domain/traffic` - Get a store's traffic data
- `GET /v1/stores/:domain/tech` - Get a store's tech stack (apps, plugins, technologies)
- `GET /v1/stores/:domain/ads` - Get a store's ad creatives
- `GET /v1/stores/compare?domains=a.com,b.com` - Compare multiple stores side by side

### Products

- `GET /v1/products` - Search products. Params: `keyword`, `min_price`, `max_price`, `currency`, `sort`, `page`, `per_page`
- `GET /v1/products/:id` - Get product detail by ID

### Ads

- `GET /v1/ads` - Search ads. Params: `keyword`, `domain`, `page`, `per_page`
- `GET /v1/ads/:id` - Get ad detail by ID

### Suppliers

- `GET /v1/suppliers` - Search suppliers. Params: `keyword`, `page`, `per_page`
- `GET /v1/suppliers/:id` - Get supplier detail by ID

### Niches

- `GET /v1/niches/:keyword` - Market overview for a niche (top stores, product stats, trending products)

### Trending

- `GET /v1/trending` - Global trending products and stores. Params: `timeframe` (day/week/month), `limit`

### Account

- `GET /v1/account` - Get API key info and usage stats

### Rate Limits

Rate limits are per API key, reset daily at midnight UTC.

| Plan | Requests/Day | Price |
|------|-------------|-------|
| Free | 100 | $0/month |
| Pro | 10,000 | $49/month |
| Business | 100,000 | $199/month |
| Enterprise | 1,000,000 | Custom |

Rate limit headers included in every response:
- `X-RateLimit-Limit` - Daily request limit
- `X-RateLimit-Remaining` - Requests remaining today
- `X-RateLimit-Reset` - Unix timestamp when limit resets
- `Retry-After` - Seconds to wait (only on 429 responses)

### Error Codes

- `401 Unauthorized` - Missing or invalid API key
- `404 Not Found` - Endpoint or resource not found
- `429 Too Many Requests` - Daily rate limit exceeded
- `400 Bad Request` - Missing required parameters

### Response Format

Success:
```json
{
  "data": [...],
  "meta": {
    "request_id": "req_...",
    "timestamp": 1234567890,
    "page": 1,
    "per_page": 20,
    "total_pages": 5,
    "total_results": 100
  },
  "usage": {
    "requests_today": 45,
    "limit": 10000
  }
}
```

Error:
```json
{
  "error": {
    "code": "error_code",
    "message": "Human readable message",
    "request_id": "req_..."
  }
}
```

## TypeScript SDK

Install: `npm install @usecart/sdk`

The SDK (`@usecart/sdk`) is a zero-dependency TypeScript client with dual ESM and CJS support.

```typescript
import { CartClient } from '@usecart/sdk';

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

// Search stores
const stores = await cart.stores.search({ keyword: 'pet supplies' });

// Get store profile
const store = await cart.stores.get('allbirds.com');

// Get store products
const products = await cart.stores.products('allbirds.com');

// Search products
const results = await cart.products.search({ keyword: 'leggings' });

// Search ads
const ads = await cart.ads.search({ keyword: 'skincare' });
```

GitHub: [FlatNineOrg/cart-sdk](https://github.com/FlatNineOrg/cart-sdk)

## MCP Server

Install: `npx @usecart/mcp-server`

The MCP server (`@usecart/mcp-server`) connects Cart to Claude Desktop, Cursor, and any MCP-compatible client. It exposes Cart API endpoints as tools that AI agents can call directly.

Configuration for Claude Desktop (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "cart": {
      "command": "npx",
      "args": ["@usecart/mcp-server"],
      "env": {
        "CART_API_KEY": "cart_sk_..."
      }
    }
  }
}
```

GitHub: [FlatNineOrg/cart-mcp](https://github.com/FlatNineOrg/cart-mcp)

## Claude Code Skills

Install: `npm install -g @usecart/skills`

9 pre-built e-commerce research skills for Claude Code:

- `/store-research [domain]` - Full store analysis
- `/product-research [keyword]` - Product market research
- `/ad-research [keyword]` - Ad creative analysis
- `/niche-research [keyword]` - Niche market overview
- `/competitor-analysis [domain]` - Competitor deep dive
- `/tech-stack [domain]` - Technology analysis
- `/traffic-analysis [domain]` - Traffic breakdown
- `/supplier-research [keyword]` - Supplier discovery
- `/trending` - Trending products and stores

GitHub: [FlatNineOrg/ecommerce-skills](https://github.com/FlatNineOrg/ecommerce-skills)

## Free Tools

6 free Shopify analysis tools, no API key required:

- [Store Analyzer](https://usecart.com/tools/store-analyzer): Get a full report card for any Shopify store including traffic, products, tech stack, and company info
- [Theme Detector](https://usecart.com/tools/theme-detector): Find out which Shopify theme any store is using and how many stores use the same theme
- [Tech Stack Checker](https://usecart.com/tools/tech-checker): Discover the full list of apps, plugins, and technologies any Shopify store uses
- [Revenue Estimator](https://usecart.com/tools/revenue-estimator): Estimate monthly revenue for any Shopify store based on traffic and order data
- [Ad Spy](https://usecart.com/tools/ad-spy): Preview ad creatives from any Shopify store, including Facebook and Instagram ads
- [Niche Finder](https://usecart.com/tools/niche-finder): Discover profitable Shopify niches with store counts, top stores, and average traffic

## Data Coverage

Cart tracks e-commerce data across five categories:

- **Stores**: 100,000+ e-commerce brands. Company info, contact details, social links, founding date, business model, platform, and status. Primarily Shopify stores.
- **Products**: 1,000,000+ products. Title, description, pricing, variants, images, vendor, and sales velocity. Updated daily.
- **Ads**: Facebook and Instagram ad creatives. Ad copy, images/video, landing pages, and activity dates.
- **Traffic**: Monthly traffic estimates, traffic sources, geographic breakdown, and historical trends.
- **Sales**: Revenue estimates, order volume, average order value, and growth trends.

## Pricing

- [Pricing page](https://usecart.com/pricing)
- [Sign up free](https://usecart.com/register?free)

| Plan | Price | Requests/Day | Support |
|------|-------|-------------|---------|
| Free | $0/month | 100 | Community |
| Pro | $49/month | 10,000 | Email |
| Business | $199/month | 100,000 | Priority |
| Enterprise | Custom | 1,000,000 | Dedicated |

All plans include access to stores, products, and ads data, plus SDK and MCP server access.

## About

Cart is an indie-built e-commerce intelligence platform, created by one person in Italy since 2019. It started as a Shopify store discovery tool and evolved into an API-first platform for AI agents and developers.

- Website: [usecart.com](https://usecart.com)
- Support: [support@usecart.com](mailto:support@usecart.com)
- GitHub: [github.com/FlatNineOrg](https://github.com/FlatNineOrg)
- Docs: [docs.usecart.com](https://docs.usecart.com)