ServiceTitan Sync Issues

ServiceTitan is the system of record for jobs and estimates once they leave YND OS — YND OS pushes data outbound to it. This page covers why a push can fail and the current known blocker.

Known, currently-blocked issue: "Door / slab" material

This is a known gap, not a new bug — if you hit it, you don't need to re-report the root cause, but you should still flag the specific job so it can be prioritized once a replacement SKU is mapped.

Where the mapping lives: /admin/servicetitan-mapping — this is where an admin maps YND OS material buckets to active ServiceTitan SKUs. This page is currently ungated (not restricted by role — see /help/permissions/known-gaps), so if you can see it and have context, you can check the current mapping, but only someone with ServiceTitan admin access should actually change it.

General troubleshooting steps for a failed sync

1. Identify what failed. Note the job/opportunity, which material bucket(s) it includes, and roughly when the push was attempted.
2. Check if it's the Door/slab issue. If the job includes a Door/slab item, that's very likely the cause — see above.
3. Check /admin/integrations/servicetitan. This is the ServiceTitan Integration admin page (visible to admin and executive) — it shows connection/integration status.
4. Check for other unmapped materials. The Door/slab SKU deletion is the known case, but any material bucket without an active mapped SKU will fail the same way. If a different bucket starts failing, treat it the same way: check /admin/servicetitan-mapping for a missing/inactive SKU.
5. Don't manually re-key the job directly in ServiceTitan as a workaround without checking with a manager first — YND OS is meant to be the source of truth going in, and manual edits on the ServiceTitan side can cause the two systems to disagree later.

What "pushed outbound" means for your day-to-day work

• Estimates and jobs are built and finalized in YND OS first.
• ServiceTitan sync failures don't block you from continuing to work the deal in YND OS — the opportunity, proposal, and payment flows are independent of whether the ServiceTitan push has succeeded.
• However, if the job can't reach ServiceTitan, downstream operations that rely on ServiceTitan (scheduling crews, invoicing through that system, etc.) will be affected. Flag it early rather than letting it surface later as a scheduling problem.

Escalation

If you hit a sync failure that isn't the known Door/slab issue, note the job ID/opportunity, the material involved, and the approximate time, and send it to an admin or manager who can check the integration page and mapping. Don't assume it's the same known issue without checking which material is involved.

Related

• /help/permissions/known-gaps
• /help/rollout/open-decisions

Appointment updates, rebooks and follow-up visits

Job creation was never the problem — updates were. Inbound ServiceTitan appointment events now flow through one processor, so the schedule you see in YND OS and on the bookings calendar tracks ServiceTitan.

What to expect now:

• A time change on the same visit updates the existing calendar event in place. You should not see the old time left behind. If you do, the appointment likely arrived without a schedule window — see below.
• A second visit on the same job (follow-up, return trip) shows up as its own row and its own calendar event, marked as a follow-up. Both remain visible on the customer's schedule.
• A technician reassignment updates the assignee shown on the schedule and in the calendar event description.
• A cancellation cancels the calendar event but keeps the record for history. Nothing is deleted silently.
• Duplicate deliveries of the same webhook are recognized and do not double-book the calendar.
• Photos attached in ServiceTitan now arrive through the main webhook, not only the integration relay, and land on the customer's photos.

If a time or assignee looks stale

1. Open Admin → Integrations → ServiceTitan and check the Appointment sync log. Every event shows the old → new time, the assignee applied, the result, and what happened to the calendar event.
2. A row with result skipped always names a reason. The common ones:
   • missing schedule window — the event arrived with no start time, so no calendar change was made on purpose.
   • missing appointment id — the event could not be tied to a specific visit. This is logged rather than guessed at, so nothing gets overwritten.
3. If the log shows the change was applied but the calendar still looks wrong, the calendar connection is the thing to check, not the ServiceTitan mapping.

Rescheduling or cancelling an appointment inside YND OS also queues that change back to ServiceTitan. It does not block you: if the push can't go out immediately it stays queued and is retried.