Orders

POST /api/vendor/v1/orders

Creates a delivery request. The response is synchronous: by the time you get it, either a delivery exists or you know exactly why it does not.

Request

POST /api/vendor/v1/orders
Authorization: Bearer <token>
X-Idempotency-Key: ADS-ORD-99213
Content-Type: application/json

{
  "externalStoreId": "ADS-34781",
  "externalOrderId": "ADS-ORD-99213",
  "orderedAt": "2026-08-04T18:42:11+03:00",
  "readyAt": "2026-08-04T18:57:00+03:00",
  "recipient": {
    "name": "Merve Yildirim",
    "phone": "5339876543"
  },
  "dropoff": {
    "text": "Cemal Gursel Cad. No:45 D:8, Kurtulus, Cankaya/Ankara",
    "latitude": 39.925310,
    "longitude": 32.862440,
    "buildingNo": "45",
    "doorNo": "8",
    "floor": "3",
    "note": "Doorbell is broken, please knock"
  },
  "packageNote": "2 wraps, 1 ayran",
  "orderAmount": 480.00,
  "payment": {
    "type": "Cash",
    "collectionAmount": 480.00
  }
}

Fields

Field	Required	Rule	Rejected with
externalStoreId	yes	Must be registered and Active	409 STORE_NOT_CONFIGURED
externalOrderId	yes	Unique within your account, max 64 chars	409 DUPLICATE_ORDER
recipient.name	yes	At least 2 characters	422 INVALID_RECIPIENT
recipient.phone	yes	10 digits; leading 0 and +90 are stripped	422 INVALID_PHONE
dropoff.text	yes	At least 10 characters	422 INVALID_ADDRESS
dropoff.latitude / longitude	yes	Inside Turkey, and inside the fleet coverage area	422 COORDINATE_MISMATCH · 422 DROPOFF_OUT_OF_COVERAGE
orderedAt	no	ISO-8601. Without an offset, UTC+3 is assumed	—
readyAt	no	Defaults to now. Past values are pulled to now; more than 4 hours ahead is rejected	422 READY_AT_TOO_FAR
packageNote	no	Max 500 characters	—
orderAmount	no	Stored for reconciliation and reporting	—
payment.type	no	Cash, Card or Prepaid	—
payment.collectionAmount	no	Amount the courier collects at the door	—

readyAt

This is when the package leaves the kitchen, not when the order was taken. We use it to time the courier's arrival. Sending it well is the single biggest thing you can do for delivery quality — a courier that arrives ten minutes early blocks itself, one that arrives late delivers cold food.

Coordinates

The courier navigates to the coordinates, not to dropoff.text. The text is what the courier reads at the door; the point is where the app takes them.

We reject coordinates outside Turkey, and coordinates the contracted fleet does not serve. What we cannot detect is a plausible-looking point that belongs to a different address than the one you wrote — so send the point your own map resolved, never a neighbourhood centroid. A wrong coordinate sends a courier to another street, and once the courier is moving it cannot be corrected.

payment

We store the amount, pass it to the courier, and include it in reports. We do not run a collection workflow: there is no "money received" confirmation in the courier app, because that would make Hızlıyo the operator of a payment process. Cash at the door stays a matter between the restaurant and the fleet.

Response

{
  "success": true,
  "data": {
    "orderId": "e5a9f0d3-7c21-4b88-a06e-3f9182bd4471",
    "externalOrderId": "ADS-ORD-99213",
    "status": "Searching",
    "fleet": { "fleetId": "9d41...5e64", "name": "Baskent Moto Kurye" },
    "trackingUrl": "https://takip.hizliyo.com/d/8fK2mQ",
    "estimatedPickupAt": "2026-08-04T18:59:00+03:00"
  }
}

Store orderId. It identifies the delivery in status queries, cancellations and webhooks.

Idempotency

Send X-Idempotency-Key with a value unique to the order — your own order id works well. If the same key arrives again with the same body, you get the original response back instead of a second delivery. If it arrives with a different body, you get 409 DUPLICATE_ORDER.

This makes a network timeout safe to resolve: resend with the same key and you will either create the order or learn it already exists.

Retry policy

We never retry your order for you

A failed request dies. Whether to send it again is your decision.

This is deliberate. A package races the clock; an order that we quietly retry from a queue and revive ten minutes later arrives at a restaurant that has already moved on, or worse, sends a courier for food nobody made.

Practical guidance:

• 401 TOKEN_EXPIRED — renew the token, resend once. Safe with the same idempotency key.
• 503 FLEET_UNAVAILABLE — no courier right now. Retrying after ~60 s is reasonable; tell the restaurant meanwhile.
• 429 RATE_LIMITED — wait Retry-After seconds.
• Everything else — do not retry. Show the restaurant what went wrong; see Errors.

Rejections

Status	Code	When
423	FLEET_SUSPENDED	The store's fleet cannot currently accept orders
503	FLEET_UNAVAILABLE	No available courier in that area right now
409	STORE_NOT_CONFIGURED	No fleet attached, or the store is not active
422	DROPOFF_OUT_OF_COVERAGE	Delivery address outside the fleet's coverage

Full list in Errors.