BigShop API

Build powerful integrations with the BigShop Truck Repair Management Platform.

Base URL: https://api.bigshopai.com/v1
Format: JSON
Auth: API Key or JWT

Conventions

Money: cents is canonical

All monetary fields are returned in both dollars and cents (e.g. totalAmount in dollars, totalAmountCents in integer cents). Cents is the source of truth — the dollar form exists for backward compatibility and is derived. When sending money in a request body, prefer the *Cents field; it sidesteps floating-point rounding bugs.

Pagination: cursor, not offset

List endpoints return up to limit items plus a lastEvaluatedKey cursor when more pages exist. Pass that cursor back as the lastEvaluatedKey query param to fetch the next page. Some queries are capped server-side; in that case the response carries truncated: true and the UI displays a banner.

Tenant isolation

API keys are scoped to a single tenant; tenant is resolved server-side from the key. You cannot read or write across tenants. Requests for resources owned by a different tenant return 404 Not Found (not 403) so the API does not leak whether a given ID exists.

PUT vs PATCH

Update endpoints accept both PUT and PATCH — the server treats them identically (partial update; only fields you include are changed). The docs use PATCH consistently because that matches the semantics; PUT works as an alias if your HTTP client doesn't support PATCH well.

Errors

Error responses are JSON: { "error": "<short, user-safe message>", "requestId": "<id>" }. Internal exception messages are never leaked — include the requestId when reporting issues.

Authentication

Include your API key in the Authorization header with the ApiKey prefix:

curl -X GET "https://api.bigshopai.com/v1/customers" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Error Codes

Code Description
200 Success
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found — resource does not exist or belongs to a different tenant. The API returns 404 (not 403) for cross-tenant access to avoid leaking whether the ID exists.
409 Conflict — optimistic-concurrency clash on a versioned resource (e.g. service-block PATCH with a stale version). Re-fetch and retry.
429 Rate Limited
500 Server Error

❤️ Health Check

Check the API status and availability.

GET /v1/health

Returns the current health status of the API.

🏢 Customers

Manage customer records for your repair shop.

GET /v1/customers

List all customers with optional filtering and pagination.

Query Parameters

Param Type Description Value
limit integer Max results (default: 50)
lastEvaluatedKey string Cursor from a prior response's lastEvaluatedKey field. Pass it back to fetch the next page (cursor-based pagination — not offset).
search string Search by name or email
POST /v1/customers

Create a new customer record.

Request Body

Field Type Description Value
name string Customer name
type string company | individual
email string Contact email
phone string Phone number
GET /v1/customers/{id}

Retrieve a single customer record.

Path Parameters

Param Type Description Value
id string Customer ID
PATCH /v1/customers/{id}

Update a customer record. Only fields you include are changed; omitted fields are left untouched.

Path & Body Parameters

Param In Type Description Value
id path string Customer ID
name body string Customer name
email body string Contact email
phone body string Phone number
DELETE /v1/customers/{id}

Soft-delete a customer. The record is hidden from list endpoints but kept on the underlying row so historical work orders / invoices keep resolving the customer name.

Path Parameters

Param Type Description Value
id string Customer ID

🚛 Vehicles

Manage vehicle records linked to customers.

GET /v1/vehicles

List all vehicles with optional filtering and search capabilities.

Query Parameters

Param Type Description Value
customerId string Filter by customer ID
limit integer Max results (default: 100)
search string General search across all fields
vin string Search by VIN (partial match)
licensePlate string Search by license plate
unitNumber string Search by unit number
make string Search by vehicle make
model string Search by vehicle model
year string Search by model year
vehicleType string Filter by vehicle type
includeArchived boolean Include archived vehicles (default: false)
POST /v1/vehicles

Create a new vehicle record.

Request Body

Field Type Description Value
customerId string Owner customer ID
vin string Vehicle Identification Number
licensePlate string License plate number
make string Vehicle make (e.g., Peterbilt)
model string Vehicle model
year integer Model year
mileage integer Current mileage
GET /v1/vehicles/{id}

Retrieve a single vehicle record.

Path Parameters

Param Type Description Value
id string Vehicle ID
PATCH /v1/vehicles/{id}

Update a vehicle record. Only fields you include are changed.

Path & Body Parameters

Param In Type Description Value
id path string Vehicle ID
licensePlate body string License plate number
mileage body integer Updated mileage
unitNumber body string Fleet unit number
nickname body string Display nickname
DELETE /v1/vehicles/{id}

Soft-delete a vehicle. The record is hidden from list endpoints; historical work orders keep resolving the vehicle display name.

Path Parameters

Param Type Description Value
id string Vehicle ID

📋 Work Orders

Manage repair work orders and service tickets.

GET /v1/work-orders

List all work orders with filtering options.

Query Parameters

Param Type Description Value
status string estimate | approved | in_progress | quality_check | ready_for_pickup | invoiced | paid | completed
customerId string Filter by customer
vehicleId string Filter by vehicle
limit integer Max results (default: 100). Card-level strip applied at ≥100 unless fullDetails=true.
fullDetails boolean Return full services / line-item arrays even past the 100-item card-strip threshold (used by reports).
GET /v1/work-orders/{id}

Retrieve a single work order with fully assembled service blocks, line items (labor / parts / tires / materials / fees), and resolved customer / vehicle names.

Path Parameters

Param Type Description Value
id string Work order ID
POST /v1/work-orders

Create a new work order.

Request Body

Field Type Description Value
customerId string Customer ID
vehicleId string Vehicle ID
complaint string Customer complaint description
priority string low | medium | high | urgent
assignedTo string Technician user ID
PATCH /v1/work-orders/{id}

Update top-level work-order fields (status, priority, name, description, due date, assigned technicians, etc.). For per-service-block edits use the /services/{svcId} endpoints below; this route does not overwrite the nested services array.

Path & Body Parameters

Param In Type Description Value
id path string Work order ID
status body string estimate | approved | in_progress | quality_check | ready_for_pickup | invoiced | paid | completed
priority body string low | medium | high | urgent
name body string Display name
dueDate body string ISO-8601 date or datetime
DELETE /v1/work-orders/{id}

Soft-delete a work order. Use the dedicated /permanent-delete endpoint (admin only) for hard deletion of test data; soft-deleted records can be restored via /restore.

Path Parameters

Param Type Description Value
id string Work order ID

Service Blocks & Line Items

Granular endpoints for editing the services[] array on a work order. Each service block carries its own version — PATCH requests must echo the version they read; the server bumps it on success and returns 409 on stale writes.

PATCH /v1/work-orders/{woId}/services/{svcId}

Update a single service block (name, description, labor entries, parts, tires, financials). Pass version from your last read; on conflict the server returns 409 and the latest stored version.

Path & Body Parameters

Param In Type Description Value
woId path string Work order ID
svcId path string Service block ID
version body integer Version you last read. Server compares and rejects with 409 if the stored version is higher.
name body string Service name
description body string Service description / notes
authorizationStatus body string approved | declined | pending
DELETE /v1/work-orders/{woId}/services/{svcId}

Remove a service block (and its labor / parts / tires / materials line items) from a work order. Totals on the work order are recomputed server-side.

Path Parameters

Param Type Description Value
woId string Work order ID
svcId string Service block ID
PATCH /v1/work-orders/{woId}/services/{svcId}/items/{itemId}

Update a single line item (labor, part, tire, material, fee) inside a service block. Use this for small edits like changing labor status or part quantity without re-PATCHing the whole service block.

Path & Body Parameters

Param In Type Description Value
woId path string Work order ID
svcId path string Service block ID
itemId path string Line item ID
kind body string labor | part | tire | material | fee
status body string For labor: pending | in_progress | paused | completed
quantity body number For parts/tires/materials
unitPriceCents body integer Price per unit in cents (canonical money form)
DELETE /v1/work-orders/{woId}/services/{svcId}/items/{itemId}

Remove a single line item from a service block.

Path & Body Parameters

Param In Type Description Value
woId path string Work order ID
svcId path string Service block ID
itemId path string Line item ID
kind body string labor | part | tire | material | fee

📦 Inventory

Manage parts and supplies inventory.

GET /v1/inventory

List all inventory items.

Query Parameters

Param Type Description Value
category string Filter by category
lowStock boolean Show only low stock items
search string Search by name or SKU

🔍 Inspections

Manage vehicle inspection records.

GET /v1/inspections

List all inspection records.

Query Parameters

Param Type Description Value
vehicleId string Filter by vehicle
workOrderId string Filter by work order
status string passed | failed | pending
GET /v1/inspections/{id}

Retrieve a single inspection with all its line items (passed / failed / NA results, photos, technician notes).

Path Parameters

Param Type Description Value
id string Inspection ID
PATCH /v1/inspections/{id}

Update top-level inspection fields (status, technician, notes). Use the dedicated /items/{itemId} endpoint to edit individual checklist items.

Path & Body Parameters

Param In Type Description Value
id path string Inspection ID
status body string passed | failed | pending
notes body string Inspector notes / summary
technicianId body string Inspecting technician's user ID
DELETE /v1/inspections/{id}

Soft-delete an inspection. Photos remain in S3 (lifecycle policy handles eventual cleanup); the record is hidden from list endpoints.

Path Parameters

Param Type Description Value
id string Inspection ID

👥 Users

Manage shop users and technicians.

GET /v1/users

List all users in the shop.

Query Parameters

Param Type Description Value
role string admin | manager | technician | service_writer
active boolean Filter by active status
GET /v1/users/me

Get the current authenticated user's profile.

🛠️ Admin

Tenant-administrator endpoints for user management. All routes are gated by the settings.users permission — non-admin API keys get 403 Forbidden. The non-admin /v1/users list above is read-only and tenant-scoped; everything below requires admin.

Path prefix: all routes in this section live under /v1/admin/users, not /v1/users.
POST /v1/admin/users

Create a new shop user. The user receives an email invite with a temporary password unless password is set explicitly.

Request Body

Field Type Description Value
email string User's email (login)
name string Full name
role string admin | manager | technician | service_writer
phone string Phone number
GET /v1/admin/users/{id}

Retrieve a user by ID, including admin-only fields like isActive, last login, and permission overrides.

Path Parameters

Param Type Description Value
id string User ID
PUT /v1/admin/users/{id}

Update user fields (name, role, phone). Admin-only. To change a password use /set-password instead.

Path & Body Parameters

Param In Type Description Value
id path string User ID
name body string Display name
role body string admin | manager | technician | service_writer
DELETE /v1/admin/users/{id}

Soft-delete a user. The user can no longer log in, but historical work-order assignments still resolve their name. Use /permanent-delete for irreversible removal of test accounts.

Path Parameters

Param Type Description Value
id string User ID

Account Actions

Targeted admin actions on a specific user account. Each is a single-purpose POST that returns the updated user.

POST /v1/admin/users/{id}/set-password

Force-set a user's password (admin-initiated reset). The new password is hashed server-side; the plaintext is never stored or echoed back.

Path & Body Parameters

Param In Type Description Value
id path string User ID
password body string New password (min 8 chars)
POST /v1/admin/users/{id}/activate

Re-enable a previously deactivated user. The user can log in again immediately; historical assignments are unchanged.

Path Parameters

Param Type Description Value
id string User ID
POST /v1/admin/users/{id}/deactivate

Disable a user without deleting them. The user can no longer log in or appear in technician pickers, but their historical activity is preserved. Reverse with /activate.

Path Parameters

Param Type Description Value
id string User ID
DELETE /v1/admin/users/{id}/permanent-delete

Hard-delete a user record. Irreversible. Use this only for test accounts or compliance-mandated deletion (right-to-be-forgotten); historical work-order assignments will fall back to displaying just the user ID.

Destructive. Prefer the soft-delete DELETE /v1/admin/users/{id} for normal offboarding. This permanent variant cannot be undone.

Path Parameters

Param Type Description Value
id string User ID

🔔 Webhooks

Configure webhooks to receive real-time notifications.

GET /v1/webhooks

List all configured webhooks.

Status: stub. The webhook subscription store is not yet wired up — this endpoint currently returns an empty list. Webhook event delivery infrastructure (signing, retries, dead-letter queue) is on the roadmap. Use polling (e.g. GET /v1/work-orders?status=in_progress) for now; if you need real-time push, contact us.

Available Webhook Events

Event Description
work_order.created New work order created
work_order.updated Work order status changed
work_order.completed Work order marked complete
customer.created New customer added
vehicle.created New vehicle added
inspection.completed Inspection finished
inventory.low_stock Item below threshold