Start Maintenance Plan

Purpose

Starts the maintenance cycle of a product unit the customer already owns.

Use it right after registering the equipment with Add New Product Unit, or on any existing unit that is not under an active cycle yet. Sodtrack creates one execution (cycle) per maintenance plan that matches the unit's product and the execution variant you send, and schedules the first maintenance date for each one.

The unit is identified by productUnitId or productSerialNumber, and the service to be executed by variantId or variantSku. The first maintenance date is either the startDate you send or, when omitted, today plus the offset configured in the plan's rule.

This endpoint does not create a booking: it opens the cycle and sets the due date. The visit is created later by a daily job, once the due date is close enough (see From cycle to booking).

Field Definitions

🔧 Product unit

Prefer productUnitId. A serial number is only unique within a product, so a serial shared by units of different products is rejected as ambiguous rather than resolved at random.

🛠️ Execution variant

The variant is resolved in Sodtrack before the cycle is created, and it also selects which plans and which rule apply. Only plans holding a rule for this exact variant are started.

📅 Schedule

Example Request (by unit id and variant id)

{
  "productUnit": {
    "type": "productUnitId",
    "value": "9871"
  },
  "executionVariant": {
    "type": "variantId",
    "value": "412"
  }
}

Example Request (by serial number and SKU, with explicit date)

{
  "productUnit": {
    "type": "productSerialNumber",
    "value": "7788001122336"
  },
  "executionVariant": {
    "type": "variantSku",
    "value": "SKU-VAR-MANT-001"
  },
  "startDate": "2026-10-01"
}

Response Example

200 OK

{
  "productUnit": {
    "id": 9871,
    "serialNumber": "7788001122336"
  },
  "executions": [
    {
      "id": 5540,
      "plan": {
        "id": 31,
        "name": "Mantenimiento semestral piscina"
      },
      "status": "PENDING",
      "executionDate": "2026-10-01T00:00:00.000Z"
    }
  ]
}

Response Fields

Error Responses

A 4xx means nothing was created and the request must be corrected. A 502 means the call can be retried as-is.

Business Rules & Constraints

Plan matching

• Plans are matched by the unit's product and the execution variant sent in the request. A plan for the same product but a different variant is not started.

• One execution is created per matching plan. Two plans covering the same product produce two cycles and two future visits.

• Within a plan, the rule applied is the one whose execution variant matches the request. When a self-perpetuating plan holds two such rules, the starting rule is used, not the one anchored to itself.

First maintenance date

• When startDate is sent, it is used as the due date of the first maintenance as-is.

• When startDate is omitted, the due date is today plus the rule's offset, converted to days: DAYS as-is, WEEKS × 7, MONTHS × 30, YEARS × 365. Months and years are therefore approximations in days, not calendar months.

• The cycle is always created with status PENDING.

From cycle to booking

• A daily job runs at 11:00 and scans cycles in PENDING status.

• A booking is created when executionDate minus the configured anticipation window (MAINTENANCE_PLAN_EXECUTION_ANTICIPATION_DAYS) is on or before today. With the window at 0, the booking is created the day the maintenance is due.

• The booking is built with the unit's current customer and address, read at that moment — not with the ones the unit had when the cycle started. If the unit moves in between, the visit follows it.

• A cycle with no executionDate is skipped by the job.

One open cycle at a time

• A unit cannot have two open cycles for the same execution variant. If one is PENDING or IN_PROGRESS, the request is rejected with MAINTENANCE_PLAN_EXECUTION_ALREADY_IN_PROGRESS.

• This endpoint does not close the previous cycle: unlike the flow triggered when a booking is completed, no service was executed here to justify closing it. Close or cancel the open cycle first.

• The same unit can hold cycles for different execution variants at the same time.

Unit identification

• productSerialNumber resolves only among units of type product, and must match exactly one unit across all products.

• Only units that already exist are accepted. To register equipment first, use Add New Product Unit.

Variant SKU availability

• Resolution by variantSku depends on the variant having its SKU loaded in Sodtrack. Most service variants currently have none, so variantId is the reliable selector unless the SKU was confirmed for your catalog.

Data and format

• All identifiers are sent as strings inside the { type, value } selectors, even when they are numeric IDs.

• All timestamps follow the ISO 8601 format (UTC) where applicable.