API docs by Redocly

DSP API (1.0.5)

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 deliveries by subscribing to webhooks.

API Implementation Guidelines

Forward Compatibility:
Client implementations must ignore unknown fields in API responses to remain forward‑compatible with future extensions of this API.
When new fields are added to responses in future API versions, clients that ignore unknown fields will continue to work without modification.
Client code should always check if a field is present before accessing it.

Optional Fields in Responses:
API responses contain many optional fields (only external_delivery_id, delivery_status, fee, and currency are required in QuoteResponse).
Optional fields in responses may be omitted by the DSP API provider when their values are not available.
Sending a field explicitly as null is technically allowed, but omitting absent/empty optional fields results in cleaner payloads.

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 (required): A unique identifier of the DSP API client, generated by the provider. Recommended format: UUID string, for example 550e8400-e29b-41d4-a716-446655440000 (must be unique per client).
  • Client ID / Key ID (required): An identifier of a specific key pair (Key ID). Recommended format: UUID string, for example 5f1c9a5b-1234-4e8a-9bcd-0a1b2c3d4e5f (must be unique per key).
  • Client Secret (required): A cryptographic secret associated with the Client ID. Format: URL-safe Base64-encoded random byte sequence (no whitespace); must be at least 16 bytes of random data before encoding and the stored value must be under 255 characters.

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 in order for integrations with this DSP API to work correctly.

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 delivery. 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, address is authoritative for fee and serviceability; location is used only as a navigation hint.

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

DEPRECATED. Legacy flag indicating whether the delivery requires signature verification during drop-off. New integrations should use dropoff_options.signature instead, which supports more values than a simple boolean.

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 delivery. 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, address is authoritative for fee and serviceability; location is used only as a navigation hint.

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

DEPRECATED. Legacy flag indicating whether the delivery requires signature verification during drop-off. New integrations should use dropoff_options.signature instead, which supports more values than a simple boolean.

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"
}

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.
This endpoint is required for production integrations.
If this endpoint is not implemented (your server returns HTTP 405 / 501), then when Cartwheel needs to change an important delivery parameter (for example, pickup or dropoff time, or dropoff address), it will cancel the existing delivery and create a new one instead.
This behavior can lead to additional cancellations and re-creations at the DSP side, so you must support this endpoint to allow in-place delivery updates.

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 delivery. 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

DEPRECATED. Legacy flag indicating whether the delivery requires signature verification during drop-off. New integrations should use dropoff_options.signature instead, which supports more values than a simple boolean.

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"
}

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

Endpoints that can be optionally implemented.
If your DSP API does not support a specific optional endpoint, the server must return HTTP 405 (Method Not Allowed) or 501 (Not Implemented).
Currently only the GET delivery endpoint is optional; all other endpoints are required.

Get Delivery

Returns the status and details of a delivery that client created.
This endpoint is optional: clients can also receive delivery status updates via webhooks only.
If you choose not to implement this endpoint, your server should respond with HTTP 405 (Method Not Allowed) or 501 (Not Implemented).

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"
}

Release Notes

See Release Notes for the latest changes.