Get raw daily report aggregates

Returns the stored per-day report rows for a date range, exactly as the platform keeps them: revenue by category, cost of sales, taxes, payments by method, invoice counts, customers and per-technician stats for each shop-local day. Use it when you need to build your own totals; the other /report-aggregates endpoints are summaries built from these rows. Days with no activity have no row and are omitted. There is no pagination: every row in the range comes back in one response. Both dates are required. Dates are shop-local calendar days (the shop's time zone from Settings; America/Chicago if none is set), written YYYY-MM-DD and inclusive at both ends. Validation: each date must be a real calendar day in YYYY-MM-DD form, must fall between 2000-01-01 and 2100-12-31, and startDate must be on or before endDate. Freshness (cached mode): the figures come from stored per-day rows that are updated as invoices, counter sales and payments change, and an overnight job (07:00 UTC, covering the last 45 days) recomputes them to correct any drift. This endpoint does not add a live calculation for today: today's numbers are whatever the stored row holds, so use mode=live to force a fresh recompute. All money fields end in Cents and are integer cents. Each row's technicianStats omits commissionCents and commissionRatePercent unless the caller holds reports:profit or attendance:financials.

Parameters

curl "https://api.bigshopai.com/v1/report-aggregates/daily?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — Either an invalid date range (error 'Invalid date range' with a message) or a missing parameter (error 'startDate and endDate are required', no message).
• 403 — Caller lacks the required permission.
• 500 — Unexpected error.

Get sales summary

Answers 'how much did the shop invoice and collect over this period, and where did it come from?' Returns revenue split by labor, parts, tires, subcontracts, shop supplies, fees, EPA and service items, with discounts, tax and card surcharge, for all invoices and for fully paid invoices only, plus payments received (by method), unique customers, average repair order, counter-sale revenue, and daily trend series. Work orders and counter sales are both included. Invoices count on their invoiced date and payments on the date received. Dates are shop-local calendar days (the shop's time zone from Settings; America/Chicago if none is set), written YYYY-MM-DD and inclusive at both ends. Validation: each date must be a real calendar day in YYYY-MM-DD form, must fall between 2000-01-01 and 2100-12-31, and startDate must be on or before endDate. When omitted, startDate defaults to the first day of the current month and endDate to today, both in shop time. Freshness (cached mode): the figures come from stored per-day rows that are updated as invoices, counter sales and payments change, and an overnight job (07:00 UTC, covering the last 45 days) recomputes them to correct any drift. This endpoint does not add a live calculation for today: today's numbers are whatever the stored row holds, so use mode=live to force a fresh recompute. Money fields are DOLLARS (decimal numbers), not cents; they are cents divided by 100 and not rounded, so round to 2 decimals for display. No cursor pagination: trendData is limited to the last 30 days of the range (trendDataTruncated says when it was clipped) and trendDaily to 3000 days (trendDailyTruncated).

Parameters

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

Response fields (first 3 levels)

Errors

• 400 — Invalid date range. message is one of: 'Dates must be real calendar days, written YYYY-MM-DD.', 'Dates must fall between 2000 and 2100.', 'The start date must be on or before the end date.'
• 403 — Caller lacks the required permission.
• 500 — Unexpected error.

Get payments summary

Answers 'how much money came in over this period, by what method, and on which days?' Returns total payments received, the number of payment transactions, totals by payment method, and a per-day list. Amounts are net of refunds and voided payments; work-order and counter-sale payments are both included, each on the day it was received. Dates are shop-local calendar days (the shop's time zone from Settings; America/Chicago if none is set), written YYYY-MM-DD and inclusive at both ends. Validation: each date must be a real calendar day in YYYY-MM-DD form, must fall between 2000-01-01 and 2100-12-31, and startDate must be on or before endDate. When omitted, startDate defaults to the first day of the current month and endDate to today, both in shop time. Freshness (cached mode): the figures come from stored per-day rows that are updated as invoices, counter sales and payments change, and an overnight job (07:00 UTC, covering the last 45 days) recomputes them to correct any drift. This endpoint does not add a live calculation for today: today's numbers are whatever the stored row holds, so use mode=live to force a fresh recompute. Money fields are DOLLARS (decimal numbers), not cents. dailyTotals lists only days that have a stored row (no zero-fill).

Parameters

curl "https://api.bigshopai.com/v1/report-aggregates/payments?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — Invalid date range. message is one of: 'Dates must be real calendar days, written YYYY-MM-DD.', 'Dates must fall between 2000 and 2100.', 'The start date must be on or before the end date.'
• 403 — Caller lacks the required permission.
• 500 — Unexpected error.

Get sales tax collected

Answers 'how much sales tax did the shop collect, at which rates, and what was taxable versus exempt?' Returns, separately for work orders and for counter sales, taxable sales, tax billed, tax received, outstanding tax, a breakdown per tax rate with a drill-down list of the orders behind each rate, a non-taxable section (including resale-certificate and exempt-organization sales), and a parts / labor / subcontract / other split. basis=accrual (default) reports by invoice date: tax billed, with received and outstanding figures pro-rated by how much of each invoice has been paid. basis=cash reports by payment date: only money actually received in the window, whatever period its invoice belongs to, so nothing is outstanding. Dates are shop-local calendar days (the shop's time zone from Settings; America/Chicago if none is set), written YYYY-MM-DD and inclusive at both ends. Validation: each date must be a real calendar day in YYYY-MM-DD form, must fall between 2000-01-01 and 2100-12-31, and startDate must be on or before endDate. When omitted, startDate defaults to the first day of the current month and endDate to today, both in shop time. The figures come from a per-order tax ledger kept current as invoices and payments change. If the ledger for the requested range looks incomplete (fewer than 95% of the expected orders, or rows in an older format) the request rebuilds it first and sets builtOnFirstView to true; that request is slower, and this GET therefore writes data. This endpoint has no mode parameter (a mode value is ignored). The orders drill-down is capped at 250 rows per rate tier and for the non-taxable list; ordersTruncated says when it was clipped, and totals are always exact. Order rows include the customer name. Money fields end in Cents and are integer cents; rates are percentages.

Parameters

curl "https://api.bigshopai.com/v1/report-aggregates/tax-collected?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — Invalid date range. message is one of: 'Dates must be real calendar days, written YYYY-MM-DD.', 'Dates must fall between 2000 and 2100.', 'The start date must be on or before the end date.'
• 403 — Caller lacks the required permission.
• 500 — Unexpected error.

Get technician commission report

Answers 'what did each technician bill and earn in commission over this period?' Returns per technician the billed labor hours, labor revenue, jobs completed, commission rate and commission earned, plus shop totals, sorted by commission (highest first). Commission is taken from what was stored on each day's invoices at the time (using the technician's commission rate then); if a technician has a rate and labor revenue but stored commission of 0, it is recomputed as revenue times rate. Labor discounts do not reduce commission. Dates are shop-local calendar days (the shop's time zone from Settings; America/Chicago if none is set), written YYYY-MM-DD and inclusive at both ends. Validation: each date must be a real calendar day in YYYY-MM-DD form, must fall between 2000-01-01 and 2100-12-31, and startDate must be on or before endDate. When omitted, startDate defaults to the first day of the current month and endDate to today, both in shop time. Freshness (cached mode): the figures come from stored per-day rows that are updated as invoices, counter sales and payments change, and an overnight job (07:00 UTC, covering the last 45 days) recomputes them to correct any drift. This endpoint does not add a live calculation for today: today's numbers are whatever the stored row holds, so use mode=live to force a fresh recompute. Money fields are DOLLARS (decimal numbers), not cents; they are re-derived from cents with floating-point arithmetic, so round to 2 decimals for display. Rates are percentages. A mechanicId that matches nobody returns an empty list and zero totals, not a 404. This is pay data: callers who hold only reports:operational get 403.

Parameters

curl "https://api.bigshopai.com/v1/report-aggregates/commission?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — Invalid date range. message is one of: 'Dates must be real calendar days, written YYYY-MM-DD.', 'Dates must fall between 2000 and 2100.', 'The start date must be on or before the end date.'
• 403 — Caller lacks the required permission.
• 500 — Unexpected error.

Get part usage totals

Answers 'which parts does the shop actually use, how many, and when was each last used?' Returns one entry per part with the quantity used on invoiced work orders over the last 180 days and over all recorded history, the latest unit cost, and the last-used date; it feeds inventory-health and parts-analytics reports. Parts are keyed by part number (or description when there is no part number). Only part lines on invoiced work orders count: tire and shop-supply lines and counter sales are not in these totals. Takes no date parameters. If startDate or endDate are sent they are validated by the shared date check (and can produce a 400) but are otherwise ignored. The totals are rebuilt once a night from a per-invoice usage ledger (the same 07:00 UTC job as the daily aggregates), so today's invoices do not appear until the next rebuild; updatedAt shows when the newest rows were written. There is no pagination and no limit: every part is returned in one response, so the payload grows with the size of the shop's parts history. totalCostCents is a unit cost in integer cents, not a total.

curl "https://api.bigshopai.com/v1/report-aggregates/part-usage" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — Invalid date range. message is one of: 'Dates must be real calendar days, written YYYY-MM-DD.', 'Dates must fall between 2000 and 2100.', 'The start date must be on or before the end date.'
• 403 — Caller lacks the required permission.
• 500 — Unexpected error.

Customer aging (accounts receivable) as of a day

Answers: who owes the shop money, and how overdue is it? Returns one row per customer with their unpaid invoice balances split into Current (not yet due), 1-30, 31-60, 61-90 and Over 90 days past due, as the books stood at the end of the chosen day in the shop's time zone. mode=asOf (default) replays invoices and dated payments, so it works for any past day and for today (pass today's date for the current picture); generatedAt is the request time. mode=snapshot returns the end-of-day row stored by the scheduled snapshot job; if no snapshot was stored for that day you get HTTP 200 with rows: [] and meta.snapshotFound=false (not an error). Use GET /reports/customer-aging/snapshots to see which days exist. An invoice is due 30 days after its invoice date unless the work order has its own due date. Only invoiced work orders that have a customer id are included; counter sales and invoices without a customer are not read. UNITS: every amount in rows is DOLLARS (decimal), but meta.untraceablePaidCents is cents.

Parameters

curl "https://api.bigshopai.com/v1/reports/customer-aging" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — {"error":"asOf must be a YYYY-MM-DD date"} (missing/malformed) or {"error":"asOf cannot be in the future"}.
• 403 — Forbidden. The caller's role lacks reports:operational.
• 500 — Server error. Body is {"error": "Failed to load historical aging"}; internal detail is logged, not returned.

List days that have a stored aging snapshot

Answers: for which days can I read the stored (audit-grade) receivables snapshot? Returns the dates, newest first. Use one of them as asOf with mode=snapshot on GET /reports/customer-aging.

curl "https://api.bigshopai.com/v1/reports/customer-aging/snapshots" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 403 — Forbidden. The caller's role lacks reports:operational.
• 500 — Server error. Body is {"error": "Failed to list snapshots"}; internal detail is logged, not returned.

Week-over-week revenue and profit trend

Answers: how is the shop trending week to week? Returns up to weeks weekly data points (Monday-Sunday in the shop's time zone), oldest to newest: revenue, labor and parts revenue and profit, labor hours, jobs, customers and invoice count. These are pre-computed rollups, not live. The nightly rollup (00:00 UTC) recomputes the current and the previous week; older weeks only change on a backfill. So the current week reflects the last nightly run, not this minute. UNITS: all money is integer cents. (A stale code comment says dollars; the payload is cents.) revenueCents includes tax; partsRevenueCents/partsProfitCents include tires.

Parameters

curl "https://api.bigshopai.com/v1/reports/weekly-trend" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 403 — Forbidden. The caller's role lacks reports:operational.
• 500 — Server error. Body is {"error": "Failed to get weekly trend"}; internal detail is logged, not returned.

List daily or weekly digests

Lists the shop's AI morning briefings, newest first, without the full text: headline, date, how it was produced, delivery status and any thumbs rating. A daily digest covers the previous completed business day in the shop's time zone and a weekly digest covers the last completed Monday-to-Sunday week (dated by its Monday). Digests exist only for shops that have the feature switched on: an hourly job writes one after the shop's send hour (5-9 am shop time, default 6), so a shop that never enabled it gets an empty list. Each digest is created once and not updated as the day goes on (regenerating overwrites it). Admin role required; API keys carry it. Pagination: none. The response holds the most recent limit digests only (1-60, default 30); there is no cursor and older digests cannot be reached through this endpoint once they fall outside the newest 60. Fetch a specific older one with GET /digests/{date}.

Parameters

curl "https://api.bigshopai.com/v1/digests" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 401 — Caller's tenant could not be resolved.
• 403 — Caller is not an admin.
• 500 — Unexpected error.

Get one digest

Returns one full digest: the written briefing (headline, summary, bullets, wins, concerns, things to watch, recommended actions, callouts) and the data snapshot it was built from (revenue, labor, parts, payments, gross profit, open work, receivables and so on, each with comparisons to yesterday, last week or the prior four weeks). Every figure in the narrative is copied from a pre-formatted display string in the snapshot; the model never computes numbers, and if validation fails a deterministic template is used (renderMode = fallback). Money in the snapshot is integer cents, each with a matching display string. Keys inside narrative and snapshot are snake_case. For daily digests {date} is the covered day. For weekly digests (period=weekly) {date} must be the Monday of the covered week; any other date returns 404 because the lookup is by exact key. {date} must match YYYY-MM-DD; it is not checked for being a real calendar day, so an impossible date such as 2026-02-31 simply returns 404. A digest that does not exist, or that belongs to another shop, returns 404. Admin role required; API keys carry it. The digest is a fixed record created once; it does not change as the day goes on.

Parameters

curl "https://api.bigshopai.com/v1/digests/2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 401 — Caller's tenant could not be resolved.
• 403 — Caller is not an admin.
• 404 — No digest for that date and period (also returned for a path that is not a YYYY-MM-DD date).
• 500 — Unexpected error.

Get daily trend aggregates

Answers 'how did invoicing and payments trend day by day over this range?' Returns one entry per shop-local day that has a stored aggregate: invoice count and revenue (total, labor, parts, tires, counter sales), the same for fully paid invoices, payments received, unique customers, and per-technician stats. It reads the same stored per-day rows as /report-aggregates/daily, converted for charting. Both dates are required. Unlike the /report-aggregates endpoints this one does NOT run the shared date validation: dates are not checked for format or range, startDate after endDate is not rejected up front, and the 2000-2100 bounds do not apply. Send real YYYY-MM-DD dates with startDate <= endDate. Freshness: reads stored daily rows, which are updated as invoices and payments change and recomputed by the overnight job (07:00 UTC, last 45 days); there is no live recalculation here, and there is no period parameter. No pagination: the endpoint issues a single database query and does not follow a continuation key, so a very wide range could be cut off at the first ~1 MB of rows with no truncated flag. Keep ranges to a few months. Money units are mixed: all top-level revenue and payment fields are DOLLARS (decimal numbers), but money inside technicianStats (laborRevenueCents, commissionCents) is still integer CENTS. technicianStats omits commissionCents and commissionRatePercent unless the caller holds reports:profit or attendance:financials.

Parameters

curl "https://api.bigshopai.com/v1/dashboard/trend-aggregates?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — Either date is missing.
• 403 — Caller lacks the required permission.
• 500 — Query failed (for example startDate after endDate).

Get dashboard metrics

The numbers behind the shop dashboard: revenue, average job, payments received, gross profit and margin, technician utilization, a day-by-day trend, customers and vehicles served, all for a date range and compared with the previous period of the same length; plus right-now shop-floor counts (open jobs, vehicles in the shop, overdue, delayed, stale, waiting for parts), unpaid invoices, the top customers and invoices owing money, collection health, and low-stock part counts. Each group has its own freshness, and freshness in the response says how old each one is. Period figures (revenue, payments, profit, utilization, trend, served counts) come from the stored per-day rows, kept current as invoices and payments change and recomputed overnight; there is no live recalculation, and isStale is always false. Floor counters are updated as work orders change and recounted hourly (:10 past the hour). Unpaid totals are updated as invoices change and re-anchored nightly. paymentHealth and collections come from last night's receivables snapshot and cover ALL outstanding receivables, not just the range. Parts counts come from the latest inventory snapshot. Date range: pass BOTH startDate and endDate (YYYY-MM-DD, shop-local, inclusive) for a custom range. If either is missing or malformed, or startDate is after endDate, the range is silently replaced by the current month to date; there is no 400 for that. Calendar-impossible dates are not rejected either (2026-02-31 is accepted and rolls over). The only range error is more than 400 days (400 'Date range too long'). The previous period is the same number of days immediately before startDate. The shop's time zone is NOT read from settings here; it comes from the timezone parameter (default America/Chicago) and only decides what 'today' is for the default range. The stored rows themselves are already bucketed by the shop's own time zone. If the shop's history has not been backfilled (stored rows start after its first invoice) the response has building = true and metrics = null. Money units are mixed: every metric is DOLLARS (decimal numbers), except trendDaily.days[*], which is integer CENTS (fields ending in Cents). Tax: periodRevenue, avgPerJob, counterRevenue and the trend's invoicedCents include sales tax; grossProfit.revenue excludes it. The other query parameters you may see used by the app (recalculate) are ignored.

Parameters

curl "https://api.bigshopai.com/v1/dashboard/metrics?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — Range longer than 400 days.
• 403 — Caller lacks dashboard:read.
• 500 — Unexpected error.

Parts purchasing ledger (opening, purchases, usage, closing)

Answers: what did the shop buy, use and hold in a period, and how did inventory value move? Default response is a shop-wide summary (opening value, purchases, usage with revenue and profit, reserved/held change, closing value, a reconciliation residual and cost changes) plus one ledger row per part, tire, fluid or shop item that had activity. Dates are shop-local days (inclusive both ends, shop time zone default America/Chicago). All money is integer cents; quantities are units. The same route has drill-down modes selected by query parameters (precedence: view=daily, then partId, then bucket; otherwise the list): partId returns that part's raw transactions, bucket returns transactions across parts, view=daily returns a part x day pivot. The detail modes are paginated with page/limit and report hasMore. Opening/closing come from end-of-day inventory snapshots; where a snapshot is missing the value is null, or live (flagged openingIsLive/closingIsLive) when the window touches today. Cost, price and profit are returned to any caller that passes the read gate; there is no per-field cost masking.

Parameters

curl "https://api.bigshopai.com/v1/inventory/parts-purchasing-report?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Errors

• 400 — {"error":"startDate and endDate are required (YYYY-MM-DD)"}.
• 403 — Forbidden. The caller's role lacks inventory:read (or parts:read).
• 500 — Unhandled server error: {"error":"Internal Server Error","message":"An unexpected error occurred"}.

Parts activity log (every stock movement and part edit in a period)

Answers: who changed inventory, when, and why? Lists quantity movements (purchases received, adjustments, reservations, usage on work orders and counter sales, returns) and part edit/create events over a date range, newest first, with KPI stats, filter facets and the same opening/closing inventory cards as the purchasing report. Pass groupBy to get subtotalled groups instead of rows (not paginated), or view=lifecycle to collapse each part's events per order. Dates are shop-local days (inclusive). All money is integer cents. Pagination is page/limit (not a cursor). Each source stream is read up to 5000 rows; when that cap is hit truncated is true and the list and stats are partial.

Parameters

curl "https://api.bigshopai.com/v1/inventory/parts-activities?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Errors

• 400 — {"error":"startDate and endDate are required (YYYY-MM-DD)"}.
• 403 — Forbidden. The caller's role lacks inventory:read (or parts:read).
• 500 — Unhandled server error: {"error":"Internal Server Error","message":"An unexpected error occurred"}.

Vendor accounts payable report (what the shop owes vendors)

Answers: how much does the shop owe its vendors, how overdue is it, and what was bought, returned and held in core deposits? One call returns vendor invoices with net-30 aging as of TODAY (shop-local), purchase orders, part returns, core-deposit lines and core write-offs. Computed live on every request from purchase orders, ad-hoc vendor invoices, vendors and core write-offs. A PO counts as an invoice only if it has a vendor invoice number. All money is integer cents. Lists are newest-first and cut at 5000 rows each; truncated is an ARRAY of the source names that hit a cap (empty = complete).

curl "https://api.bigshopai.com/v1/vendors/ap-report" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 403 — Forbidden. The caller's role lacks vendors:read.
• 500 — Unhandled server error: {"error":"Internal Server Error","message":"An unexpected error occurred"}.

A customer's open (unpaid) invoices

Answers: what does this customer currently owe, invoice by invoice? Lists the customer's invoiced work orders and counter sales that still have a balance, oldest first. Archived invoices that are still unpaid are included. Balances are computed from the Payments table (net of refunds), with declined services excluded, so they match what a statement would show. Money is returned twice: integer cents (*Cents, canonical) and dollar decimals (total, paid, balance). Dates for startDate/endDate are shop-local, compared against the invoice date (invoiced date, else created); invoices with no date are included. If the customer has more than 1500 open invoices only the 1500 most recent are evaluated and truncated is true; narrow with startDate/endDate. An unknown or other-shop customer id returns 200 with an empty list, not 404.

Parameters

curl "https://api.bigshopai.com/v1/customers/<customerId>/unpaid-invoices?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 403 — Forbidden. The caller's role lacks customers:read.
• 500 — {"error":"Failed to list unpaid invoices"}.

Statements created for a customer

Answers: what statements has the shop built for this customer and where do they stand? Each statement bundles several invoices; every read re-resolves the bundled invoices live (total, paid, balance and the payments applied), so numbers are current rather than as-created. Newest first. Money is returned as integer cents plus dollar twins (totalAmount, paidAmount, totalDue). status is recomputed to Paid when nothing is due or Partial when something was paid, otherwise the stored status (Draft when created). There is no pagination and no truncation flag. Payment rows include card brand/last4, check numbers and bank names.

Parameters

curl "https://api.bigshopai.com/v1/customers/<customerId>/statements" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 403 — Forbidden: lacks customers:read, or the role is explicitly denied customers:financials. Body is PERMISSION_DENIED.
• 404 — {"error":"Customer not found"} - unknown id OR a customer in another shop (cross-tenant reads return 404).
• 500 — {"error":"Failed to list statements"}.

List payments received (work orders and counter sales)

Answers: what money came in, and when? Returns payment records for the whole shop (work-order invoices and counter sales merged), optionally restricted to a date range. Amounts are integer cents. PAGING: cursor-based, but with cursor/nextCursor (opaque base64), NOT lastEvaluatedKey. To fetch everything in a period, pass startDate+endDate and keep passing the returned nextCursor until hasMore is false. limit is a minimum target rather than a hard maximum: pages stop at a database page boundary, so a page can return more than limit rows. The payment day used for the date filter is date, else paymentDate, else createdAt (shop-local when timezone is given, otherwise the UTC date prefix). Without a date range the rows are NOT the newest payments: work-order payments are stored under PAYMENT#<uuid>, so the first page is an arbitrary slice. Always pass a date range for reporting. Rows are the stored payment records, including payer details such as Zelle contact and check/bank details, and createdByName (the employee who recorded it).

Parameters

curl "https://api.bigshopai.com/v1/payments?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 403 — Forbidden. The caller's role lacks payments:read.
• 500 — {"error":"Internal Server Error"}.

List months that have shop financials

Answers: which months have overhead/expense and income bookkeeping, and what are their totals? Returns one record per month (newest first) with total expenses, total income, net, and entry counts. These are the shop-entered Shop Financials figures (rent, utilities, insurance, payroll as booked, etc.), not work-order revenue. All money is integer cents. Totals are stored on the month record and updated whenever an entry changes.

Parameters

curl "https://api.bigshopai.com/v1/shop-financials/months" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 401 — {"error":"Unauthorized"} when the tenant cannot be resolved from the authorizer context.
• 403 — {"error":"You do not have permission to view shop financials."} - NOTE this route does not use the PERMISSION_DENIED body.
• 500 — {"error":"Something went wrong loading shop financials."} (or Could not complete the accounting request. from the accounting router).

One month of shop financials with all expense and income lines

Answers: what overhead did the shop book in this month and what other income did it record? Returns the month record plus every expense line (vendor, category, amount, paid status, linked bank transaction), income line (with linked counter-sale status) and recorded payment/receipt transaction. These are shop-entered or bank-promoted entries - not derived from work orders. All money is integer cents. The month must be YYYY-MM; a month that was never created returns 404.

Parameters

curl "https://api.bigshopai.com/v1/shop-financials/months/<month>" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 401 — {"error":"Unauthorized"}.
• 403 — {"error":"You do not have permission to view shop financials."}.
• 404 — {"error":"Month not found"} (no such month for this shop) or {"error":"Shop Financials endpoint not found","details":{path,method}} (malformed month).
• 500 — {"error":"Something went wrong loading shop financials."}.

Per-technician completed labor hours, revenue and cost

Answers: how many labor hours did each technician complete in this period, what did that labor bill, and what did it cost the shop? Per technician: hours, labor revenue, jobs, hours per day and a line-by-line breakdown. LABOR ONLY (parts are not attributed to technicians). basis decides which date puts a labor line in the period: labor-completed (the day the line was completed) or invoiced (the day its work order was invoiced). The shop's own setting (Settings > Labor, billableHoursBasis) is the default; you may request either value via basis. Days are shop-local. EMPLOYEE PAY DATA: laborCostCents, commissionCents and breakdown[].costCents reveal what the shop pays each technician (hourly cost rate x hours; flat-weekly staff prorated) and their commission. The server removes these fields for callers without reports:profit or attendance:financials; API keys authenticate as admin and always receive them. All money is integer cents; hours are decimal. The read is capped at 5000 work orders; truncated: true means totals are partial.

Parameters

curl "https://api.bigshopai.com/v1/work-orders/technician-labor-summary?startDate=2026-10-01&endDate=2026-10-09" \
  -H "Authorization: ApiKey bsk_live_..."

Response fields (first 3 levels)

Errors

• 400 — {"error":"startDate and endDate are required (YYYY-MM-DD)"}.
• 403 — Forbidden. The caller's role lacks workorders:read / workorders:read-all.
• 500 — Unexpected server error: {"error":"Internal Server Error","message":"An unexpected error occurred"}.