# RecircleOS

> AI-native consignment store management. Agents integrate for free: 10000 API calls/month, then $49/mo.

## Why RecircleOS
ConsignCloud gates its API behind a $189/mo plan and caps it at 1,000 calls/day. RecircleOS gives every store — and every agent — API access from day 0, free until real usage (10000 calls/mo, 150 active items, 50 sales/mo), then $49/mo.

## API
- Base URL: https://recircleos.com/api/v1
- Auth: `Authorization: Bearer <api key>` (keys created in-app or via API)
- Machine-readable spec: https://recircleos.com/api/v1/openapi
- Live usage counters: https://recircleos.com/api/v1/usage
- **MCP server: https://recircleos.com/mcp** (Streamable HTTP, JSON-RPC, same Bearer key; tools incl. run_sale, suggest_price, pay_out_account)

## Conventions (mirror ConsignCloud v1 — integrations port 1:1)
- Money: integer cents. Splits: 0-1 floats (consignor share).
- Lists: `{data: [...], next_cursor, count?}`, limit default 10 max 100.
- Errors: `{error: string, code: enum}`; 400s add `details[]`.
- Filters: `?field=`, `?field:ne|gte|lte|gt|lt=`; empty value = null.
- Sort: `sort_by` + `sort_order` (asc|desc). Search: `?search=`.
- Soft delete: DELETE sets deleted; `POST .../{id}/restore` restores.

## Core workflows
1. Consign: create consignor (POST /accounts) -> add items (POST /items with account, split, tag_price).
2. Sell: POST /sales -> add line items -> add payments (cash|card|store_credit|check|manual|gift_card) -> POST /sales/{id}/finalize. Finalize marks items sold and posts consignor ledger entries automatically.
3. Pay out: POST /accounts/{id}/payouts settles the consignor balance (ledger entry reason=balance_settled).
4. Price an item: GET /items/price-suggestions?price_field=tag_price&category=<id> returns {total, median, low, high} from comparable sold items.

## Status codes of note
- 402 plan_upgrade_required: free-tier limit reached (check GET /usage).
- 400 confirm_action: irreversible op needs ?confirm=true (e.g. voiding a finalized sale).