API & AI agents
Let Claude, ChatGPT, Cursor or your own scripts look up consignors, add items and draft notices in your Trovette shop. Available on the Pro plan.
Quick start
- In Trovette, go to Settings › Apps › AI agents & API (Owners only) and create a key. Choose Read-only unless the agent needs to make changes.
- Copy the key (it starts with
tvk_). It is shown once; Trovette stores only a fingerprint. - Call the API with the key as a Bearer token:
curl https://trovette.com/api/v1/shop \ -H "Authorization: Bearer tvk_your_key_here"
Authentication
Every request needs Authorization: Bearer <key>. Each key belongs to one shop and only sees that shop's data. Keys are read-only (default) or read + write; a read-only key gets 403 insufficient_scope on any change. Revoke a key any time from the same settings page; it stops working immediately.
Responses are JSON. Success: {"data": …}. Errors always look like:
{"error": {"code": "invalid_input", "message": "Check the input", "details": {...}}}Codes: unauthorized (401), plan_required / insufficient_scope (403), not_found (404), method_not_allowed (405), item_limit_reached (409), invalid_input / invalid_json (400), rate_limited (429). Money is always integer cents; ids are UUIDs.
Read endpoints
| Endpoint | MCP tool | What it does |
|---|---|---|
GET /api/v1/shop | get_shop | Shop name, currency, time zone and item counts. |
GET /api/v1/consignors | list_consignors | List consignors (newest first) with current balance in cents. Search by name, email, phone or account number. |
GET /api/v1/consignors/:id | get_consignor | One consignor: contact details, notes, balance and available-to-pay balance (cents), recurring fees. |
GET /api/v1/consignors/balances | consignor_balances | Balance and available balance (cents) for every consignor with a non-zero balance. Negative = owes the shop. |
GET /api/v1/items | list_items | Search items by title/SKU/barcode with optional status, consignor and category filters. Prices in cents. |
GET /api/v1/items/:id | get_item | One item by id. |
GET /api/v1/sales | list_sales | Sales with their lines in a date range (shop time zone, inclusive). Defaults to the last 30 days. |
GET /api/v1/payouts | list_payouts | Consignor payouts (newest first), optionally for one consignor. Read-only: the API can't make payouts. |
GET /api/v1/reports/consignors-who-owe | consignors_who_owe | Consignors with a negative balance (they owe the shop), with amounts, monthly fees and last activity. |
GET /api/v1/reports/sales-summary | sales_summary | Totals for a date range: gross, discounts, refunds, revenue, consignor portions, profit, tax (cents), vs. the previous period. |
GET /api/v1/reports/inventory-summary | inventory_summary | Item counts by status, on-hand value, and per-category sell-through for a date range. |
Write endpoints (read + write keys)
| Endpoint | MCP tool | What it does |
|---|---|---|
POST /api/v1/items | create_item | Add an item (price in cents). A consignor account is required, unless collectionId is a bought-outright collection: those items are shop-owned and need no account. A consigned collection still needs an account. Not listed on Shopify automatically. Category, condition and collectible details (card, comic, figure, slab) are optional. For a CD, DVD, Blu-ray, VHS or cassette, a blank condition is saved as Used. Sealed and New (open-box) are the other choices. |
PATCH /api/v1/items/:id | update_item | Change an item's title, price (cents), quantity, status (draft, active, inactive, returned, donated, expired, lost), category, condition or collectible details. Only the fields you send change. When the shop turns on “remove from Shopify when gone”, setting a linked item to returned, donated, lost, or expired also takes it off Shopify (archived if it's the last unit, otherwise the quantity is lowered). Putting one of those items back to active needs a store Owner in Trovette and a written reason; the API can't do that. |
POST /api/v1/consignors | create_consignor | Add a consignor. Optional split = consignor's percentage (else the shop default). |
PATCH /api/v1/consignors/:id | update_consignor | Change a consignor's name, email, phone or notes. Only the fields you send change. (The email is also their portal sign-in.) |
POST /api/v1/consignors/:id/payments-received | record_payment_received | Record money a consignor paid the shop (e.g. rent paid in cash). Raises their balance. Does not charge any card. |
POST /api/v1/consignors/:id/notes | add_note | Append a dated note to a consignor's notes. |
POST /api/v1/consignors/:id/notice-drafts | draft_notice | Fill in a past-due notice template (d1–d6) for a consignor and save it as a DRAFT (returned here and kept in the activity log) for staff to review and send. Never sends email. |
Examples
# Consignors who owe the shop
curl https://trovette.com/api/v1/reports/consignors-who-owe -H "Authorization: Bearer $KEY"
# Search active items
curl "https://trovette.com/api/v1/items?q=denim&status=active&limit=20" -H "Authorization: Bearer $KEY"
# Sales for September
curl "https://trovette.com/api/v1/sales?from=2026-09-01&to=2026-09-30" -H "Authorization: Bearer $KEY"
# Add an item ($45.00, quantity 1)
curl -X POST https://trovette.com/api/v1/items -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"consignorId":"<uuid>","title":"Levi 501 jeans","priceCents":4500}'
# Record $20 cash rent received
curl -X POST https://trovette.com/api/v1/consignors/<uuid>/payments-received -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" -d '{"amountCents":2000,"method":"cash"}'MCP server
Trovette runs a remote MCP server (Streamable HTTP) at https://trovette.com/api/mcp. It uses the same key; a read-only key only lists the read tools. Tools: get_shop, list_consignors, get_consignor, consignor_balances, list_items, get_item, list_sales, list_payouts, consignors_who_owe, sales_summary, inventory_summary, create_item, update_item, create_consignor, update_consignor, record_payment_received, add_note, draft_notice.
Cursor (~/.cursor/mcp.json) and other clients that accept a URL with headers:
{
"mcpServers": {
"trovette": {
"url": "https://trovette.com/api/mcp",
"headers": { "Authorization": "Bearer tvk_your_key_here" }
}
}
}Claude Desktop (claude_desktop_config.json), through the mcp-remote bridge:
{
"mcpServers": {
"trovette": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://trovette.com/api/mcp",
"--header", "Authorization:${TROVETTE_AUTH}"],
"env": { "TROVETTE_AUTH": "Bearer tvk_your_key_here" }
}
}
}Safety limits
- Agents can never charge cards, send payouts, delete anything, read tax IDs or W-9s, or change settings, billing or connected apps. Those actions don't exist in the API.
- Notices are only saved as drafts; the API never emails anyone.
- Items aren't pushed to Shopify automatically.
- 120 requests per minute per key.
- Every call is recorded in your shop's activity log with the key's name.
- The API and MCP server are not available for the public demo shop.