Fleet operators API

Partner fleets: fleets, vehicles, branches, webhooks, bots and autonomous delivery units.

Root types are FleetOperatorQuery and FleetOperatorMutation.

Start with Authentication.

Profile and settings

profile returns the authenticated vendor's profile; settings returns the settings blob. Both are read-only through this API.

Fleets

A fleet groups vehicles and the drivers who operate them.

Cursor-paginated, with search matching free text across name, email and phone. fleet(fleetId:) fetches one and may return null — handle it.

Drivers and vehicles are assigned independently — a driver is not bound to a specific vehicle by the fleet model. Every one of these mutations checks that the fleet belongs to your business before it does anything.

Vehicles

Your vehicle inventory. A vehicle exists whether or not it is in a fleet; assigning it to one is a separate step.

Cursor-paginated, filterable by search, vehicleTypeId, vehicleCategory, isActive and verified. vehicle(vehicleId:) fetches one and may return null.

verified is set by the platform during review, not by you — filter on it, do not try to write it.

Coupons

Discount codes that run on your own storefront.

vendorCoupons lists only the coupons your vendor owns. Platform coupons your storefront happens to qualify for are not included, and cannot be changed here.

A code is unique across the whole platform, not just your storefront, so createVendorCoupon rejects a code another vendor already uses.

discount is a percentage when percentage is true and a fixed amount otherwise, and it can never be negative. maxCouponAmount caps a percentage discount and is ignored for a fixed one. minOrderAmount is in your currency. All three are Decimal — a string on the wire.

productIds and vendorLocationIds narrow where the coupon applies; an empty list means all of your products, or all of your locations. On updateVendorCoupon either list replaces the existing restriction outright, and an empty list clears it. times caps redemptions across all customers. expiresOn is UTC; omit it for a coupon that never expires.

Reviews and performance

Read-only figures on how your business is doing.

The two analytics queries need vendors:analytics:read; vendorReviews needs vendors:reviews:read. See Authentication.

Sales analytics

period and date are plain Strings, not enums, so a typo is not caught by query validation.

For a single day, pass date — YYYY-MM-DD or an RFC 3339 timestamp — together with a period that is none of the four names. An unknown period without a usable date is rejected rather than widened to all time. Passing date on its own does not work: period then defaults to month, and date is ignored.

Your timezone is that of your location with the lowest ID, or UTC if you have no locations.

In topProducts, up to ten products are ranked by revenue. In trends:

• dailySales has one entry per day that saw a counted order, in date order. Days without one are skipped, and entries carry no date, so the series is not continuous.
• growthRate is the percentage change against the preceding window of the same length. It reads 0 when that window sold nothing.
• peakHours holds up to three hours of the day (0–23, your timezone), busiest first.

Performance metrics

vendorPerformanceMetrics takes no arguments, and its order figures cover the last 30 days. orderAcceptanceRate and deliverySuccessRate are percentages, 0–100.

avgPreparationTime is the average number of minutes from order creation to delivery, across delivered orders. Despite the name, it is not preparation time.

customerSatisfaction is your average star rating out of 5. It is averaged over all of your reviews, not only the last 30 days.

Every figure reads 0 both when there is nothing to measure and when it could not be worked out, so a 0 is not proof of a real zero.

Reviews

vendorReviews returns your most recent reviews first. limit defaults to 20 and is capped at 100; the response's limit echoes the value applied. There is no pagination, so reviews past the cap cannot be reached. ratingFilter keeps a single star rating, 1 to 5, and any other value is rejected.

A review's date is YYYY-MM-DD HH:MM:SS in UTC, not RFC 3339. orderId is 0 when the review is not tied to an order, and comment is empty when the customer left a rating without words.

Locations

Your branches.

Cursor-paginated. location(locationId:) fetches one. createLocation, updateLocation and deleteLocation manage them; delete returns true.

To stop trading at a branch temporarily, deactivate via updateLocation rather than deleting — deletion loses the association with historical records.

Webhooks

The alternative to polling. There are no GraphQL subscriptions, and polling for unit and fleet changes every few seconds will exhaust your rate limit.

webhooks(first:, after:) lists them. webhook(webhookId:) fetches one. updateWebhook and deleteWebhook manage them; set isActive: false to pause without losing configuration.

events is the WebhookEvent enum, so a typo is now a query validation error rather than a subscription that silently never fires.

The enum spelling and the wire spelling differ. On the wire an event is dot-separated — ORDER_CREATED is delivered as order.created — and that is what the X-Kesk-Event header carries, what the payload's eventType key holds, and what is stored against the subscription. The underscored form exists only because a GraphQL enum value cannot contain a dot. Match on the header value you actually receive rather than deriving it from the enum name.

Verifying deliveries

The body is the event's fields plus an eventType key naming the event.

Sign the raw bytes. Parsing the JSON and re-stringifying it changes key order or whitespace, and every valid delivery will fail.

Deliveries time out after 10 seconds and are attempted at most 3 times, retrying 30 seconds after the first failure and 5 minutes after the second. A non-2xx response, a timeout and a transport error all count as failures. Redirects are not followed — point the webhook at its final URL.

Return 2xx as soon as you have durably accepted the event, then process asynchronously. Be idempotent — retries mean you will see events more than once.

Every attempt is recorded with its request body, response status and failure reason. Response bodies are not retained.

Getting the signing secret

The same mutation rotates the secret later. The value is stored hashed and cannot be retrieved again.

Bots

Automations registered against your account.

BotType: WEBHOOK, SCRIPTED, AI_POWERED. BotStatus: ACTIVE, INACTIVE, SUSPENDED, PENDING_REVIEW.

Autonomous units

Drones and ground robots you own and provision for delivery.

Cursor-paginated. unit(id:) fetches one. Besides status and verificationStatus, units filters on isActive, isDispatchable, hasCredential, an exact serialNo, and maxBatteryPct for units at or below a charge level.

registerUnit registers a unit, owned by the vendor your token acts for — the input has no owner field. Nor does it take an operating area: that is set by an administrator, and updateUnit cannot change it either. Verification status is not settable; units start unverified and are moved through review by the platform.

setUnitStatus reports operational state, restricted to states an owner may legitimately report. ASSIGNED, ENROUTE and RETURNING follow from dispatch and DISABLED is an administrative act, so none of them is settable by you.

isDispatchable says whether a unit can be sent on a job right now: in service, verified, and in a state that accepts work. Use it rather than deriving your own check from battery and verification fields.

Machine credentials

The credential's scopes are the same fixed set on every unit: units:telemetry:write, units:jobs:read, units:jobs:write and units:status:write. Provisioning grants all four — there is nothing to narrow and nothing to choose. A unit cannot read your catalogue or touch orders.

These are absent from the issuer's scopes_supported on purpose: that document advertises what a developer application may request, and no application can ask for a units:* scope. The hardware need not send them either — a unit that leaves scope out of its token request is granted all four.

Reference

Generated reference — every type, field and argument, built from the live schema.