Context

If you have previously negotiated contracts directly with certain delivery providers, you can enter the API credentials from those delivery providers into the Burq platform. This allows you to use Burq to continue sending deliveries to those providers that you have direct relationships with, while also leveraging Burq's delivery network when better rates from other providers are available, or when extended coverage is needed.

We call this the "Bring Your Own Provider Keys" feature, aka. BYOPK.

Request Access

Any merchant can request to enable BYOPK for any provider on the Burq platform. If you have a dedicated sales person or account person, you can reach out to them for access. Otherwise, you can reach out to customer support via the dashboard chat widget. When requesting access to BYOPK, please specify the provider that you want to use.

Setup Provider Credentials

Once you receive access to the BYOPK feature, you can now access the provider management tab from the Burq Dashboard. Select the provider, and you should now see the "BYOPK" tab in the slider (as shown below):

From here, you can enter your own provider credentials.

Please note:

1. Your BYOPK credentials are test-mode-sensitive. This means the top test-mode toggle will affect the target environment in which your credentials are used for. If you enter your BYOPK credentials when the test mode toggle is on, your credentials will only be used when creating deliveries in test mode with that provider.
2. Most delivery providers send webhooks whenever your delivery status changes, and when your deliveries have to be canceled. When using BYOPK, it's important that you update your webhook setting directly with your delivery provider so that they start sending webhooks to Burq. This ensures your delivery statuses are updated in the Burq platform, and that Burq customer support team can monitor your deliveries when issues occur (such as delivery cancelation or no driver assignment). Please get the Burq webhook url from your sales/account manager or customer support representative.
3. When you are ready to go live with your own credentials, please toggle the "Enable API Key" switch from the BYOPK tab in the slider. Once toggled on, all quotes and deliveries created from this point on from the Burq platform will start using your own provider credentials.

Going Live

Once you toggled on the "Enable API Key" switch under live mode, all quotes and deliveries created from now on will be using your own credentials. The way cost information is displayed/returned may differ based on how you access the Burq platform. This difference is outlined below.

Dashboard Merchants

Merchants creating deliveries via the Burq dashboard will continue to see quote prices displayed as usual.

Once a delivery is created, however, BYOPK deliveries will show a separate section for cost factors that will be billed directly to the merchant by the provider (as shown below):

From the screenshot above, the "Total" under "Payment Details" outlines the total payable to Burq; whereas the "BYOPK Cost Factors" section outlines the various costs that merchant should expect to be billed directly by the provider.

API Merchant

Merchants creating deliveries via Burq's V1 API will see delivery cost returned directly both from the Quote API and the Delivery APIs.

Quote API Resource

When calling the Quote API, BYOPK cost is not returned under the usual fee field. Instead, you can find the cost from the byopk_cost_factors array:

"fee": 0,
"burq_fee": 99,
"byopk_cost_factors": [
  {
    "name": "Delivery Fee",
    "amount": 600
  }
],

At this time, the byopk_cost_factors array only contains one element, with the name "Delivery Fee". However, we recommend summing up the amount field from all elements in the array for forward compatibility, as additional cost factors may be added over time.

Delivery API Resource

The Delivery API Resource is returned from all v1 Delivery APIs and delivery-related webhooks. For BYOPK deliveries, costs that will be directly billed by providers to the merchants (delivery cost, tips, etc.) are not included in the usual payment_amount field. Instead, they are returned separately under the top-level byopk_cost_factors object:

"payment_amount": 99,
"tip": 0,
"fee": 0,
"byopk_cost_factors": [
  {
    "name": "Delivery Fee",
    "amount": 600
  },
  {
    "name": "Tip",
    "amount": 120
  }
],

Currently, byopk_cost_factors only contains Delivery Fee and Tip. However, we recommend summing up the amount field from all elements in the array for forward compatibility, as additional cost factors may be added over time.

BYOPK Fees

There is no additional fee for using BYOPK beyond the standard $0.99 Burq processing fee that applies to all deliveries. Merchants with negotiated rates should reach out to their sales/account manager to inquire details about their fees for BYOPK deliveries.