API docs by Redocly

DSP API (1.0.3)

Download OpenAPI specification:

Building Integrations with Cartwheel as DSP Service Provider

To build integrations with Cartwheel as a DSP service provider, you should build and host a DSP REST API. This API will be used for requesting deliveries.

Typical Flow for Delivery Processing

  1. Request a Quote (Optional): This will tell your client estimated pickup time and cost for your delivery.
  2. Request a Delivery.
  3. Reschedule, Modify, or Cancel the Delivery.
  4. The Delivery is Executed.

Webhooks

You can receive updates about a delivery by subscribing to webhooks.

Authorization

DSP API should be secured. Clients will authenticate themselves by presenting a Bearer token in the request header.

DSP API clients should get the following keys from the DSP API provider:

  • Developer ID
  • Client ID
  • Client Secret

Clients will use these keys to generate a JWT, and every request to DSP API will contain the JWT token in the header.
DSP API will use JWTs to authenticate users before allowing them to access the API. This is done by validating the JWT that the user sends in the Authorization header of their request.

Clients will authenticate with the following header format:

Authorization: Bearer <JWT Token>

JWT Token Structure

  1. Header:
  • The header contains two parameters:
    • dd-ver: The version of the JWT, set to "DD-JWT-V1".
    • typ: The type of token, set to "JWT".
  1. Payload (Claims):
  • The payload, represented by the claims map, contains the following key-value pairs:
    • iss: The issuer of the token, typically a developer's ID, which should be replaced with the actual developer ID.
    • kid: The key ID, which should be replaced with the actual client ID.
    • aud: The audience of the token, set to "cartwheel".
    • exp: The expiration time in UTC time zone of the token, set to 5 minutes for example (300 seconds) from the current time.
    • iat: The epoch time at which the token was issued, set to the current time.
  1. Signature:
  • The JWT is signed with an HMAC (Hash-based Message Authentication Code) using a secret key.
  • The key is derived from the client secret using Base64 URL decoding.

Provided code is a Java program that generates a JSON Web Token (JWT) using the io.jsonwebtoken library. 

public class main { 
  public static void main(String[] args) { 
    Map<String, Object> claims = new HashMap<>(); 
    // Replace these constants below with the credentials generated by the DSP Service Provider
    claims.put("iss", "{developer_id}");
    claims.put("kid", "{client_id}");

    claims.put("aud", "cartwheel");
    // Set token expiry to be one minute (5 minutes in this case)
    claims.put("exp", ZonedDateTime.now(ZoneOffset.UTC).plusMinutes(5).toEpochSecond());
    claims.put("iat", ZonedDateTime.now(ZoneOffset.UTC).toEpochSecond());

    // Replace these constants below with the credentials generated by the DSP Service Provider
    byte[] keyBytes = Decoders.BASE64URL.decode("{client _secret}");
    Key key = Keys.hmacShaKeyFor(keyBytes);
    String jwt = Jwts.builder()
            .setHeaderParam("dd-ver", "DD-JWT-V1")
            .setHeaderParam("typ", "JWT")
            .setClaims(claims)
            .signWith(key)
            .compact();

    System.out.println(jwt);
  }
}

Required Endpoints

Endpoint that requires mandatory implementation.

Create Quote

Confirms that a delivery is serviceable by DSP API and what it would cost by creating a quote. Get a quote on delivery fee and validates coverage.

Authorizations:
bearerAuth
Request Body schema: application/json

A JSON object containing quote information

external_delivery_id
required
string/[a-zA-Z0-9-._~]+/

Unique ID generated by the caller for the delivery.

pickup_address
required
string

Comma-separated full address, in the order appropriate for your locale.

pickup_business_name
string

Optional name of the place, to help Drivers find the location.

pickup_phone_number
string

The phone number for the Driver to call if there are any issues with the pick up. Should include the country code and must match the country of the store for which the delivery is created. Must adhere to E.164 international phone number standard.

pickup_instructions
string

Instructions for the Driver to follow when picking up the order.

pickup_external_store_id
string

Unique ID of the store.

external_business_id
string

Unique ID of the business that initiates a request. Should be used for billing purposes.

dropoff_address
required
string

Comma-separated full address, in the order appropriate for your locale.

dropoff_business_name
string

Dropoff Address Name. Optional name of the place, to help Drivers find the location.

object

The precise location, as latitude and longitude, of the drop-off. If request includes both location and address, location must be used for Driver navigation only; address must be used for fee and serviceability checks.

dropoff_phone_number
required
string

Drop-off Phone number. The phone number for the Driver to call if there are any issues with the delivery. Should include the country code. Must adhere to E.164 international phone number standard.

dropoff_instructions
string

Instructions for the Driver to follow when picking up the order.

dropoff_contact_given_name
string

Given/first name of the contact.

dropoff_contact_family_name
string

Family/last name of the contact.

dropoff_contact_send_notifications
boolean

Whether the notifications should be sent to contact by DSP for this delivery. The default is false.

object (DropoffOptions)

Additional options for drop off.

order_value
integer

The subtotal for all items in the order, excluding tax/tip, in the lowest currency denomination (e.g. cents). i.e. $19.99 = 1999.

Array of objects (DeliveryItem)
pickup_time
string

Time details in ISO-8601 format.

dropoff_time
string

Time details in ISO-8601 format.

contactless_dropoff
boolean

Whether the delivery should be contactless, which prompts a Driver to take a picture of the delivery at drop-off.

action_if_undeliverable
string
Enum: "return_to_pickup" "dispose"

What the Driver should do if the delivery is undeliverable. The default is 'dispose'.

tip
integer

The tip amount. Use cents or the equivalent lowest currency denomination (e.g. $5.99 = 599).

object (OrderContains)

An object that specifies the restricted item(s) contained in this order.

driver_allowed_vehicles
Array of strings

Items Enum: 'car', 'bicycle', 'walking'. The vehicle type(s) that a Driver can use to complete this delivery. The default is 'car'.

dropoff_requires_signature
boolean

Whether the delivery requires signature verification during drop-off.

dropoff_cash_on_delivery
integer

The cash to collect when this order is dropped off, value in the lowest currency denomination (e.g. cents). i.e. $19.99 = 1999.

Responses

Request samples

Content type
application/json
{
  • "external_delivery_id": "D-1763",
  • "pickup_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "pickup_business_name": "Wells Fargo SF Downtown",
  • "pickup_phone_number": "+16505555555",
  • "pickup_instructions": "Go to the bar for pick up.",
  • "pickup_external_store_id": "ase-243-dzs",
  • "external_business_id": "local_default",
  • "dropoff_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "dropoff_business_name": "The Avery Condominium",
  • "dropoff_location": {
    },
  • "dropoff_phone_number": "+16505555555",
  • "dropoff_instructions": "Enter gate code 1234 on the callbox.",
  • "dropoff_contact_given_name": "John",
  • "dropoff_contact_family_name": "Doe",
  • "dropoff_contact_send_notifications": true,
  • "dropoff_options": {
    },
  • "order_value": "1991",
  • "items": [
    ],
  • "pickup_time": "2018-08-22T17:20:28Z",
  • "dropoff_time": "2018-08-22T17:20:28Z",
  • "contactless_dropoff": "false",
  • "action_if_undeliverable": "return_to_pickup",
  • "tip": "599",
  • "order_contains": {
    },
  • "driver_allowed_vehicles": [
    ],
  • "dropoff_requires_signature": "false",
  • "dropoff_cash_on_delivery": "1999"
}

Response samples

Content type
application/json
{
  • "external_delivery_id": "D-1763",
  • "pickup_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "pickup_business_name": "Wells Fargo SF Downtown",
  • "pickup_phone_number": "+16505555555",
  • "pickup_instructions": "Go to the bar for pick up.",
  • "pickup_external_store_id": "ase-243-dzs",
  • "external_business_id": "local_default",
  • "dropoff_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "dropoff_business_name": "The Avery Condominium",
  • "dropoff_location": {
    },
  • "dropoff_phone_number": "+16505555555",
  • "dropoff_instructions": "Enter gate code 1234 on the callbox.",
  • "dropoff_contact_given_name": "John",
  • "dropoff_contact_family_name": "Doe",
  • "dropoff_contact_send_notifications": true,
  • "dropoff_options": {
    },
  • "order_value": "1999",
  • "currency": "USD",
  • "items": [
    ],
  • "delivery_status": "quote",
  • "cancellation_reason": "cancelled_by_creator",
  • "updated_at": "2018-08-22T17:20:28Z",
  • "pickup_time_estimated": "2018-08-22T17:20:28Z",
  • "pickup_time_actual": "2018-08-22T17:20:28Z",
  • "dropoff_time_estimated": "2018-08-22T17:20:28Z",
  • "dropoff_time_actual": "2018-08-22T17:20:28Z",
  • "return_time_estimated": "2018-08-22T17:20:28Z",
  • "return_time_actual": "2018-08-22T17:20:28Z",
  • "return_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "fee": "1900",
  • "fee_components": [
    ],
  • "tax": "520",
  • "tax_components": [
    ],
  • "support_reference": "86313",
  • "tracking_url": "https://dspapi.com/tracking?id=",
  • "dropoff_verification_image_url": "https://dspapi-static.s3...",
  • "pickup_verification_image_url": "https://dspapi-static.s3...",
  • "dropoff_signature_image_url": "https://dspapi-static.s3...",
  • "shipping_label": {
    },
  • "dropped_items": [
    ],
  • "contactless_dropoff": true,
  • "action_if_undeliverable": "return_to_pickup",
  • "tip": "599",
  • "order_contains": {
    },
  • "driver_allowed_vehicles": [
    ],
  • "dropoff_requires_signature": true,
  • "dropoff_cash_on_delivery": "1999",
  • "driver_id": "1232142",
  • "driver_name": "John D.",
  • "driver_dropoff_phone_number": "+15555555555",
  • "driver_pickup_phone_number": "+14444444444",
  • "driver_location": {
    },
  • "driver_vehicle_make": "Toyota",
  • "driver_vehicle_model": "Corolla Verso",
  • "driver_vehicle_year": "2003"
}

Create Delivery

Creates a delivery.

Authorizations:
bearerAuth
Request Body schema: application/json

A JSON object containing quote information

external_delivery_id
required
string/[a-zA-Z0-9-._~]+/

Unique ID generated by the caller for the delivery.

pickup_address
required
string

Comma-separated full address, in the order appropriate for your locale.

pickup_business_name
string

Optional name of the place, to help Drivers find the location.

pickup_phone_number
string

The phone number for the Driver to call if there are any issues with the pick up. Should include the country code and must match the country of the store for which the delivery is created. Must adhere to E.164 international phone number standard.

pickup_instructions
string

Instructions for the Driver to follow when picking up the order.

pickup_external_store_id
string

Unique ID of the store.

external_business_id
string

Unique ID of the business that initiates a request. Should be used for billing purposes.

dropoff_address
required
string

Comma-separated full address, in the order appropriate for your locale.

dropoff_business_name
string

Dropoff Address Name. Optional name of the place, to help Drivers find the location.

object

The precise location, as latitude and longitude, of the drop-off. If request includes both location and address, location must be used for Driver navigation only; address must be used for fee and serviceability checks.

dropoff_phone_number
required
string

Drop-off Phone number. The phone number for the Driver to call if there are any issues with the delivery. Should include the country code. Must adhere to E.164 international phone number standard.

dropoff_instructions
string

Instructions for the Driver to follow when picking up the order.

dropoff_contact_given_name
string

Given/first name of the contact.

dropoff_contact_family_name
string

Family/last name of the contact.

dropoff_contact_send_notifications
boolean

Whether the notifications should be sent to contact by DSP for this delivery. The default is false.

object (DropoffOptions)

Additional options for drop off.

order_value
integer

The subtotal for all items in the order, excluding tax/tip, in the lowest currency denomination (e.g. cents). i.e. $19.99 = 1999.

Array of objects (DeliveryItem)
pickup_time
string

Time details in ISO-8601 format.

dropoff_time
string

Time details in ISO-8601 format.

contactless_dropoff
boolean

Whether the delivery should be contactless, which prompts a Driver to take a picture of the delivery at drop-off.

action_if_undeliverable
string
Enum: "return_to_pickup" "dispose"

What the Driver should do if the delivery is undeliverable. The default is 'dispose'.

tip
integer

The tip amount. Use cents or the equivalent lowest currency denomination (e.g. $5.99 = 599).

object (OrderContains)

An object that specifies the restricted item(s) contained in this order.

driver_allowed_vehicles
Array of strings

Items Enum: 'car', 'bicycle', 'walking'. The vehicle type(s) that a Driver can use to complete this delivery. The default is 'car'.

dropoff_requires_signature
boolean

Whether the delivery requires signature verification during drop-off.

dropoff_cash_on_delivery
integer

The cash to collect when this order is dropped off, value in the lowest currency denomination (e.g. cents). i.e. $19.99 = 1999.

Responses

Request samples

Content type
application/json
{
  • "external_delivery_id": "D-1763",
  • "pickup_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "pickup_business_name": "Wells Fargo SF Downtown",
  • "pickup_phone_number": "+16505555555",
  • "pickup_instructions": "Go to the bar for pick up.",
  • "pickup_external_store_id": "ase-243-dzs",
  • "external_business_id": "local_default",
  • "dropoff_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "dropoff_business_name": "The Avery Condominium",
  • "dropoff_location": {
    },
  • "dropoff_phone_number": "+16505555555",
  • "dropoff_instructions": "Enter gate code 1234 on the callbox.",
  • "dropoff_contact_given_name": "John",
  • "dropoff_contact_family_name": "Doe",
  • "dropoff_contact_send_notifications": true,
  • "dropoff_options": {
    },
  • "order_value": "1991",
  • "items": [
    ],
  • "pickup_time": "2018-08-22T17:20:28Z",
  • "dropoff_time": "2018-08-22T17:20:28Z",
  • "contactless_dropoff": "false",
  • "action_if_undeliverable": "return_to_pickup",
  • "tip": "599",
  • "order_contains": {
    },
  • "driver_allowed_vehicles": [
    ],
  • "dropoff_requires_signature": "false",
  • "dropoff_cash_on_delivery": "1999"
}

Response samples

Content type
application/json
{
  • "external_delivery_id": "D-1763",
  • "pickup_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "pickup_business_name": "Wells Fargo SF Downtown",
  • "pickup_phone_number": "+16505555555",
  • "pickup_instructions": "Go to the bar for pick up.",
  • "pickup_external_store_id": "ase-243-dzs",
  • "external_business_id": "local_default",
  • "dropoff_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "dropoff_business_name": "The Avery Condominium",
  • "dropoff_location": {
    },
  • "dropoff_phone_number": "+16505555555",
  • "dropoff_instructions": "Enter gate code 1234 on the callbox.",
  • "dropoff_contact_given_name": "John",
  • "dropoff_contact_family_name": "Doe",
  • "dropoff_contact_send_notifications": true,
  • "dropoff_options": {
    },
  • "order_value": "1999",
  • "currency": "USD",
  • "items": [
    ],
  • "delivery_status": "quote",
  • "cancellation_reason": "cancelled_by_creator",
  • "updated_at": "2018-08-22T17:20:28Z",
  • "pickup_time_estimated": "2018-08-22T17:20:28Z",
  • "pickup_time_actual": "2018-08-22T17:20:28Z",
  • "dropoff_time_estimated": "2018-08-22T17:20:28Z",
  • "dropoff_time_actual": "2018-08-22T17:20:28Z",
  • "return_time_estimated": "2018-08-22T17:20:28Z",
  • "return_time_actual": "2018-08-22T17:20:28Z",
  • "return_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "fee": "1900",
  • "fee_components": [
    ],
  • "tax": "520",
  • "tax_components": [
    ],
  • "support_reference": "86313",
  • "tracking_url": "https://dspapi.com/tracking?id=",
  • "dropoff_verification_image_url": "https://dspapi-static.s3...",
  • "pickup_verification_image_url": "https://dspapi-static.s3...",
  • "dropoff_signature_image_url": "https://dspapi-static.s3...",
  • "shipping_label": {
    },
  • "dropped_items": [
    ],
  • "contactless_dropoff": true,
  • "action_if_undeliverable": "return_to_pickup",
  • "tip": "599",
  • "order_contains": {
    },
  • "driver_allowed_vehicles": [
    ],
  • "dropoff_requires_signature": true,
  • "dropoff_cash_on_delivery": "1999",
  • "driver_id": "1232142",
  • "driver_name": "John D.",
  • "driver_dropoff_phone_number": "+15555555555",
  • "driver_pickup_phone_number": "+14444444444",
  • "driver_location": {
    },
  • "driver_vehicle_make": "Toyota",
  • "driver_vehicle_model": "Corolla Verso",
  • "driver_vehicle_year": "2003"
}

Cancel Delivery

Cancel a delivery. Deliveries can't be cancelled after a Driver is assigned.

Authorizations:
bearerAuth
path Parameters
external_delivery_id
required
string
Example: D-1763

Unique (per client) ID of the delivery.

Responses

Response samples

Content type
application/json
{
  • "external_delivery_id": "D-1763",
  • "pickup_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "pickup_business_name": "Wells Fargo SF Downtown",
  • "pickup_phone_number": "+16505555555",
  • "pickup_instructions": "Go to the bar for pick up.",
  • "pickup_external_store_id": "ase-243-dzs",
  • "external_business_id": "local_default",
  • "dropoff_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "dropoff_business_name": "The Avery Condominium",
  • "dropoff_location": {
    },
  • "dropoff_phone_number": "+16505555555",
  • "dropoff_instructions": "Enter gate code 1234 on the callbox.",
  • "dropoff_contact_given_name": "John",
  • "dropoff_contact_family_name": "Doe",
  • "dropoff_contact_send_notifications": true,
  • "dropoff_options": {
    },
  • "order_value": "1999",
  • "currency": "USD",
  • "items": [
    ],
  • "delivery_status": "quote",
  • "cancellation_reason": "cancelled_by_creator",
  • "updated_at": "2018-08-22T17:20:28Z",
  • "pickup_time_estimated": "2018-08-22T17:20:28Z",
  • "pickup_time_actual": "2018-08-22T17:20:28Z",
  • "dropoff_time_estimated": "2018-08-22T17:20:28Z",
  • "dropoff_time_actual": "2018-08-22T17:20:28Z",
  • "return_time_estimated": "2018-08-22T17:20:28Z",
  • "return_time_actual": "2018-08-22T17:20:28Z",
  • "return_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "fee": "1900",
  • "fee_components": [
    ],
  • "tax": "520",
  • "tax_components": [
    ],
  • "support_reference": "86313",
  • "tracking_url": "https://dspapi.com/tracking?id=",
  • "dropoff_verification_image_url": "https://dspapi-static.s3...",
  • "pickup_verification_image_url": "https://dspapi-static.s3...",
  • "dropoff_signature_image_url": "https://dspapi-static.s3...",
  • "shipping_label": {
    },
  • "dropped_items": [
    ],
  • "contactless_dropoff": true,
  • "action_if_undeliverable": "return_to_pickup",
  • "tip": "599",
  • "order_contains": {
    },
  • "driver_allowed_vehicles": [
    ],
  • "dropoff_requires_signature": true,
  • "dropoff_cash_on_delivery": "1999",
  • "driver_id": "1232142",
  • "driver_name": "John D.",
  • "driver_dropoff_phone_number": "+15555555555",
  • "driver_pickup_phone_number": "+14444444444",
  • "driver_location": {
    },
  • "driver_vehicle_make": "Toyota",
  • "driver_vehicle_model": "Corolla Verso",
  • "driver_vehicle_year": "2003"
}

Optional Endpoints

Endpoint that can be optionally implemented.
Server can return the code 405 (Method Not Allowed) or 501 (Not Implemented)

Get Delivery

Returns the status and details of a delivery that client created. Client can proactively receive updates about a delivery with webhooks.

Authorizations:
bearerAuth
path Parameters
external_delivery_id
required
string

Unique (per client) ID of the delivery.

Responses

Response samples

Content type
application/json
{
  • "external_delivery_id": "D-1763",
  • "pickup_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "pickup_business_name": "Wells Fargo SF Downtown",
  • "pickup_phone_number": "+16505555555",
  • "pickup_instructions": "Go to the bar for pick up.",
  • "pickup_external_store_id": "ase-243-dzs",
  • "external_business_id": "local_default",
  • "dropoff_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "dropoff_business_name": "The Avery Condominium",
  • "dropoff_location": {
    },
  • "dropoff_phone_number": "+16505555555",
  • "dropoff_instructions": "Enter gate code 1234 on the callbox.",
  • "dropoff_contact_given_name": "John",
  • "dropoff_contact_family_name": "Doe",
  • "dropoff_contact_send_notifications": true,
  • "dropoff_options": {
    },
  • "order_value": "1999",
  • "currency": "USD",
  • "items": [
    ],
  • "delivery_status": "quote",
  • "cancellation_reason": "cancelled_by_creator",
  • "updated_at": "2018-08-22T17:20:28Z",
  • "pickup_time_estimated": "2018-08-22T17:20:28Z",
  • "pickup_time_actual": "2018-08-22T17:20:28Z",
  • "dropoff_time_estimated": "2018-08-22T17:20:28Z",
  • "dropoff_time_actual": "2018-08-22T17:20:28Z",
  • "return_time_estimated": "2018-08-22T17:20:28Z",
  • "return_time_actual": "2018-08-22T17:20:28Z",
  • "return_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "fee": "1900",
  • "fee_components": [
    ],
  • "tax": "520",
  • "tax_components": [
    ],
  • "support_reference": "86313",
  • "tracking_url": "https://dspapi.com/tracking?id=",
  • "dropoff_verification_image_url": "https://dspapi-static.s3...",
  • "pickup_verification_image_url": "https://dspapi-static.s3...",
  • "dropoff_signature_image_url": "https://dspapi-static.s3...",
  • "shipping_label": {
    },
  • "dropped_items": [
    ],
  • "contactless_dropoff": true,
  • "action_if_undeliverable": "return_to_pickup",
  • "tip": "599",
  • "order_contains": {
    },
  • "driver_allowed_vehicles": [
    ],
  • "dropoff_requires_signature": true,
  • "dropoff_cash_on_delivery": "1999",
  • "driver_id": "1232142",
  • "driver_name": "John D.",
  • "driver_dropoff_phone_number": "+15555555555",
  • "driver_pickup_phone_number": "+14444444444",
  • "driver_location": {
    },
  • "driver_vehicle_make": "Toyota",
  • "driver_vehicle_model": "Corolla Verso",
  • "driver_vehicle_year": "2003"
}

Update Delivery

Update the details of a delivery. Only the fields listed below can be updated; to update other fields, you need to cancel the delivery and then create a new one.

Authorizations:
bearerAuth
path Parameters
external_delivery_id
required
string
Example: D-1763

Unique (per client) ID of the delivery.

Request Body schema: application/json

A JSON object containing delivery information

pickup_address
string

Comma-separated full address, in the order appropriate for your locale.

pickup_business_name
string

Optional name of the place, to help Drivers find the location.

pickup_phone_number
string

The phone number for the Driver to call if there are any issues with the pick up. Should include the country code and must match the country of the store for which the delivery is created. Must adhere to E.164 international phone number standard.

pickup_instructions
string

Instructions for the Driver to follow when picking up the order.

pickup_external_store_id
string

Unique ID of the store.

external_business_id
string

Unique ID of the business that initiates a request. Should be used for billing purposes.

dropoff_address
string

Comma-separated full address, in the order appropriate for your locale.

dropoff_business_name
string

Optional name of the place, to help Drivers find the location.

object

The precise location, as latitude and longitude, of the drop-off. If request includes both location and address, location must be used for Driver navigation only; address must be used for fee and serviceability checks.

dropoff_phone_number
string

The phone number for the Driver to call if there are any issues with the delivery. Should include the country code. Must adhere to E.164 international phone number standard.

dropoff_instructions
string

Instructions for the Driver to follow when picking up the order.

dropoff_contact_given_name
string

Given/first name of the contact.

dropoff_contact_family_name
string

Family/last name of the contact.

dropoff_contact_send_notifications
boolean

Whether the notifications should be sent to contact by DSP for this delivery. The default is false.

object (DropoffOptions)

Additional options for drop off.

contactless_dropoff
boolean

Whether the delivery should be contactless, which prompts a Driver to take a picture of the delivery at drop-off.

action_if_undeliverable
string
Enum: "return_to_pickup" "dispose"

What the Driver should do if the delivery is undeliverable. The default is 'dispose'.

tip
integer

The tip amount. Use cents or the equivalent lowest currency denomination (e.g. $5.99 = 599).

object (OrderContains)

An object that specifies the restricted item(s) contained in this order.

driver_allowed_vehicles
Array of strings

Items Enum: 'car', 'bicycle', 'walking'. The vehicle type(s) that a Driver can use to complete this delivery. The default is 'car'.

dropoff_requires_signature
boolean

Whether the delivery requires signature verification during drop-off.

dropoff_cash_on_delivery
integer

The cash to collect when this order is dropped off, value in the lowest currency denomination (e.g. cents). i.e. $19.99 = 1999.

order_value
integer

The subtotal for all items in the order, excluding tax/tip, in the lowest currency denomination (e.g. cents). i.e. $19.99 = 1999.

Array of objects (DeliveryItemForUpdate)
pickup_time
string

Time details in ISO-8601 format.

dropoff_time
string

Time details in ISO-8601 format.

Responses

Request samples

Content type
application/json
{
  • "pickup_address": "string",
  • "pickup_business_name": "string",
  • "pickup_phone_number": "string",
  • "pickup_instructions": "string",
  • "pickup_external_store_id": "ase-243-dzs",
  • "external_business_id": "local_default",
  • "dropoff_address": "string",
  • "dropoff_business_name": "string",
  • "dropoff_location": {
    },
  • "dropoff_phone_number": "string",
  • "dropoff_instructions": "Enter gate code 1234 on the callbox.",
  • "dropoff_contact_given_name": "John",
  • "dropoff_contact_family_name": "Doe",
  • "dropoff_contact_send_notifications": true,
  • "dropoff_options": {
    },
  • "contactless_dropoff": true,
  • "action_if_undeliverable": "return_to_pickup",
  • "tip": "599",
  • "order_contains": {
    },
  • "driver_allowed_vehicles": [
    ],
  • "dropoff_requires_signature": true,
  • "dropoff_cash_on_delivery": "1999",
  • "order_value": "1999",
  • "items": [
    ],
  • "pickup_time": "2018-08-22T17:20:28Z",
  • "dropoff_time": "2018-08-22T17:20:28Z"
}

Response samples

Content type
application/json
{
  • "external_delivery_id": "D-1763",
  • "pickup_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "pickup_business_name": "Wells Fargo SF Downtown",
  • "pickup_phone_number": "+16505555555",
  • "pickup_instructions": "Go to the bar for pick up.",
  • "pickup_external_store_id": "ase-243-dzs",
  • "external_business_id": "local_default",
  • "dropoff_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "dropoff_business_name": "The Avery Condominium",
  • "dropoff_location": {
    },
  • "dropoff_phone_number": "+16505555555",
  • "dropoff_instructions": "Enter gate code 1234 on the callbox.",
  • "dropoff_contact_given_name": "John",
  • "dropoff_contact_family_name": "Doe",
  • "dropoff_contact_send_notifications": true,
  • "dropoff_options": {
    },
  • "order_value": "1999",
  • "currency": "USD",
  • "items": [
    ],
  • "delivery_status": "quote",
  • "cancellation_reason": "cancelled_by_creator",
  • "updated_at": "2018-08-22T17:20:28Z",
  • "pickup_time_estimated": "2018-08-22T17:20:28Z",
  • "pickup_time_actual": "2018-08-22T17:20:28Z",
  • "dropoff_time_estimated": "2018-08-22T17:20:28Z",
  • "dropoff_time_actual": "2018-08-22T17:20:28Z",
  • "return_time_estimated": "2018-08-22T17:20:28Z",
  • "return_time_actual": "2018-08-22T17:20:28Z",
  • "return_address": "901 Market Street 6th Floor San Francisco, CA 94103",
  • "fee": "1900",
  • "fee_components": [
    ],
  • "tax": "520",
  • "tax_components": [
    ],
  • "support_reference": "86313",
  • "tracking_url": "https://dspapi.com/tracking?id=",
  • "dropoff_verification_image_url": "https://dspapi-static.s3...",
  • "pickup_verification_image_url": "https://dspapi-static.s3...",
  • "dropoff_signature_image_url": "https://dspapi-static.s3...",
  • "shipping_label": {
    },
  • "dropped_items": [
    ],
  • "contactless_dropoff": true,
  • "action_if_undeliverable": "return_to_pickup",
  • "tip": "599",
  • "order_contains": {
    },
  • "driver_allowed_vehicles": [
    ],
  • "dropoff_requires_signature": true,
  • "dropoff_cash_on_delivery": "1999",
  • "driver_id": "1232142",
  • "driver_name": "John D.",
  • "driver_dropoff_phone_number": "+15555555555",
  • "driver_pickup_phone_number": "+14444444444",
  • "driver_location": {
    },
  • "driver_vehicle_make": "Toyota",
  • "driver_vehicle_model": "Corolla Verso",
  • "driver_vehicle_year": "2003"
}