Connect an AI Agent

Give a personal AI agent (Claude, ChatGPT, a script, a dashboard) a view of your shop: reports, work orders, customers, inventory and the morning digest — without letting it change anything.

1. Create a read-only key

In BigShop go to Admin → API Keys → Create API Key and leave Access on Read-only. The key is shown once; store it like a password.

A read-only key can call GET endpoints only. Any POST, PUT, PATCH or DELETE is refused with 403 before it reaches BigShop.
It cannot read credentials, secrets or sharing links (integration tokens, clock-in PINs, API key or webhook secrets, customer share links) or any endpoint that sends or syncs something when called. Employee pay and commission endpoints (staff list, payroll, commission and per-technician labor-cost reports) are hidden too, unless you tick Also allow employee pay and commission reports when you create the key (API: "includePayData": true).
Keys created through the API default to full access for backwards compatibility. Send "accessLevel": "read_only" to POST /v1/api-keys to create a read-only key.

A full-access key acts as a shop administrator. Only use one for an integration that must create or change records, such as the dealer-invoice receiving flow.

2. Point the agent at BigShop

Claude Desktop, Cursor, Windsurf: use the BigShop MCP server — it exposes search, report and digest tools. Setup is in mcp-server/README.md.
Any other agent or framework: load the OpenAPI spec or llms.txt and call the REST API directly.

curl "https://api.bigshopai.com/v1/report-aggregates/sales-summary?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..." \
  -H "X-Agent-Name: my-shop-agent"

3. Read reports and digests

The Reports & Digests reference lists every report endpoint, its parameters and response shape. For a daily briefing:

In BigShop, turn on Settings → AI Daily Digest (admin).
Subscribe a webhook to digest.ready (POST /v1/webhooks needs a full-access key; read-only keys cannot create it).
When it fires, call GET /v1/digests/{businessDate} (add ?period=weekly for the weekly one).

A digest holds a snapshot of computed numbers and a narrative written from them. Quote figures from the snapshot; never recompute them from the narrative text.

Conventions an agent must know

Money is integer cents (totalCents: 125050 is $1,250.50). A few legacy report fields are dollars; the reference marks which.
Dates are shop-local YYYY-MM-DD in the shop’s timezone, not UTC.
Paging: pass limit; if the response has lastEvaluatedKey, send it back as a query parameter for the next page. If it has truncated: true, the result was capped — narrow the date range and say so rather than treating it as complete.
Rate: the fair-use limit is 3,000 requests per 5 minutes per key (about 10 per second). Enforcement is being switched on: over-limit calls will get 429 with Retry-After: 60. Back off on 429 and prefer webhooks to polling.
Missing is 404: a record that does not exist and one that belongs to another shop look the same.
Identify your agent: send X-Agent-Name and X-Agent-Run-Id. They are recorded in the audit trail for purchase-order and receiving changes.
Retries on creates: send an Idempotency-Key header (any unique string, kept 24 hours) so a retry returns the first response instead of creating a duplicate.

Work Order Lifecycle

Understanding how work orders move through the system is key to building effective integrations.

Status Flow

estimate

→

approved

→

in_progress

→

quality_check

→

ready_for_pickup

→

invoiced

→

paid

→

completed

Tenants can also configure custom workflow statuses; pass any string to status and the API stores it as-is. The list above is the default set.

1. Creation

Work orders start with a customer and vehicle link. Use POST /v1/work-orders to initialize a ticket.

2. Adding Services & Line Items

Edit the services[] array via PATCH /v1/work-orders/{id}/services/{svcId} to add labor / parts / tires / materials. Each service block carries its own version — PATCH must echo the version it read; the server returns 409 on stale writes. Totals on the work order are recomputed server-side.

3. Updating Status

Use PATCH /v1/work-orders/{id} with a status body field. Status changes trigger webhook events (work_order.updated).

Inventory Management

Keep your stock levels accurate by syncing your inventory system with BigShop.

Real-time Updates

When parts are added to a work order, stock is reserved. When the work order is completed, stock is deducted.

Low Stock Alerts

Set reorder points for items. The API returns low_stock flags you can filter by.

Dealer Invoice Receiving API

If you parse dealer invoices externally (e.g., via an AI agent or OCR pipeline), you can push the structured line items directly into BigShop using POST /v1/inventory/receiving.

Draft Mode: Creates a draft purchase order for shop staff to review before stocking.
Receive Mode: Immediately increments on-hand quantities, logs FIFO costing layers, and registers new parts.
Vendor Matching & Idempotency: Matches existing vendors automatically, creates missing ones, and prevents duplicate invoice processing.

View the full endpoint documentation & example payloads →

Webhook Integration

Webhooks allow your system to react immediately to changes in BigShop.

Example Payload: digest.ready

{
  "id": "evt_3f9c2a71d0b84e5f9a1c6d2e8b407a15",
  "event": "digest.ready",
  "createdAt": "2026-10-10T11:06:12.481Z",
  "tenantId": "your-shop-id",
  "data": {
    "businessDate": "2026-10-09",
    "period": "daily",
    "headline": "Revenue up 12% on yesterday; 3 estimates waiting on approval",
    "renderMode": "llm",
    "anomalyCount": 1,
    "overwritten": false
  }
}

Best Practices

Verify the X-BigShop-Signature-256 header (format t=<unix>,v1=<hex>; the hex is HMAC-SHA256 of <t>.<raw body> with your webhook secret; reject timestamps more than 5 minutes old). The event name is also sent in X-BigShop-Event and a per-attempt id in X-BigShop-Delivery.
Respond with a 200 OK immediately to prevent retries.
Process heavy logic asynchronously after receiving the event.