Example Integrations

1. Website appointment booking

Scopes: shop.read, customers.read, customers.write, vehicles.read, vehicles.write, appointments.read, appointments.write.

1. Show availability: GET /v1/appointments/availability?date=2026-09-14 returns the shop's open slots for that day, already respecting hours, closures, and capacity.
2. Find or create the customer: GET /v1/customers?phone=4165550123; if empty, POST /v1/customers with an Idempotency-Key derived from your form submission id.
3. Find or create the vehicle: GET /v1/vehicles?customer=cus_…&plate=ABCD123, else POST /v1/vehicles.
4. Book: POST /v1/appointments (Idempotency-Key required) with customer_id, vehicle_id, date, time, duration_minutes, reason, and the customer's concern in notes. A 409 with shop_hours or technician_capacity blockers means the slot went away — re-fetch availability and offer another.
5. Stay in sync: subscribe to appointment.status_changed so your confirmation page reflects a shop-side reschedule or cancellation.

2. Custom shop dashboard

Scopes: shop.read, repair_orders.read, appointments.read, technicians.read, invoices.read.

• Open work: GET /v1/repair-orders?state=in_progress&limit=200 — each order carries one stable state, promised_at, assigned technician ids, and pricing when pricing.read is granted.
• Today's board: GET /v1/appointments?scheduled_date_from=<today>&scheduled_date_to=<today> (use the shop's timezone from GET /v1/shop to compute "today").
• Names for technician_ids: GET /v1/technicians.
• Revenue posted today: GET /v1/invoices?business_date_from=<today>&business_date_to=<today> and sum total — posted documents are immutable, so the numbers reconcile.
• Live updates: subscribe to repair_order.status_changed, job.status_changed, appointment.*, invoice.posted, then GET the changed object and patch your view. Fall back to an updated_after crawl every few minutes.

3. Accounting export

Scopes: invoices.read, payments.read, customers.read.

• On invoice.posted, GET /v1/invoices/{id}: the document carries typed lines (service, fee, discount, …) with gross_amount, discount_alloc, tax_alloc, line_total, per-rate tax components, and the customer/vehicle references. Line totals sum to the header to the cent by construction.
• On credit_note.issued, the credit note references its original invoice — book it as a dated correction, never as an edit.
• On payment.recorded / payment.reversed, GET /v1/payments/{id}: payments form a signed ledger; a reversal is a negative payment linked by reversal_of, so summing amounts over a period reconciles to the bank.
• Nightly, crawl GET /v1/invoices?business_date_from=…&business_date_to=… and GET /v1/payments?business_date_from=…&business_date_to=… to catch anything a webhook missed.
• Attach your ledger ids with external references so re-runs are idempotent.

More patterns

Fleet maintenance sync (unit_number filter + external ids + repair_order.* events), CRM two-way sync (updated_after crawls + customer.*/vehicle.* events + expected_version on writes), tire-shop websites (GET /v1/inventory-items?tire_size=225/65R17&in_stock=true), and warranty-to-task automation (tasks.write) all compose from the same primitives. The AI-agent guide condenses the rules a coding agent needs to build any of them.