Taxis API

Ride dispatch: rides, branches, webhooks and bots.

https://api.kesk.app/v1/taxis/graphql

Root types are TaxiQuery and TaxiMutation.

Start with Authentication.

Profile and settings

query {
  profile { id name isActive isOpen }
  settings { ... }
}

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

Rides

Rides use the orders / order queries, progressed with ride-specific mutations.

query {
  orders(first: 50, status: PREPARING) {
    nodes { id status }
    pageInfo { hasNextPage endCursor }
  }
}

A ride reaches you already accepted by one of your drivers, so there is no accept step: the ride's order is created at that moment, in PREPARING.

Mutation	Effect
`markRideEnroute(orderId:)`	The rider is on board: `PREPARING` → `ENROUTE`
`completeRide(orderId:)`	Ride finished: `ENROUTE` → `COMPLETED`
`cancelRide(orderId:)`	Cancel a ride before it is under way

If a driver hands a ride back before pickup, its order moves to REASSIGNED and the ride goes back to finding another driver. The rider never sees an order in that state.

As of 2026-09-17 the backend accepts cancelRide only for an order in PENDING or ACCEPTED, but a ride's order is created in PREPARING. Expect the call to be rejected, and handle the error rather than assuming the ride was cancelled. Tracked in backend#909.

PaymentStatus is tracked separately: PENDING, REQUEST, REVIEW, FAILED, CANCELLED, SUCCESSFUL, CAPTURE_FAILED, REFUNDED. Do not infer a ride's payment state from its order status, or the reverse.

Coupons

Discount codes that run on your own storefront.

mutation {
  createVendorCoupon(input: {
    code: "WELCOME10"
    color: "#FF5733"
    discount: "10"
    percentage: true
    maxCouponAmount: "5.00"
    forDelivery: false
    isActive: true
  }) { id code discount percentage expiresOn }
}

Operation	Notes
`vendorCoupons(activeOnly:)`	The coupons you own. Not paginated
`createVendorCoupon(input:)`	The code must be unique across the platform
`updateVendorCoupon(couponId:, input:)`	Change a coupon you own
`deleteVendorCoupon(couponId:)`	Delete a coupon you own

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.

The three coupon mutations need vendors:promotions:write, which a coarse vendors grant does not include. Request it by name — see Authentication.

Reviews and performance

Read-only figures on how your business is doing.

query {
  vendorSalesAnalytics(period: "week") {
    analytics {
      totalSales
      orderCount
      avgOrderValue
      topProducts { id name salesCount revenue }
      trends { dailySales growthRate peakHours }
    }
  }
  vendorPerformanceMetrics {
    metrics {
      orderAcceptanceRate
      deliverySuccessRate
      avgPreparationTime
      customerSatisfaction
    }
  }
  vendorReviews(limit: 20, ratingFilter: 1) {
    reviews { id rating comment customerName date orderId }
  }
}

Operation	Notes
`vendorSalesAnalytics(period:, date:)`	Sales, top products and trends for a window
`vendorPerformanceMetrics`	Acceptance, delivery success, timing and rating
`vendorReviews(limit:, ratingFilter:)`	Most recent reviews first

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.

`period`	Window
`today`	From midnight in your timezone until now
`week`	The last 7 days, ending now
`month`	The last 30 days, ending now. The default
`year`	The last 365 days, ending now
Any other value	The single day named by `date`, in your timezone

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.

Sales figures count only orders whose status is DELIVERED, by when they were placed. An order in any other status — COMPLETED included — is left out. A window is read up to 10,000 orders, and past that the figures understate. Verified against the backend source as of 2026-09-17; tracked in backend#909.

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.

query {
  locations(first: 50, activeOnly: true) {
    nodes { id name isActive }
    pageInfo { hasNextPage endCursor }
  }
}

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 new rides every few seconds will exhaust your rate limit.

mutation {
  createWebhook(input: {
    url: "https://example.com/hooks/kesk"
    events: [ORDER_CREATED, ORDER_UPDATED]
    isActive: true
  }) { id url events isActive }
}

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.

Group	Values
Orders	`ORDER_CREATED`, `ORDER_UPDATED`, `ORDER_ASSIGNED`, `ORDER_CANCELLED`, `ORDER_COMPLETED`
Bookings	`BOOKING_CREATED`, `BOOKING_CONFIRMED`, `BOOKING_CANCELLED`, `BOOKING_COMPLETED`
Payments	`PAYMENT_RECEIVED`, `PAYMENT_REFUNDED`
Catalogue and customers	`PRODUCT_LOW_STOCK`, `REVIEW_CREATED`, `CUSTOMER_MESSAGE`
Autonomous units	`UNIT_REGISTERED`, `UNIT_VERIFIED`, `UNIT_ASSIGNED`, `UNIT_STATUS_CHANGED`, `UNIT_DELIVERY_COMPLETED`, `UNIT_MAINTENANCE_REQUIRED`, `UNIT_TELEMETRY_ALERT`

The enum lists values this vertical will never emit. Subscribing to one is accepted and simply 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

Header	Contents
`X-Kesk-Signature`	`HMAC-SHA256(secret, raw_request_body)`, lowercase hex, no prefix
`X-Kesk-Event`	The event's wire name, e.g. `order.created`

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

const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret)
    .update(rawBody)              // RAW bytes, exactly as received
    .digest("hex");
  const a = Buffer.from(signature, "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

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.

When a delivery exhausts its three attempts the webhook is disabled — isActive flips to false and it stops receiving events entirely until you re-enable it. An endpoint that is down long enough does not just miss those deliveries; it stops being a webhook. Monitor isActive.

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

Getting the signing secret

createWebhook does not return a signing secret. Call regenerateWebhookSecret(webhookId:) once after registering to obtain it — that is the only time it is shown. Until you do, you have a webhook whose deliveries you cannot verify.

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.

query {
  bots(first: 50, status: ACTIVE) {
    nodes {
      id
      identity { displayName username }
      statusFlags { status }
      botType
    }
    pageInfo { hasNextPage endCursor }
  }
}

Operation	Notes
`createBot`	Permissions, version and tags are not editable afterwards
`updateBot`	Cannot change permissions, version or tags
`deleteBot`	Permanent
`testBotWebhook(botId:)`	Queue a test delivery to a `WEBHOOK` bot
`regenerateBotSecret(botId:)`	Rotate, returns the new secret
`botAnalytics(botId:, days:)`	Totals, webhook health, daily series. `days` defaults to 7, max 90

Reference

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

Services API authentication Taxis API authentication

Built with