API docs by Redocly

Core API (1.0.48)

Download OpenAPI specification:

Webhooks

You can receive updates about an order by subscribing to webhooks.

API Authorization

API uses Basic authentication, which involves sending a verified username and password with request. Take credential for Basic authentication(username and password) from API integrations secrets.

Direct request

Request must contain a header field in the form of Authorization: Basic, where credentials is the Base64 encoding of ID and password joined by a single colon:

For example, if in API "user" as username and "password" as the password, then the field's value is the Base64 encoding of user:password, or dXNlcjpwYXNzd29yZA==.

Then the Authorization header field will appear in request as:

Authorization: Basic dXNlcjpwYXNzd29yZA==.

Postman:

In the request Authorization tab, select Basic Auth from the Type dropdown list.

Enter API username and password in the Username and Password fields. In the request Headers, the Authorization header passes the API a Base64 encoded string representing your username and password values, appended to the text Basic.

Guide

The detailed API user guide is available via the following link.

Orders

Creating an order

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

Request Body schema: application/json
optional

CreateOrderRequest

required
object (CreatePickupWaypoint)
required
object (CreateDropOffWaypoint)
order_id
string
team_id
string
Array of objects (OrderItem)
payment_type
string
Enum: "cash" "paid"
order_total
number <double>
sub_total
number <double>
tax
number <double>
delivery_fee
number <double>
tip
number <double>
allowed_vehicles
string
quote_external_reference
string <= 255 characters
object (OrderControlledSubstances)
is_contactless_delivery
boolean
require_photo
boolean
require_photo_at_drop_off
string
Enum: "none" "required" "optional"
require_photo_at_pick_up
string
Enum: "none" "required" "optional"
object (CustomerNotification)
object (CustomerIdDetailsRequest)
barcode
string
object (RouteItem)
catering
boolean

Responses

Request samples

Content type
application/json
{
  • "pickup_waypoint": {
    },
  • "dropoff_waypoint": {
    },
  • "order_id": "testId",
  • "team_id": "c7456517-ce01-e4d4-1c04-111ba075463e",
  • "order_items": [
    ],
  • "order_total": 10,
  • "sub_total": 7,
  • "tax": 1,
  • "delivery_fee": 1,
  • "tip": 1,
  • "allowed_vehicles": "Car,Motorcycle,Bicycle,Walking,Van",
  • "quote_external_reference": "quote",
  • "payment_type": "cash",
  • "controlled_substances": {
    },
  • "is_contactless_delivery": false,
  • "require_photo": false,
  • "require_photo_at_drop_off": "required",
  • "require_photo_at_pick_up": "optional",
  • "customer_notification": {
    },
  • "route": {
    },
  • "catering": false
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status_code": 0
}

Getting an order

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

jobId
required
string <uuid>

Order identifier

Responses

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "order_id": "string",
  • "external_order_id": "EXT-12345",
  • "source": "src-1",
  • "status": "submitted",
  • "notes": {
    },
  • "timestamps": {
    },
  • "payments": {
    },
  • "flags": {
    },
  • "dsp": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "driver": {
    },
  • "allowed_vehicles": "string",
  • "customer_id_details": {
    },
  • "route": {
    },
  • "log": [
    ],
  • "urls": {
    }
}

Updating an order

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

jobId
required
string <uuid>

Order identifier

Request Body schema: application/json
optional

UpdateOrderRequest

status
string
Enum: "done_cancelled" "cancelled"
arrive_at
string <ISO 8601 Localized Datetime>

Responses

Request samples

Content type
application/json
{
  • "status": "cancelled",
  • "arrive_at": "2021-10-01T15:00:00-0800"
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "order_id": "string",
  • "external_order_id": "EXT-12345",
  • "source": "src-1",
  • "status": "submitted",
  • "notes": {
    },
  • "timestamps": {
    },
  • "payments": {
    },
  • "flags": {
    },
  • "dsp": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "driver": {
    },
  • "allowed_vehicles": "string",
  • "customer_id_details": {
    },
  • "route": {
    },
  • "log": [
    ],
  • "urls": {
    }
}

Patching an order

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

jobId
required
string <uuid>

Order identifier

Request Body schema: application/json
optional

PatchOrderRequest

object (PatchPickupWaypoint)
object (PatchDropOffWaypoint)
order_id
string
status
string
Enum: "done_cancelled" "cancelled"
Array of objects (OrderItem)
payment_type
string
Enum: "cash" "paid"
order_total
number <double>
sub_total
number <double>
tax
number <double>
delivery_fee
number <double>
tip
number <double>
object (CustomerNotification)
object (RouteItem)
catering
boolean

Responses

Request samples

Content type
application/json
{
  • "pickup_waypoint": {
    },
  • "dropoff_waypoint": {
    },
  • "order_id": "testId",
  • "status": "cancelled",
  • "order_items": [
    ],
  • "payment_type": "cash",
  • "order_total": 10,
  • "sub_total": 7,
  • "tax": 1,
  • "delivery_fee": 1,
  • "tip": 1,
  • "customer_notification": {
    },
  • "route": {
    },
  • "catering": false
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "order_id": "string",
  • "external_order_id": "EXT-12345",
  • "source": "src-1",
  • "status": "submitted",
  • "notes": {
    },
  • "timestamps": {
    },
  • "payments": {
    },
  • "flags": {
    },
  • "dsp": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "driver": {
    },
  • "allowed_vehicles": "string",
  • "customer_id_details": {
    },
  • "route": {
    },
  • "log": [
    ],
  • "urls": {
    }
}

Pickups

Getting pickups in team

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

query Parameters
fields
Array of strings
Items Value: "quote-delivery-model"

Fields that must be returned additionally

Responses

Response samples

Content type
application/json
{
  • "pickups": [
    ]
}

Drivers

Creating a driver

Phone value must be unique among all drivers in a Company and is used instead of login value.
If you don’t provide password a random password will be generated.
Login instruction will be sent to the driver via text message if it is configured by Company's settings. You can forcefully override sending message behaviour by optional send_sms parameter.

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

Request Body schema: application/json
optional

CreateDriverRequest

login
string
Deprecated
password
string
email
string <RFC 822>
phone
required
string <E.164>
first_name
required
string
last_name
required
string
date_of_birth
string <ISO 8601 Localized Date>
object (TeamIdRequest)
driver_id
string
send_sms
boolean

Responses

Request samples

Content type
application/json
{
  • "email": "peter@example.com",
  • "password": "94PV/evNTo5i",
  • "phone": "+18005553535",
  • "first_name": "Peter",
  • "last_name": "Parker",
  • "date_of_birth": "1991-12-21",
  • "team": {
    },
  • "driver_id": "driverId",
  • "send_sms": "true"
}

Response samples

Content type
application/json
{
  • "id": "53c50a1a-6c80-491d-13b9-6149dd67cef2",
  • "login": "+18005553535",
  • "email": "peter@example.com",
  • "phone": "+18005553535",
  • "first_name": "Peter",
  • "last_name": "Parker",
  • "dsp": {
    },
  • "date_of_birth": "1991-12-21",
  • "active": true,
  • "team": {
    },
  • "photo": {
    },
  • "driver_id": "driverId"
}

Getting a driver

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

query Parameters
login
required
string

Driver login

Responses

Response samples

Content type
application/json
{
  • "id": "53c50a1a-6c80-491d-13b9-6149dd67cef2",
  • "login": "+18005553535",
  • "email": "peter@example.com",
  • "phone": "+18005553535",
  • "first_name": "Peter",
  • "last_name": "Parker",
  • "dsp": {
    },
  • "date_of_birth": "1991-12-21",
  • "active": true,
  • "team": {
    },
  • "photo": {
    },
  • "driver_id": "driverId"
}

Getting drivers in team

This API use a pagination strategy for dealing with operations that can return a large number of drivers. This strategy is built around the notion of a "cursor" and a "limit" that determines the maximum number of drivers that can be returned in a single response. Received "cursor" from the previous request can again be added to the original query to get the next page. This continues until the response returns a drivers list less than "limit" value which signifies that there are no more pages of results.

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

teamId
required
string

Team in which the getting drivers takes place

query Parameters
cursor
string

Cursor that can be used for getting next page

limit
integer [ 1 .. 1000 ]
Default: 100

Maximum number of drivers that can be returned in requested page

Responses

Response samples

Content type
application/json
{
  • "drivers": [
    ],
  • "cursor": "eyJjcmVhdGVUcyI6IjIwMjItMDItMDFUMDU6NTc6MjEuMDkxWiIsImlkIjoiNTE2ZTgwY2ItNzYwYy0wZDRkLTMxMjAtZGE2NjQwNDFhNmRjIiwic2VlZCI6eyJkYXRlIjp7InllYXIiOjIwMjQsIm1vbnRoIjozLCJkYXkiOjE4fSwidGltZSI6eyJob3VyIjo2LCJtaW51dGUiOjM1LCJzZWNvbmQiOjUzLCJuYW5vIjozNjM5MTAwMH19fQ=="
}

Patching a driver

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

driverId
required
string <uuid>

Driver identifier

Request Body schema: application/json
optional

PatchDriverRequest

email
string <RFC 822>
phone
string <E.164>
first_name
string
last_name
string
date_of_birth
string <ISO 8601 Localized Date>
object (TeamIdRequest)
driver_id
string

Responses

Request samples

Content type
application/json
{
  • "email": "peter@example.com",
  • "phone": "+18005553535",
  • "first_name": "Peter",
  • "last_name": "Parker",
  • "date_of_birth": "1991-12-21",
  • "team": {
    },
  • "driver_id": "driverId"
}

Response samples

Content type
application/json
{
  • "id": "53c50a1a-6c80-491d-13b9-6149dd67cef2",
  • "login": "+18005553535",
  • "email": "peter@example.com",
  • "phone": "+18005553535",
  • "first_name": "Peter",
  • "last_name": "Parker",
  • "dsp": {
    },
  • "date_of_birth": "1991-12-21",
  • "active": true,
  • "team": {
    },
  • "photo": {
    },
  • "driver_id": "driverId"
}

Activating a driver

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

driverId
required
string <uuid>

Driver identifier

Responses

Response samples

Content type
application/json
{
  • "id": "53c50a1a-6c80-491d-13b9-6149dd67cef2",
  • "login": "+18005553535",
  • "email": "peter@example.com",
  • "phone": "+18005553535",
  • "first_name": "Peter",
  • "last_name": "Parker",
  • "dsp": {
    },
  • "date_of_birth": "1991-12-21",
  • "active": true,
  • "team": {
    },
  • "photo": {
    },
  • "driver_id": "driverId"
}

Deactivating a driver

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

driverId
required
string <uuid>

Driver identifier

Responses

Response samples

Content type
application/json
{
  • "id": "53c50a1a-6c80-491d-13b9-6149dd67cef2",
  • "login": "+18005553535",
  • "email": "peter@example.com",
  • "phone": "+18005553535",
  • "first_name": "Peter",
  • "last_name": "Parker",
  • "dsp": {
    },
  • "date_of_birth": "1991-12-21",
  • "active": true,
  • "team": {
    },
  • "photo": {
    },
  • "driver_id": "driverId"
}

Teams

Getting teams

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

query Parameters
fields
Array of strings
Items Value: "quote-delivery-model"

Fields that must be returned additionally

Responses

Response samples

Content type
application/json
{
  • "teams": [
    ]
}

Quotes

Requesting a quote

Request quote(s) for the delivery.

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

Request Body schema: application/json
optional

CreateQuoteRequest

required
object (CreatePickupWaypoint)
required
object (CreateDropOffWaypoint)
order_id
string
team_id
string
Array of objects (OrderItem)
payment_type
string
Enum: "cash" "paid"
order_total
number <double>
sub_total
number <double>
tax
number <double>
delivery_fee
number <double>
tip
number <double>
allowed_vehicles
string
quote_external_reference
string <= 255 characters
object (OrderControlledSubstances)
is_contactless_delivery
boolean
require_photo
boolean
require_photo_at_drop_off
string
Enum: "none" "required" "optional"
require_photo_at_pick_up
string
Enum: "none" "required" "optional"
object (CustomerNotification)
object (CustomerIdDetailsRequest)
barcode
string
object (RouteItem)
catering
boolean
send_dsp_quotes
boolean
Default: false

When true, the response uses the multi-quote format (MultiQuoteResponse) with arrays of available and unavailable quotes, including the in-house quote and quotes obtained from connected DSPs. When false or not specified (default), the response is a single flat QuoteResponse. If DSP quote requests are not enabled for your integration, only the in-house quote appears in the multi-quote response.

Responses

Request samples

Content type
application/json
{
  • "pickup_waypoint": {
    },
  • "dropoff_waypoint": {
    },
  • "order_id": "testId",
  • "team_id": "c7456517-ce01-e4d4-1c04-111ba075463e",
  • "order_items": [
    ],
  • "order_total": 10,
  • "sub_total": 7,
  • "tax": 1,
  • "delivery_fee": 1,
  • "tip": 1,
  • "allowed_vehicles": "Car,Motorcycle,Bicycle,Walking,Van",
  • "quote_external_reference": "quote",
  • "payment_type": "cash",
  • "controlled_substances": {
    },
  • "is_contactless_delivery": false,
  • "require_photo": false,
  • "require_photo_at_drop_off": "required",
  • "require_photo_at_pick_up": "optional",
  • "customer_notification": {
    },
  • "route": {
    },
  • "catering": false,
  • "send_dsp_quotes": false
}

Response samples

Content type
application/json
Example
{
  • "is_available": true,
  • "quote_id": "bca6c1ca-b56c-1c4b-cb68-ee8e276e0155",
  • "fee": 4.5,
  • "return_fee": 1,
  • "unavailable_reason": "unavailable reason",
  • "estimated_pickup_time": "2021-10-01T15:01:00-0800",
  • "estimated_dropoff_time": "2021-10-01T16:02:00-0800",
  • "expires": "2021-10-01T16:00:00-0800"
}

Accepting a quote

Confirms a quote from a recent POST .../quotes call and creates the delivery order for that quote.

No request body is required.

If you call this again with the same quote_id after it was already accepted successfully, the API returns 409 Conflict with the same response body as the original 200 (safe for retries).

If the quote's cache entry has expired (expires has passed), the API returns 410 Gone with error_code quote_expired (not 404).

Fulfillment follows the option you chose in the quotes response (carrier or platform delivery, as shown there).

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

quote_id
required
string

The quote_id from the quotes response for the option you want to confirm. It must belong to this integration and still be within its expires window; otherwise the API returns 410 Gone (expired) or 404 Not Found (unknown id or not valid for this integration).

Responses

Response samples

Content type
application/json
{
  • "job_id": "bca6c1ca-b56c-1c4b-cb68-ee8e276e0155",
  • "order_id": "testId",
  • "status": "accepted",
  • "provider": {
    },
  • "delivery_fee": 4.5,
  • "estimated_pickup_time": "2021-10-01T15:01:00-0800",
  • "estimated_dropoff_time": "2021-10-01T16:02:00-0800"
}

Routes

Creating a route

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

Request Body schema: application/json
optional

RouteRequest

name
string
Array of objects (RouteItemRequest)

Responses

Request samples

Content type
application/json
{
  • "name": "route_2",
  • "stops": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "26da0ca1-f7bb-cc51-f700-f19bfa8d9116",
  • "name": "route_2",
  • "stops": [
    ]
}

Getting a route

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

routeId
required
string <uuid>

Route identifier

Responses

Response samples

Content type
application/json
{
  • "id": "26da0ca1-f7bb-cc51-f700-f19bfa8d9116",
  • "name": "route_2",
  • "stops": [
    ]
}

Updating a route

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

routeId
required
string <uuid>

Route identifier

Request Body schema: application/json
optional

RouteRequest

name
string
Array of objects (RouteItemRequest)

Responses

Request samples

Content type
application/json
{
  • "name": "route_2",
  • "stops": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "26da0ca1-f7bb-cc51-f700-f19bfa8d9116",
  • "name": "route_2",
  • "stops": [
    ]
}

Deleting a route

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

routeId
required
string <uuid>

Route identifier

Responses

Response samples

Content type
application/json
{
  • "order_ineligible_status": {
    }
}

Asynchronous API

Creating a list of orders

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

Request Body schema: application/json
required

AsyncBulkCreateOrderRequest

Array of objects (CreateOrderRequestAsync)

Responses

Request samples

Content type
application/json
{
  • "jobs": [
    ]
}

Response samples

Content type
application/json
{
  • "token": "1355c3a0-bf35-4cbe-8854-33409379a511"
}

Getting status of creating orders

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

tokenId
required
string <uuid>

Order identifier for bulk request

Responses

Response samples

Content type
application/json
{
  • "token": "1355c3a0-bf35-4cbe-8854-33409379a511",
  • "status": [
    ]
}

Getting result of creating orders

Authorizations:
Basic
path Parameters
URL_part
required
string

Part of the URL from the Cartwheel integration settings

tokenId
required
string <uuid>

Order identifier for bulk request

Responses

Response samples

Content type
application/json
{
  • "token": "7c0b0559-1325-4879-bae5-520b9026e6ca",
  • "jobs": [
    ]
}

Release Notes

See Release Notes for the latest changes.