Introduction
Welcome to the Budbee API!
This document contains information about endpoints that you may use to manage orders in our system.
Prerequisites
There are three mandatory steps required to create each order:
- Validate Delivery Postalcode
- Request Upcoming Intervals
- Post a valid order
Failure to complete any of these tasks may result in erronous input which would be ignored by the API.
When an order is created it is considered a complete booking and will be performed unless it is cancelled.
If you use a Transport Administration system, like Unifaun Online you must add Parcel information to the Order (the Shipping label) before we collect the parcel.
This is so our automatic terminals can scan the parcels and route it to the correct distribution vehicle.
Failure to append Parcel information will result in a cancelled order.
Available Integrations
Our API has been integrated into several existing e-commerce stores and Transport Administration systems.
If you find what you use here, you may not need to do any development at all.
Transport Management System | Link |
---|---|
Centiro | www.centiro.se |
DeliveryMatch | www.deliverymatch.eu |
Eseco | www.eseco.se |
Ingrid | www.ingrid.com |
Logtrade | www.logtrade.se |
Metapack | www.metapack.com |
nShift Delivery | www.nshift.com/solutions/delivery |
nShift DeliveryHub | www.nshift.com/solutions/delivery-hub |
nShift TMS | www.nshift.com/solutions/transport-management-system |
Paazl | www.paazl.com |
Packiyo | www.packiyo.com |
Pakketpartner | www.pakketpartner.nl |
Sendcloud | www.sendcloud.com |
Shiphero | www.shiphero.com |
Shipmondo | www.shipmondo.com |
Shops United | shops-united.nl |
Smart Send | www.smartsend.io |
Transsmart | www.nshift.com |
Webshipper | www.webshipper.com |
Zhipster | www.zhipster.se |
E-commerce platforms | Link |
---|---|
Askås | www.askas.se |
Carismar | www.carismar.com |
E37 | www.e37.se |
Golden Planet | www.goldenplanet.com |
Ingrid Checkout Widget | www.ingrid.com |
Kodmyran | www.kodmyran.se |
Logtrade Delivery Checkout | www.logtrade.se |
nShift Delivery Checkout | www.nshift.com/solutions/checkout |
Paazl Delivery Checkout | www.paazl.com |
Shopify | apps.shopify.com/budbee |
Vendre | www.vendre.se |
Wikinggruppen | www.wikinggruppen.se/ |
Woocommerce | krokedil.se/budbee |
MyCashFlow | www.mycashflow.com |
Returns management platforms | Link |
---|---|
Returnless | www.returnless.com |
Authentication
Webhooks V1 only supports HTTP Basic authentication,
WebHooks V2 supports both Basic and OAuth2 authentication
To authorize, use this code:
curl --user apiKey:apiSecret "api_endpoint_here"
Make sure to replace
apiKey
andapiSecret
with your API key and secret key.
An API user connects to the API via TLS (HTTPS) and authenticates with Basic Authentication. Budbee generates public and private keys for each API users, one set of keys for the sandbox and one set for the production environment.
Use the API Key as username and API Secret as password in the Basic Authentication
Authorization: Basic base64_encode(apiKey:apiSecret)
Environment | URL |
---|---|
Sandbox | https://api.staging.budbee.com |
Production | https://api.budbee.com |
Serialization
This is a REST JSON API.
Dates are serialized as Unix Epoch timestamps in milliseconds unless otherwise documented.
When your application deserializes JSON it should ignore unknown fields, as additional fields may be added without prior notice.
Breaking changes will be implemented in a new version of the API - The versioning is set in the Content-Type
header.
Deprecated versions of the API endpoints will be supported for at least 6 months.
Rate limits
Rate Limits for the public API help control the rate of traffic.
The limit is the specified number of requests per 5-minute time span
If you attempt to access the API in a rate above the limits, we will return HTTP 429 until the rate falls below the limit.
The rate limits is divided into three separate type of tiers:
Type | Tier | Limit |
---|---|---|
Creating data (POST requests) | Tier 1 | Max 300 requests |
Reading data (GET requests) | Tier 2 | Max 1.000 requests |
Validating data (GET requests to specific endpoints) | Tier 3 | Max 5.000 requests |
For each endpoint documented you will see which tier it is rate limited to
Sender Addresses
Sender Addresses are the registered locations where Budbee will pickup the Merchants parcels.
Get all Sender Addresses
curl "https://api.budbee.com/users/collection-points"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.users-v1+json"
The above command returns JSON structured like this:
[
{
"id": 2672,
"name": "Merchant Warehouse",
"referencePerson": "John Doe",
"telephoneNumber": "+46700000000",
"address": {
"id": 8793,
"street": "Sender Street 1",
"postalCode": "16353",
"city": "Stockholm",
"country": "SE"
},
"doorCode": "",
"outsideDoor": false,
"defaultCollectionPoint": true
},
{
"id": 7313,
"name": "Merchant Warehouse 2",
"referencePerson": "Jane Doe",
"telephoneNumber": "+46700000000",
"address": {
"id": 8797,
"street": "Sender Street 2",
"postalCode": "40010",
"city": "Göteborg",
"country": "SE"
},
"doorCode": "",
"outsideDoor": false,
"defaultCollectionPoint": false
}
]
This endpoint retrieves all Sender addresses
HTTP Request
GET https://api.budbee.com/users/collection-points
Delivery Postalcode Validation
Before home [delivery + return] orders are created, it is crucial that the consumer postalcode is validated. Failure to do so may result in the order not being created. This validation should solely be used for the home delivery and return services.
Validate Postalcode
curl "https://api.budbee.com/postalcodes/validate/SE/11453"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.postalcodes-v2+json"
The above command will generate a JSON array containing the Sender addresses that this Delivery postalcode may be used in conjuction with when creating an order:
[
{
"id": 2672,
"name": "Merchant Warehouse",
"referencePerson": "John Doe",
"telephoneNumber": "+46700000000",
"address": {
"id": 8793,
"street": "Sender Streeet 1",
"postalCode": "16353",
"city": "Stockholm",
"country": "SE"
},
"doorCode": "",
"outsideDoor": false,
"defaultCollectionPoint": true,
"fossilFree": true
}
]
You may display and select Budbee as a Shipping option if the recipients postal code is within the Budbee Delivery Area.
This endpoint returns either 200 OK (Postal code is within Delivery Area) or 404 Not Found (Postal code is outside of Delivery Area)
Additionally, the response body contains the Merchants sender addresses that is applicable for this Delivery postal code.
If there are different sender addresses per country (E.g Sweden and Finland) you may use this result to decide what sender address to use.
A valid postal code may be serviced by a fossil free delivery vehicle, such as an Electrical delivery van or bicycle. the fossilFree
field (boolean)
indicates if this postal code is serviced by such a vehicle.
HTTP Request
GET https://api.budbee.com/postalcodes/validate/{countryCode}/{postalCode}
Status Codes
Code | Description |
---|---|
200 | Budbee performs deliveries in this Postal Code |
404 | Postal Code is invalid |
Path parameters
Parameter | Type | Description |
---|---|---|
countryCode | String | Recipient Country code ISO 3166-1 alpha-2 e.g. “SE” |
postalCode | String | The delivery Postalcode to validate |
Postal Code list
curl "https://api.budbee.com/postalcodes/SE"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.postalcodes-v1+json"
The above command returns a JSON array containing all valid postalcodes that Budbee performs deliveries in.
[
"10012",
"10026",
"10027",
"10028",
"10029",
"10031",
"10040"
]
This endpoint retrieves all postalcodes that Budbee performs deliveries in, separated by Country.
HTTP Request
GET https://api.budbee.com/postalcodes/{countryCode}
Path parameters
Parameter | Type | Description |
---|---|---|
countryCode | String | Recipient Country code ISO 3166-1 alpha-2 e.g. “SE” |
Estimated Delivery Date
You may display an estimated Delivery time to show solely for Home deliveries for recipients in the Checkout. We will return our estimates based on the deadlines you have for pick-and-pack and pick-up schedules.
Get Upcoming Delivery Windows
This endpoint will retrieve upcoming delivery windows for a specific delivery postalcode.
We use Unix epoch time in milliseconds, and the timezone we return is always in UTC (GMT+0)
A valid postal code may be serviced by a fossil free delivery vehicle, such as an Electrical delivery van or bicycle. the fossilFree
field (boolean)
indicates if this postal code is serviced by such a vehicle.
curl "https://api.budbee.com/intervals/SE/11453/1"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.intervals-v2+json"
The above command will retrieve 1 upcoming interval for the postalcode 11453:
[
{
"collection": {
"start": 1479880800000,
"stop": 1479916800000
},
"delivery": {
"start": 1479884400000,
"stop": 1479916800000
},
"collectionPointIds": [
2
],
"fossilFree": true
}
]
curl "https://api.budbee.com/intervals/SE/11453/2016-12-01/2016-12-02"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.intervals-v2+json"
The above command will retrieve intervals between 2016-12-01 and 2016-12-02 for postalcode 11453:
[
{
"collection": {
"start": 1480572000000,
"stop": 1480608000000
},
"delivery": {
"start": 1480575600000,
"stop": 1480608000000
},
"collectionPointIds": [
2
],
"fossilFree": true
},
{
"collection": {
"start": 1480658400000,
"stop": 1480712400000
},
"delivery": {
"start": 1480687200000,
"stop": 1480712400000
},
"collectionPointIds": [
2
],
"fossilFree": true
}
]
HTTP Request
GET https://api.budbee.com/intervals/{countryCode}/{postalCode}/{n}
GET https://api.budbee.com/intervals/{countryCode}/{postalCode}/{toDate}
GET https://api.budbee.com/intervals/{countryCode}/{postalCode}/{fromDate}/{toDate}
Status Codes
Code | Description |
---|---|
200 | OK, body contains list of Intervals |
404 | Postal Code is invalid or no Intervals are available |
Path parameters
Parameter | Type | Description |
---|---|---|
countryCode | String | Recipient Country code ISO 3166-1 alpha-2 e.g. “SE” |
n | Integer | Number of intervals to request (limit 20) |
toDate | Date | Intervals up to and including a date (YYYY-MM-DD) |
fromDate | Date | Intervals from and including a date (YYYY-MM-DD) |
Orders
To create an order you need to populate these required fields:
- cart
- cartId
- articles
- collectionId
- delivery
- name
- telephoneNumber
- address
- street
- postalCode
- city
- country
- outsideDoor
- requireSignature
Each object is described in detail below
Objects
Cart
The cart
consists of a mandatory cartId
that should be a unique identifier describing the purchase in your e-commerce store. Most e-commerce softwares call this “order number”. Additionally it allows you to specify the products sold to the consumer, this data is used to enable & simply the claims process.
Field | Type | Max len. | Optional | Description |
---|---|---|---|---|
cartId | string | 255 | false | The sales order number from your e-commerce software |
articles | Products | N/A | false | List of products sold in this shipment |
Products
Products (or articles) describe each individual product sold to the consumer that is being shipped in this Order.
This information is used for a variety of features, such as an improved return experience, claims management among other things.
Field | Type | Max len. | Optional | Description |
---|---|---|---|---|
name | string | 255 | false | The name of the product as presented to the consumer in checkout |
reference | string | 255 | false | The reference for the product, such as SKU, EAN etc. |
quantity | number | N/A | false | The quantity of this product sold |
unitPrice | number | N/A | false | The price (including VAT) of the product, in cents, e.g. “199” cents equals “1,99 EUR” |
currency | ISO4217 currency | N/A | false | The currency of the price, e.g. “EUR”, “SEK”, “USD” |
taxRate | number | N/A | true | Percentual VAT of the product, e.g. “2500” equals “25%” |
discountRate | number | N/A | true | Percentual discount rate of the product, eg. 10% = 1000 |
{
"cart": {
"cartId": "123456",
"articles": [
{
"name": "High Sneakers - Blue",
"reference": "VJ215A02F-A12",
"quantity": 1,
"unitPrice": 16000, // 160.00 EUR
"currency": "EUR",
"taxRate": 2500,
"discountRate": 0
},
{
"name": "Melody JACKET - Winter coat",
"reference": "LE225G05F-T12",
"quantity": 1,
"unitPrice": 19999, // 199.99 EUR
"currency": "EUR",
"taxRate": 2500,
"discountRate": 0
}
]
}
}
Delivery
The delivery
object describes the consumer and delivery address for an order.
You may at any time update the consumer information, but you may never update the delivery address on an order. To change either delivery address or interval see Update Interval or Address
Field | Type | Max len. | Optional | Description |
---|---|---|---|---|
name | string | 255 | false | Name of the recipient, e.g “John Doe” or “Company Ltd.” |
referencePerson | string | 255 | true | Reference person of the recipient, e.g. “John Doe” |
socialSecurityNumber | string | 255 | true | Social Security Number of the recipient |
telephoneNumber | string | 255 | false | The telephone number of recipient, prefferably mobile phone |
string | 255 | false | The email of the recipient | |
address | Address | N/A | false | See Address |
doorCode | string | 255 | true | Doorcode |
outsideDoor | boolean | N/A | false | Is it ok to leave shipment outside door if recipient is not at home |
additionalInfo | string | N/A | true | Additional info to us and/or driver regarding shipment |
Address
Field | Type | Max len. | Optional | Description |
---|---|---|---|---|
street | string | 255 | false | Street name and number of address |
street2 | string | 255 | true | Street name two, e.g. apartment number |
postalCode | string | 255 | false | Postalcode |
city | string | 255 | false | City |
country | string | 2 | false | Country code ISO 3166-1 alpha-2 e.g. “SE” |
{
"name": "<string>",
"referencePerson": "<string>",
"socialSecurityNumber": "<string>",
"telephoneNumber": "<string>",
"email": "<string>",
"address": {
"street": "<string>",
"street2": "<string>",
"postalCode": "<string>",
"city": "<string>",
"country": "<string>"
},
"doorCode": "<string>",
"outsideDoor": <boolean>,
"additionalInfo": "<string>"
}
Additional Services
additionalServices
defines extra settings available for each order, such as identification checking, if the recipient must be the same as the end customer etc.
Field | Default value | Description |
---|---|---|
identificationCheckRequired | false | Driver must check identification at delivery |
recipientMinimumAge | 0 | The recipient must be at least this old at delivery |
recipientMustMatchEndCustomer | false | The recipient must be the same person that booked the order |
numberOfMissRetries | null | Number of times that a failed delivery may be retried until returned to your Warehouse (null for infinite) |
{
"identificationCheckRequired": <boolean>,
"recipientMinimumAge": <integer>,
"recipientMustMatchEndCustomer": <boolean>,
"numberOfMissRetries": <integer>
}
Parcels
Parcels have a shipment number (unique per order/shipment) and a package number (unique per parcel).
Parcels may also have optional Dimensions.
If you supply empty values in either shipmentId or packageId we will generate values for you.
Field | Type | Max len. | Optional | Description |
---|---|---|---|---|
shipmentId | string | 255 | true | The shipment number (Must be unique per shipment/order) |
packageId | string | 255 | true | The package number (Must be unique per Parcel) |
dimensions | Dimensions | N/A | true | Dimensions of Parcel |
{
"shipmentId": "<string>",
"packageId": "<string>",
"dimensions": {
"width": <integer of width in cm>,
"height": <integer of height in cm>,
"length": <integer of length in cm>,
"weight": <integer of weight in grams>,
"volume": <integer of volume in cm3>
}
}
Dimensions
Field | Type | Description |
---|---|---|
width | int | Width in centimeters |
height | int | Height in centimeters |
length | int | Length in centimeters |
weight | int | Weight in gram |
volume | int | Volume in cubic centimeters (cm3) |
Create Order
You must perform all required steps above before creating an order. All required fields in an order must exist.
If order is created we return 200 OK
along with the created order in the body.
You must handle the response in case of error
Status Codes
Code | Description |
---|---|
200 | Order created |
400 | Bad Request – Your request is wrong |
401 | Unauthorized – Your API key is wrong |
403 | Forbidden – One or more fields you have supplied have invalid values |
422 | Validation Error. You have supplied something that cannot be parsed |
500 | Internal Server Error – We had a problem with our server. Try again later. |
502 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |
503 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |
curl "https://api.budbee.com/multiple/orders"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v2+json"
-X POST -d
{
"collectionId": 2672,
"cart": {
"cartId": "0000001",
"articles": [
{
"name": "High Sneakers - Blue",
"reference": "VJ215A02F-A12",
"quantity": 1,
"unitPrice": 16000, // 160.00 EUR
"currency": "EUR",
"taxRate": 2500,
"discountRate": 0
},
{
"name": "Melody JACKET - Winter coat",
"reference": "LE225G05F-T12",
"quantity": 1,
"unitPrice": 19999, // 199.99 EUR
"currency": "EUR",
"taxRate": 2500,
"discountRate": 0
}
]
},
"delivery": {
"name": "John Doe",
"referencePerson": null,
"socialSecurityNumber": "19891109-8690",
"telephoneNumber": "+46700000000",
"email": "john.doe@budbee.com",
"address": {
"street": "Grevgatan 9",
"street2": "LGH 1601",
"postalCode": "11453",
"city": "Stockholm",
"country": "SE"
},
"doorCode": "1337",
"outsideDoor": true,
"additionalInfo": "I live on the 6th floor"
},
"requireSignature": false,
"additionalServices": {
"identificationCheckRequired": false,
"recipientMinimumAge": 0,
"recipientMustMatchEndCustomer": false,
"numberOfMissRetries": null
}
}
Set delivery date
Set the delivery date of an Order by supplying a valid value generated by the Estimated Delivery Date endpoint.
The input will be validated, and rejected if not valid / has expired.
curl "https://api.budbee.com/multiple/orders"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v2+json"
-X POST -d
{
"interval": {
"delivery": {
"start": 1556636400000,
"stop": 1556654400000
}
},
"collectionId": 2672,
"cart": {
"cartId": "0000001"
},
"delivery": {
"name": "John Doe",
"referencePerson": null,
"socialSecurityNumber": "19891109-8690",
"telephoneNumber": "+46700000000",
"email": "john.doe@budbee.com",
"address": {
"street": "Grevgatan 9",
"street2": "LGH 1601",
"postalCode": "11453",
"city": "Stockholm",
"country": "SE"
},
"doorCode": "1337",
"outsideDoor": true,
"additionalInfo": "I live on the 6th floor"
},
"requireSignature": false,
"additionalServices": {
"identificationCheckRequired": false,
"recipientMinimumAge": 0,
"recipientMustMatchEndCustomer": false,
"numberOfMissRetries": null
}
}
Retrieve a Specific Order
This will retrieve a specific order
curl "https://api.budbee.com/multiple/orders/e140396d-5679-4211-96f8-c6c877b43186"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v1+json"
HTTP Request
GET https://api.budbee.com/multiple/orders/{id}
Status Codes
Code | Description |
---|---|
200 | OK, body contains Order |
404 | Order not found |
Path parameters
Parameter | Type | Description |
---|---|---|
id | uuid | The id of the order |
Update Consumer information
This will update the information about the End Customer on an order.
curl "https://api.budbee.com/multiple/orders/e140396d-5679-4211-96f8-c6c877b43186"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v1+json"
-X PUT -d
{
"name": "Jane Doe",
"referencePerson": "John Doe",
"socialSecurityNumber": "19900205-9146",
"telephoneNumber": "+46700000001",
"email": "jane.doe@budbee.com",
"doorCode": "1337",
"outsideDoor": true,
"additionalInfo": "We moved to the 5th floor, its all downhill from here"
}
HTTP Request
PUT https://api.budbee.com/multiple/orders/{id}
Status Codes
Code | Description |
---|---|
200 | OK, body contains updated Order |
404 | Order not found |
Path parameters
Parameter | Type | Description |
---|---|---|
id | uuid | The id of the order |
Update Delivery Date or Address
To change delivery address or date, cancel it and create a new order.
Cancel an Order
This will cancel an order. Once an order is cancelled, it can not be undone.
curl "https://api.budbee.com/multiple/orders/e140396d-5679-4211-96f8-c6c877b43186"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v1+json"
-X DELETE
HTTP Request
DELETE https://api.budbee.com/multiple/orders/{id}
Status Codes
Code | Description |
---|---|
204 | Order cancelled |
403 | Not allowed to cancel Order |
404 | Order not found |
Path parameters
Parameter | Type | Description |
---|---|---|
id | uuid | The id of the order |
Parcels
Add Parcels to an existing Order
You can populate multiple parcels per Order.
Either supply existing unique shipment number and package numbers in the respective shipmentId
and packageId
fields, or leave the fields blank and we will generate values for you.
curl "https://api.budbee.com/multiple/orders/e140396d-5679-4211-96f8-c6c877b43186/parcels"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v2+json"
-X POST -d
[
{
"shipmentId": "6178966427",
"packageId": "373325380927798300",
"dimensions": {
"weight": 2400
}
}
]
The above request returns JSON structured like this:
[
{
"id": 123,
"shipmentId": "6178966427",
"packageId": "373325380927798300",
"label": "https://api.budbee.com/orders/e140396d-5679-4211-96f8-c6c877b43186/373325380927798300/label"
}
]
Leave blank values for Budbee generated ID’s:
curl "https://api.budbee.com/multiple/orders/e140396d-5679-4211-96f8-c6c877b43186/parcels"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v2+json"
-X POST -d
[
{
"shipmentId": "",
"packageId": "",
"dimensions": {
"weight": 2400
}
}
]
The above request returns JSON structured like this:
[
{
"id": 123,
"shipmentId": "73501099200000086",
"packageId": "735010992000000082",
"label": "https://api.budbee.com/orders/e140396d-5679-4211-96f8-c6c877b43186/735010992000000082/label"
}
]
HTTP Request
POST https://api.budbee.com/multiple/orders/{id}/parcels
Accept: application/vnd.budbee.multiple.orders-v2+json
Status Codes
Code | Description |
---|---|
200 | Parcels created |
404 | Order not found |
Path parameters
Parameter | Type | Description |
---|---|---|
id | uuid | The id of the order |
Remove a Parcel
This will remove a Parcel from an Order. You can do this until the Parcel has been picked up by Budbee.
curl "https://api.budbee.com/multiple/orders/e140396d-5679-4211-96f8-c6c877b43186/parcels/123"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v1+json"
-X DELETE
HTTP Request
DELETE https://api.budbee.com/multiple/orders/{id}/parcels/{parcelId}
Status Codes
Code | Description |
---|---|
204 | Deleted Parcel |
403 | Not allowed to delete Parcel |
404 | Parcel not found |
Path parameters
Parameter | Type | Description |
---|---|---|
id | uuid | The id of the order |
parcelId | id | The id of the parcel |
Shipping Labels
In the response body of a Parcel there is a URL to a shipping label that can be printed.
The generated shipping label is a PDF file of 10x15cm, for other formats, supply any of these query parameters:
Parameter | Values |
---|---|
fileType | pdf, zpl |
documentSize | 10x15 |
ZPL label in 10x15cm
https://url/label?X-Budbee-Algorithm=BUDBEE1-HMAC-SHA256&X-Budbee-Date=20210101T101000Z&X-Budbee-Expires=172800&X-Budbee-Signature=xxxxx**&fileType=zpl&size=10x15**
Presigned URL
The URL returned by the Budbee API is pre-signed using query-string parameters. This differs from other endpoints that uses Authorization HTTP headers, as this is useful for enabling direct third-party browser/printer access to your private shipping labels, without proxying the request.
Additionally, the pre-signed URL is valid for 48 hours, afterwards it will expire and the label is no longer available. It is not possible to request the label without this signature.
The URL will contain the following query parameters:
Parameter | Description |
---|---|
X-Budbee-Algorithm | Algorithm used to create signature |
X-Budbee-Date | Date URL was pre-signed (UTC) |
X-Budbee-Expires | Seconds from X-Budbee-Date the URL will expire |
X-Budbee-Signature | Pre-signed signature |
You do not need to compute any of these values yourself, it will be returned in the API.
The query parameters above are percent-encoded, so you should not URL encode it again, as that would result in an invalid signature.
Track & Trace
You may want to notify recipients about upcoming shipments with Budbee.
Recipients may only edit information about their shipment if the tracking link is authenticated and comes for a secure source. You can request such a link with the following resource.
Request Tracking link for Order
This will retrieve a tracking link for a specific order. This will be the same link that we send to recipients from our service.
curl "https://api.budbee.com/multiple/orders/e140396d-5679-4211-96f8-c6c877b43186/tracking-url"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v1+json"
{
"url": "https://bdb.ee/abc123"
}
curl "https://api.budbee.com/parcels/00373325381304831806/tracking-url"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.parcels-v1+json"
{
"url": "https://bdb.ee/abc123"
}
HTTP Request
GET https://api.budbee.com/multiple/orders/{id}/tracking-url
GET https://api.budbee.com/parcels/{packageId}/tracking-url
Path parameters
Parameter | Type | Description |
---|---|---|
id | uuid | The id of the order |
Parameter | Type | Description |
---|---|---|
packageId | string | The package ID of the Parcel |
Returns
Standalone returns mean that the delivery could have been performed with another courier than Budbee, i.e it is standalone from the original delivery order.
Return Pickup
This method allows you to book a standalone Return Pickup.
Budbee will notify consumer about the upcoming pickup and perform the pickup during the first available time window and return it to the Merchants specified address.
Create Return Pickup
To create a standalone return pickup you need to populate the required fields:
Field | Type | Description |
---|---|---|
cartId | string | Unique Merchant Order identification |
warehouseId | number | Registered Return Address |
consumer | Consumer | Contact information to Consumer |
numberOfParcels | number | Number of Parcels to pick up |
Consumer
Field | Type | Optional | Description |
---|---|---|---|
name | string | false | Name of consumer |
referencePerson | string | true | Reference person of the consumer |
telephoneNumber | string | false | The consumers telephone number |
string | false | The consumers email | |
address | Address | false | The pickup address |
doorCode | string | true | Doorcode at pickup address |
additionalInfo | string | true | Additional Information left by consumer |
Pickup Address
Field | Type | Optional | Description |
---|---|---|---|
street | string | false | Street name incl. house number |
street2 | string | true | Street2, eg apartment number |
postalCode | string | false | Postal code |
city | string | false | City |
country | string | false | Country Code ISO 3166-1 alpha-2 |
curl "https://api.budbee.com/returns"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.returns-v1+json"
-X POST -d
{
"cartId": "0000001",
"warehouseId": 2672,
"consumer": {
"name": "John Doe",
"referencePerson": null,
"telephoneNumber": "+46700000000",
"email": "john.doe@budbee.com",
"address": {
"street": "Grevgatan 9",
"street2": "LGH 1601",
"postalCode": "11453",
"city": "Stockholm",
"country": "SE"
},
"doorCode": "1337",
"additionalInfo": "I live on the 6th floor"
},
"numberOfParcels": 1
}
The above request results in a response structured like this:
{
"id": "8c96ab59-aea8-4dba-917f-12cfdc55fa39",
"token": "0p7v2rp4",
"interval": {
"start": "2020-12-02T16:00:00.000Z",
"stop": "2020-12-02T21:00:00.000Z"
},
"returnWarehouse": {
"id": 2672,
"name": "Your warehouse",
"referencePerson": null,
"telephoneNumber": "+46700000000",
"address": {
"street": "Street 1",
"postalCode": "11111",
"city": "Stockholm",
"country": "SE"
}
},
"consumer": {
"name": "John Doe",
"referencePerson": null,
"telephoneNumber": "+46700000000",
"email": "john.doe@budbee.com",
"address": {
"street": "Grevgatan 9",
"street2": "LGH 1601",
"postalCode": "11453",
"city": "Stockholm",
"country": "SE"
}
},
"createdAt": "2020-12-01T15:01:41.000Z",
"updatedAt": "2020-12-01T15:01:41.000Z",
"parcels": [
{
"shipmentId": "6178966427",
"packageId": "373325380927798300",
"label": "https://api.budbee.com/orders/8c96ab59-aea8-4dba-917f-12cfdc55fa39/373325380927798300/label"
}
]
}
Return Drop Off
This method allows you to create a standalone box return drop-off order, which means that the delivery could have been performed with another carrier than Budbee.
When the call has been made, Budbee will notify the consumer about the initiated box return drop-off. The consumer will choose preferred return box. Budbee will pick up the return parcel at the chosen box and return it to the Merchants specified address.
Create Return Drop Off
To create a standalone return drop off you need to populate the required fields:
Field | Type | Optional | Description |
---|---|---|---|
cartId | string | false | Unique Merchant Order identification |
warehouseId | number | false | Registered Return Address |
consumer | Consumer | false | Contact information to Consumer |
lockerId | string | false | Id of the locker, e.g. “BOX0000” |
dimensions | Dimensions | false | see Dimensions |
Consumer
Field | Type | Optional | Description |
---|---|---|---|
name | string | false | Name of consumer |
telephoneNumber | string | false | The consumers telephone number |
string | false | The consumers email | |
address | Address | false | Address of the consumer |
Consumer Address
Field | Type | Optional | Description |
---|---|---|---|
street | string | false | Street name incl. house number |
postalCode | string | false | Postal code |
city | string | false | City |
country | string | false | Country Code ISO 3166-1 alpha-2 |
Dimensions
Field | Type | Optional | Description |
---|---|---|---|
width | int | false | Width in centimeters |
length | int | false | Length in centimeters |
height | int | false | Height in centimeters |
weight | int | true | Weight in gram |
volume | int | true | Volume in cubic centimeters (cm3) |
curl "https://api.budbee.com/box/return"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.standalone-box-returns-v1+json"
-X POST -d
{
"warehouseId":99,
"cartId":"CartId9999",
"consumer":{
"name":"John Doe",
"phoneNumber":"+330000000000",
"email":"john.Doe@budbee.com",
"address":{
"street":"Liberty Street 123",
"postalCode":"12345",
"city":"Amsterdam",
"country":"NL"
}
},
"lockerId":"BOX0001",
"dimensions":{
"width":100,
"length":100,
"height":100,
"weight":1,
"volume":1000000
}
}
The above request results in a response structured like this:
{
"id":"8c96ab59-aea8-4dba-917f-12cfdc55fa39",
"token":"fgb4d34",
"cartId":"CartId9999",
"returnWarehouse":{
"id":99,
"name":"Bumble & Bumble",
"referencePerson":"Ann Dogney",
"phoneNumber":"+357843748 ",
"address":{
"street":"Vasa street 1",
"postalCode":"30922",
"city":"Amsterdam",
"country":"NL"
}
},
"consumer":{
"name":"John Doe",
"phoneNumber":"+330000000000",
"email":"john.doe@budbee.com",
"address":{
"street":"Liberty Street 123",
"postalCode":"12345",
"city":"Amsterdam",
"country":"NL"
}
},
"parcels":[
{
"shipmentId":"6178966427",
"packageId":"373325380927798300",
"label":"https://api.budbee.com/orders/8c96ab59-aea8-4dba-917f-12cfdc55fa39/373325380927798300/label"
}
],
"lockerId":"BOX0001",
"dimensions":{
"width":100,
"length":100,
"height":100,
"weight":1,
"volume":1000000
},
"createdAt":"2020-12-01T15:01:41.000Z",
"updatedAt":"2020-12-01T15:01:41.000Z"
}
Webhook Callbacks
You can subscribe to API Callbacks via Webhooks to get notified about events for Orders. Your webservice must respond with 200 OK for all webhooks. If the request fails (not 200 OK) we will retry 10 times, with 30 minute intervals. If the request still fails after that the Webhook will be deleted and you may re-subscribe to it once your webservice is functional.
You can subscribe to these different webhooks by either creating them via the API, or adding them manually through our web interface:
Type | Explanation |
---|---|
Order Status Updates | Updates on Order Statuses, including “On Route to Collection”, “Collected”, “On Route to Delivery”, “Delivered” |
Misses | Failed deliveries |
Cancellations | Cancelled Orders |
Ratings | Ratings on Orders left by End Customer |
End Customer Edits | Edits of End Customer information, like name and telephone number |
Delivery Address Edits | Edits of Delivery Address information, like doorcode |
Order Settings Edits | Edits of Order Settings, like outsideDoorOk |
Security
We sign each request made to your service using the merchants Secret API key.
The signature (found in the X-Budbee-Signature
header) is a SHA-1 HMAC hash of the request body.
Optionally you can also supply username/password credentials that we will attach in every request using Basic authentication (in the Authorization
header). You can supply credentials when subscribing:
{
"url": "http://yourserver.com/callbacks/status-updates",
"username": "foobar",
"password": "letmein"
}
HTTPS is needed for keeping the credentials and data secure on webhooks integration
OAuth2 authentication is supportad by WebHooks V2
Webhooks V2
Configure Webhooks V2
- Go to https://buyer.budbee.com
- Click on the “Profile” tab
- Scroll down to the “Webhooks V2” section
- Enter the HTTP endpoint where all webhooks for V2 will be sent to
- Provide a contact email to be used about notifications regarding webhooks
- Select the authentication type (HTTP Basic or OAuth2)
- For HTTP Basic authentication provide:
- Specify a username and password that will be used to secure the webhook with HTTP Basic Auth
- For OAuth2:
- Token endpoint
- Client ID
- Client Secret
- Scope (optional)
- For HTTP Basic authentication provide:
- Click “Save”
Security
Basic and OAuth2 authentication is supported by WebHooks V2
Basic Authentication
In the merchants portal a username and password must be provided when setting up the webhook integration.
These credentials will be used for generating the HTTP Basic Authorization header on each webhook request.
The header will be as Authorization: Basic BASE_64({USERNAME}:{PASSWORD})
OAuth2 Authentication
As an alternative to Basic, we also support OAuth2 for authentication on Webhooks V2.
Refer to Configure Webhooks V2 for configuration.
The header will be as Authorization: Bearer <access_token>
Webhook Request
Headers
Name | Description or Value |
---|---|
Authorization | Auth token (Basic or OAuth2) |
Budbee-Event | Name of the event that triggered the webhook |
Budbee-Event-ID | ID of the event |
Content-Type | application/json |
Timestamp | Time of when the event was triggered |
Body
{
"event": "PARCEL_CREATED",
"eventData": {
"tmsId": "ABCD",
"cartId": "1234",
"budbeeOrderToken": "a75dd44k",
"shipmentId": "0000A5464644",
"packageId": "3573847654593475837465345"
}
}
The property
eventData
structure will change given the type of event. Check with each individual event to see what data will be included
Common properties for eventData
Property | Data Type | Description |
---|---|---|
tmsId |
String | This is a Budbee generated ID that is used to identify an order in the API integration |
cartId |
String | This is an identifier supplied by the merchant for the order/purchase |
budbeeOrderToken |
String | Budbee generated token used for tracking |
shipmentId |
String | Shipment number/identifier |
packageId |
String | Package number |
timestamp |
Date Time | Time of when the event occurred |
Retries
If a response is received with a status code that is not 2XX or no response received with 15 seconds, then the HTTP request will be sent again. There will be a delay between each reattempt with a maximum number of attempts.
Data Types
Name | JSON Type | Description |
---|---|---|
String | String | Free text value |
Date Time | String | A date time in ISO 8601 (UTC) format. Example: "2020-01-01T12:00:00.000Z" |
Party | String | Either "BUDBEE" , "CONSUMER" , or "MERCHANT" |
Flow | String | Either "DELIVERY" , "RETURN" , or "C2C" |
Events
All of the following events will include these listed properties in
eventData
as described above:
tmsId
cartId
budbeeOrderToken
shipmentId
packageId
timestamp
Events that contain extra properties will be described in the events section.
PARCEL_CREATED
A parcel has been electronically received and registered by Budbee.
Property | Data Type | Description |
---|---|---|
responsible |
Party | Who was responsible for creating the parcel |
SORTED_AT_TERMINAL
The parcel has been sorted a Budbee terminal.
Property | Data Type | Description |
---|---|---|
city |
String | The city where the terminal is located |
postalCode |
String | The postal code of the terminal location |
address |
String | The address of the terminal |
PARCEL_RECALLED
A parcel has been set to be returned to the merchant.
Property | Data Type | Description |
---|---|---|
reason |
String | A reason as to why it has been recalled |
responsible |
Party | Who was responsible for recalling the parcel |
HOME_DELIVERY_CHANGED
The delivery for a parcel to the consumers home has been changed.
Property | Data Type | |
---|---|---|
intervalStart |
Date Time | Timestamp of the start of scheduled time window expected to be delivered in |
intervalStop |
Date Time | Timestamp of the end of scheduled time window expected to be delivered in |
responsible |
Party | Who was responsible for changing the delivery |
DELIVERED_TO_CONSUMER
The parcel was successfully delivered to the consumer.
Property | Data Type | Description |
---|---|---|
deliveryInformation |
String | Any additional information about how the parcel was delivered |
DELIVERY_FAILED
Budbee was unable to deliver the parcel to the consumer.
Property | Data Type | Description |
---|---|---|
reason |
String | A brief reason as to why the delivery failed |
DELIVERY_CANCELLED
A delivery that was book has been canceled.
Property | Data Type | Description |
---|---|---|
reason |
String | A brief reason as to why the delivery was cancelled |
responsible |
Party | Who was responsible for cancelling the delivery |
RETURN_BOOKED_HOME
A return pick-up has been booked to collect the parcel from the consumers home.
Property | Data Type | |
---|---|---|
intervalStart |
Date Time | Timestamp of the start of scheduled time window expected to be picked-up in |
intervalStop |
Date Time | Timestamp of the end of scheduled time window expected to be picked-up in |
The
shipmentId
andpackageId
will be the Budbee generated values. ThecartId
andtmsId
will be from the original order
RETURN_HOME_PICKED_UP
The parcel has been picked-up from the consumer.
RETURN_HOME_PICK_UP_FAILED
Budbee was unable to pick-up the parcel from the consumer.
Property | Data Type | Description |
---|---|---|
reason |
String | The reason to why the pick-up failed |
RETURN_HOME_PICK_UP_CANCELLED
The return pick-up has been canceled.
Property | Data Type | Description |
---|---|---|
reason |
String | A brief reason as to why the pick-up was cancelled |
responsible |
Party | Who was responsible for cancelling the pick-up |
RETURNED_TO_MERCHANT
The parcel picked-up from the consumer has now been returned to the merchant.
LOCKER_CHANGED
The parcel has been changed to be delivered to a new locker location.
Property | Data Type | Description |
---|---|---|
lockerName |
String | The name of the location of the new locker |
street |
String | The street of the new locker location |
postalCode |
String | The postal code of the new locker location |
city |
String | The city where the locker is located in |
DELIVERED_TO_LOCKER
The parcel has been delivered to the locker for the consumer to collect.
Property | Data Type | Description |
---|---|---|
lockerName |
String | The name of the location of the new locker |
street |
String | The street of the new locker location |
postalCode |
String | The postal code of the new locker location |
city |
String | The city where the locker is located in |
CONSUMER_PICKED_UP_FROM_LOCKER
The consumer has picked-up the parcel from the locker.
Property | Data Type | Description |
---|---|---|
lockerName |
String | The name of the location of the new locker |
street |
String | The street of the new locker location |
postalCode |
String | The postal code of the new locker location |
city |
String | The city where the locker is located in |
INJECTED_IN_LOCKER
The parcel has been placed in the locker to be collected.
Property | Data Type | Description |
---|---|---|
responsible |
Party | Who was responsible for placing the parcel in the locker |
flow |
Flow | The flow in which this event was published |
lockerName |
String | The name of the location of the locker |
street |
String | The street of the locker location |
postalCode |
String | The postal code of the locker location |
city |
String | The city of the locker location |
CHANGED_TO_LOCKER_DELIVERY
The parcel will now be delivered to a locker box.
Property | Data Type | Description |
---|---|---|
reason |
String | The reason as to why the parcel was changed to a locker delivery |
responsible |
Party | Who was responsible for changing to a locker delivery |
lockerName |
String | The name of the location of the locker |
street |
String | The street of the locker location |
postalCode |
String | The postal code of the locker location |
city |
String | The city where the locker is located |
CHANGED_TO_HOME_DELIVERY
The parcel will now be delivered to the consumers home.
Property | Data Type | Description |
---|---|---|
reason |
String | The reason as to why the parcel was changed to a home delivery |
responsible |
Party | Who was responsible for changing to a home delivery |
RETURN_BOOKED_LOCKER
A return pick-up has been scheduled to collect the parcel from a locker box.
Will be available when locker returns has a GA release
Property | Data Type | Description |
---|---|---|
lockerName |
String | The name of the location of the locker |
street |
String | The street of the locker location |
postalCode |
String | The postal code of the locker location |
city |
String | The city where the locker is located |
The
shipmentId
andpackageId
will be the Budbee generated values. ThecartId
andtmsId
will be from the original order
RETURN_LOCKER_PICK_UP_FAILED
Budbee was unable to pick-up the parcel from the locker.
Will be available when locker returns has a GA release
Property | Data Type | Description |
---|---|---|
reason |
String | The reason to why the pick-up failed |
DELIVERY_VEHICLE_LOADED
The parcel has been loaded into the delivery vehicle ready to begin the deliveries.
Status Updates
Subscribe to Status Updates for Parcels
Available Statuses:
- NotStarted
- Collected
- CrossDocked
- Delivered
- Backordered
- ReturnedToTerminal
- ReturnedToMerchant
HTTP Request
POST https://api.budbee.com/webhooks/parcel-status-updates
curl "https://api.budbee.com/webhooks/parcel-status-updates"
--user apiKey:apiSecret
-H "Content-Type: application/json"
-X POST -d
{
"url": "http://yourserver.com/callbacks/status-updates"
}
This webhook callback will contain JSON that looks like this:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"status": "Delivered",
"shipmentId": "6133911930",
"packageId": "373325381317444680",
"coordinate": {
"latitude": 59.1234,
"longitude": 18.1234
}
}
Failed Deliveries
Subscribe to information about failed delivery attempts
HTTP Request
POST https://api.budbee.com/webhooks/misses
curl "https://api.budbee.com/webhooks/misses"
--user apiKey:apiSecret
-H "Content-Type: application/json"
-X POST -d
{
"url": "http://yourserver.com/callbacks/misses"
}
This webhook callback will contain JSON that looks like this:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"comment": "Could not get into building. Customer did not answer phone",
"category": "other",
"coordinate": {
"latitude": 59.1234,
"longitude": 18.1234
}
}
Cancelled Orders
Subscribe to Order Cancellations (Order was cancelled by Budbee).
This happens when an Order should not be delivered anymore.
HTTP Request
POST https://api.budbee.com/webhooks/cancellations
curl "https://api.budbee.com/webhooks/cancellations"
--user apiKey:apiSecret
-H "Content-Type: application/json"
-X POST -d
{
"url": "http://yourserver.com/callbacks/cancellations"
}
This webhook callback will contain JSON that looks like this:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"comment": "This order should be returned to sender",
"category": "OTHER",
"coordinate": {
"latitude": 59.1234,
"longitude": 18.1234
}
}
Cancelled Delivery attempts
Subscribe to Delivery Attempt Cancellations. A callback will be posted when a Delivery Attempt is cancelled.
This may happen when the delivery has been delayed, or it has been rebooked into a new delivery attempt
HTTP Request
POST https://api.budbee.com/webhooks/delivery-attempt-cancellations
curl "https://api.budbee.com/webhooks/delivery-attempt-cancellations"
--user apiKey:apiSecret
-H "Content-Type: application/json"
-X POST -d
{
"url": "https://yourserver.com/callbacks/delivery-attempt-cancellations"
}
This webhook callback will contain JSON that looks like this:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"deliveryAttemptId": 589866,
"collectionInterval": {
"startTimestamp": {
"date": 1479880800000,
"timezone": "UTC"
},
"stopTimestamp": {
"date": 1479916800000,
"timezone": "UTC"
}
},
"deliveryInterval": {
"startTimestamp": {
"date": 1479884400000,
"timezone": "UTC"
},
"stopTimestamp": {
"date": 1479916800000,
"timezone": "UTC"
}
},
"comment": "This delivery attempt has been cancelled",
"category": "OTHER"
}
Consumer Reviews
Subscribe to reviews (consumer has left a review about a delivery)
Ratings has a score between 1-5, and an optional comment. If the consumer selected a score between 1-3 they must select a category describing the issue.
HTTP Request
POST https://api.budbee.com/webhooks/ratings
curl "https://api.budbee.com/webhooks/ratings"
--user apiKey:apiSecret
-H "Content-Type: application/json"
-X POST -d
{
"url": "http://yourserver.com/callbacks/ratings"
}
This webhook callback will contain JSON that looks like this:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"score": 5,
"comment": "Super delivery!"
}
Or:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"score": 1,
"comment": "Delivery was not good",
"category": "time_of_arrival"
}
Edited Consumer
Subscribe to Consumer Edits (name, email, phonenumber)
HTTP Request
POST https://api.budbee.com/webhooks/end-customer-edits
curl "https://api.budbee.com/webhooks/end-customer-edits"
--user apiKey:apiSecret
-H "Content-Type: application/json"
-X POST -d
{
"url": "http://yourserver.com/callbacks/end-customer-edits"
}
This webhook callback will contain JSON that looks like this:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"previousEndCustomer": {
"id": 1,
"name": "John Doe",
"referencePerson": null,
"phoneNumber": "+001234567",
"email": "john.doe@budbee.com",
"comment": null
},
"newEndCustomer": {
"id": 2,
"name": "Jane Doe",
"referencePerson": null,
"phoneNumber": "+009876543",
"email": "jane.doe@budbee.com",
"comment": null
}
}
Edited Delivery Address
Subscribe to Delivery Address Edits (e.g Door code)
HTTP Request
POST https://api.budbee.com/webhooks/delivery-address-edits
curl "https://api.budbee.com/webhooks/delivery-address-edits"
--user apiKey:apiSecret
-H "Content-Type: application/json"
-X POST -d
{
"url": "http://yourserver.com/callbacks/delivery-address-edits"
}
This webhook callback will contain JSON that looks like this:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"previousAddress": {
"id": 1,
"street": "Sandhamnsgatan 63C",
"street2": null,
"postalCode": "11528",
"city": "Stockholm",
"countryCode": "SE",
"addressSettings": {
"doorCode": "1234"
}
},
"newAddress": {
"id": 2,
"street": "Sandhamnsgatan 63C",
"street2": null,
"postalCode": "11528",
"city": "Stockholm",
"countryCode": "SE",
"addressSettings": {
"doorCode": "1337"
}
}
}
Edited Order Settings
Subscribe to Order Settings Edits (Leave shipment outside door, require signature, require identification check)
HTTP Request
POST https://api.budbee.com/webhooks/order-settings-edits
curl "https://api.budbee.com/webhooks/order-settings-edits"
--user apiKey:apiSecret
-H "Content-Type: application/json"
-X POST -d
{
"url": "http://yourserver.com/callbacks/order-settings-edits"
}
This webhook callback will contain JSON that looks like this:
{
"id": "d95bad19-9252-4143-9abe-27bfaccb42ad",
"token": "onww1jr4",
"date": 1474976376000,
"previousSettings": {
"id": 1,
"outsideDoorOk": true,
"signatureRequired": false,
"identificationCheckRequired": false
},
"newSettings": {
"id": 2,
"outsideDoorOk": false,
"signatureRequired": true,
"identificationCheckRequired": true
}
}
Box Deliveries
Get available Lockers
Get available Lockers to display in checkout, the results are sorted in best to worst option for the recipient based on the requested postal code.
A box has the following format:
Field | Type | Description |
---|---|---|
id | String | Box Identifier to use when creating Order |
address | Address | Location of Locker |
estimatedDelivery | Date (ISO8601) | Estimated Delivery time |
cutoff | Date (ISO8601) | Estimated Delivery time is valid until the cutoff |
distance | Integer | Distance in meters to locker from requested postal code |
name | String | Name of Locker/Location, to display in checkout |
directions | String | Directions to locate the locker |
label | String | Pretty label to use in checkout, ie. in dropdown select |
openingHours | See Opening Hours | Regular Opening Hours of location |
HTTP Request
GET https://api.budbee.com/boxes/postalcodes/validate/{countryCode}/{postalCode}?collectionPointId={collectionPoint}&language={language}&width={width}&height={height}&length={length}&readyToShip={readyToShip}
Path parameters
Parameter | Type | Description |
---|---|---|
countryCode | String | Country Code ISO 3166-1 alpha-2 e.g. “SE” |
postalCode | String | Postal code of recipient |
Query parameters (Optional)
Parameter | Type | Description |
---|---|---|
collectionPointId | Integer | Registered sender address for more accurate Estimated time of Delivery |
language | String | Preferred language of result |
width | Integer | Expected width of parcel (cm) |
height | Integer | Expected height of parcel (cm) |
length | Integer | Expected length of parcel (cm) |
readyToShip | Date (ISO8601) | Optional. The date and time (ISO 8601 in UTC) of when the parcel will be ready to be shipped from the merchants warehouse. This is used to calculate the ETA of the delivery. If no value is specified then the current date and time will be used. |
Opening Hours
The opening hours are described by periods, an array of opening periods covering seven days, starting on Monday.
Each period contains: open, a pair of day and time objects describing when the location opens.
day is an enum of WEEKDAY, corresponding to the days of the week.
time may contain a time of day in 24-hour hh:mm format. Values are in the range 00:00-23:59.
The time will be reported in the locations time zone.
close may contain a pair of day and time objects describing when the location closes.
If a location is open 24h for a day, close will be null in the response.
If a location is closed an entire day that period will be missing from response.
Language of weekdayText and label is defaulted to the postal codes language, or requested by query parameter language.
curl "https://api.budbee.com/boxes/postalcodes/validate/SE/11247" \
--user apiKey:apiSecret \
-H "Content-Type: application/vnd.budbee.boxes-v1+json"
The request above will return a JSON object containing the boxes that are available for delivery.
{
"lockers": [
{
"id": "BOX0001",
"address": {
"street": "Alströmergatan 39",
"postalCode": "11247",
"city": "Stockholm",
"country": "SE",
"coordinate": {
"latitude": 59.336125,
"longitude": 18.028590
}
},
"estimatedDelivery": "2020-02-12T14:00:00Z",
"cutoff": "2020-02-12T09:00:00Z",
"distance": 50,
"name": "Budbee Kontorsbox",
"directions": "Boxen är direkt till vänster i entrén",
"label": "Budbee Kontorsbox (imorgon 16:00)",
"openingHours": {
"periods": [
{ "open": { "day": "MONDAY", "time": "08:00" }, "close": {"day": "MONDAY", "time": "19:00" } },
{ "open": { "day": "TUESDAY", "time": "08:00" }, "close": {"day": "TUESDAY", "time": "19:00" } },
{ "open": { "day": "WEDNESDAY", "time": "08:00" }, "close": {"day": "WEDNESDAY", "time": "19:00" } },
{ "open": { "day": "THURSDAY", "time": "08:00" }, "close": {"day": "THURSDAY", "time": "19:00" } },
{ "open": { "day": "FRIDAY", "time": "00:00" }, "close": null },
{ "open": { "day": "SATURDAY", "time": "10:00" }, "close": {"day": "SATURDAY", "time": "15:00" } },
],
"weekdayText": [
"Måndag: 08 – 19",
"Tisdag: 08 – 19",
"Onsdag: 08 – 19",
"Torsdag: 08 – 19",
"Fredag: Öppet dygnet runt",
"Lördag: 10 – 15",
"Söndag: Stängt"
]
}
}
]
}
Get all available lockers in a country
Get a list of all available lockers in a country. This method can be used to pre-fetch lockers for displaying in your checkout if you are unable to fetch lockers in realtime using the Get available lockers method.
HTTP Request
GET https://api.budbee.com/boxes/all/{countryCode}
Path parameters
Parameter | Type | Description |
---|---|---|
countryCode | String | Country Code ISO 3166-1 alpha-2 e.g. “SE” |
Query parameters (Optional)
Parameter | Type | Description |
---|---|---|
language | String | Preferred language of result |
curl "https://api.budbee.com/boxes/all/SE" \
--user apiKey:apiSecret \
-H "Content-Type: application/vnd.budbee.boxes-v1+json"
The request above will return a JSON object containing the boxes that are available for delivery.
{
"lockers": [
{
"id": "BOX0001",
"address": {
"street": "Alströmergatan 39",
"postalCode": "11247",
"city": "Stockholm",
"country": "SE",
"coordinate": {
"latitude": 59.336125,
"longitude": 18.028590
}
},
"name": "Budbee Kontorsbox",
"directions": "Boxen är direkt till vänster i entrén",
"openingHours": {
"periods": [
{ "open": { "day": "MONDAY", "time": "08:00" }, "close": {"day": "MONDAY", "time": "19:00" } },
{ "open": { "day": "TUESDAY", "time": "08:00" }, "close": {"day": "TUESDAY", "time": "19:00" } },
{ "open": { "day": "WEDNESDAY", "time": "08:00" }, "close": {"day": "WEDNESDAY", "time": "19:00" } },
{ "open": { "day": "THURSDAY", "time": "08:00" }, "close": {"day": "THURSDAY", "time": "19:00" } },
{ "open": { "day": "FRIDAY", "time": "00:00" }, "close": {"day": "FRIDAY", "time": null } },
{ "open": { "day": "SATURDAY", "time": "10:00" }, "close": {"day": "SATURDAY", "time": "15:00" } },
],
"weekdayText": [
"Måndag: 08 – 19",
"Tisdag: 08 – 19",
"Onsdag: 08 – 19",
"Torsdag: 08 – 19",
"Fredag: Öppet dygnet runt",
"Lördag: 10 – 15",
"Söndag: Stängt"
]
}
}
]
}
Get locker by locker identifier
This method returns a single locker based on the unique locker identifier.
HTTP Request
GET https://api.budbee.com/boxes/{identifier}
Path parameters
Parameter | Type | Description |
---|---|---|
identifier | String | Locker Indentifier e.g. “BOX0001” |
Query parameters (Optional)
Parameter | Type | Description |
---|---|---|
language | String | Preferred language of result |
curl "https://api.budbee.com/boxes/BOX0001?language=EN" \
--user apiKey:apiSecret \
-H "Content-Type: application/vnd.budbee.boxes-v1+json"
The request above will return a JSON object containing the box.
{
"id": "BOX0001",
"address": {
"street": "Alströmergatan 39",
"postalCode": "11247",
"city": "Stockholm",
"country": "SE",
"coordinate": {
"latitude": 59.336125,
"longitude": 18.028590
}
},
"name": "Budbee Kontorsbox",
"directions": "The Budbee Box is found by the entrance to Connect Hotel and Nordnet at Alströmergatan 39.",
"openingHours": {
"periods": [
{ "open": { "day": "MONDAY", "time": "08:00" }, "close": {"day": "MONDAY", "time": "19:00" } },
{ "open": { "day": "TUESDAY", "time": "08:00" }, "close": {"day": "TUESDAY", "time": "19:00" } },
{ "open": { "day": "WEDNESDAY", "time": "08:00" }, "close": {"day": "WEDNESDAY", "time": "19:00" } },
{ "open": { "day": "THURSDAY", "time": "08:00" }, "close": {"day": "THURSDAY", "time": "19:00" } },
{ "open": { "day": "FRIDAY", "time": "00:00" }, "close": {"day": "FRIDAY", "time": null } },
{ "open": { "day": "SATURDAY", "time": "10:00" }, "close": {"day": "SATURDAY", "time": "15:00" } },
],
"weekdayText": [
"Monday: 08 – 19",
"Tuesday: 08 – 19",
"Wednesday: 08 – 19",
"Thursday: 08 – 19",
"Friday: Open 24h",
"Saturday: 10 – 15",
"Sunday: Closed"
]
}
}
Create Box Delivery Order
To Create a Box Order, specify DLVBOX
as a Product Code, and optionally supply the locker selected in checkout (UUID).
This is the same endpoint as Creating Home Delivery Order.
Add parcel information is the same request as Adding Parcels to Home Delivery Order
curl "https://api.budbee.com/multiple/orders"
--user apiKey:apiSecret
-H "Content-Type: application/vnd.budbee.multiple.orders-v2+json"
-X POST -d
{
"collectionId": 2672,
"cart": {
"cartId": "0000001"
},
"delivery": {
"name": "John Doe",
"telephoneNumber": "+46700000000",
"email": "john.doe@budbee.com",
"address": {
"street": "Grevgatan 9",
"street2": "LGH 1601",
"postalCode": "11453",
"city": "Stockholm",
"country": "SE"
}
},
"productCodes": [ "DLVBOX" ],
"boxDelivery": {
"selectedBox": "AAA0001"
},
"additionalServices": {
"fraudDetection": false
}
}