API Reference

API Referenceexpand_more

Deliveries

HubRise offers two complementary resources to manage order deliveries:

Delivery quotes enable third-party services to provide cost estimates and delivery timeframes.
Deliveries represent the actual fulfillment process. They contain real-time tracking information including the estimated and actual pickup and drop-off times, driver details, and current delivery status.

While an order can have multiple delivery quotes, only a single delivery can be created and tracked per order.

The most general workflow is as follows - in scenarios with a single provider, a delivery may be created directly without quotes:

An order is created, and sent to one or several delivery quote providers.
Each provider creates a delivery quote for the order.
The business or customer accepts one of the quotes.
The provider whose quote was accepted creates a delivery for the order.
The provider updates the delivery status as the order is picked up and delivered.

Delivery Quotes

1. Create a Delivery Quote

Creates a delivery quote for an order.

Endpoint:	POST /locations/:location_id/orders/:order_id/delivery_quotes
Short endpoint:	POST /location/orders/:order_id/delivery_quotes (location only)
Access level:	Location, Account

This endpoint can only be called for orders whose service_type is set to delivery.

Parameters:

Name	Type	Description
`carrier`	`string`	The name of the carrier.
`carrier_ref` optional	`string`	A ref code that identifies the carrier.
`ref` optional	`string`	The carrier's identifier of the quote.
`fee`	`string`	The quoted delivery fee.
`estimated_pickup_at` optional	Time	The estimated pickup time.
`estimated_dropoff_at` optional	Time	The estimated drop-off time.

Example request

POST /location/orders/5dpm9/delivery_quotes

{  "carrier": "UPS",  "carrier_ref": "ups",  "ref": "1Z12345E0291980793",  "status": "pending",  "fee": "4.50 EUR",  "estimated_pickup_at": "2023-01-01T12:00:00+01:00",  "estimated_dropoff_at": "2023-01-01T12:30:00+01:00"}

2. Accept a Delivery Quote

Marks a delivery quote as accepted, and saves the acceptance time.

This action is not reversible, and will usually result in the creation of a delivery by the carrier. Several quotes can be accepted for the same order, for example if the first carrier does not create a delivery in time.

Endpoint:	POST /locations/:location_id/orders/:order_id/delivery_quotes/:id/accept
Short endpoint:	POST /location/orders/:order_id/delivery_quotes/:id/accept (location only)
Access level:	Location, Account

Example request

POST /location/orders/5dpm9/delivery_quotes/ez351/accept

3. Retrieve Delivery Quote

Retrieves a delivery quote attached to an order.

Endpoint:	GET /locations/:location_id/orders/:order_id/delivery_quotes/:id
Short endpoint:	GET /location/orders/:order_id/delivery_quotes/:id (location only)
Access level:	Location, Account

All the fields of a delivery quote creation request are returned, plus a few more:

Name	Type	Description
`id`	`string`	The id of the delivery quote.
`order_id`	`string`	The id of the order.
`location_id`	`string`	The id of the location.
`accepted_at` optional	Time	Time the quote was accepted by the customer or the business, or `null` if it has not been accepted.

Example request

GET /location/orders/5dpm9/delivery_quotes/ez351

Response:

{    "id": "ez351",    "order_id": "5dpm9",    "location_id": "3r4s3-1",    "carrier": "UPS",    "carrier_ref": "ups",    "ref": "Q12345E029198";    "fee": "4.50 EUR",    "estimated_pickup_at": "2023-01-01T12:17:00+01:00",    "estimated_dropoff_at": null,    "accepted_at": "2023-01-01T11:45:00+01:00"}

4. List Delivery Quotes

Returns the delivery quotes attached to an order.

Endpoint:	GET /locations/:location_id/orders/:order_id/delivery_quotes
Short endpoint:	GET /location/orders/:order_id/delivery_quotes (location only)
Access level:	Location, Account

Example request

GET /location/orders/5dpm9/delivery_quotes

[    {      "id": "ez351",      "order_id": "5dpm9",      "location_id": "3r4s3-1",      "carrier": "UPS",      "carrier_ref": "ups",      "ref": "Q12345E029198";      "fee": "4.50 EUR",      "estimated_pickup_at": "2023-01-01T12:17:00+01:00",      "estimated_dropoff_at": null,      "accepted_at": "2023-01-01T11:45:00+01:00"    },    {      "id": "a5z32",      "order_id": "5dpm9",      "location_id": "3r4s3-1",      "carrier": "FedEx",      "carrier_ref": "fedex",      "ref": "FQ6678136645";      "fee": "6.50 EUR",      "estimated_pickup_at": "2023-01-01T12:10:00+01:00",      "estimated_dropoff_at": "2023-01-01T12:40:00+01:00",      "accepted_at": null    }]

Deliveries

1. Create a Delivery

Attaches a delivery to an order.

Endpoint:	POST /locations/:location_id/orders/:order_id/delivery
Short endpoint:	POST /location/orders/:order_id/delivery (location only)
Access level:	Location, Account

This endpoint can only be called if:

The order has no delivery yet.
The order's service_type is set to delivery.

Parameters:

Name	Type	Description
`carrier`	`string`	The name of the carrier.
`carrier_ref` optional	`string`	A ref code that identifies the carrier.
`ref` optional	`string`	The carrier's identifier of the delivery, such as a tracking number.
`status`	`string`	The delivery status. See Delivery Statuses.
`fee` optional	`string`	The delivery fee charged by the carrier to the business.
`estimated_pickup_at` optional	Time	The pickup time, estimated by the carrier.
`estimated_dropoff_at` optional	Time	The drop-off time, estimated by the carrier.
`tracking_url` optional	`string`	URL where the customer can track the delivery status, the driver position, or both.
`driver_pickup_url` optional	`string`	URL the driver must scan at the pickup location to confirm handover of the order. Often displayed as a QR code; scanning it notifies the carrier that the order was collected.
`driver_name` optional	`string`	The driver name.
`driver_phone` optional	`string`	The driver phone number.
`driver_phone_access_code` optional	`string`	The access code to provide when calling the phone number above.
`driver_latitude` optional	decimal	The current latitude of the driver.
`driver_longitude` optional	decimal	The current longitude of the driver.
`assigned_at` optional	Time	Time the status changed to `pickup_enroute`.
`pickup_at` optional	Time	Time the status changed to `dropoff_enroute`.
`delivered_at` optional	Time	Time the status changed to `delivered`.
`cancelled_at` optional	Time	Time the status changed to `cancelled`.

Example request

POST /location/orders/5dpm9/delivery

{  "carrier": "UPS",  "carrier_ref": "ups",  "ref": "1Z12345E0291980793",  "status": "pending",  "fee": "4.50 EUR",  "estimated_pickup_at": "2023-01-01T12:00:00+01:00",  "estimated_dropoff_at": "2023-01-01T12:30:00+01:00",  "tracking_url": "https://www.ups.com/track/1Z12345E0291980793",  "driver_pickup_url": "https://driver.ups.com/pickup/1Z12345E0291980793",  "driver_name": "John",  "driver_phone": "+33612345678",  "driver_phone_access_code": "1234",  "driver_latitude": "48.856614",  "driver_longitude": "2.3522219"}

Delivery statuses

The following statuses are available:

Status	Description
`pending`	Not started
`pickup_enroute`	En route to pickup
`pickup_approaching`	Nearing pickup
`pickup_waiting`	At pickup
`dropoff_enroute`	En route to dropoff
`dropoff_approaching`	Nearing dropoff
`dropoff_waiting`	At dropoff
`delivered`	Completed
`cancelled`	Cancelled

2. Retrieve a Delivery

Retrieves the delivery attached to an order.

Endpoint:	GET /locations/:location_id/orders/:order_id/delivery
Short endpoint:	GET /location/orders/:order_id/delivery (location only)
Access level:	Location, Account

If the order has no delivery, a 404 - Not Found error is returned.

Example request

GET /location/orders/5dpm9/delivery

{  "id": "ez351",  "order_id": "5dpm9",  "location_id": "3r4s3-1",  "carrier": "UPS",  "carrier_ref": "ups",  "ref": "1Z12345E0291980793",  "status": "pickup_waiting",  "fee": "4.50 EUR",  "estimated_pickup_at": "2023-01-01T12:17:00+01:00",  "estimated_dropoff_at": "2023-01-01T12:29:00+01:00",  "tracking_url": "https://www.ups.com/track?tracknum=1Z12345E0291980793",  "driver_name": "John",  "driver_phone": "+33612345678",  "driver_phone_access_code": "1234",  "driver_latitude": "48.856702",  "driver_longitude": "2.35222",  "assigned_at": "2023-01-01T12:11:03+01:00",  "pickup_at": null,  "delivered_at": null,  "cancelled_at": null}

3. Update a Delivery

Updates the delivery attached to an order.

Endpoint:	PATCH /locations/:location_id/orders/:order_id/delivery
Short endpoint:	PATCH /location/orders/:order_id/delivery (location only)
Access level:	Location, Account

All fields can be updated, except: carrier, carrier_ref, fee.

If the order has no delivery, a 404 - Not Found error is returned.

Example request

PATCH /location/orders/5dpm9/delivery

{  "driver_latitude": "48.856614",  "driver_longitude": "2.3522219"}

Auto-updated fields

The following fields are updated automatically when the delivery status changes:

Status	Field
`pickup_enroute`	`assigned_at`
`dropoff_enroute`	`pickup_at`
`delivered`	`delivered_at`
`cancelled`	`cancelled_at`

You can manually override these fields if required. This can be useful when status updates are skipped or delayed.

Feedback on this page

OrderLine

Catalog Manager

Dashboard

Any specific needs?

Included Apps

OrderLine

Catalog Manager

Dashboard

Developers

Resources

Any specific needs?

API Reference

API Reference

API Referenceexpand_more

Deliveries

Delivery Quotes

1. Create a Delivery Quote

Parameters:

2. Accept a Delivery Quote

3. Retrieve Delivery Quote

Response:

4. List Delivery Quotes

Deliveries

1. Create a Delivery

Parameters:

Delivery statuses

2. Retrieve a Delivery

3. Update a Delivery

Auto-updated fields