---
version: 1.0.0
name: firestarter-seller
description: |
  Onboard as a seller on the Firestarter commerce network. Use when the user says "list my products", "sell on Firestarter", "connect my store", "onboard my catalog", or wants to make their inventory available to AI agent buyers.
allowed-tools:
  - Bash(curl:*)
  - Bash(npx:*)
metadata:
  author: firestarter
  url: firestarter.network
user-invocable: true
---

# Firestarter Seller Onboarding

Get your products in front of every AI agent on the Firestarter commerce network. One onboarding flow - your catalog becomes discoverable, purchasable, and fulfillable by autonomous buyer agents.

## What you need

1. A Firestarter account (sign up at https://firestarter.network/auth) and an API key (Dashboard > Developer > API Keys, or `POST /v1/keys` once you have a session) - looks like `fs_live_...` / `fs_test_...`. Every call below sends it as `Authorization: Bearer $FIRESTARTER_KEY`.
2. Your store URL or product catalog

**MCP alternative:** if your agent runtime speaks MCP, you can skip the curl calls below entirely - `https://api.firestarter.network/mcp` (download a ready-made bundle at `/mcp/download`) exposes the same actions as typed tools: `firestarter_register_seller`, `firestarter_list`, `firestarter_import`, `firestarter_connect_shopify`, `firestarter_connect_tiktok`, `firestarter_sync_shopify`, and more.

## Step 1: Register as a seller

```bash
curl -X POST https://api.firestarter.network/v1/sellers \
  -H "Authorization: Bearer $FIRESTARTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_name": "YOUR_BUSINESS", "type": "retailer"}'
```

`type` is optional (`retailer` | `wholesaler` | `manufacturer` | `reseller` | `distributor`, defaults to `retailer`). This only creates the seller profile - it does not start Stripe Connect. Do that explicitly in Step 5.

## Step 2: Detect the store platform

Before connecting, identify what platform the store runs on. Check in this order:

### Detection checklist

1. **Check for MCP/OpenAPI** - Fetch `https://STORE_URL/.well-known/mcp.json` and `https://STORE_URL/.well-known/openapi.json`. If either exists, use it directly. No credentials needed.

2. **Check for Shopify** - Fetch `https://STORE_URL/products.json`. If it returns product JSON, this is a Shopify store. Also check page source for `cdn.shopify.com` or `Shopify.theme`.

3. **Check for WooCommerce** - Fetch `https://STORE_URL/wp-json/wc/v3/`. If it returns the WooCommerce REST API root, this is WooCommerce. Also check page source for `woocommerce` or `wp-content/plugins/woocommerce`.

4. **Check for BigCommerce** - Check page source for `bigcommerce.com` in scripts, or `stencil` theme references.

5. **Check for Wix** - Check page source for `wix.com` or `parastorage.com` in script/asset URLs.

6. **Check for TikTok Shop** - Check for `tiktok.com/shop` or `seller.tiktokglobalshop` in URL/source.

7. **Check for Shopee** - Check for `shopee.com` or regional `shopee.` domains.

8. **Check for Lazada** - Check for `lazada.com` or regional `lazada.` domains.

9. **Check for product structured data** - Look for `<script type="application/ld+json">` containing `@type: Product` or `@type: ItemList`. Most e-commerce sites embed this for SEO - this is what the single-product import in Step 3 reads.

10. **Nothing matched** - There is no generic multi-page crawler. Import each product page individually (see "Any product page" below), or enter products manually.

## Step 3: Connect the store

Platform catalogs (Shopify, BigCommerce, TikTok Shop, Shopee, Lazada, Wix, WooCommerce) all go through one endpoint. You need a read-scoped API token from the platform first - there is no token-free tier for this call.

```bash
curl -X POST https://api.firestarter.network/v1/connections \
  -H "Authorization: Bearer $FIRESTARTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "shopify", "shop_domain": "yourstore.myshopify.com", "access_token": "shpat_xxxxx"}'
```

`platform` must be one of: `shopify`, `bigcommerce`, `tiktok_shop`, `shopee`, `lazada`, `wix`, `woocommerce`. This starts a background catalog sync immediately; listings appear shortly after. To re-sync later: `POST /v1/connections/:id/sync`. To disconnect (and delist everything it synced): `DELETE /v1/connections/:id`.

How to get `access_token` per platform:

- **Shopify:** "Go to your Shopify admin > Settings > Apps and sales channels > Develop apps > Create an app > Configure Admin API scopes (enable read_products, read_inventory) > Install app > Copy the Admin API access token."
- **WooCommerce:** "Go to your WordPress admin > WooCommerce > Settings > Advanced > REST API > click 'Add Key'. Set permissions to 'Read', click 'Generate API key'. Copy the Consumer Key and Consumer Secret" (send as `access_token`, with `shop_domain` as the store URL - pack both into `access_token` as `key:secret` if a single token field is limiting, or contact support for a two-field flow).
- **BigCommerce:** "Go to your BigCommerce admin > Settings > API > API Accounts > Create API Account. Give it read-only access to Products and Orders. Copy the Access Token" (use the store hash as `shop_domain`).
- **Wix:** "Go to your Wix dashboard > Developer Tools > API Keys > Generate API Key with 'Wix Stores - Read Products' permission."
- **TikTok Shop:** "Go to TikTok Shop Seller Center > Settings > API Management. Copy the access token" (`platform: "tiktok_shop"`).
- **Shopee:** "Go to Shopee Open Platform > My Apps. Generate an access token" (`platform: "shopee"`).
- **Lazada:** "Go to Lazada Open Platform > App Console. Generate an access token" (`platform: "lazada"`).

Squarespace is not yet supported by this endpoint.

### Any product page (single-item import)

For one product at a time - your own store, or any page with the right markup - paste the URL:

```bash
curl -X POST https://api.firestarter.network/v1/listings/import \
  -H "Authorization: Bearer $FIRESTARTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_url": "https://example.com/products/widget-a"}'
```

Extraction tries, in order: JSON-LD product markup, OpenGraph tags, then an AI reader over the page text. Lands as a `draft` for review - it never publishes directly. This is a single fetch of a URL you explicitly submit; there is no crawling and no bulk mode here.

Some platforms (Amazon, Walmart, eBay, Etsy, Facebook Marketplace, OfferUp, Mercari) block server-side fetches. For those, skip `source_url` and paste the listing text instead:

```bash
curl -X POST https://api.firestarter.network/v1/listings/import \
  -H "Authorization: Bearer $FIRESTARTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"raw_text": "Widget A - $29.99 - durable widget for...", "photo_urls": ["https://..."]}'
```

### Manual entry

If none of the above work, products can be added one at a time:

```bash
curl -X POST https://api.firestarter.network/v1/listings \
  -H "Authorization: Bearer $FIRESTARTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name": "Product Name", "base_price": 29.99, "description": "...", "category": "Office Supplies"}'
```

### Many products at once

If you have more than one product ready (e.g. parsed from the seller's own CSV or site), submit up to 100 in one call:

```bash
curl -X POST https://api.firestarter.network/v1/listings/bulk \
  -H "Authorization: Bearer $FIRESTARTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"products": [{"product_name": "Widget A", "base_price": 29.99}, {"product_name": "Widget B", "base_price": 15.00}]}'
```

One bad item never blocks the rest — the response lists `created` and `failed` separately, each with the reason for any failure. For more than 100 products, call this endpoint again with the next batch.

## Step 4: Product qualification

After upload, each product is scored for discoverability:

| Check | What it verifies |
|-------|-----------------|
| Has title | Product has a non-empty title |
| Has price | Price is greater than $0 |
| Has image | At least one product image URL |
| Has description | Non-empty description (50+ chars preferred) |
| Valid category | Recognized product category |

Products that pass all checks are marked **active** and immediately discoverable AND buyable by agents. Products missing requirements are saved as a **draft** - the create/import response lists exactly what's blocking activation.

A payout method is **not** required to sell: earnings from sales are held safely in escrow until one is connected (Step 5). Selling pauses automatically once held earnings reach $1,000, the oldest hold turns 30 days old, or US INFORM Act thresholds are hit - connecting any payout method resumes it immediately.

## Step 5: Set up payments

To receive your earnings (and any held escrow), connect Stripe:

```bash
curl -X POST https://api.firestarter.network/v1/sellers/stripe-connect \
  -H "Authorization: Bearer $FIRESTARTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "MY"}'
```

`country` is ISO-3166-1 alpha-2 and must be the country your business banks in - **pass your real country, never a placeholder**. Stripe locks it when the account is created and it can never be changed afterwards, so a wrong value can only be undone by discarding the account and starting over.

Eligibility is decided by Stripe, not by Firestarter: there is no country allowlist. A country Stripe cannot open a payouts account in returns `422 COUNTRY_NOT_ELIGIBLE` naming that country, so pass the real one and let Stripe answer rather than guessing whether it qualifies. Sellers outside the platform's own country receive a transfers-only account under Stripe's `recipient` service agreement, which is the correct shape for receiving payouts.

This returns an `onboarding_url` - open it to complete Stripe Connect Express onboarding. Once connected, payouts happen automatically when orders are delivered.

## Step 6: Monitor sales

Check orders:
```bash
curl https://api.firestarter.network/v1/sellers/orders \
  -H "Authorization: Bearer $FIRESTARTER_KEY"
```

Confirm an order:
```bash
curl -X PUT https://api.firestarter.network/v1/sellers/orders/ORDER_ID/confirm \
  -H "Authorization: Bearer $FIRESTARTER_KEY"
```

Ship an order:
```bash
curl -X POST https://api.firestarter.network/v1/sellers/orders/ORDER_ID/ship \
  -H "Authorization: Bearer $FIRESTARTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"carrier": "USPS", "tracking_number": "9400111899223..."}'
```

`carrier` is required unless the number's format identifies it (UPS `1Z…`, USPS IMpb/S10 — those are inferred); an ambiguous number without a carrier returns `400 CARRIER_REQUIRED`. An optional `tracking_url` must be on the carrier's own domain (ups.com, usps.com, fedex.com, dhl.com); for another courier, an https link that contains the tracking number is accepted.

View analytics:
```bash
curl https://api.firestarter.network/v1/sellers/analytics \
  -H "Authorization: Bearer $FIRESTARTER_KEY"
```

## Seller API reference

| Endpoint | Method | Description |
|----------|--------|-------------|
| /v1/sellers | POST | Register as a seller |
| /v1/sellers | GET | Get seller profile |
| /v1/sellers | PATCH | Update seller profile |
| /v1/connections | POST | Connect a platform catalog (Shopify, BigCommerce, TikTok Shop, Shopee, Lazada, Wix, WooCommerce) |
| /v1/connections | GET | List connected platforms |
| /v1/connections/:id/sync | POST | Trigger a manual re-sync |
| /v1/connections/:id | DELETE | Disconnect a platform (delists its synced products) |
| /v1/listings | POST | Add a product manually |
| /v1/listings/bulk | POST | Add up to 100 products in one call |
| /v1/listings/import | POST | Import one product from a URL or pasted text |
| /v1/listings | GET | List your products |
| /v1/listings/:id | PATCH | Update a listing (title, price, inventory, status, detail fields) |
| /v1/listings/:id | DELETE | Delete a listing (soft delete) |
| /v1/sellers/orders | GET | List your orders |
| /v1/sellers/orders/:id/confirm | PUT | Confirm a pending order |
| /v1/sellers/orders/:id/ship | POST | Mark order shipped with tracking |
| /v1/sellers/analytics | GET | View seller analytics |
| /v1/sellers/vouchers | GET | List vouchers with status and what each has cost you |
| /v1/sellers/vouchers | POST | Create a voucher (percent / fixed amount / free shipping) |
| /v1/sellers/vouchers/:id | PATCH | Pause, resume, extend, or adjust limits |
| /v1/sellers/vouchers/:id | DELETE | Delete a voucher that has never been redeemed |
| /v1/sellers/disputes | GET | List disputes on your sales |
| /v1/sellers/disputes/:id | GET | Read one dispute's full thread — the buyer's claim and every message. Read this before resolving |
| /v1/sellers/disputes/:id/messages | POST | Reply to the buyer: `message` and/or `attachment_urls`. No money moves |
| /v1/sellers/disputes/:id/attachments | POST | Upload evidence — `image_url` (a hosted photo URL) or `image_base64`. Returns the URL to pass in `attachment_urls` |
| /v1/sellers/disputes/:id/resolve | PUT | Resolve: `voluntary_refund`, `propose_split`, or `contest`. Moves money |
| /v1/sellers/stripe-connect | POST | Set up Stripe payouts |

## Listing status

Each listing has a status:
- **draft** - saved but not live (the state a new import, or a create that failed a qualification check, lands in)
- **active** - live and discoverable by buyer agents
- **paused** - hidden by the seller
- **out_of_stock** - auto-set when inventory hits 0; comes back automatically once inventory is set positive again
- **delisted** - permanently removed (via DELETE)

To change status, `PATCH /v1/listings/:id` with `{"status": "active"}` (to relist) or `{"status": "paused"}` (to hide) or `{"status": "out_of_stock"}`. Activating a draft additionally requires a positive `base_price` and at least one image - the response lists exactly what's missing if either is absent.

## Platform fees

Firestarter takes a 5% + 50¢ commission on completed sales only. The seller is paid the remainder via Stripe Connect - the lowest take rate in agent commerce.

## Links

- Seller Dashboard: https://firestarter.network/seller
- Buyer Docs: https://firestarter.network/SKILL.md
- API Docs: https://firestarter.network/docs
- Support: https://firestarter.network/dashboard (tab: Settings)