API Reference
Every V1 endpoint, generated from the frozen OpenAPI document.
Base URL https://api.shopcommander.com/v1. Every operation needs Authorization: Bearer sc_live_…. Generated from openapi.json (version 1.0.0-rc.4); response shapes are described on the resource pages and pinned by the contract tests.
- appointments
- canned-jobs
- customers
- events
- inventory-items
- invoices
- jobs
- payments
- repair-orders
- shop
- tasks
- technicians
- vehicles
- webhook-endpoints
appointments
GET /v1/appointments
List Appointments
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
scheduled_date_from | string (date) | null | |
scheduled_date_to | string (date) | null | |
status | string | null | |
customer | string | null | |
vehicle | string | null | |
technician | string | null | |
updated_after | string (date-time) | null | |
sort | string matching ^(created_at|updated_at)$ | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/appointments
Create Appointment
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
customer_id required | string | |
date required | string (date) | |
duration_minutes | integer | |
notes | string | null | |
reason | string | null | |
technician_id | string | null | |
time required | string matching ^(?:[01]\d|2[0-3]):[0-5]\d$ | |
utc_offset | string matching ^(?:[+-](?:0\d|1[0-3]):[0-5]\d|[+-]14:00)$ | null | |
vehicle_id | string | null |
Responses: 201 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/appointments/availability
Availability
Query parameters
| Name | Type | Notes |
|---|---|---|
date | string (date) | null | |
start_date | string (date) | null | |
end_date | string (date) | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/appointments/{public_id}
Get Appointment
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PATCH /v1/appointments/{public_id}
Update Appointment
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
date | string (date) | |
duration_minutes | integer | |
expected_version | integer | null | |
notes | string | null | |
reason | string | null | |
technician_id | string | null | |
time | string matching ^(?:[01]\d|2[0-3]):[0-5]\d$ | |
utc_offset | string matching ^(?:[+-](?:0\d|1[0-3]):[0-5]\d|[+-]14:00)$ | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/appointments/{public_id}/cancel
Cancel Appointment
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/appointments/{public_id}/check-in
Check In Appointment
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/appointments/{public_id}/repair-order
Convert To Repair Order
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 201 400 401 403 404 409 429 500 503 — errors use the error envelope.
canned-jobs
GET /v1/canned-jobs
List Canned Jobs
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
q | string | null | |
category | string | null | |
active | boolean | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/canned-jobs/{public_id}
Get Canned Job
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
customers
GET /v1/customers
List Customers
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
q | string | null | |
email | string | null | |
phone | string | null | |
external_id | string | null | |
updated_after | string (date-time) | null | |
lifecycle | string matching ^(active|archived|all)$ | |
sort | string matching ^(created_at|updated_at)$ | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/customers
Create Customer
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
address | string | null | |
city | string | null | |
company_name | string | null | |
email | string | null | |
first_name required | string | |
fleet_account | boolean | |
last_name required | string | |
notes | string | null | |
phone | string | null | |
phone_alt | string | null | |
postal_code | string | null | |
preferred_contact | string matching ^(sms|email|phone)$ | null | |
region | string | null | |
tags | array of string | null | |
tax_exempt | boolean |
Responses: 201 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/customers/{public_id}
Get Customer
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PATCH /v1/customers/{public_id}
Update Customer
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
address | string | null | |
city | string | null | |
company_name | string | null | |
email | string | null | |
expected_version | integer | null | |
first_name | string | |
fleet_account | boolean | |
last_name | string | |
notes | string | null | |
phone | string | null | |
phone_alt | string | null | |
postal_code | string | null | |
preferred_contact | string matching ^(sms|email|phone)$ | null | |
region | string | null | |
tags | array of string | |
tax_exempt | boolean |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/customers/{public_id}/archive
Archive Customer
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
DELETE /v1/customers/{public_id}/external-id
Delete Customer External Id
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PUT /v1/customers/{public_id}/external-id
Put Customer External Id
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
external_id required | string |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
events
GET /v1/events
List Events
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
type | string | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/events/{public_id}
Get Event
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
inventory-items
GET /v1/inventory-items
List Inventory Items
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
q | string | null | |
part_number | string | null | |
product_family | string | null | |
in_stock | boolean | null | |
active | boolean | null | |
tire_size | string | null | |
tire_width | integer | null | |
tire_aspect_ratio | integer | null | |
tire_rim_diameter | number | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/inventory-items/{public_id}
Get Inventory Item
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
invoices
GET /v1/invoices
List Invoices
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
status | string matching ^(posted|voided)$ | null | |
doc_type | string matching ^(invoice|credit_note)$ | null | |
customer | string | null | |
repair_order | string | null | |
number | integer | null | |
business_date_from | string (date) | null | |
business_date_to | string (date) | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/invoices/{public_id}
Get Invoice
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
jobs
GET /v1/jobs/{public_id}
Get Job
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/jobs/{public_id}/complete
Complete Job
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/jobs/{public_id}/labor
List Job Labor
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/jobs/{public_id}/parts
List Job Parts
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/jobs/{public_id}/start
Start Job
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/jobs/{public_id}/unable-to-complete
Unable To Complete Job
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
payments
GET /v1/payments
List Payments
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
settlement_target | string matching ^(invoice|warranty_claim)$ | null | |
repair_order | string | null | |
invoice | string | null | |
business_date_from | string (date) | null | |
business_date_to | string (date) | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/payments/{public_id}
Get Payment
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
repair-orders
GET /v1/repair-orders
List Repair Orders
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
state | string matching ^(scheduled|checked_in|estimating|awaiting_authorization|authorized|in_progress|waiting_for_parts|quality_check|completed|ready_for_pickup|invoiced|paid|picked_up|closed|cancelled|unknown)$ | null | |
customer | string | null | |
vehicle | string | null | |
number | integer | null | |
created_after | string (date-time) | null | |
created_before | string (date-time) | null | |
updated_after | string (date-time) | null | |
sort | string matching ^(created_at|updated_at)$ | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/repair-orders
Create Repair Order
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
customer_concern | string | null | |
customer_id required | string | |
odometer_in | integer | null | |
vehicle_id required | string |
Responses: 201 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/repair-orders/{public_id}
Get Repair Order
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
DELETE /v1/repair-orders/{public_id}/external-id
Delete Repair Order External Id
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PUT /v1/repair-orders/{public_id}/external-id
Put Repair Order External Id
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
external_id required | string |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/repair-orders/{public_id}/jobs
List Jobs
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/repair-orders/{public_id}/jobs
Add Job
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
canned_job_id | string | null | |
description | string | null | |
labor_hours | number | string matching ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ | null | |
name | string | null | |
technician_id | string | null |
Responses: 201 400 401 403 404 409 429 500 503 — errors use the error envelope.
shop
GET /v1/shop
Get Shop
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
tasks
GET /v1/tasks
List Tasks
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
status | string | null | |
assignee | string | null | |
updated_after | string (date-time) | null | |
sort | string matching ^(created_at|updated_at)$ | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/tasks
Create Task
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
assigned_to | string | null | |
category | string | null | |
customer_id | string | null | |
description | string | null | |
due_at | string (date-time) | null | |
priority | string matching ^(low|normal|high|urgent)$ | |
repair_order_id | string | null | |
title required | string |
Responses: 201 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/tasks/{public_id}
Get Task
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PATCH /v1/tasks/{public_id}
Update Task
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
assigned_to | string | null | |
category | string | null | |
description | string | null | |
due_at | string (date-time) | null | |
priority | string matching ^(low|normal|high|urgent)$ | |
status | string matching ^(open|in_progress|blocked|waiting)$ | |
title | string |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/tasks/{public_id}/complete
Complete Task
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
DELETE /v1/tasks/{public_id}/external-id
Delete Task External Id
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PUT /v1/tasks/{public_id}/external-id
Put Task External Id
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
external_id required | string |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
technicians
GET /v1/technicians
List Technicians
Query parameters
| Name | Type | Notes |
|---|---|---|
active | boolean | null | |
limit | integer | null | |
cursor | string | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
vehicles
GET /v1/vehicles
List Vehicles
Query parameters
| Name | Type | Notes |
|---|---|---|
limit | integer | null | |
cursor | string | null | |
customer | string | null | |
vin | string | null | |
plate | string | null | |
unit_number | string | null | |
q | string | null | |
external_id | string | null | |
updated_after | string (date-time) | null | |
lifecycle | string matching ^(active|archived|all)$ | |
sort | string matching ^(created_at|updated_at)$ | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/vehicles
Create Vehicle
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
color | string | null | |
customer_id required | string | |
license_plate | string | null | |
make | string | null | |
model | string | null | |
notes | string | null | |
odometer | integer | null | |
plate_region | string | null | |
trim | string | null | |
unit_number | string | null | |
vehicle_type | string | null | |
vin | string | null | |
year | integer | null |
Responses: 201 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/vehicles/{public_id}
Get Vehicle
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PATCH /v1/vehicles/{public_id}
Update Vehicle
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
color | string | null | |
expected_version | integer | null | |
license_plate | string | null | |
notes | string | null | |
odometer | integer | |
plate_region | string | null | |
unit_number | string | null |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
DELETE /v1/vehicles/{public_id}/external-id
Delete Vehicle External Id
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PUT /v1/vehicles/{public_id}/external-id
Put Vehicle External Id
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
external_id required | string |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
webhook-endpoints
GET /v1/webhook-endpoints
List Endpoints
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/webhook-endpoints
Create Endpoint
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
description | string | null | |
event_types required | array of string | |
url required | string |
Responses: 201 400 401 403 404 409 429 500 503 — errors use the error envelope.
GET /v1/webhook-endpoints/{public_id}
Get Endpoint
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
PATCH /v1/webhook-endpoints/{public_id}
Update Endpoint
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Request body
| Field | Type | Notes |
|---|---|---|
description | string | null | |
event_types | array of string | |
status | string matching ^(active|disabled)$ | |
url | string |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/webhook-endpoints/{public_id}/rotate-secret
Rotate Secret
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 200 400 401 403 404 409 429 500 503 — errors use the error envelope.
POST /v1/webhook-endpoints/{public_id}/test
Send Test Event
Query parameters
| Name | Type | Notes |
|---|---|---|
Idempotency-Key required | string matching ^[\x21-\x7E]+$ | A unique 1-255 character visible-ASCII command key. Same key and canonical body replays for 7 days; changed reuse is rejected for 30 days. |
Responses: 202 400 401 403 404 409 429 500 503 — errors use the error envelope.