Context

Delivery providers on the Burq platform offer a variety of features such as signature collection from customers, return-to-store when customers are unreachable, and etc. You can leverage these features to improve delivery experience, meet compliance requirements, and improve operational efficiency. This guide covers how to request these features for each delivery while requesting quotes and creating deliveries using the "provider settings" options.

The full and updated list of provider settings can be found in the API documentation of the endpoints that support provider settings (more details below). At the time of this writing, we support the following provider settings:

signature
contactless
undeliverable_action
recipient_minimum_age (coming)

Required vs. Preferred

The Burq API supports two types of provider settings.

When required provider settings are requested, you will not receive any quotes from delivery providers who do not support all of the requested features. For example, at the time of writing, Dlivrd (a delivery provider) does not support contactless and return-to-store at the same time. Therefore, if you request both features under required provider settings, your deliveries will not see any quote from Dlivrd.

When using required provider settings, please keep in mind that each delivery provider tends to support only a subset of all the selectable features on Burq. Therefore, requiring a large number of provider settings may significantly reduce quote availability. We strongly recommend only using required provider settings for features that are essential to your delivery experience.
Preferred provider settings allow you to request features without compromising provider availability. In other words, when preferred provider settings are requested, Burq will continue to request quotes from delivery providers even if they do not support the requested features.

If you are selecting quotes with custom logic, your system can programmatically check the features supported by each provider from the Quote API resource under the provider_capability property. If Burq selects quote for you, the quote selection process will not take into account of preferred provider settings.
Once a quote is selected, Burq will forward the supported features from your preferred provider settings to the provider. If any requested features are not supported by the selected delivery provider, they will be ignored. In doing so, preferred provider settings allows you to choose, for example, the lowest cost delivery option while requesting preferred features when possible.

API

There are two APIs that accept provider settings:

/v1/quote (spec) accepts required_provider_settings. Set this property to filter quotes by providers that support all the requested features. For example, if you only want to see quotes from providers that support signature collection, you can call the API with the following required_provider_settings payload:
```
// POST /v1/quote
{
  "required_provider_settings": {
    "signature": true 
  }
}
```
Please note, this API only uses the provided required_provider_settings to filter eligible providers for quote generation. It does not, however, automatically carry over the requested settings when a delivery is eventually created from one of the quotes returned - to do that, please provide the same provider settings to /v1/delivery_information (see details below).
/v1/delivery_information (spec) accepts both required_provider_settings and preferred_provider_settings. Both properties can be provided at the same time. If you provide quote_id with required_provider_settings, an error will be returned if the provider does not support all the required provider settings.

Reroute

All required and preferred provider settings are carried over when a delivery is rerouted. This is another important consideration when setting required provider settings - excessive required provider settings can reduce quote availability, which in turn makes it more likely for reroute to fail due to lack of available providers.

API Examples

This section shows a few examples of how required_provider_settings can be used together with preferred_provider_settings.

When your customer wants a contactless delivery, but you want to make sure if the customer is not available, or declines the package, the driver brings the package back to store whenever possible, you can supply the below payload. We set undeliverable_action under preferred_provider_settings because not all providers support undeliverable action, and providers like Dlivrd don't allow contactless and return-to-store to be set together. Keeping undeliverable_action under preferred_provider_settings maximizes quote availability.

// POST /v1/delivery_information
{
  "required_provider_settings": {
    "contactless": true,
  },
  "preferred_provider_settings": {
    "undeliverable_action": "return_to_store",
  },
}

If, for however, ensuring undeliverable packages are returned to store is more important to you than quote availability or finding low cost options, you can choose to set undeliverable_action under required_provider_settings:

// POST /v1/delivery_information
{
  "required_provider_settings": {
    "contactless": true,
    "undeliverable_action": "return_to_store"
  },
}

Similarly, you can request signature alongside return-to-store undeliverable action:

// POST /v1/delivery_information
{
  "required_provider_settings": {
    "signature": true,
    "undeliverable_action": "return_to_store",
  },
}

For pharmacy deliveries, Burq requires signature to be collected and undeliverable action to be set to return-to-store. This requirement can be met by

// POST /v1/delivery_information
{
  "required_provider_settings": {
    "signature": true,
    "undeliverable_action": "return_to_store",
  },
}

Additionally, Burq also supports age verification via the recipient_minimum_age setting. Please note at the time of this writing, Uber is the only provider that supports this feature, and thus we recommend setting recipient_minimum_age under preferred_provider_settings unless you are required by law to verify recipient age for your delivery:

// POST /v1/delivery_information
{
  "required_provider_settings": {
    "signature": true,
    "undeliverable_action": "return_to_store",
  },
  "preferred_provider_settings": {
    "recipient_minimum_age": 18,
  },
}