Delivery V3

The Delivery V3 API enables integration with third-party delivery services for quotes and order tracking.

Overview

V3 introduces comprehensive delivery service integration with support for multiple providers, real-time quote generation, and delivery tracking. This is a new capability not available in V2.

API Endpoints

Retrieve Delivery Settings

GET /online-ordering/v3/{locationId}/delivery-service/settings

Returns a Location Delivery configuration.

Response: 200 OK

Returns a list of available delivery services for the requested location.

Response Body:

{
  "deliveryServices": [
    {
      "name": "Doordash Drive",
      "ref": "310ddc51-5256-44b0-a08b-a239d4a301cc"
    },
    {
      "name": "InhouseDelivery",
      "ref": "0b2d5658-3cdf-44c0-9fe6-5111d9bf5def"
    }
  ]
}

Retrieve Delivery Quotes

POST /online-ordering/v3/{locationId}/delivery-service/quotes

Returns a list of Delivery Quotes for the requested location.

Request Body (required)

Content-Type: application/json

{
  "hasAgeRestrictedItems": "boolean",
  "deliveryAddress": {
    "city": "San Francisco",
    "state": "CA",
    "line1": "901 Market Street",
    "line2": "Suite #600",
    "postalCode": "94105",
    "instructions": "string | null"
  },
  "expectedDeliveryAt": null,
  "expectedPickupAt": "2022-02-25T01:07:10Z"
}

Responses:

• 200 - Returns a list of delivery quotes

Response Body:

{
  "quotes": [
    {
      "ref": "crn:[conecto-app-guid]:[3rd-party-external-indetifier]",
      "fee": "integer",
      "currency": "USD",
      "estimatedDeliveryAt": "2022-02-25T01:30:39Z",
      "estimatedPickupAt": "2022-02-25T01:07:10Z"
    }
  ]
}

• 412 - Precondition Failed - no DELIVERY SERVICE subscriptions for location

Place Delivery Orders

POST /online-ordering/v3/{locationId}/orders

Delivery Order is placed as other orders.

Prerequisites:

• Delivery Service Provider is installed for the location. E.g., DoorDash Drive, Inhouse Delivery.

Essential fields for Delivery Order Placement:

{
  ...,
  "fulfillmentType": "DELIVERY",
  "expectedAt": "<expected-food-delivery-time>",
  "deliveryInfo": {
    "deliveryType": "DELIVERY_SERVICE|SELF_DELIVERY",
    "isContactless": false,
    "address": "<Address>",
    "instructions": null,
    "contactInfo": "<ContactInfo>",
    "deliveryService": {
      "deliveryQuoteRef": "crn:310ddc51-5256-44b0-a08b-a239d4a301cc:dqt_SPR-sYE7xc0f4883",
      "expectedPickupAt": "<expected-food-pickup-time>"
    }
  }
}

For delivery orders pickupInfo, dineInInfo, curbsideInfo fields should be null.

Full order structure is available in Order V3.

Data Models

DeliveryServiceSettings

QuoteRequest

Quote Response

Delivery Service Data (in Order)

Implementation Workflow

Standard Delivery Order Flow

1. Retrieve Available Services

   GET /online-ordering/v3/{locationId}/delivery-service/settings
   

   CopyCopied!
   • Check which delivery services are configured
   • Display service options to customer if multiple available

2. Request Delivery Quotes

   POST /online-ordering/v3/{locationId}/delivery-service/quotes
   

   CopyCopied!
   • Provide delivery address
   • Specify expected pickup time
   • Include age-restricted item flag if applicable
   • Receive fee estimates and ETAs

3. Display Quote to Customer

   • Show delivery fee
   • Display estimated delivery time
   • Allow customer to confirm or modify

4. Place Order with Delivery

   POST /online-ordering/v3/{locationId}/orders
   

   CopyCopied!
   • Set fulfillmentType: "DELIVERY"
   • Set deliveryInfo.deliveryType: "DELIVERY_SERVICE"
   • Include deliveryInfo.deliveryService.quoteRef from step 2
   • Provide complete delivery address and contact info

5. Track Order Status

   • Monitor status via Order V3 endpoints
   • Subscribe to status change webhooks
   • Display delivery progress to customer

Delivery Types

DELIVERY_SERVICE

• Third-party delivery provider (DoorDash, Uber, etc.)
• Requires quote reference
• Service handles driver assignment and routing
• Provider-specific pricing and ETAs

SELF_DELIVERY

• Restaurant's own delivery fleet
• No quote required
• Restaurant manages driver assignment
• Custom pricing and timing

Best Practices

Quote Management

• Request quotes early in checkout process
• Display fees clearly before order confirmation
• Refresh quotes if user delays checkout
• Handle quote expiration gracefully

Error Handling

• Fallback to SELF_DELIVERY if services unavailable
• Validate address before requesting quotes
• Handle 412 responses by disabling delivery option
• Provide clear error messages for invalid addresses

Performance

• Cache delivery service settings
• Request quotes asynchronously
• Display estimated times prominently
• Update ETAs dynamically as order progresses

Customer Experience

• Show delivery fee breakdown
• Display estimated delivery time range
• Provide delivery tracking updates
• Include driver contact information when available

Validation Requirements

• Address Validation: All required address fields must be provided
• Phone Format: Contact numbers must follow E.164 format
• Quote Validity: Quotes have limited validity period, refresh if expired
• Timing Logic: expectedPickupAt must be reasonable (typically 15-60 minutes from now)
• Service Availability: Check 412 response, handle no-service scenarios gracefully

Key Features

• Multi-provider support (choose between multiple delivery services)
• Real-time fee and ETA calculation
• Age-restricted item handling
• Contactless delivery support
• Special instruction support
• Address validation
• Quote-based pricing