BigShop API
Build powerful integrations with the BigShop Truck Repair Management Platform.
https://api.bigshopai.com/v1
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.
/v1/health
Returns the current health status of the API.
🏢 Customers
Manage customer records for your repair shop.
/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 |
/v1/customers
Create a new customer record.
Request Body
| Field | Type | Description | Value |
|---|---|---|---|
| name | string | Customer name | |
| type | string | company | individual | |
| string | Contact email | ||
| phone | string | Phone number |
/v1/customers/{id}
Retrieve a single customer record.
Path Parameters
| Param | Type | Description | Value |
|---|---|---|---|
| id | string | Customer ID |
/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 | |
| body | string | Contact email | ||
| phone | body | string | Phone number |
/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.
/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) |
/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 |
/v1/vehicles/{id}
Retrieve a single vehicle record.
Path Parameters
| Param | Type | Description | Value |
|---|---|---|---|
| id | string | Vehicle ID |
/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 |
/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.
/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). |
/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 |
/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 |
/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 |
/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.
/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 |
/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 |
/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) |
/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.
/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.
/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 |
/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 |
/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 |
/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.
/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 |
/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.
/v1/admin/users, not /v1/users.
/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 |
|---|---|---|---|
| string | User's email (login) | ||
| name | string | Full name | |
| role | string | admin | manager | technician | service_writer | |
| phone | string | Phone number |
/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 |
/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 |
/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.
/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) |
/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 |
/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 |
/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.
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.
/v1/webhooks
List all configured webhooks.
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 |