FleetBridge Order Source Integration

Everything an external Order Source engineering team needs to integrate with FleetBridge, in one offline-usable, self-contained page — authentication, order lifecycle, webhooks, signature verification, idempotency, errors, and certification.

API major: v1 Contract revision: 1.1.0 No external dependencies Works offline

Overview

API major: v1 Contract revision: 1.1.0 Audience: engineering teams at POS systems, restaurant platforms, e-commerce systems, ordering applications, marketplaces, and ERP/order-management systems that create delivery orders through FleetBridge (an "Order Source").

This document describes the public Order Source API as it actually behaves. Every field name, header, status code, and behavior below comes straight from the running FleetBridge implementation, not a design doc someone wrote before the code existed. If something genuinely isn't built yet (a fixed per-key rate limit, for instance), we say so plainly instead of pretending it's there.

1. Integration model

Order Source ──HTTP request───► FleetBridge Order API
Order Source ◄──HTTPS webhook── FleetBridge (delivery status / tracking events)

FleetBridge sits between your system and one or more Delivery Providers. You never talk to a Delivery Provider directly, you never hold its credentials, and you never see its webhook format. Here's the flow:

  1. Create an order with FleetBridge.
  2. FleetBridge resolves a branch and dispatches a Delivery Provider, failing over to another one automatically if needed (before pickup only), and manages the delivery from there.
  3. FleetBridge sends you webhooks as the delivery progresses.
  4. You update or cancel the order through FleetBridge, not through the Delivery Provider.
  5. You always correlate on the identifiers FleetBridge gives you back. Not on the identity of whichever Delivery Provider happens to be handling the order at a given moment — that can change.

A few things this API deliberately doesn't do. There's no quotes or pricing endpoint; FleetBridge doesn't calculate delivery pricing or shop it across providers. There's no items[] concept anywhere in the contract, because FleetBridge orchestrates the delivery, not what's inside the order. And PaymentMethod is just order metadata passed through to the Delivery Provider — FleetBridge never settles or reconciles COD funds.

2. Authentication

2.1 Header

Every request is authenticated with a single header:

X-Api-Key: key_<64 lowercase hex characters>

The header must be present exactly once, with a non-empty value. There's no Authorization: Bearer scheme for Order Source calls — that one's reserved for FleetBridge's own dashboard users.

2.2 Key format

A raw key is always key_ followed by 64 lowercase hexadecimal characters (68 characters total), for example:

key_9f2c1a7b3e5d8046a1c2b3d4e5f60718293a4b5c6d7e8f9012345678abcdef0

FleetBridge generates the key and shows it to you exactly once, at creation time, in the tenant dashboard. It can't be redisplayed after that — FleetBridge only keeps a short, non-secret prefix (the first 12 characters, e.g. key_9f2c1a7b) for identification purposes. Lose it and it's gone for good; issue a new one and revoke the old one (Section 2.4).

There's no separate test/sandbox key format. A key authenticates against whatever FleetBridge environment (Base URL) it was issued for — see Section 20. Don't look for a _test_ / _live_ naming convention in the key itself, because there isn't one.

2.3 What the key identifies

A key belongs to exactly one Order Source inside exactly one Tenant. You never send a tenant ID or Order Source ID anywhere in the request — FleetBridge resolves both from the key itself. Your externalOrderId only needs to be unique within your Order Source, not across the whole tenant. A different Order Source under the same tenant can reuse the same externalOrderId for a completely unrelated order and FleetBridge keeps them apart without any extra effort on your part.

Every order, cancellation, update, and read you perform is scoped to what your own Order Source created. Try to read or modify an order that belongs to a different Order Source, even one under the same tenant, and you'll get 404 ORDER_NOT_FOUND — FleetBridge won't confirm or deny that such an order exists for someone else.

2.4 Rotation and revocation

Unlike webhook secrets (Section 9.10, which support rotation with an overlap window), there's no in-place "rotate" for an Order Source API key. To rotate one without downtime:

  1. Ask FleetBridge (through your tenant's dashboard user) to issue a new key for your Order Source. Multiple keys can be active for the same Order Source at once for exactly this reason.
  2. Deploy the new key to your systems.
  3. Ask FleetBridge to revoke the old key once you've confirmed the new one is working.

A revoked or expired key fails authentication immediately (Section 2.5). Both creation and revocation get recorded in FleetBridge's audit log.

2.5 Authentication failures

Two different failure layers here, with two different response shapes. Getting this distinction right matters for building correct error handling.

(a) The key itself is missing, malformed, unknown, revoked, or expired. This fails inside FleetBridge's authentication layer before your request ever reaches business logic. You get back:

HTTP/1.1 401 Unauthorized

with an empty body — not a JSON error object. Don't try to parse one from a 401 here.

(b) The key is valid, but your Order Source or Tenant can't currently accept orders (disabled Order Source, suspended tenant). This is a business-rule rejection that happens *after* authentication succeeds, so it comes back through FleetBridge's standard error envelope (Section 16):

{
  "status": 403,
  "title": "Forbidden",
  "detail": "This order source is disabled.",
  "errorCode": "ORDER_SOURCE_DISABLED",
  "correlationId": "0HNOOIIC1J8FA:00000001"
}
errorCodeHTTP statusMeaning
TENANT_SUSPENDED403The tenant is not currently accepting new orders.
ORDER_SOURCE_DISABLED403Your Order Source has been deactivated.
INVALID_API_KEY403The authenticated caller is not a valid Order Source context for this operation (should not occur in normal use of a correctly issued key).

2.6 What not to log

Never log the raw X-Api-Key header value, the raw webhook signing secret (Section 9), or full request bodies that carry customer phone numbers and addresses into whatever log retention policy you run. If you need to identify which credential made a call, log the key prefix (first 12 characters) instead — that part isn't sensitive.

3. Base URL and environments

We don't publish one fixed public hostname in this document, because your Base URL gets issued during onboarding and activation and is specific to your deployment. You'll receive:

  • A staging Base URL and staging API key during development/certification.
  • A production Base URL and production API key at activation.

Every example here uses the placeholder:

https://<fleetbridge-host>

Swap in the actual Base URL you were given. The paths themselves (/api/v1/orders, etc.) are real and literal — only the host is a stand-in.

All endpoints are versioned under /api/v1. Section 21 covers the versioning and backward-compatibility policy if you want the details now.

4. Quick start

  1. Get your X-Api-Key and Base URL from FleetBridge during onboarding.
  2. Register a webhook callback URL and grab your webhook signing secret (Section 9) — you'll want this before relying on lifecycle updates, though it's not required just to create a test order.
  3. Create an order (Section 7). Store the platformOrderId you get back.
  4. Poll GET /api/v1/orders/{platformOrderId}/status once, or just wait for your first webhook, to watch the order move past PendingRouting.
  5. Implement webhook signature verification (Section 10) so you can actually trust the events you're receiving.
  6. Wire up Update and Cancel (Sections 11–12) for whichever parts of your own order lifecycle need them.
  7. Reconcile: if you're ever unsure whether a Create request actually went through (timeout, no response), replay the exact same request with the same Idempotency-Key. Read Section 13 before you build any retry logic — the behavior here isn't what you'd guess.

First request, end to end

curl -X POST "https://<fleetbridge-host>/api/v1/orders" \
  -H "X-Api-Key: key_9f2c1a7b3e5d8046a1c2b3d4e5f60718293a4b5c6d7e8f9012345678abcdef0" \
  -H "Idempotency-Key: order-1001-create-1" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderId": "ORD-1001",
    "branchId": null,
    "externalBranchId": "MAIN-BRANCH",
    "deliveryProviderCode": null,
    "scheduledDeliveryAt": null,
    "pickup": {
      "address": "Ramallah Branch, Al-Manara St.",
      "lat": 31.9021,
      "lng": 35.2034
    },
    "dropoff": {
      "customerName": "Ahmed Khalil",
      "customerPhone": "+970590000000",
      "customerEmail": null,
      "address": "Al-Tireh, Ramallah",
      "lat": 31.9102,
      "lng": 35.2111
    },
    "payment": {
      "method": "Cash",
      "methodRaw": "cash_on_delivery",
      "amount": 85.00,
      "deliveryFee": 10.00,
      "currency": "ILS"
    },
    "preparationTimeMinutes": 15,
    "notes": "Call before arrival"
  }'

Response:

HTTP/1.1 201 Created
Location: /api/v1/orders/6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c
Content-Type: application/json
{
  "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "externalOrderId": "ORD-1001",
  "externalOrderNumber": "ORD-1001",
  "status": "PendingRouting",
  "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "routingMode": "PriorityFailover",
  "createdAt": "2026-09-22T13:00:00Z"
}

Store platformOrderId. Every subsequent call — Update, Cancel, GetById, GetStatus, GetTracking, GetTrackingHistory — uses it as a path parameter. externalOrderId comes back unchanged too, and you can use it to look the order up later (Section 12.4), scoped to your own Order Source. externalOrderNumber echoes your display number, or externalOrderId when you didn't send one (Section 7.1).

5. Every endpoint — summary

All paths are relative to your Base URL. All are under /api/v1.

MethodPathPurpose
POST/api/v1/ordersCreate an order
PATCH/api/v1/orders/{platformOrderId}Update mutable order business data
GET/api/v1/orders/{platformOrderId}Get full order detail
GET/api/v1/orders/by-external-id/{externalOrderId}Look up an order by your own reference
GET/api/v1/orders/{platformOrderId}/statusGet current order + delivery status
GET/api/v1/orders/{platformOrderId}/trackingGet current driver/tracking snapshot
GET/api/v1/orders/{platformOrderId}/tracking-historyGet the full tracking event timeline
POST/api/v1/orders/{platformOrderId}/cancelCancel an order
POST/api/v1/webhooks/testSend a test webhook to your own registered endpoint

All nine of these, webhook test included, require the X-Api-Key header (Section 2) and operate only on orders (or webhook endpoints) belonging to your own Order Source.

A few endpoints exist on this API but aren't available to an Order Source key — listed here just so you don't go looking for them: order search/listing, manual provider dispatch, return resolution, webhook endpoint management (create/rotate/subscribe), and Order Source or API key management. Those need a FleetBridge dashboard user session, so they're out of scope for this document.

6. Common conventions

  • Request and response bodies are application/json, fields in camelCase.
  • Enum values are always JSON strings ("Cash", not 0). An unrecognized enum string gets rejected as a validation error — it won't silently coerce to something else.
  • Any timestamp you send (scheduledDeliveryAt) needs ISO 8601 with an explicit UTC offset (2026-09-01T18:30:00+03:00 or ...Z). Leave the offset off and it's rejected. Everything FleetBridge sends back is UTC, suffixed Z.
  • GUIDs (platformOrderId, branchId, etc.) are lowercase, hyphenated UUID strings.
  • Unknown or extra JSON properties in a request get silently ignored, not rejected. Don't rely on that to smuggle data through — it's just how the underlying JSON binding happens to work.

7. Create Order

POST /api/v1/orders

Optional header: Idempotency-Key (Section 13). We'd strongly recommend sending it on every Create call — without it, a network-level retry looks identical to a second, separate order.

7.1 Request fields

FieldTypeRequiredNotes
externalOrderIdstring, ≤200 charsYesYour own technical order identifier: the correlation, lookup, and de-dup key. Unique within your Order Source (Section 2.3).
externalOrderNumberstring, ≤200 charsNoYour human-readable order number (for example the number printed on the receipt). Shown to operators and sent to the Delivery Provider as its visible order reference. Display only: not unique, never used for correlation, lookup, de-duplication, or idempotency. Omitted or blank means FleetBridge uses externalOrderId. Set at create only.
branchIdGUIDNoFleetBridge branch ID, if known. See Section 19 for resolution priority.
externalBranchIdstringNoYour own branch/store code, if you don't track FleetBridge branch GUIDs.
deliveryProviderCodestringNoRequest a specific Delivery Provider by code. See Section 15.
scheduledDeliveryAtISO 8601 datetime w/ offsetNoOmit or null for an immediate (ASAP) order. See Section 14.
pickup.addressstring, ≤500 charsYesFree-text pickup address (display/reference only — resolution uses coordinates/branch).
pickup.latnumberYes−90..90.
pickup.lngnumberYes−180..180.
dropoff.customerNamestring, ≤200 charsYes
dropoff.customerPhonestring, ≤50 charsYes
dropoff.customerEmailstring, ≤320 charsNo
dropoff.addressstring, ≤500 charsYes
dropoff.latnumberYes−90..90.
dropoff.lngnumberYes−180..180.
payment.methodenumYesOne of Cash, Card, Online, Wallet, Other. See Section 17.
payment.methodRawstring, ≤100 charsNoYour own original payment-method label, preserved alongside the normalized method.
payment.amountdecimalYes≥0, at most 2 decimal places, at most 9,999,999,999.99. The order total.
payment.deliveryFeedecimalNoSame range/precision rules as amount. Informational only — never used in routing or provider selection.
payment.currencystring, exactly ≤3 charsYese.g. ILS, USD. Normalized to uppercase.
preparationTimeMinutesintegerYes≥0. No enforced upper bound.
notesstring, ≤2000 charsNo

One gotcha: if a required value-type field (lat, lng, amount, preparationTimeMinutes, payment.method) is missing from the JSON entirely, FleetBridge treats that exactly like an explicit required-and-missing field — it gets rejected, not quietly defaulted to zero. Send these explicitly, every time.

7.2 Minimal valid Create

{
  "externalOrderId": "ORD-2002",
  "externalBranchId": "MAIN-BRANCH",
  "pickup": { "address": "Main Branch", "lat": 31.9021, "lng": 35.2034 },
  "dropoff": {
    "customerName": "Sara Ahmad",
    "customerPhone": "+970599111222",
    "address": "Al-Bireh",
    "lat": 31.9075,
    "lng": 35.2160
  },
  "payment": { "method": "Cash", "amount": 42.5, "currency": "ILS" },
  "preparationTimeMinutes": 10
}

7.3 Full Create (every optional field populated)

{
  "externalOrderId": "ORD-2003",
  "externalOrderNumber": "1042",
  "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "externalBranchId": null,
  "deliveryProviderCode": "cervo",
  "scheduledDeliveryAt": "2026-09-22T18:30:00+03:00",
  "pickup": { "address": "Downtown Branch", "lat": 31.9021, "lng": 35.2034 },
  "dropoff": {
    "customerName": "Ahmed Khalil",
    "customerPhone": "+970590000000",
    "customerEmail": "ahmed@example.com",
    "address": "Al-Tireh, Ramallah, Building 12",
    "lat": 31.9102,
    "lng": 35.2111
  },
  "payment": {
    "method": "Card",
    "methodRaw": "visa_online",
    "amount": 120.00,
    "deliveryFee": 12.00,
    "currency": "ILS"
  },
  "preparationTimeMinutes": 20,
  "notes": "Leave at the door, ring the bell twice"
}

7.4 Response — 201 Created

{
  "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "externalOrderId": "ORD-2003",
  "externalOrderNumber": "1042",
  "status": "Scheduled",
  "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "routingMode": "PriorityFailover",
  "createdAt": "2026-09-22T13:05:00Z"
}

The Location header comes back set to /api/v1/orders/{platformOrderId}. status is the order's first computed status: Scheduled if scheduledDeliveryAt was in the future, otherwise PendingRouting (Section 14). routingMode (DefaultOnly | ManualProvider | PriorityFailover | BroadcastToAll) comes from your tenant/branch configuration — it's not something you ask for per order. A deliveryProviderCode override (Section 15) changes which provider gets targeted, not the routing mode itself.

7.5 Errors specific to Create

errorCodeStatusCause
BRANCH_NOT_FOUND404branchId/externalBranchId didn't resolve to an active branch, and no active branch matches the pickup coordinates either.
INVALID_PICKUP_LOCATION400pickup.lat/pickup.lng out of range.
INVALID_DROPOFF_LOCATION400dropoff.lat/dropoff.lng out of range.
INVALID_AMOUNT400payment.amount or payment.deliveryFee negative.
STRUCTURAL_LIMIT_EXCEEDED400A string field exceeded its max length, or an amount had more than 2 decimal places / exceeded the numeric cap.
INVALID_PREPARATION_TIME400preparationTimeMinutes negative.
INVALID_PAYMENT_METHOD400payment.method was not a recognized enum value.
INVALID_SCHEDULED_TIME400scheduledDeliveryAt less than the minimum lead time in the future. See Section 14.
PROVIDER_NOT_ENABLED400deliveryProviderCode unknown or not enabled for your tenant.
MANUAL_OVERRIDE_NOT_ALLOWED400deliveryProviderCode supplied but manual provider selection is not permitted for this branch/tenant, or the requested provider isn't eligible right now.
TENANT_SUSPENDED / ORDER_SOURCE_DISABLED403See Section 2.5.
RATE_LIMIT_EXCEEDED429See Section 22.

8. Order status, delivery status, and tracking

8.1 Two lifecycles, not one

FleetBridge keeps order status (your business view) and delivery status (the physical delivery view) separate. They're related, but not the same thing, and you should show/store both.

  • OrderStatus — the field you see as status/orderStatus — is your order's business lifecycle. FleetBridge derives it automatically from the order's attempts and shipment; you never set it directly. It moves in response to routing, provider events, cancellation, and operator actions.
  • UnifiedDeliveryStatus — nested as delivery.status/delivery.unifiedStatus — is the physical delivery, once one exists. It stays null/absent until a Delivery Provider has actually been sent the order.

8.2 OrderStatus values

ValueMeaningTerminal?Can you still Update/Cancel?
CreatedMomentary internal state immediately before the order is first persisted. You will never observe this value from any GET call — by the time an order is readable, it has already moved to Scheduled or PendingRouting.No—
ScheduledscheduledDeliveryAt is in the future; dispatch has not started.NoYes
PendingRoutingWaiting for the routing engine to select/dispatch a provider.NoYes
DispatchingOne or more delivery attempts are in flight — sent, awaiting acceptance, or failing over to the next provider.NoUpdate yes; Cancel yes (immediate, platform-side).
InDeliveryA Delivery Provider has accepted and the delivery is actively progressing (accepted through on-the-way).NoUpdate yes; Cancel only if the provider supports cancellation at the current stage (Section 12).
CancellationRequestedYou (or an operator) requested cancellation; FleetBridge is waiting for the Delivery Provider to confirm.NoA repeat Cancel call is safe (Section 12.3).
ReturnInProgressThe delivery failed after pickup; a return-to-branch flow is active. See Section 18.NoRead-only from your side; no self-service action.
DeliveredFinal: delivered to the customer.YesNo — 409 ORDER_ALREADY_FINAL.
CancelledFinal: cancellation confirmed.YesNo.
FailedFinal: the delivery failed terminally, including "returned to origin" outcomes.YesNo.
NoProviderAvailableHeld: every eligible provider was exhausted during automatic routing; a FleetBridge operator must intervene.NoUpdate yes; Cancel yes.
ManualReviewRequiredHeld: a failure needs operator attention (failed cancellation, failed return, correlation problem).NoUpdate yes; Cancel yes.

Only Delivered, Cancelled, and Failed are truly final. The two "held" statuses (NoProviderAvailable, ManualReviewRequired) can resume automatically once a FleetBridge operator steps in, so don't treat them as final in your own state machine — and keep expecting webhooks for orders sitting in either state.

8.3 UnifiedDeliveryStatus values (the delivery.status field)

ValueMeaning
SentToProviderSent to a Delivery Provider, awaiting acceptance.
ProviderAcceptedThe Delivery Provider accepted the delivery.
DriverAssignedA driver has been assigned.
ArrivedAtPickupThe driver has arrived at the branch.
PickedUpThe driver has collected the order.
OnTheWayThe order is en route to the customer.
DeliveredFinal: delivered.
CancelledFinal: cancelled.
FailedFinal: failed (not a return case).
ReturnRequestedPost-pickup failure; a return has been initiated.
ReturningToOriginGoods are on the way back to the branch.
ReturnedToOriginFinal: goods are back at the branch (order-level status becomes Failed).
ReturnFailedThe return itself could not be completed; requires operator resolution (order-level status becomes ManualReviewRequired).

8.4 Lifecycle diagram

                         ┌───────────┐
                         │ Scheduled │  (only if scheduledDeliveryAt is in the future)
                         └─────┬─────┘
                               │ dispatch time reached
                               ▼
 ┌────────────────┐    ┌────────────────┐    ┌─────────────┐    ┌────────────┐
 │ PendingRouting  │───►│  Dispatching   │───►│ InDelivery  │───►│ Delivered  │  (final)
 └────────────────┘    │ (attempts/     │    │ (accepted → │    └────────────┘
                        │  failover)     │    │  on the way)│
                        └───────┬────────┘    └──────┬──────┘
                                │                     │
                    all providers exhausted     failure after pickup
                                │                     │
                                ▼                     ▼
                    ┌────────────────────┐   ┌──────────────────┐
                    │ NoProviderAvailable │   │ ReturnInProgress │
                    │      (held)         │   └────────┬─────────┘
                    └─────────────────────┘            │
                                                         ▼
                                                  ┌────────────┐
                                                  │   Failed    │  (final; includes
                                                  └────────────┘   "returned to origin")

           Cancellation, from any non-final status, at any point above:
           Dispatching/PendingRouting/Scheduled → Cancelled directly (platform-side)
           InDelivery (before pickup, if supported) → CancellationRequested → Cancelled
           InDelivery (after pickup, if supported)  → CancellationRequested → Cancelled

           Any unexpected failure needing a human → ManualReviewRequired (held)

Treat this as an orientation aid, not the literal implementation. OrderStatus gets recomputed from scratch on every relevant event — it's not a fixed adjacency list you could hard-code — so the exact transitions you see depend on your tenant's routing configuration and whatever the Delivery Provider itself supports. For what's actually authoritative, go back to the table in 8.2 (terminal vs. held vs. active).

8.5 Get order status

GET /api/v1/orders/{platformOrderId}/status
{
  "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "orderStatus": "InDelivery",
  "delivery": {
    "shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "platformReference": "att_18c9a4f2b3c1a2b3c4d5e6f708192a3b",
    "deliveryProviderId": "5e9ca8a5-0c61-4312-ba14-cf9546aea68a",
    "providerCode": "cervo",
    "unifiedStatus": "DriverAssigned",
    "slaStatus": "OnTrack"
  }
}

delivery stays null until a Delivery Provider has actually been sent the order — so while orderStatus is still Scheduled or PendingRouting, expect it to be empty. slaStatus is one of OnTrack, AtRisk, Breached, CompletedWithinSla, CompletedBreached, NotApplicable.

GET /api/v1/orders/{platformOrderId} (full detail) gives you everything above plus your original business fields: customer, addresses, payment, notes, and the createdAt/deliveredAt/cancelledAt/failedAt timestamps.

8.6 Get tracking

GET /api/v1/orders/{platformOrderId}/tracking
{
  "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "unifiedStatus": "OnTheWay",
  "driverName": "Mohammed",
  "driverPhone": "0590000000",
  "driverLat": 31.9038,
  "driverLng": 35.2034,
  "driverLocationUpdatedAt": "2026-09-22T13:40:00Z",
  "trackingUrl": "https://tracking.example.com/abc",
  "currentEta": "2026-09-22T14:05:00Z"
}

Every field here is nullable. You'll see null when there's no shipment yet, or simply because the current Delivery Provider doesn't supply that signal — not every provider sends live driver coordinates, a tracking URL, or an ETA. Presence is provider-dependent; don't count on it universally.

8.7 Get full tracking history

GET /api/v1/orders/{platformOrderId}/tracking-history

Returns every recorded tracking/status event for the order's shipment, oldest first, as a plain array (empty, not an error, if no shipment exists yet):

[
  {
    "eventTimeUtc": "2026-09-22T13:28:54Z",
    "receivedAtUtc": "2026-09-22T13:28:55Z",
    "status": "ArrivedAtPickup",
    "providerStatus": "arrived_at_store",
    "source": "Webhook",
    "driverName": "Mohammed",
    "driverPhone": "0590000000",
    "driverLat": 31.9038,
    "driverLng": 35.2034,
    "estimatedDeliveryAtUtc": "2026-09-22T14:05:00Z",
    "providerCorrelationId": "DLV-9001"
  }
]

status is always a UnifiedDeliveryStatus value (Section 8.3), the normalized, provider-agnostic status. providerStatus and providerCorrelationId are different — they're opaque, best-effort diagnostic text straight from the Delivery Provider's own raw event. Useful for support and debugging, but not a stable contract: exact values differ per provider and per integration, and FleetBridge makes no promises about their format. Build your business logic against status, never against providerStatus. source is one of Webhook, Polling, Platform (FleetBridge's own administrative actions).

9. Webhooks — FleetBridge → you

9.1 Direction

This section flips the direction: FleetBridge is calling your server now, not the other way around like everything in Sections 7 and 8:

Order Source ◄──HTTPS POST── FleetBridge   (this section)
Order Source ──HTTPS POST──► FleetBridge   (Sections 7, 8, 11, 12)

9.2 How your callback URL is configured

FleetBridge registers your webhook callback URL and signing secret for you (through your tenant's dashboard user) as part of onboarding. An Order Source API key can't create or modify its own webhook endpoint registration. You get the secret once, at registration time — capture it right then, because FleetBridge can't show it to you again later. Rotating it is possible (Section 9.10); redisplaying the old one isn't.

You can, though, trigger a one-off test delivery to your own registered endpoint with your API key:

POST /api/v1/webhooks/test

This fires a webhook.test event (Section 9.9) at your registered URL, signed exactly like any real event, so you can check connectivity and signature verification before going live.

9.3 Delivery mechanics

Every webhook is an HTTP POST with Content-Type: application/json to your registered URL. A 2xx counts as acknowledged. Anything else — non-2xx, timeout, connection failure — counts as a failure and gets retried per the schedule below. FleetBridge waits 15 seconds for your response, so respond fast and push any slow processing to the background on your side.

9.4 Retry schedule

If your endpoint doesn't return 2xx, FleetBridge retries up to 5 times after the initial attempt (6 attempts total), at increasing delays:

attempt 1 (immediate) → fail
  +1 minute  → attempt 2
  +5 minutes → attempt 3
  +15 minutes → attempt 4
  +1 hour     → attempt 5
  +3 hours    → attempt 6 → still failing → delivery marked Exhausted, no further automatic retry

Each attempt's number rides along in the X-Platform-Retry-Count header (0 on the first try). An Exhausted delivery isn't gone forever — a FleetBridge operator can still resend it manually. It's just done retrying on its own.

9.5 At-least-once delivery — you must deduplicate

FleetBridge's webhook delivery is at-least-once, not exactly-once, and not guaranteed in-order. In rare recovery scenarios the same logical event can land on your server twice, and two different events for the same order can arrive out of order relative to each other — a fast retry of an older event racing a newer event's first attempt, for example. So your webhook handler needs to be:

  • Idempotent: dedupe on the eventId field (it's also in the X-Platform-Event-Id header). Processing the same eventId twice should have zero additional effect the second time.
  • Order-tolerant: use eventTime, or for delivery-status events the delivery.status value itself against whatever you last recorded, to decide if an incoming event is actually newer than what you already have. Don't assume events arrive in the order they happened.

9.6 Headers on every webhook request

POST /your/callback/url HTTP/1.1
Content-Type: application/json
X-Platform-Event-Id: evt_9f1c2b3a4d5e6f708192a3b4c5d6e7f8
X-Platform-Timestamp: 2026-09-22T13:20:00Z
X-Platform-Signature: sha256=1a2b3c4d5e6f...
X-Platform-Retry-Count: 0
X-Platform-Api-Version: v1

Section 10 (Webhook Security) covers exactly how X-Platform-Signature gets computed and how to verify it. Don't skip it before going to production.

FleetBridge doesn't enforce a server-side replay window — no built-in expiry on how old a valid signature can be. If your security posture needs old or replayed requests rejected, that's on you to build: an X-Platform-Timestamp freshness check (rejecting anything older than, say, 5 minutes) as part of your own verification code. The worked examples in Section 10.5 show how.

9.7 Event catalog

Event typeFires when
order.createdThe order was created inside FleetBridge.
order.updatedOrder business data was changed via Update (Section 11); includes per-field propagation results.
delivery.provider_assignedA Delivery Provider was selected for this dispatch round.
delivery.sent_to_providerThe order was actually sent to that provider.
delivery.acceptedThe provider accepted the delivery.
driver.assignedA driver was assigned.
driver.location_updatedDriver coordinates changed.
tracking.updatedThe tracking URL changed.
delivery.arrived_at_pickupThe driver arrived at the branch.
delivery.picked_upThe driver collected the order.
delivery.on_the_wayThe order is en route.
eta.updatedThe estimated delivery time changed.
sla.at_riskThe order is at risk of breaching its configured SLA.
sla.breachedThe order breached its configured SLA.
delivery.deliveredThe order was delivered.
order.cancellation_requestedA cancellation was accepted into the workflow; provider confirmation is pending.
delivery.cancelledThe delivery was cancelled and confirmed.
order.cancellation_failedA provider-side cancellation attempt failed; the order needs manual attention.
delivery.failedThe delivery failed terminally (not a return case).
delivery.return_requestedA post-pickup failure triggered a return.
delivery.returning_to_originGoods are on the way back to the branch.
delivery.returned_to_originGoods are back at the branch.
delivery.return_failedThe return itself could not be completed.
provider.failedThe current provider failed and FleetBridge is trying the next eligible one (see Section 15.3).
order.no_provider_availableEvery eligible provider was exhausted.
order.manual_review_requiredThe order needs FleetBridge operator attention.
webhook.testA manually triggered connectivity test (Section 9.2) — different payload shape, see 9.9.

You don't need to subscribe to every event type. Subscriptions are configured per callback URL by FleetBridge on your behalf during onboarding — just tell them which ones you want.

9.8 Standard payload shape

Every event except webhook.test (9.9) uses this shape. Sections that don't apply to a given event are null — for example driver/tracking/eta are all null on an order.created event, since no shipment exists yet.

{
  "eventId": "evt_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
  "eventType": "delivery.accepted",
  "eventTime": "2026-09-22T13:20:00Z",
  "apiVersion": "v1",
  "tenantId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "orderSource": { "id": "8a1b2c3d-4e5f-4a3b-8c2d-1e0f9a8b7c6d", "code": "qr_menu", "name": "QR Menu" },
  "order": {
    "platformOrderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
    "externalOrderId": "ORD-2003",
    "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
    "orderStatus": "InDelivery"
  },
  "delivery": {
    "shipmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "platformReference": "att_18c9a4f2b3c1a2b3c4d5e6f708192a3b",
    "providerCode": "cervo",
    "providerDeliveryId": "DLV-9001",
    "status": "ProviderAccepted"
  },
  "driver": null,
  "tracking": null,
  "eta": null,
  "sla": { "isAtRisk": false, "isBreached": false, "breachedStages": [] },
  "failure": null,
  "routing": null,
  "updatePropagation": null
}

Field reference:

PathTypeNotes
eventIdstringGlobally unique. Your deduplication key.
eventTypestringOne of Section 9.7.
eventTimeISO 8601 UTCWhen FleetBridge recorded the event.
apiVersionstringAlways "v1" today.
tenantIdGUIDYour tenant.
orderSource.{id,code,name}Always your own Order Source.
order.platformOrderIdGUIDMatches what Create returned.
order.orderStatusstringOrderStatus value, Section 8.2.
delivery.statusstringUnifiedDeliveryStatus value, Section 8.3. delivery itself is null before dispatch.
delivery.platformReferencestringAn internal correlation id, format att_<hex>. Not the same as providerDeliveryId.
delivery.providerDeliveryIdstring, nullableThe Delivery Provider's own id for this delivery, when the provider exposes one.
driver.{name,phone,lat,lng}null until a driver is assigned; individual fields may still be null afterward depending on the provider.
tracking.trackingUrlstring, nullableProvider-hosted tracking page, when the provider supplies one.
eta.estimatedDeliveryAt / remainingMinutes / confidenceBest-effort; not every provider supplies an ETA.
sla.{isAtRisk,isBreached,breachedStages}Reflects your tenant's configured SLA thresholds.
failure.{reasonCode,reasonText,rawProviderReason}Populated on provider.failed/delivery.failed/cancellation-failure events.
routing.{nextAction,nextProviderCode}Populated on provider.failed — see Section 15.3.
updatePropagation.fieldsobjectPopulated only on order.updated — mirrors the per-field propagation result from the Update response (Section 11).

9.9 webhook.test payload (different shape)

{
  "eventId": "evt_test_1a2b3c4d5e6f7081",
  "eventType": "webhook.test",
  "eventTime": "2026-09-22T13:00:00Z",
  "apiVersion": "v1",
  "tenantId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "orderSourceId": "8a1b2c3d-4e5f-4a3b-8c2d-1e0f9a8b7c6d",
  "message": "This is a test event from FleetBridge to verify your webhook endpoint is reachable and correctly signed."
}

webhook.test is intentionally flat, with no order/delivery/orderSource nested objects. If your handler assumes every event has the full Section 9.8 shape, it'll break on this one — check eventType first and branch your parsing from there.

9.10 Secret rotation

If FleetBridge rotates your webhook signing secret, you get a 24-hour overlap window where both the old and new secret are valid. During that window, X-Platform-Signature carries both signatures, comma-separated, newest first:

X-Platform-Signature: sha256=<hex-with-new-secret>,sha256=<hex-with-old-secret>

Your verification code needs to accept the request if any of the comma-separated values matches what you compute. Don't assume there's exactly one value in this header.

10. Webhook signature verification

Don't skip this section. An unverified webhook is just a POST request from the internet with no authentication behind it.

10.1 What is signed

The signing input is the concatenation, in this exact order, of four values, with no delimiter between them:

signingInput = apiVersion + timestamp + eventId + rawRequestBody
  • apiVersion — the literal string v1, always.
  • timestamp — the exact string value of the X-Platform-Timestamp header (not a re-formatted version of it).
  • eventId — the exact string value of the X-Platform-Event-Id header.
  • rawRequestBody — the exact raw bytes of the HTTP request body, before any JSON parsing — see 10.4 for why this matters.

10.2 Which secret

Your per-endpoint webhook signing secret, handed to you once at registration. Format is whsec_ followed by 64 lowercase hex characters — structurally similar to your X-Api-Key, but a different credential. Never send it to FleetBridge or anyone else. It's used only locally, by you, to verify.

10.3 Algorithm

HMAC-SHA256 over the UTF-8 bytes of signingInput, keyed by the UTF-8 bytes of your secret, hex-encoded in lowercase. The header value is prefixed sha256=:

X-Platform-Signature: sha256=<64 lowercase hex characters>

(During a secret-rotation overlap window, the header may contain two comma-separated sha256=... values — see Section 9.10.)

10.4 Why you must use the raw body

FleetBridge signs the exact bytes it sent — not a value derived from re-serializing the parsed JSON. Here's the trap: most web frameworks parse the JSON body before your signature-verification code even runs. If you then re-serialize that parsed object to build your comparison string, key ordering, whitespace, or number formatting can drift just enough to produce a different byte sequence — and a signature "mismatch" that has nothing to do with an actual security problem. Capture and verify against the raw, unparsed body bytes, before or independent of JSON parsing, no matter which language you're in.

10.5 Verification steps (all languages)

  1. Read the raw request body as bytes (or a string, using the same encoding your framework received it in — UTF-8) before any JSON deserialization.
  2. Read the X-Platform-Timestamp, X-Platform-Event-Id, and X-Platform-Signature headers.
  3. (Optional, recommended) Check that X-Platform-Timestamp is within your own acceptable freshness window (Section 9.6 — FleetBridge does not enforce one for you).
  4. Build signingInput = "v1" + timestamp + eventId + rawBody.
  5. Compute HMAC-SHA256(secret, signingInput), hex-encode it in lowercase.
  6. Split X-Platform-Signature on commas. For each candidate value, strip the sha256= prefix and compare it to your computed value using a constant-time comparison (never ==/.equals on secret-derived strings) — accept if any candidate matches.
  7. Only after verification succeeds, parse the body as JSON and process the event.

10.6 C#

using System.Security.Cryptography;
using System.Text;

public static bool VerifyFleetBridgeWebhook(
    string rawBody, string timestamp, string eventId, string signatureHeader, string secret)
{
    var signingInput = "v1" + timestamp + eventId + rawBody;
    var computedBytes = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(signingInput));
    var computedHex = Convert.ToHexString(computedBytes).ToLowerInvariant();

    foreach (var candidate in signatureHeader.Split(','))
    {
        var trimmed = candidate.Trim();
        if (!trimmed.StartsWith("sha256=", StringComparison.Ordinal))
        {
            continue;
        }

        var presentedHex = trimmed["sha256=".Length..];
        var presentedBytes = Encoding.UTF8.GetBytes(presentedHex);
        var computedHexBytes = Encoding.UTF8.GetBytes(computedHex);
        if (presentedBytes.Length == computedHexBytes.Length &&
            CryptographicOperations.FixedTimeEquals(presentedBytes, computedHexBytes))
        {
            return true;
        }
    }

    return false;
}

// ASP.NET Core minimal API example — read the RAW body before model binding:
app.MapPost("/fleetbridge/webhooks", async (HttpRequest request) =>
{
    request.EnableBuffering();
    using var reader = new StreamReader(request.Body, Encoding.UTF8, leaveOpen: true);
    var rawBody = await reader.ReadToEndAsync();
    request.Body.Position = 0;

    var timestamp = request.Headers["X-Platform-Timestamp"].ToString();
    var eventId = request.Headers["X-Platform-Event-Id"].ToString();
    var signature = request.Headers["X-Platform-Signature"].ToString();

    if (!VerifyFleetBridgeWebhook(rawBody, timestamp, eventId, signature, YourStoredSecret))
    {
        return Results.Unauthorized();
    }

    // Only now parse rawBody as JSON and process the event, deduplicating on eventId.
    return Results.Ok();
});

10.7 JavaScript (Node.js)

const crypto = require("crypto");

function verifyFleetBridgeWebhook(rawBody, timestamp, eventId, signatureHeader, secret) {
  const signingInput = "v1" + timestamp + eventId + rawBody;
  const computedHex = crypto.createHmac("sha256", secret).update(signingInput, "utf8").digest("hex");

  return signatureHeader.split(",").some((candidate) => {
    const trimmed = candidate.trim();
    if (!trimmed.startsWith("sha256=")) return false;
    const presentedHex = trimmed.slice("sha256=".length);
    const presented = Buffer.from(presentedHex, "utf8");
    const computed = Buffer.from(computedHex, "utf8");
    return presented.length === computed.length && crypto.timingSafeEqual(presented, computed);
  });
}

// Express example — you MUST capture the raw body before express.json() parses it.
const express = require("express");
const app = express();

app.use(
  "/fleetbridge/webhooks",
  express.raw({ type: "application/json" }), // gives req.body as a Buffer, unparsed
);

app.post("/fleetbridge/webhooks", (req, res) => {
  const rawBody = req.body.toString("utf8");
  const timestamp = req.header("X-Platform-Timestamp");
  const eventId = req.header("X-Platform-Event-Id");
  const signature = req.header("X-Platform-Signature");

  if (!verifyFleetBridgeWebhook(rawBody, timestamp, eventId, signature, process.env.FLEETBRIDGE_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }

  const event = JSON.parse(rawBody);
  // Deduplicate on event.eventId, then process.
  res.status(200).end();
});

10.8 Python

import hashlib
import hmac


def verify_fleetbridge_webhook(raw_body: bytes, timestamp: str, event_id: str, signature_header: str, secret: str) -> bool:
    signing_input = ("v1" + timestamp + event_id).encode("utf-8") + raw_body
    computed_hex = hmac.new(secret.encode("utf-8"), signing_input, hashlib.sha256).hexdigest()

    for candidate in signature_header.split(","):
        candidate = candidate.strip()
        if not candidate.startswith("sha256="):
            continue
        presented_hex = candidate[len("sha256="):]
        if hmac.compare_digest(presented_hex, computed_hex):
            return True
    return False


# Flask example — request.get_data() returns the raw, unparsed body.
from flask import Flask, request, abort

app = Flask(__name__)


@app.route("/fleetbridge/webhooks", methods=["POST"])
def fleetbridge_webhook():
    raw_body = request.get_data()  # bytes, raw — read before request.get_json()
    timestamp = request.headers.get("X-Platform-Timestamp", "")
    event_id = request.headers.get("X-Platform-Event-Id", "")
    signature = request.headers.get("X-Platform-Signature", "")

    if not verify_fleetbridge_webhook(raw_body, timestamp, event_id, signature, FLEETBRIDGE_WEBHOOK_SECRET):
        abort(401)

    event = request.get_json()
    # Deduplicate on event["eventId"], then process.
    return "", 200

11. Update Order

PATCH /api/v1/orders/{platformOrderId}

11.1 Partial-update semantics — read this before building your client

The request body only ever describes the fields you want to change. There are three distinct states for every field:

  1. Omit the field from the JSON body entirely → left unchanged.
  2. Send the field with an explicit null (only meaningful for fields that are nullable, like customerEmail or notes) → clears it.
  3. Send the field with a value → sets it to that value.

This means {} is a valid (no-op) request body, and you must not send a field just because your own internal object happens to have that property populated — only send what actually changed.

11.2 Mutable fields

FieldNotes
customerName
customerPhone
customerEmailNullable — send null to clear.
dropoff.addressIndependent of dropoff.lat/dropoff.lng — patching one doesn't reset the others.
dropoff.lat / dropoff.lng
notesNullable.
paymentMethod
paymentMethodRawNullable.
amount
deliveryFeeNullable.
currencyRe-normalized to uppercase; a same-currency different-casing PATCH is treated as a no-op.
preparationTimeMinutes
scheduledDeliveryAtNullable; see restriction below.

11.3 Immutable fields

externalOrderId, externalOrderNumber, branchId/pickup location, and the routing/provider selection fields can't be changed through Update — send them anyway and they're just silently ignored, since they're not even part of the request schema. Need a different branch? Cancel and recreate the order. Need a different provider? That happens through cancellation too, never through Update.

11.4 Example: Request → Success

{
  "customerPhone": "+970590000111",
  "notes": "Leave with the neighbor if no answer",
  "amount": 92.00
}
HTTP/1.1 200 OK
{
  "orderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "addressPropagation": "NotApplicable",
  "phonePropagation": "Propagated",
  "scheduledDeliveryPropagation": "NotApplicable",
  "notesPropagation": "Propagated",
  "customerNamePropagation": "NotApplicable",
  "customerEmailPropagation": "NotApplicable",
  "amountPropagation": "Propagated",
  "currencyPropagation": "NotApplicable",
  "paymentMethodPropagation": "NotApplicable",
  "deliveryFeePropagation": "NotApplicable",
  "preparationTimePropagation": "NotApplicable"
}

FleetBridge always saves your update on its own side first, whether or not the active Delivery Provider can accept the change. The response then tells you, field by field, what happened when FleetBridge tried to forward that specific change to whoever's handling the delivery right now:

ValueMeaning
PropagatedSuccessfully forwarded to the Delivery Provider.
NotSupportedByProviderThe current provider's integration doesn't support changing this field once a delivery is in flight. Your change is saved in FleetBridge, but the provider (and its driver) may not see it.
PropagationFailedFleetBridge tried to forward the change and the provider call failed (transient/technical). Your change is still saved in FleetBridge.
NotApplicableThis field wasn't part of your request, or there is no active shipment yet to propagate to.

A NotSupportedByProvider or PropagationFailed result isn't an HTTP error by itself — the update succeeded from FleetBridge's point of view. But if a field's real-world propagation matters to you (a changed dropoff address after the driver's already en route, say), check that specific field in the response and handle a non-Propagated result in your own UI or ops process. FleetBridge won't escalate it to an operator on your behalf.

11.5 Updating never changes order status

Update never pushes orderStatus/delivery.status forward or back. Change a customer's phone number on an order that's DriverAssigned and it stays DriverAssigned — it can't slip back to PendingRouting, and it can't jump ahead either. Lifecycle transitions only happen through routing, Delivery Provider events, Cancel, and FleetBridge's own operator workflows.

11.6 Scheduled-delivery-specific restriction

You can change scheduledDeliveryAt only while the shipment hasn't progressed past ProviderAccepted — unless the current Delivery Provider explicitly supports updating a scheduled time after acceptance. Otherwise you'll get 400 PROVIDER_UPDATE_NOT_SUPPORTED.

11.7 Invalid update example

{ "amount": -5 }
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "'amount' must not be negative.",
  "errorCode": "INVALID_AMOUNT",
  "correlationId": "0HNOOIIC1J8FA:00000002"
}

11.8 When Update is rejected outright

errorCodeStatusCause
ORDER_ALREADY_FINAL409The order is Delivered, Cancelled, or Failed.
PROVIDER_UPDATE_NOT_SUPPORTED400scheduledDeliveryAt change rejected per Section 11.6.
(validation errors)400Same field-length/amount/payment-method rules as Create, Section 7.5, applied to the merged (post-patch) values.

12. Cancel Order

POST /api/v1/orders/{platformOrderId}/cancel

Optional body:

{ "reason": "customer_requested" }

reason is a free-text string, ≤500 characters, entirely optional. Skip the body altogether if you've got nothing to say.

12.1 Behavior by stage

Order / delivery stageWhat happens
Created, Scheduled, PendingRouting — nothing dispatched yetCancelled immediately, platform-side. No call to any Delivery Provider. outcome: "Cancelled".
Dispatching — sent to a provider, not yet acceptedOpen delivery attempts are cancelled; FleetBridge notifies the provider best-effort. Order becomes Cancelled immediately once no attempt remains active. outcome: "Cancelled".
InDelivery, before pickup (ProviderAccepted / DriverAssigned / ArrivedAtPickup)Allowed only if the current Delivery Provider supports cancellation before pickup. If not supported: rejected, 409 CANCELLATION_NOT_SUPPORTED_AT_STAGE. If supported: order moves to CancellationRequested and FleetBridge waits for the provider to confirm; outcome: "ConfirmationPending".
InDelivery, after pickup (PickedUp / OnTheWay)Allowed only if the current Delivery Provider supports cancellation after pickup (this is uncommon — most providers do not). If not supported: 409 CANCELLATION_NOT_SUPPORTED_AT_STAGE. If supported: same CancellationRequested / ConfirmationPending flow as above.
Any final status (Delivered/Cancelled/Failed)Rejected: 409 ORDER_ALREADY_FINAL.

Once pickup has happened and the provider doesn't support after-pickup cancellation, there are only two ways forward: delivery, or a provider-side failure that FleetBridge handles as a Return (Section 18). There's no "force cancel a physically-picked-up order" button available to an Order Source — it just doesn't exist.

12.2 Response

HTTP/1.1 200 OK
{
  "orderId": "6e1c1a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
  "status": "CancellationRequested",
  "outcome": "ConfirmationPending"
}

outcome is either Cancelled (finalized right away) or ConfirmationPending (waiting on the provider). Watch for the delivery.cancelled webhook — or order.cancellation_failed if the provider-side cancellation itself fails, in which case the order moves to ManualReviewRequired instead of sitting in limbo forever. FleetBridge never marks an order Cancelled while a provider that already accepted it hasn't actually confirmed.

12.3 Idempotent repeated cancellation

Calling Cancel again on an order that's already CancellationRequested or already Cancelled is safe. A repeat call on an already-final Cancelled order comes back 409 ORDER_ALREADY_FINAL, which you can just treat as "already cancelled, nothing to do" in your retry logic. A repeat call while still CancellationRequested won't create a duplicate cancellation attempt either.

12.4 Related: look up by your own reference

GET /api/v1/orders/by-external-id/{externalOrderId}

Same shape as GET /api/v1/orders/{platformOrderId}, scoped to orders your Order Source created. Handy if you need to re-establish platformOrderId from your own stored externalOrderId before calling Update or Cancel — after a crash, say, where you're not sure whether you'd already persisted the FleetBridge id. Lookup is by externalOrderId only; externalOrderNumber is never a lookup key.

13. Idempotency

13.1 Header

Idempotency-Key: <your own unique string, ≤200 characters>

Supported only on Create (POST /api/v1/orders). Update and Cancel don't accept or need one — Cancel is naturally idempotent already (Section 12.3), and Update's partial-patch semantics mean a retried identical PATCH just re-applies the same, already-applied change harmlessly.

13.2 Scope

An idempotency key is scoped to (your tenant, your Order Source, the key string). So two different Order Sources under the same tenant can reuse the identical key string with zero risk of collision.

13.3 Behavior on repeat — same key, read carefully

Say you send a second Create request with an Idempotency-Key that already succeeded once.

FleetBridge returns the original order, unconditionally: 201 Created, the same platformOrderId, the same response shape as the first call — whether or not the new request body matches the original.

There's no payload-equality check, and no "conflicting payload" error. Replay the same key with a genuinely different body — a bug on your side, or a legitimate change of mind — and FleetBridge does not create a second order and does not apply your new body to the existing one. It just quietly hands back the original order, exactly as it already was. Need to change something about an order you already created? Use Update (Section 11). Never a second Create with the same key and different fields.

13.4 Behavior with no idempotency key

Skip Idempotency-Key entirely and FleetBridge still protects you from an accidental true duplicate: a second Create with the same externalOrderId (scoped to your Order Source) resolves to the existing order the same way a matching Idempotency-Key would. You get the original back, not a new one. externalOrderId itself is always a de-dup key, with or without an explicit Idempotency-Key header. externalOrderNumber never is: two orders may share one. We'd still recommend sending the header explicitly — it lets you retry safely with the *same* externalOrderId semantics even in flows where you generate that id late, and it says what you mean more clearly than relying on a side effect.

13.5 Retention

Idempotency records stick around indefinitely. There's no expiry after which the same key could suddenly create a second order — it's permanently tied to whatever it first created.

13.6 What to do after a timeout / unknown outcome

Create request times out, or you get a network error with no HTTP response at all — now you can't tell if FleetBridge actually processed it. The right move: retry the exact same request, including the same Idempotency-Key. Whether the original attempt succeeded or never arrived, that retry is safe. You'll either get the freshly created order or the original one back. Don't generate a new Idempotency-Key for what you think is a retry of the same logical order — that defeats the whole mechanism and can actually create a duplicate.

13.7 Worked examples

First request:

POST /api/v1/orders
Idempotency-Key: web-order-7781
{ "externalOrderId": "WEB-7781", "payment": { "method": "Cash", "amount": 50, "currency": "ILS" }, ... }
→ 201 Created, platformOrderId = "aaa...", externalOrderId = "WEB-7781"

Exact retry (same key, same body) — safe, expected:

POST /api/v1/orders
Idempotency-Key: web-order-7781
{ "externalOrderId": "WEB-7781", "payment": { "method": "Cash", "amount": 50, "currency": "ILS" }, ... }
→ 201 Created, platformOrderId = "aaa..." (identical to the first response)

Same key, different body — still returns the original, does NOT apply the new body:

POST /api/v1/orders
Idempotency-Key: web-order-7781
{ "externalOrderId": "WEB-7781", "payment": { "method": "Card", "amount": 999, "currency": "ILS" }, ... }
→ 201 Created, platformOrderId = "aaa..." — still Cash/50, the ORIGINAL order, unchanged

14. Scheduled orders

14.1 Semantics

  • scheduledDeliveryAt omitted or null → immediate (ASAP) order, dispatched under your tenant's normal immediate-routing rules right away.
  • scheduledDeliveryAt set to a future timestamp → the order is created with status: "Scheduled" and dispatched automatically when due.

14.2 Validation

scheduledDeliveryAt needs to be at least a minimum lead time out — 15 minutes by FleetBridge's platform default, though your tenant might be configured differently. Treat 15 minutes as the floor to design against, not a guarantee. Anything before that minimum, or in the past, gets rejected:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "scheduledDeliveryAt must be at least 15 minutes in the future.",
  "errorCode": "INVALID_SCHEDULED_TIME",
  "correlationId": "..."
}

Must be ISO 8601 with an explicit UTC offset (Section 6).

14.3 Dispatch timing

FleetBridge doesn't wait until the exact scheduledDeliveryAt moment to start dispatching. It starts ahead of time, so the delivery actually has a shot at arriving on schedule:

dispatchAt = scheduledDeliveryAt − dispatchLeadTimeMinutes

dispatchLeadTimeMinutes is a per-tenant setting (30 minutes by platform default) that can be overridden per branch. You don't send this value at all — it's purely a FleetBridge/tenant configuration concern. At dispatchAt, the order moves from Scheduled to PendingRouting and enters normal routing.

14.4 While scheduled

A Scheduled order can be updated (Section 11) and cancelled (Section 12) freely. Cancellation before dispatch is always platform-side only, since no provider is involved yet. SLA timers don't start until the order actually dispatches — not at creation time.

14.5 Example

{
  "externalOrderId": "ORD-3010",
  "externalBranchId": "MAIN-BRANCH",
  "scheduledDeliveryAt": "2026-09-23T09:00:00+03:00",
  "pickup": { "address": "Main Branch", "lat": 31.9021, "lng": 35.2034 },
  "dropoff": { "customerName": "Layla Odeh", "customerPhone": "+970598765432", "address": "Al-Masyoun", "lat": 31.9130, "lng": 35.2010 },
  "payment": { "method": "Online", "amount": 65, "currency": "ILS" },
  "preparationTimeMinutes": 10
}
{
  "platformOrderId": "7f2d1a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b",
  "externalOrderId": "ORD-3010",
  "externalOrderNumber": "ORD-3010",
  "status": "Scheduled",
  "branchId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "routingMode": "PriorityFailover",
  "createdAt": "2026-09-22T14:00:00Z"
}

15. Provider routing and failover

15.1 You integrate with FleetBridge, not with a Delivery Provider

Order Source
     │
     ▼
FleetBridge Order API   ← this document
     │
     ▼
Routing / Orchestration  (FleetBridge-internal — provider selection, failover, retries)
     │
     ▼
Delivery Provider        ← you never see this layer directly

You never get Delivery Provider credentials, never see its webhook format, and never need to know how FleetBridge's internal adapter for a given provider actually works. delivery.providerCode/delivery.providerDeliveryId, when present, are informational — handy for support conversations and driver-facing tracking links, but not something your integration logic should branch on.

15.2 Requesting a specific provider (optional)

You can set deliveryProviderCode on Create to request a specific Delivery Provider by its FleetBridge-known code ("cervo", say). It's honored only if:

  • The provider is known and enabled for your tenant.
  • Manual provider selection is permitted for the branch/tenant.
  • The provider is currently eligible — enabled, active credentials, allowed for this branch.

Unknown or not-enabled code: 400 PROVIDER_NOT_ENABLED. Real, known provider but the override isn't currently honorable (disabled for this branch, credentials not configured, manual override turned off for your tenant): 400 MANUAL_OVERRIDE_NOT_ALLOWED. Leave the field out entirely and FleetBridge picks the provider per your tenant's normal routing configuration — the default, and the right choice unless you have a specific reason to override it for a given order.

15.3 Failover — what you observe, and what you should do

Before pickup, if a Delivery Provider fails — rejects, times out, cancels — FleetBridge may automatically route the order to another eligible one, depending on your tenant's routing mode. Here's what you'll see:

{ "eventType": "provider.failed", "delivery": { "providerCode": "cervo", "attemptStatus": "CancelledByProvider" },
  "failure": { "reasonCode": "NO_DRIVERS_AVAILABLE", "reasonText": "No drivers available", "rawProviderReason": "No couriers nearby" },
  "routing": { "nextAction": "RetryingWithNextProvider", "nextProviderCode": "provider_b" } }

If a next provider is found, that's followed by the normal delivery.provider_assigned / delivery.sent_to_provider sequence again, just for the new provider — same platformOrderId, same externalOrderId. If every eligible provider gets exhausted, routing.nextAction becomes NoProviderAvailable, you get order.no_provider_available, and the order status becomes NoProviderAvailable (held, Section 8.2) until a FleetBridge operator steps in.

What you actually need to do: keep correlating on platformOrderId/externalOrderId. Never create a second order because a provider failed — that's exactly the scenario failover exists to handle transparently for you. Don't key any of your own logic off providerCode either, since it can legitimately change mid-order. And failover only happens before pickup — once the order is physically picked up, a delivery problem becomes a Return (Section 18), never a silent re-dispatch to a different provider.

16. Error model

Every business-logic rejection (as opposed to a raw authentication failure, Section 2.5, or malformed-JSON parse failure) comes back in this shape, content-type: application/problem+json:

{
  "status": 404,
  "title": "Not Found",
  "detail": "No active branch was found for the provided branchId or pickup location.",
  "errorCode": "BRANCH_NOT_FOUND",
  "details": { "pickupLat": 31.9021, "pickupLng": 35.2034 },
  "correlationId": "0HNOOIIC1J8FA:00000003"
}

details shows up only for some error codes, when FleetBridge has specific structured context to offer. correlationId is there whenever available, and worth logging — include it if you ever need to ask FleetBridge support about a specific failed request.

16.1 Status code matrix

HTTPMeaning hereRetryable?Typical client action
400Request failed validation (bad field value, bad JSON, missing required field).No — fix the request first.Correct the field named in detail/errorCode and resend with a new logical attempt (existing Idempotency-Key, if any, is unaffected since no order was created).
401Missing/invalid/expired/revoked API key. Empty body — see Section 2.5.No, unless you can fix the credential.Check the X-Api-Key header is present, well-formed, and current.
403Authenticated, but your Order Source or Tenant cannot act right now (disabled/suspended).No.Contact FleetBridge/your tenant admin; this is a configuration state, not a transient fault.
404The referenced order (or branch, on Create) does not exist, or does not belong to your Order Source.No.Re-check the id; if you expected it to exist, look it up again via GET .../by-external-id/{externalOrderId}.
409The request is well-formed, but conflicts with the order's current state (already final, cancellation not supported at this stage).No — the state itself needs to change first, if it ever will.Read the order's current status before deciding what to do next; do not blindly retry a 409.
429Rate limited. See Section 22.Yes, after the delay in Retry-After.Back off and retry; safe to retry a Create with the same Idempotency-Key.
5xxAn unexpected server-side fault.Situational — see below.See 16.2.

16.2 On a 5xx or no response at all

Don't blindly retry every 5xx with a brand-new request. For Create specifically, always retry with the same Idempotency-Key (Section 13.6) — that's what makes a 5xx/timeout retry safe, regardless of whether the original request actually succeeded server-side before failing to respond. Update and Cancel are naturally safe to retry as-is (Update re-applies the same patch; Cancel is idempotent, Section 12.3), so a plain retry with backoff works fine there. Use increasing backoff between attempts — 1s, 2s, 5s, say — rather than hammering it in a tight loop.

16.3 Full error code reference (Order-Source-relevant)

errorCodeHTTPWhere you'll see it
BRANCH_NOT_FOUND404Create — Section 7.5, 19.
INVALID_PICKUP_LOCATION400Create — bad pickup.lat/lng.
INVALID_DROPOFF_LOCATION400Create/Update — bad dropoff.lat/lng.
INVALID_AMOUNT400Create/Update — negative amount/deliveryFee.
STRUCTURAL_LIMIT_EXCEEDED400Create/Update — string too long, or amount precision/size.
INVALID_PREPARATION_TIME400Create/Update — negative preparationTimeMinutes.
INVALID_PAYMENT_METHOD400Create/Update — unrecognized payment.method.
INVALID_SCHEDULED_TIME400Create/Update — scheduledDeliveryAt too soon.
PROVIDER_NOT_ENABLED400Create — unknown/disabled deliveryProviderCode.
MANUAL_OVERRIDE_NOT_ALLOWED400Create — provider override not currently honorable.
PROVIDER_UPDATE_NOT_SUPPORTED400Update — scheduledDeliveryAt change rejected post-acceptance.
TENANT_SUSPENDED403Any call — Section 2.5.
ORDER_SOURCE_DISABLED403Any call — Section 2.5.
INVALID_API_KEY403Rare/abnormal caller-context mismatch.
ORDER_NOT_FOUND404Any order-scoped call — wrong id, or belongs to a different Order Source.
ORDER_ALREADY_FINAL409Update/Cancel on Delivered/Cancelled/Failed.
CANCELLATION_NOT_SUPPORTED_AT_STAGE409Cancel — Section 12.1.
RATE_LIMIT_EXCEEDED429Section 22.

DUPLICATE_ORDER and IMMUTABLE_FIELD aren't real runtime error codes you'll ever actually receive. Duplicate Create requests get handled transparently by idempotent replay (Section 13), and immutable fields just aren't part of the Update schema in the first place (Section 11.3) — there's nothing to error on.

17. PaymentMethod

"payment": { "method": "Cash", "methodRaw": "cash_on_delivery" }

method (required on Create) is one of exactly five values:

Cash | Card | Online | Wallet | Other

methodRaw (optional) lets you keep your own original label alongside the normalized value. Handy if your system has a richer payment taxonomy than FleetBridge's five buckets — map whatever doesn't fit cleanly to Other and put your real value in methodRaw.

PaymentMethod is order metadata, nothing more. FleetBridge is not a payment processor. Setting method: "Cash" doesn't make FleetBridge collect, hold, settle, or reconcile any cash-on-delivery funds — that stays entirely between you, your Delivery Provider, and your customer. FleetBridge just passes the value through to the Delivery Provider where its contract accepts it, and reports it back to you. It never affects routing or provider selection.

18. Returns

Phase 1 has no self-service return action for an Order Source. If a delivery fails after physical pickup — customer unreachable, refuses delivery, address unusable, provider cancels mid-route — FleetBridge doesn't silently re-dispatch to another provider. Normal failover stops at pickup (Section 15.3). Instead, the order enters a return flow that a FleetBridge operator resolves by hand. There's no API call an Order Source can make to trigger, speed up, or resolve a return.

What you *can* do:

  • Observe. orderStatus becomes ReturnInProgress while the return is active, and Failed once goods are confirmed back at the branch. If the return itself can't be completed, the order becomes ManualReviewRequired (Section 8.2) and needs a human — on FleetBridge's or your tenant's side — to sort it out.
  • Subscribe to return webhooks: delivery.return_requested, delivery.returning_to_origin, delivery.returned_to_origin, delivery.return_failed (Section 9.7) keep you posted in real time without polling.
  • Re-delivery is a new order. FleetBridge won't automatically re-attempt delivery of returned goods. If your business needs a second delivery attempt after a return, create a new order for it once the original is resolved.

Don't advertise automated return handling to your own end users based on this integration. "FleetBridge notifies us and our operations team follows up" is the honest description of what happens today — stick to that.

19. Branch / pickup resolution

Create resolves the delivery's origin branch in this priority order:

  1. branchId, if supplied — must resolve to an active branch belonging to your tenant, or 404 BRANCH_NOT_FOUND.
  2. Else externalBranchId, if supplied and non-blank — same active-branch requirement.
  3. Else nearest match by pickup.lat/pickup.lng — FleetBridge finds the closest active branch whose configured match radius (a per-branch setting, 100 meters by default) contains your supplied pickup coordinates. If no active branch is within its own radius of the supplied point, 404 BRANCH_NOT_FOUND (with pickupLat/pickupLng echoed in details).

If you already know your FleetBridge branchId — most integrations will, once set up — send it. It's the fastest, least ambiguous path. externalBranchId is for integrations that track their own store/branch codes instead. The coordinate-based fallback exists for integrations that only know a physical location, not a code, but it's inherently less precise (a pickup point sitting exactly between two branches' radii is genuinely ambiguous). Avoid leaning on it as your primary mechanism if you can help it.

20. Environments

FleetBridge doesn't publish one fixed hostname for every customer. As part of onboarding you get:

  • A staging Base URL and staging X-Api-Key, for development and certification (Section 23).
  • A production Base URL and production X-Api-Key, issued at activation.

There's no way to tell "which environment" a key belongs to from its format (Section 2.2) — the Base URL you point at is what determines that. Keep staging and production credentials in clearly separate configuration in your own systems. FleetBridge can't protect you from accidentally pointing a production key at a staging URL, or the reverse.

21. Versioning

  • API major version: v1, in every path (/api/v1/...). A breaking change (wire format, authentication, signature algorithm, a required field, or a status/event semantic change) would require a new major version and a distinct migration path — it would never be silently applied to v1.
  • This document's revision: 1.1.0, tracked in the Changelog (CHANGELOG.md) alongside this package.
  • Additive changes (a new optional field, a new event type, a new enum value in a non-exhaustively-matched position) may ship within v1 without notice beyond the changelog. Write your JSON parsing to ignore unknown fields (Section 6) and your event-type handling to tolerate an event type you don't recognize yet (skip it, don't crash), so additive changes never break your integration.
  • Removing or renaming a field, changing a field's type, or changing the meaning of an existing status/event is a breaking change and would ship as a new API major version with its own contract document, never silently inside v1.

22. Rate limits

There's currently one rate limit on Order Source traffic, and it's intentionally coarse. We're documenting it honestly here rather than implying some business-level quota that doesn't actually exist:

  • 300 requests per minute, per source IP address, applied to *any* request carrying an X-Api-Key header. Not specific to order creation, not scoped per API key, not configurable per tenant. It exists purely to bound abusive traffic before it reaches authentication, not as a fair-use business quota.
  • On rejection: 429 Too Many Requests, a Retry-After header (seconds), and the standard error envelope:
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/problem+json
{
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Too many requests carrying an API key from this address. Please try again later.",
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "correlationId": "..."
}

Respect Retry-After instead of guessing your own backoff. If you're behind a shared outbound IP — a NAT gateway, a shared hosting provider — remember this limit is IP-scoped, not key-scoped, and plan capacity with that in mind. There's no separate, higher, per-tenant business quota to request right now. If your real traffic needs exceed this ceiling, talk to FleetBridge directly rather than architecting around a quota that isn't actually part of the contract.

Retrying a rate-limited Create call is always safe if you reuse the same Idempotency-Key (Section 13).

23. Integration checklist

Before development

  • Staging X-Api-Key and staging Base URL received.
  • Your callback URL is reachable over HTTPS from the public internet.
  • Webhook endpoint registered by FleetBridge and your webhook signing secret captured and stored securely (Section 9.2, 10.2).
  • You understand the idempotency-replay semantics in Section 13.3 before writing any retry logic.

Development

  • Authentication works — a valid Create request returns 201 with the expected shape.
  • Create works for both immediate and scheduled orders.
  • Idempotent replay proven: same Idempotency-Key, same body, twice → same platformOrderId both times.
  • Update works, and you've confirmed a field's NotApplicable/NotSupportedByProvider/ PropagationFailed result doesn't crash your handling.
  • Cancel works for at least the "before dispatch" case; you understand the CANCELLATION_NOT_SUPPORTED_AT_STAGE case can legitimately happen.
  • GET .../status, .../tracking, .../tracking-history all work and null-safe your parsing (most tracking fields are nullable).
  • Webhook signature verification implemented and tested against POST /api/v1/webhooks/test (Section 9.2), using the raw request body (Section 10.4).
  • Your webhook handler deduplicates on eventId and tolerates out-of-order delivery (Section 9.5).

Staging certification (Section 24)

  • Duplicate Create (same Idempotency-Key) returns the original order, not a new one.
  • Create with the same Idempotency-Key but a different body still returns the original, unchanged — confirms you are not relying on a "conflict" error that does not exist.
  • A scheduled order validates the minimum lead time and dispatches around the expected time.
  • An invalid request (bad coordinates, bad enum, missing required field) returns the expected 400 + errorCode.
  • Cancellation at each reachable stage behaves as documented in Section 12.1.
  • A webhook delivery failure (temporarily break your own endpoint) is retried per the schedule in Section 9.4, and you can observe/request a manual resend through FleetBridge if needed.
  • Duplicate webhook delivery does not double-process on your end.
  • If your staging environment lets you exercise a failover scenario, confirm you continue correlating correctly on platformOrderId across a provider change (Section 15.3).

Production activation

  • Production X-Api-Key and production Base URL configured, kept separate from staging (Section 20).
  • Production callback URL registered and its own webhook secret captured.
  • You have a documented process for what happens if/when FleetBridge needs to rotate your webhook secret (Section 9.10 — you have a 24-hour overlap window, not zero downtime, if you react promptly).
  • You know who to contact at FleetBridge for integration issues, and you log correlationId from error responses so a support conversation can reference a specific failed request.

24. Certification / self-test

Check certification/README.md in this package for a runnable checklist and script (certification/certify.py) that exercises this whole contract — Create, idempotent replay, Update, Cancel, validation errors, and optionally webhook signature verification against a local receiver — using your own staging credentials. No access to FleetBridge's source code or infrastructure required; it just calls the public HTTP contract described in this document, and prints a pass/fail report per checklist item plus a machine-readable JSON result file you can attach to a certification request.

25. Changelog

See CHANGELOG.md in this package.

No sections match your search.