TrovetteStart free trial
Developers

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

  1. 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.
  2. Copy the key (it starts with tvk_). It is shown once; Trovette stores only a fingerprint.
  3. 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

EndpointMCP toolWhat it does
GET /api/v1/shopget_shopShop name, currency, time zone and item counts.
GET /api/v1/consignorslist_consignorsList consignors (newest first) with current balance in cents. Search by name, email, phone or account number.
GET /api/v1/consignors/:idget_consignorOne consignor: contact details, notes, balance and available-to-pay balance (cents), recurring fees.
GET /api/v1/consignors/balancesconsignor_balancesBalance and available balance (cents) for every consignor with a non-zero balance. Negative = owes the shop.
GET /api/v1/itemslist_itemsSearch items by title/SKU/barcode with optional status, consignor and category filters. Prices in cents.
GET /api/v1/items/:idget_itemOne item by id.
GET /api/v1/saleslist_salesSales with their lines in a date range (shop time zone, inclusive). Defaults to the last 30 days.
GET /api/v1/payoutslist_payoutsConsignor payouts (newest first), optionally for one consignor. Read-only: the API can't make payouts.
GET /api/v1/reports/consignors-who-oweconsignors_who_oweConsignors with a negative balance (they owe the shop), with amounts, monthly fees and last activity.
GET /api/v1/reports/sales-summarysales_summaryTotals for a date range: gross, discounts, refunds, revenue, consignor portions, profit, tax (cents), vs. the previous period.
GET /api/v1/reports/inventory-summaryinventory_summaryItem counts by status, on-hand value, and per-category sell-through for a date range.

Write endpoints (read + write keys)

EndpointMCP toolWhat it does
POST /api/v1/itemscreate_itemAdd 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/:idupdate_itemChange 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/consignorscreate_consignorAdd a consignor. Optional split = consignor's percentage (else the shop default).
PATCH /api/v1/consignors/:idupdate_consignorChange 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-receivedrecord_payment_receivedRecord 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/notesadd_noteAppend a dated note to a consignor's notes.
POST /api/v1/consignors/:id/notice-draftsdraft_noticeFill 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.
API & AI agents · Trovette