Orders

How orders work, the workflow steps they run through, and the actors that complete them

Overview

Orders are the central entity in Installer.com. An order represents a service request, typically an installation, inspection, or maintenance job, that needs to be dispatched to an installer and tracked through completion.

What makes an order more than a record is its workflow. Every order runs on a configurable workflow that defines the steps it goes through and the data each step collects. The workflow, not a fixed status field, is what drives the order forward. Configuring that workflow once and letting every order follow it, with installer selection, booking, offers, and payment as first-class steps, is the core of the platform.

An order always belongs to an organization (router) and references a workflow template that its steps are created from.

How an order progresses

A workflow template is an ordered set of steps. Steps can depend on earlier steps, so an order advances as each step is completed and unlocks the next. Rather than a single linear status, the order's state is the combined state of its steps.

Each step is completed by its actor, the party responsible for it:

Operator: the routing organisation running the order, working in the Routing App.
Installer / contractor: the assigned contractor organisation, working in the contractor app.
End customer: answers questions, accepts the offer, and pays in the client portal (my.installer.com).
Automation: a background event or auto-dispatch completing a step without a human, driven by the platform or an external system.

A step produces data when it transitions (an assigned installer, a booked date, a captured payment, uploaded photos). Those transitions are also the webhook and background-event integration points.

Common steps

An operator builds a workflow from the step types below, which are the options in the Add step menu in the Routing App. These are what you configure and reorder; they are not API values you send.

Step	What happens	Who completes it
Select Installer	Select an installer from your network and get their confirmation	Operator or automation, then installer
Booking	Schedule a date, get the customer's confirmation, and complete the booking on-site	Operator, customer, and installer
Offer	Create an offer with products and pricing, and get the customer's approval	Operator or automation, then customer
Payment	Collect payment for the accepted offer	End customer
Documentation	Upload relevant files, images, text, or videos	Installer or operator
Rate experience	Collect feedback and ratings for the completed work	End customer
Standard step	A custom step with your own actions and descriptions	Configurable
Select upcoming steps	Branch between different paths to continue the workflow	Configurable

Steps like Booking, Offer, and Payment expand into a few sub-steps (schedule, confirm, complete). Not every order has every step, and a template can include several steps of the same kind.

Creating an order

Create an order with the Create Order endpoint, referencing the workflow template it should run on. At minimum you provide the customer contact details, the installation address, and the workflow reference.

Most of the data a workflow needs is collected as the order moves through its steps, so you don't have to supply it upfront. If your own system already holds some of it (custom field answers, a chosen installer, a priced offer), you can prefill it at creation to skip or speed up the corresponding step. See:

Quick Start for the minimal end-to-end flow.
Creating Orders for the full request, including every prefill option and what is required versus optional.

Once created, the order needs to reach an installer. That fulfils the workflow's Select Installer step, and it normally happens inside the platform, either manually by the operator or automatically via auto-dispatch, so no API call is required. When your own system owns the decision, two API options fulfil the same step:

Pre-assign at creation: include actorAssignments in the Create Order request to name the installer upfront. See Creating Orders.
Dispatch afterwards: call the Dispatch Order endpoint to route an order that already exists, for example once your system decides who should take it.

Both are optional. If you use neither, the order waits at the Select Installer step for the operator or auto-dispatch to route it.

Tracking progress

Because an order's state is its steps' states, you track it by subscribing to step transitions rather than polling a status field. Configure webhooks on the steps you care about to receive state changes as they happen, or use background events for steps that wait on an external system. See Integrating with External Systems for the full model.

Managing orders

Cancel: cancel an order at any point with the Cancel Order endpoint.
Files: attach photos, documents, and surveys with the Upload File endpoint. The response includes a file ID you reference from other API calls, from file custom fields, and from outbound payloads. See Creating Orders for how file IDs wire into custom field answers.
Tags: organize orders for filtering with List, Create, Assign, and Remove tag endpoints.

All v1 API endpoints require a Bearer token for authentication. See the API Reference for full request/response schemas and to try endpoints directly.