Bond's logo
Documentation Powered by ReDoc

Bond API v1.0 (1.0)

Download OpenAPI specification:Download

Introduction

BOND, the post-purchase company, is changing the game of last-mile delivery experience.

Bond’s tech-driven network of nano distribution centers (NDCs) enables brands to provide fast, convenient, and friendly deliveries. With in-city storage, same-day delivery, next day scheduled delivery and scheduled returns, Bond offers D2C brands the most advanced and personalized last-mile solutions in the industry.

API Overview

Welcome to Bond’s core API Reference!

Current API Version is 1.0

The Bond platform offers a post-purchase and last-mile delivery solution that integrates directly into your current flow and systems. Our API configures and manipulates Bond features and capabilities to seamlessly fit your business order needs. To use our API, make sure to set up your Bond account by contacting your Bond Account Manager or Bond Support, and checking that the prerequisite features are enabled for your account. Most user actions within Bond API can be performed programmatically using the REST API

Common Use Cases:

  • Determine the site for an address
    • Create a new order
    • Update existing order
    • Get ordering list
    • Get single order data
    • Webhooks
    • Scheduling

Authentication

Api Key

In order to use Bond API, each request must be authenticated with an API key.
The API key should be sent with each request in the header section with the header X-BOND-KEY

Security Scheme Type API Key
Header parameter name: X-BOND-KEY

Site

To interact with our advanced site management capabilities, you can use these simple endpoints.

Get site list

Gets all the sites

Authorizations:
Api Key
query Parameters
timeslot
string

Should be "true" if timeslot data should be included in the response

geometry
string

Should be "true" if geometry data should be included in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get sites of address

This endpoint should answer your question: which sites could serve my upcoming order from a specific address?

Authorizations:
Api Key
Request Body schema: application/json
object (Address)

Responses

Request samples

Content type
application/json
{
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "sites": [
    ]
}

Get site details

Gets a single site matching the given ID

Authorizations:
Api Key
query Parameters
id
string

site ID

timeslot
string

Should be "true" if timeslot data should be included in the response

geometry
string

Should be "true" if geometry data should be included in the response

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "isActive": true,
  • "region": "string",
  • "address": {
    },
  • "shiftParameters": {
    },
  • "carriers": [
    ],
  • "configurations": [
    ]
}

Inventory

The following endpoints should enable you interact with our state of the art inventory management capabilities.

Get inventory for site

Get the current inventory available for sale in the site.

Attention! if some query skus are not registered in the site, a 206 response will be return and the quantity part of the product will be null.

Authorizations:
Api Key
query Parameters
skus
Array of strings
Example: skus=BO-12,BO-11

comma separated list of skus to get inventory availability for.

Responses

Response samples

Content type
application/json
{
  • "siteId": "5e37090877955425238646e2",
  • "inventory": [
    ]
}

Order

Our automatic ordering function makes fulfillment as easy as pie! Whether it be for order delivery, service fulfillment, or package return requests.
Each order should be set for a single customer, delivery address, and delivery date. Updating orders is just as simple and can be done as often as necessary to communicate exact delivery needs.

Order's Lifecycle

Each order will have an assigned status to reflect its position in the delivery lifecycle:

  • Pending: all newly created orders.
  • Ready to be delivered:
    • Orders that arrived to the Bond site already packed
    • Pick&Pack orders packaged by Bond that are ready for delivery
  • On the way: Bond is on the way to the customer.
  • Servicing: Bond has made it to the customer for handover.
  • Done: Order is complete and the customer has their package.
  • Canceled: Rejected or canceled orders.

Order Types

When creating an order, an order “type” should always be set. The type will initiate the workflow (aka process):

  • PackDeliver- Use this when you wish to initiate an order (with 1 or more SKUs). We will pick&pack the order at our Bond site.
  • Deliver- Use this when you wish to initiate an order that has already been packed (with 1 or more SKUs). Arrives at Bond site ready for delivery.
  • Return - Use this when you wish to initiate an exchange package workflow or a return.

Feasibility check

Check whether an order is valid and supported by bond, without creating it.

Authorizations:
Api Key
Request Body schema: application/json
type
required
string (OrderType)

The order type

PACK-DELIVER
PACK-DELIVER
DELIVER
RETURN
displayId
string

The order display Id given by the brand

brandOrderId
string

The order Id given by the brand

creationDate
string <date-time>

The order's creation date and time (in ISO8601 format).
If not given, the date time will be now.

requestedDeliveryDate
string <date> YYYY-MM-DD

The order's requested date to deliver (in the order's address timezone).

readinessDate
string <date-time>

not yet supported

object

The order's customer contact.
if not given, the contact will be the same as the receiver's contact details.

required
object

The recipient of the order.

notes
string
externalTrackingNumber
string

Generate a special tracking number from the external tracking number and Bond prefix.
Special tracking numbers can be requested by the brand and implemented by Bond.
If not requested, Bond will generate tracking numbers.

batchId
string

Use batches to organize similar orders together, by whatever criteria you choose.

Array of objects (Item)

The order items.
If a DELIVER type order is selected, the items will be ignored.

Responses

Request samples

Content type
application/json
Example
PACK-DELIVER
PACK-DELIVER
DELIVER
RETURN
{
  • "type": "PACK-DELIVER",
  • "displayId": "display-acme-201",
  • "brandOrderId": "acmem-201",
  • "creationDate": "2020-02-10T08:00:00Z",
  • "requestedDeliveryDate": "2020-02-11",
  • "readinessDate": "2020-02-11T10:00:00Z",
  • "customer": {
    },
  • "receiver": {
    },
  • "notes": "Make sure it's fresh",
  • "externalTrackingNumber": "1527348963",
  • "batchId": "batch-1763",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "isValid": false,
  • "message": "The order was rejected because the address is not supported."
}

Create new order

Create a new order to be delivered with Bond

Authorizations:
Api Key
Request Body schema: application/json
type
required
string (OrderType)

The order type

PACK-DELIVER
PACK-DELIVER
DELIVER
RETURN
displayId
string

The order display Id given by the brand

brandOrderId
string

The order Id given by the brand

creationDate
string <date-time>

The order's creation date and time (in ISO8601 format).
If not given, the date time will be now.

requestedDeliveryDate
string <date> YYYY-MM-DD

The order's requested date to deliver (in the order's address timezone).

readinessDate
string <date-time>

not yet supported

object

The order's customer contact.
if not given, the contact will be the same as the receiver's contact details.

required
object

The recipient of the order.

notes
string
externalTrackingNumber
string

Generate a special tracking number from the external tracking number and Bond prefix.
Special tracking numbers can be requested by the brand and implemented by Bond.
If not requested, Bond will generate tracking numbers.

batchId
string

Use batches to organize similar orders together, by whatever criteria you choose.

Array of objects (Item)

The order items.
If a DELIVER type order is selected, the items will be ignored.

Responses

Request samples

Content type
application/json
Example
PACK-DELIVER
PACK-DELIVER
DELIVER
RETURN
{
  • "type": "PACK-DELIVER",
  • "displayId": "display-acme-201",
  • "brandOrderId": "acmem-201",
  • "creationDate": "2020-02-10T08:00:00Z",
  • "requestedDeliveryDate": "2020-02-11",
  • "readinessDate": "2020-02-11T10:00:00Z",
  • "customer": {
    },
  • "receiver": {
    },
  • "notes": "Make sure it's fresh",
  • "externalTrackingNumber": "1527348963",
  • "batchId": "batch-1763",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "BOuQ84HaQZ",
  • "displayId": "display-acme-201",
  • "brandOrderId": "acmem-201",
  • "status": "DONE",
  • "type": "PACK-DELIVER",
  • "site": {
    },
  • "location": "Customer",
  • "creationDate": "2020-02-10T08:00:00Z",
  • "requestedDeliveryDate": "2020-02-11",
  • "requestedDeliveryWindow": {
    },
  • "readinessDate": "2020-02-11T10:00:00Z",
  • "expectedArrivalDate": "2020-02-11T12:30:00Z",
  • "actualArrivalDate": "2020-02-11T12:32:10Z",
  • "customer": {
    },
  • "receiver": {
    },
  • "packages": [
    ],
  • "items": [
    ],
  • "batchId": "batch-1763",
  • "notes": "Make sure it's fresh",
  • "history": [
    ]
}

List orders

List and filter orders

Authorizations:
Api Key
query Parameters
status
Array of strings (OrderStatus)
Items Enum: "PENDING" "READY_FOR_DELIVERY" "ON_THE_WAY" "SERVICING" "DONE" "CANCELLED"
Example: status=DONE

filter by order status

type
Array of strings (OrderType)
Items Enum: "PACK-DELIVER" "DELIVER" "RETURN"
Example: type=PACK-DELIVER

filter by order type

creation_start
string <date-time>

range start of the creation date

creation_end
string <date-time>

range end of the creation date

requested_delivery_start
string <date-time>

range start of the requested delivery date

requested_delivery_end
string <date-time>

range end of the requested delivery date

page
number
Default: 1

items page

per_page
number [ 1 .. 200 ]
Default: 50

number of items to show in each page (between 1-200).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update order

Update an existing order

Authorizations:
Api Key
path Parameters
prefix
required
string
Enum: "bond-order" "brand-order" "bond-package" "brand-package"

order id type:

  • bond-order - retrieve order by its Bond Id
  • brand-order - retrieve order by its Brand Id
  • bond-package - retrieve order by one of its package Bond Ids
  • brand-package - retrieve order by one of its package Brand Ids
id
required
string
Request Body schema: application/json
brandOrderId
string

The order Id given by the brand

status
string
Value: "CANCELLED"

Change the current status of the order.
Can't change to CANCELLED if order is already DONE

requestedDeliveryDate
string <date>

The order's requested date to deliver (in the order's address timezone).

object
readinessDate
string <date-time>

not yet supported

object

The order's customer contact details.
* updating customer doesn't change receiver

object

The recipient of the order.
* updating receiver doesn't change costumer

Array of objects

The brand package ids which will be deliveded by Bond.
If the order is a PACK-DELIVER order, the packages will be ignored.
If the order is already ON_THE_WAY, this can't be changed.

Array of objects (Item)

The order items. If a DELIVER type order is selected, the items will be ignored.
If the order is already ON_THE_WAY, this can't be changed.

notes
string

Notes left by the customer when placing the order.

batchId
string

Use batches to organize similar orders together, by whatever criteria you choose.
* Updating with null will remove the batch id from the order.

Responses

Request samples

Content type
application/json
{
  • "brandOrderId": "string",
  • "status": "CANCELLED",
  • "requestedDeliveryDate": "2020-02-11",
  • "requestedDeliveryWindow": {
    },
  • "readinessDate": "2020-02-11T10:00:00Z",
  • "customer": {
    },
  • "receiver": {
    },
  • "packages": [
    ],
  • "items": [
    ],
  • "notes": "Make sure it's fresh",
  • "batchId": "batch-1763"
}

Response samples

Content type
application/json
{
  • "id": "BOuQ84HaQZ",
  • "displayId": "display-acme-201",
  • "brandOrderId": "acmem-201",
  • "status": "DONE",
  • "type": "PACK-DELIVER",
  • "site": {
    },
  • "location": "Customer",
  • "creationDate": "2020-02-10T08:00:00Z",
  • "requestedDeliveryDate": "2020-02-11",
  • "requestedDeliveryWindow": {
    },
  • "readinessDate": "2020-02-11T10:00:00Z",
  • "expectedArrivalDate": "2020-02-11T12:30:00Z",
  • "actualArrivalDate": "2020-02-11T12:32:10Z",
  • "customer": {
    },
  • "receiver": {
    },
  • "packages": [
    ],
  • "items": [
    ],
  • "batchId": "batch-1763",
  • "notes": "Make sure it's fresh",
  • "history": [
    ]
}

Get order details

Get order details

Authorizations:
Api Key
path Parameters
prefix
required
string
Enum: "bond-order" "brand-order" "bond-package" "brand-package"

order id type:

  • bond-order - retrieve order by its Bond Id
  • brand-order - retrieve order by its Brand Id
  • bond-package - retrieve order by one of its package Bond Ids
  • brand-package - retrieve order by one of its package Brand Ids
id
required
string

Responses

Response samples

Content type
application/json
Example
Order
Order
OrderLean
{
  • "id": "BOuQ84HaQZ",
  • "displayId": "display-acme-201",
  • "brandOrderId": "acmem-201",
  • "status": "DONE",
  • "type": "PACK-DELIVER",
  • "site": {
    },
  • "location": "Customer",
  • "creationDate": "2020-02-10T08:00:00Z",
  • "requestedDeliveryDate": "2020-02-11",
  • "requestedDeliveryWindow": {
    },
  • "readinessDate": "2020-02-11T10:00:00Z",
  • "expectedArrivalDate": "2020-02-11T12:30:00Z",
  • "actualArrivalDate": "2020-02-11T12:32:10Z",
  • "customer": {
    },
  • "receiver": {
    },
  • "packages": [
    ],
  • "items": [
    ],
  • "batchId": "batch-1763",
  • "notes": "Make sure it's fresh",
  • "history": [
    ]
}

Update order Delivery status

Update a delivery status for an order, this will force update the order status. Please be noted, this update will not update external services.

Authorizations:
Api Key
path Parameters
prefix
required
string
Enum: "bond-order" "brand-order" "bond-package" "brand-package"

order id type:

  • bond-order - retrieve order by its Bond Id
  • brand-order - retrieve order by its Brand Id
  • bond-package - retrieve order by one of its package Bond Ids
  • brand-package - retrieve order by one of its package Brand Ids
id
required
string
Request Body schema: application/json
newStatus
string
Enum: "READY_FOR_DELIVERY" "ON_THE_WAY" "DONE" "CANCELLED"

The new delivery status to set the order to

Responses

Request samples

Content type
application/json
{
  • "newStatus": "DONE"
}

Response samples

Content type
application/json
{
  • "message": "Unauthorized"
}

Label

To print a Label for your pacakge, you can use our label API.

Generate labels

It is possible to generate a label for any or your orders or packages, using this label API. Send your Bond Order ID or list of Order IDs and get back a single PDF file with all Labels and Picking slips (if exists) Please note: when using Shopify, generating the label might set the Shopify order as fulfillment done.

Authorizations:
Api Key
Request Body schema: application/json
bondIds
Array of strings

an array of bond's unique order ids

onlyLabel
boolean
Default: false

print only the label (without packing slip)

Responses

Request samples

Content type
application/json
{
  • "bondIds": [
    ],
  • "onlyLabel": true
}

Response samples

Content type
application/json
{
  • "message": "Invalid request"
}

Scheduling

Scheduling allows you to offer your end-users the option to choose their preferred date and time for Bond delivery or return pickup.

We offer 2 call types: Retrieve the list of all available dates and time slots Retrieve the list of time slots for a specific date

Bond will replay back with the list of relevant time slots according to the call, and the recommended best date and time slot per the call field.

Please note - an action will only be active on our systems once the timeslot was chosed, otherwise - the suggested times will be freed back for the next users.

Lifecycle

This section will present the flow to create a scheduled order:

  1. Create a temporary inactive order and Bond will create a unique tracking number to be used later. This will Creating a scheduling session, to get back the available time slots for your customer to choose from.

  2. Once the user selected his wished time slot, the selection will be validated, to ensure we will be able to fulfil the customer request, and if the selected time slot is available, the order scheduling process will be completed, and a new order will be created at Bond

Cancelation of Scheduled Order

To cancel a previously scheduled order please refer to the Order Update and update the order to CANCELLED.

Security

For service aggregators, please be noted that access will be done through the Brand API Key and not via a generic one.

Create new Scheduling session

Create a new draft order and a scheduling session

Authorizations:
Api Key
Request Body schema: application/json
type
required
string (OrderType)

The order type

PACK-DELIVER
PACK-DELIVER
DELIVER
RETURN
displayId
string

The order display Id given by the brand

brandOrderId
string

The order Id given by the brand

creationDate
string <date-time>

The order's creation date and time (in ISO8601 format).
If not given, the date time will be now.

requestedDeliveryDate
string <date> YYYY-MM-DD

The order's requested date to deliver (in the order's address timezone).

readinessDate
string <date-time>

not yet supported

object

The order's customer contact.
if not given, the contact will be the same as the receiver's contact details.

required
object

The recipient of the order.

notes
string
externalTrackingNumber
string

Generate a special tracking number from the external tracking number and Bond prefix.
Special tracking numbers can be requested by the brand and implemented by Bond.
If not requested, Bond will generate tracking numbers.

batchId
string

Use batches to organize similar orders together, by whatever criteria you choose.

Array of objects (Item)

The order items.
If a DELIVER type order is selected, the items will be ignored.

Responses

Request samples

Content type
application/json
Example
PACK-DELIVER
PACK-DELIVER
DELIVER
RETURN
{
  • "type": "PACK-DELIVER",
  • "displayId": "display-acme-201",
  • "brandOrderId": "acmem-201",
  • "creationDate": "2020-02-10T08:00:00Z",
  • "requestedDeliveryDate": "2020-02-11",
  • "readinessDate": "2020-02-11T10:00:00Z",
  • "customer": {
    },
  • "receiver": {
    },
  • "notes": "Make sure it's fresh",
  • "externalTrackingNumber": "1527348963",
  • "batchId": "batch-1763",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "bond_id": "437fa207-cd7d-488d-b71e-a4663f6bd788",
  • "availableTimeslots": [
    ]
}

Select Wanted Timeslot

Select a specific timeslot and truly create the order

Authorizations:
Api Key
path Parameters
bond_id
required
string <uuid>
Request Body schema: application/json
date
dateYYYY-MM-DD
windowStart
string^\d{1,2}\:\d{1,2}$

a window start time - hour and minutes, in 24 hour format

windowEnd
string^\d{1,2}\:\d{1,2}$

a window end time - hour and minutes, in 24 hour format

Responses

Request samples

Content type
application/json
{
  • "date": "2020-12-31T00:00:00.000Z",
  • "windowStart": "08:00",
  • "windowEnd": "10:30"
}

Response samples

Content type
application/json
{
  • "id": "BOuQ84HaQZ",
  • "displayId": "display-acme-201",
  • "brandOrderId": "acmem-201",
  • "status": "DONE",
  • "type": "PACK-DELIVER",
  • "site": {
    },
  • "location": "Customer",
  • "creationDate": "2020-02-10T08:00:00Z",
  • "requestedDeliveryDate": "2020-02-11",
  • "requestedDeliveryWindow": {
    },
  • "readinessDate": "2020-02-11T10:00:00Z",
  • "expectedArrivalDate": "2020-02-11T12:30:00Z",
  • "actualArrivalDate": "2020-02-11T12:32:10Z",
  • "customer": {
    },
  • "receiver": {
    },
  • "packages": [
    ],
  • "items": [
    ],
  • "batchId": "batch-1763",
  • "notes": "Make sure it's fresh",
  • "history": [
    ]
}

Gets available timeslots for an existing Order

Use this to select\update a specific time slot for a temporary or an existing order. Selecting a time slot for a temporary order will make it active (Status: Pending).

Authorizations:
Api Key
path Parameters
bond_id
required
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Webhooks

/ Webhooks

Subscribe to a webhook

Subscribe to a webhook in order to recieve updates on changes in orders

Authorizations:
Api Key
Request Body schema: application/json
callbackUrl
required
string

the url webhooks will be triggered to.

secret
string

string that will be used to create the hash for validating the message

eventTypes
Array of strings (WebhookType)
Items Enum: "ORDER_CREATED" "ORDER_STATUS_UPDATED" "ORDER_DETAILS_UPDATED"

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "3e4172cf8df637503a5ee822",
  • "callbackUrl": "string",
  • "eventTypes": [
    ]
}

Callback payload samples

Callback
POST: {$request.body#/callbackUrl}
Content type
application/json
{
  • "eventTypes": "ORDER_CREATED",
  • "payload": {
    }
}

List current webhooks

Get current subscribed webhooks

Authorizations:
Api Key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove webhook

Unsubscribe from a specific webhook

Authorizations:
Api Key
path Parameters
id
required
string

The webhook Id to delete

Responses

Response samples

Content type
application/json
{
  • "message": "Webhook deleted successfully"
}

Webhook Callbacks

Each webhook will contain the X-Bond-Signature-256 header which contains the response signature.

We use an HMAC-SHA256 hexdigest to compute the signature.
You can valdiate the message with the secret you sent when subscribing to the webhook, and the entire message body as the HMAC message. For more information on HMAC-SHA256 validation, check this article.

Following request-body is send as POST request on the URL used to register the callback:

eventType
string (WebhookType)
Enum: "ORDER_CREATED" "ORDER_STATUS_UPDATED" "ORDER_DETAILS_UPDATED"
object (Order)
{
  • "eventType": "ORDER_CREATED",
  • "payload": {
    }
}