Check Options

Purpose

Given a set of service variants and a location, returns which variants have no coverage there and the different ways of grouping the covered ones into bundles: groups of variants that a single provider can execute together, in the same visit.

Use it as the first step of a bundled booking: pick one grouping option, then use POST /api/integration/bundle/dates and POST /api/integration/bundle/times with the variants of each group to find when that group can be scheduled.

Each variant can carry its quantity and its addons. They extend the duration of the visit exactly as they do when the booking is created, so the grouping that checks providers' agendas accounts for the real duration of each group.

Variants are returned identified the same way they were requested (by id or by SKU), so the response can be matched directly against the request.

Field Definitions

🔐 Authentication

🧩 Service variants

🏠 Location

When both are sent, addressId is used.

📅 Search range and grouping

Example Request

{
  "variants": [
    {
      "type": "variantSku",
      "value": "SKU-INSTALLATION",
      "quantity": 2,
      "addons": [
        { "type": "addonReference", "value": "ADDON-EXTRA-HOSE", "quantity": 1 }
      ]
    },
    { "type": "variantSku", "value": "SKU-MAINTENANCE" },
    { "type": "variantId", "value": "52" },
    { "type": "variantId", "value": "63", "quantity": 2 }
  ],
  "addressId": 17,
  "startDate": "2026-10-05",
  "quantityOfDays": 14,
  "groupingMode": "all_maximal_by_agenda"
}

Minimal request, by coordinates and with the default grouping mode:

{
  "variants": [
    { "type": "variantId", "value": "32" },
    { "type": "variantId", "value": "33" }
  ],
  "coordinates": { "lat": -33.42, "lng": -70.6 }
}

Response Example

201 Created

{
  "serviceVariantsWithoutCoverage": [],
  "groupingOptions": [
    [
      [
        { "type": "variantSku", "value": "SKU-INSTALLATION" },
        { "type": "variantSku", "value": "SKU-MAINTENANCE" },
        { "type": "variantId", "value": "63" }
      ],
      [
        { "type": "variantId", "value": "52" }
      ]
    ]
  ]
}

Response Fields

Error Responses

Business Rules & Constraints

Coverage

A variant has coverage at the location when at least one provider executes it there. Variants without coverage are listed in serviceVariantsWithoutCoverage and never appear in groupingOptions. Every covered variant appears exactly once in every option.

Grouping modes

Each group is checked on its own: two groups of the same option may rely on the same provider on the same day.

Duration of a group

Each variant counts as one visit of variant duration × quantity, plus addon duration × addon quantity for each of its addons, the same duration the booking gets when it is created. A group needs the sum of the durations of its variants. Higher quantities or more addons can therefore split variants that would otherwise be grouped together.

Identification

• A variant can be identified by id or by SKU, and both can be mixed in the same request.

• If two entries identify the same variant (for example its id and its SKU), the first one is used and the variant is evaluated once.

• Variants and addons are always returned with the same type and value sent in the request.

Addons

Each addon must be offered for its variant and must be offered at the location. Otherwise the request is rejected (see Error Responses); addons are never silently ignored.

Scope

Availability is computed for bookings without origin address, without products with a promised delivery date and with automatic provider assignment. When the booking is created with any of them, the travel time from the origin, the delivery date of the products or the chosen provider may change which groups are actually feasible.