FleetRunnr API
1.0

This is the documentation for version 1.0 of the API. Last update on Jul 20, 2022.

Base URL

https://{workspace}.fleetrunnr.com/api/v1

Authentication

Send a bearer token in the Authorization HTTP header to authenticate with the API.

To generate an access token, please go to the Settings page in the FleetRunnr portal, click on Access Tokens, and create a new one from there (https://app.fleetrunnr.com/settings/access-tokens).

Error Responses

All API requests return HTTP status codes that can tell you more about the response.

401 Unauthorized

The client doesn't have proper authentication headers.

{
  "message": "Unauthorized."
}

402 Payment Required

The account doesn't have a valid subscription or has overdue payments.

{
  "message": "Payment Required."
}

403 Forbidden

The requested resource is not accessible.

{
  "message": "Forbidden."
}

404 Not Found

The requested resource was not found.

{
  "message": "Not found."
}

422 Unprocessable Entity

The request body contains semantic errors. This is typically caused by incorrect formatting, omitting required fields, or logical errors.

{
  "message": "The given data was invalid."
  "errors": {
    ...
  }
}

429 Too Many Requests

The client has exceeded the API rate limit.

{
  "message": "Too many requests."
}

5xx Errors

An internal error occurred in FleetRunnr. Contact support for more information.

{
  "message": "Internal server error."
}

Carriers

Retrieve Carriers

GET /carriers

Retrieve your connected carriers

Responses

• 200 object
- message string
- data object
  carriers array[object]
  
  uuid string(uuid)
  
  name string
  
  avatar string(uri)
  
  shipping_methods array[object]
  
  Available shipping methods
  
  uuid string(uuid)
  
  name string
  
  currency string
  
  Currency in ISO-3 format
  
  base_fee number
  
  The base fee that is always applied when this shipping method is used
  
  Minimum value is 0.
  
  weight_threshold number
  
  The threshold in weight_unit:kg|oz at when the weight surcharge begins
  
  Minimum value is 0.
  
  weight_surcharge number
  
  The amount to charge for every additional weight_unit:kg|oz above the weight_threshold
  
  Minimum value is 0.
  
  weight_unit string
  
  Values are kg or oz.
  
  distance_threshold number
  
  The threshold in distance_unit:km|mi at when the distance surcharge begins
  
  Minimum value is 0.
  
  distance_surcharge number
  
  The amount to charge for every additional distance_unit:km|mi above the distance_threshold
  
  Minimum value is 0.
  
  distance_unit string
  
  Values are km or mi.

GET /carriers

curl \
 -X GET https://{workspace}.fleetrunnr.com/api/v1/carriers \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Response example (200)

{
  "message": "string",
  "data": {
    "carriers": [
      {
        "uuid": "a66def5d-c2bc-4cbc-9ed6-a8815d08114c",
        "name": "ABC Logistics",
        "avatar": "https://example.com/logo.png",
        "shipping_methods": [
          {
            "uuid": "2beb8038-c028-480a-9d53-2eb1feea9252",
            "name": "On-Demand",
            "currency": "USD",
            "base_fee": 20,
            "weight_threshold": 5,
            "weight_surcharge": 0.25,
            "weight_unit": "kg",
            "distance_threshold": 10,
            "distance_surcharge": 7.5,
            "distance_unit": "km"
          },
          {
            "uuid": "b990bed5-f4d9-4fca-be74-7e990a4cd450",
            "name": "3-Day Shipping",
            "currency": "USD",
            "base_fee": 15,
            "weight_threshold": 10,
            "weight_surcharge": 2.25,
            "weight_unit": "kg",
            "distance_threshold": 30,
            "distance_surcharge": 5,
            "distance_unit": "km"
          }
        ]
      }
    ]
  }
}

Calculate Rates

POST /carriers/rates

Provide an order's information and retreive all carriers along with each of their assigned shipping methods with its calculated rate

Body

source_location object

The source location coordinates
- lat number
  
  Minimum value is -90, maximum value is 90.
- lng number
  
  Minimum value is -180, maximum value is 180.
destination_location object

The destination location coordinates
- lat number
  
  Minimum value is -90, maximum value is 90.
- lng number
  
  Minimum value is -180, maximum value is 180.
departure_time string(date-time)

Format should match the following pattern: YYYY-MM-DD HH:MM.
total_weight number

Minimum value is 0.
weight_unit string

Values are kg or oz.

Responses

• 200 object
- message string
- data object
  carriers array[object]
  
  uuid string(uuid)
  
  name string
  
  avatar string(uri)
  
  shipping_methods array[object]
  
  The carrier's shipping methods.
  
  uuid string(uuid)
  
  name string
  
  currency string
  
  Currency in ISO-3 format
  
  rate number
  
  The total sum of fees charged by using this shipping method, which includes:
  
  Base Fee
  
  Weight surcharge
  
  Distance surcharge
  
  Delivery zone surcharge
  
  Minimum value is 0.

POST /carriers/rates

curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/carriers/rates \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"source_location":{"lat":46.371826,"lng":-118.496391},"destination_location":{"lat":47.58213,"lng":-122.38324},"departure_time":"2022-01-20 13:30","total_weight":23.45,"weight_unit":"kg"}'

Request example

{
  "source_location": {
    "lat": 46.371826,
    "lng": -118.496391
  },
  "destination_location": {
    "lat": 47.58213,
    "lng": -122.38324
  },
  "departure_time": "2022-01-20 13:30",
  "total_weight": 23.45,
  "weight_unit": "kg"
}

Response example (200)

{
  "message": "success",
  "data": {
    "carriers": [
      {
        "uuid": "a66def5d-c2bc-4cbc-9ed6-a8815d08114c",
        "name": "ABC Logistics",
        "avatar": "https://example.com/logo.png",
        "workspace": "abc-logistics",
        "shipping_methods": [
          {
            "id": 1,
            "name": "Standard Shipping",
            "rate": 50,
            "currency": "USD"
          },
          {
            "id": 2,
            "name": "Return Shipping",
            "rate": 150,
            "currency": "USD"
          }
        ]
      }
    ]
  }
}

Customers

Get Customer

GET /customers

Retrieve a single customer by phone or email.

Set locations=true to include the customer's locations.

Query parameters

phone string(phone) Required

Phone number in E.164 international format
email string(email) Required

Valid email address (only required if phone is not specified)
locations boolean

Include the customer’s locations

Responses

• 200 object
- message string
- data object
  customer object
  
  uuid string(uuid)
  
  external_id string
  
  Customer's ID generated from a third-party system such as a CRM, POS, or accounting software
  
  first_name string
  
  last_name string
  
  email string(email)
  
  phone string(phone)
  
  Customer's phone number in E.164 international format
  
  notes string

GET /customers

curl \
 -X GET https://{workspace}.fleetrunnr.com/api/v1/customers?phone=string&email=hello%40example.com \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Response example (200)

{
  "message": "string",
  "data": {
    "customer": {
      "uuid": "69e93118-a581-4a13-afea-b6d4a2d2c40c",
      "external_id": "ABCDE12345",
      "first_name": "John",
      "last_name": "Ondricka",
      "email": "john.ondricka@example.com",
      "phone": "+12163547758",
      "notes": "Some notes here...",
      "locations": [
        {
          "uuid": "84e249df-8d50-4212-8329-6059fc002563",
          "name": null,
          "line_1": "4840 Sun Valley Road",
          "line_2": "Flat 302",
          "city": "Prescott",
          "region": "Washington",
          "country": "US",
          "zip_code": "99348",
          "coordinates": {
            "lat": 46.371826,
            "lng": -118.496391
          }
        }
      ]
    }
  }
}

Create Customer

POST /customers

Create a new customer

Body

external_id string

Customer's ID generated from a third-party system such as a CRM, POS, or accounting software
first_name string Required
last_name string Required
email string(email) Required

Required if phone is not provided
phone string(phone) Required

Phone number in E.164 international format.
Required if email is not provided.
notes string

Responses

• 200 object
- message string
- data object
  customer_uuid string(uuid)
  
  The customer's generated unique identifier

POST /customers

curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/customers \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"external_id":"ABCD1234","first_name":"string","last_name":"string","email":"user@example.com","phone":"+12163547758","notes":"string"}'

Request example

{
  "external_id": "ABCD1234",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "+12163547758",
  "notes": "string"
}

Response example (200)

{
  "message": "string",
  "data": {
    "customer_uuid": "string"
  }
}

Update Customer

PUT /customers/{customer_uuid}

Update the information of an existing customer

Body

external_id string

Customer's ID generated from a third-party system such as a CRM, POS, or accounting software
first_name string Required
last_name string Required
email string(email) Required

Required if phone is not provided
phone string(phone) Required

Phone number in E.164 international format.
Required if email is not provided.
notes string

Responses

• 200 object
- message string

PUT /customers/{customer_uuid}

curl \
 -X PUT https://{workspace}.fleetrunnr.com/api/v1/customers/{customer_uuid} \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"external_id":"ABCD1234","first_name":"string","last_name":"string","email":"user@example.com","phone":"+12163547758","notes":"string"}'

Request example

{
  "external_id": "ABCD1234",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "+12163547758",
  "notes": "string"
}

Response example (200)

{
  "message": "success"
}

Locations

Retrieve Locations

GET /locations

Retrieve your account locations

Responses

• 200 object
- message string
- data object
  locations array[object]
  
  uuid string(uuid)
  
  name string
  
  line_1 string
  
  line_2 string
  
  city string
  
  region string
  
  country string
  
  Country code in ISO-2 format
  
  zip_code string
  
  coordinates object
  
  lat number
  
  Minimum value is -90, maximum value is 90.
  
  lng number
  
  Minimum value is -180, maximum value is 180.

GET /locations

curl \
 -X GET https://{workspace}.fleetrunnr.com/api/v1/locations \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Response example (200)

{
  "message": "string",
  "data": {
    "locations": [
      {
        "uuid": "27df9695-5565-4091-b888-ca321b8566ff",
        "name": "Main Warehouse",
        "line_1": "2313 Retreat Avenue",
        "line_2": "Ste 300",
        "city": "Birmingham",
        "region": "Alabama",
        "country": "US",
        "zip_code": "35203",
        "coordinates": {
          "lat": 33.527805,
          "lng": -86.768112
        }
      }
    ]
  }
}

Orders

Get Order

GET /orders

Retrieve a single order by order_number or external_id

Query parameters

external_id string Required

The ID generated by your system (required if order_number is not specified)
order_number string Required

The unique order number generated by FleetRunnr (required if external_id is not specified)

Responses

• 200 object
- message string
- data object
  order object
  
  uuid string(uuid)
  
  order_number string
  
  The unique order number used for tracking purposes
  
  external_id string
  
  The order ID generated from a third-party system such as a CRM, POS, or accounting software
  
  tracking_url string(uri)
  
  The tracking URL for this order
  
  status string
  
  Values are NEW, READY, DISPATCHED, SHIPPED, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, DELIVERY_ATTEMPTED, CANCELLED, CLOSED, DISPATCHED_FOR_RETURN, RETURN_IN_PROGRESS, or RETURN_ATTEMPTED.
  
  customer object
  
  uuid string(uuid)
  
  external_id string
  
  Customer's ID generated from a third-party system such as a CRM, POS, or accounting software
  
  first_name string
  
  last_name string
  
  email string(email)
  
  phone string(phone)
  
  Customer's phone number in E.164 international format
  
  notes string
  
  source_location object
  
  uuid string(uuid)
  
  name string
  
  line_1 string
  
  line_2 string
  
  city string
  
  region string
  
  country string
  
  Country code in ISO-2 format
  
  zip_code string
  
  coordinates object
  
  lat number
  
  Minimum value is -90, maximum value is 90.
  
  lng number
  
  Minimum value is -180, maximum value is 180.
  
  source_contact object
  
  name string
  
  email string(email)
  
  phone string(phone)
  
  Contact's phone number in E.164 international format
  
  destination_location object
  
  uuid string(uuid)
  
  name string
  
  line_1 string
  
  line_2 string
  
  city string
  
  region string
  
  country string
  
  Country code in ISO-2 format
  
  zip_code string
  
  coordinates object
  
  lat number
  
  Minimum value is -90, maximum value is 90.
  
  lng number
  
  Minimum value is -180, maximum value is 180.
  
  destination_contact object
  
  name string
  
  email string(email)
  
  phone string(phone)
  
  Contact's phone number in E.164 international format
  
  collections array[object]
  
  The collections to be expected on delivery (multiple collections can be present for different currencies)
  
  amount number
  
  Minimum value is 0.
  
  currency string
  
  Currency in ISO-3 format
  
  type string
  
  Collection's payment method
  
  Values are CASH, CHEQUE, or CREDIT_CARD.
  
  packages array[object]
  
  uuid string(uuid)
  
  barcode string
  
  The unique barcode for this package
  
  type string
  
  Values are ENVELOPE, BAG, or BOX.
  
  length number
  
  Minimum value is 0.
  
  width number
  
  Minimum value is 0.
  
  height number
  
  Minimum value is 0.
  
  weight number
  
  Minimum value is 0.
  
  length_unit string
  
  Values are cm or in.
  
  weight_unit string
  
  Values are kg or oz.
  
  proof_of_delivery object
  
  signature boolean
  
  Indicate whether to require a signature upon delivery
  
  image boolean
  
  Indicate whether to require a picture to be taken upon delivery
  
  pickup_schedule object
  
  from string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
  
  to string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
  
  delivery_schedule object
  
  from string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
  
  to string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
  
  is_return boolean
  
  Indicates that the order is using the return workflow (sourced from a customer)
  
  notes string
  
  created_at string(date-time)
  
  The timestamp when the order was created
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
  
  completed_at string(date-time)
  
  The timestamp when the order was completed
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.

GET /orders

curl \
 -X GET https://{workspace}.fleetrunnr.com/api/v1/orders?external_id=string&order_number=string \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Response example (200)

{
  "message": "string",
  "data": {
    "order": {
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "order_number": "382968892483436544",
      "external_id": "XYZ987",
      "tracking_url": "https://track.fleetrunnr.com/382968892483436544?s=7fc3b54b8a4b02ffd",
      "status": "NEW",
      "customer": {
        "first_name": "John",
        "last_name": "Ondricka",
        "external_id": "ABCDE12345",
        "email": "john.ondricka@example.com",
        "phone": "+12163547758",
        "notes": "Some notes here..."
      },
      "source_location": {
        "uuid": "27df9695-5565-4091-b888-ca321b8566ff",
        "name": "Main Warehouse",
        "line_1": "2313 Retreat Avenue",
        "line_2": "Ste 300",
        "city": "Birmingham",
        "region": "Alabama",
        "country": "US",
        "zip_code": "35203",
        "coordinates": {
          "lat": 33.527805,
          "lng": -86.768112
        }
      },
      "source_contact": {
        "name": "Amanda Murrin",
        "email": "amanda.murrin@example.com",
        "phone": "+12025550159"
      },
      "destination_location": {
        "uuid": "84e249df-8d50-4212-8329-6059fc002563",
        "name": null,
        "line_1": "4840 Sun Valley Road",
        "line_2": "Flat 302",
        "city": "Prescott",
        "region": "Washington",
        "country": "US",
        "zip_code": "99348",
        "coordinates": {
          "lat": 46.371826,
          "lng": -118.496391
        }
      },
      "destination_contact": {
        "name": "John Ondricka",
        "email": "john.ondricka@example.com",
        "phone": "+12163547758"
      },
      "collections": [
        {
          "amount": 120.75,
          "currency": "USD",
          "type": "CASH"
        }
      ],
      "packages": [
        {
          "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
          "barcode": "383176549899173888",
          "type": "BAG",
          "length": 20,
          "width": 30,
          "height": 1,
          "weight": 0.25,
          "length_unit": "cm",
          "weight_unit": "kg"
        }
      ],
      "proof_of_delivery": {
        "signature": true,
        "image": false
      },
      "pickup_schedule": {
        "from": "2022-01-20 13:30",
        "to": "2022-01-20 15:00"
      },
      "delivery_schedule": {
        "from": "2022-01-23 09:00",
        "to": "2022-01-23 11:30"
      },
      "is_return": false,
      "notes": "These notes are used internally and not visible to customers..."
    }
  }
}

Create Order

POST /orders

Create a new order

Body

If the order uses the standard workflow (is_return is false), then the source_location should include the uuid of one of your account's locations.

If the order uses the return workflow (is_return is true), then the destination_location should include the uuid of one of your account's locations.

For packages, please check your account preferences for the measurement system your account is using (https://app.fleetrunnr.dev/settings/account)

external_id string

The order ID generated from a third-party system such as a CRM, POS, or accounting software
customer object Required
- uuid string(uuid)
- external_id string
  
  Customer's ID generated from a third-party system such as a CRM, POS, or accounting software
- first_name string
- last_name string
- email string(email)
- phone string(phone)
  
  Customer's phone number in E.164 international format
- notes string
source_location object Required
- uuid string(uuid)
- name string
- line_1 string
- line_2 string
- city string
- region string
- country string
  
  Country code in ISO-2 format
- zip_code string
- coordinates object
  lat number
  
  Minimum value is -90, maximum value is 90.
  
  lng number
  
  Minimum value is -180, maximum value is 180.
source_contact object
- name string
- email string(email)
- phone string(phone)
  
  Contact's phone number in E.164 international format
destination_location object Required
- uuid string(uuid)
- name string
- line_1 string
- line_2 string
- city string
- region string
- country string
  
  Country code in ISO-2 format
- zip_code string
- coordinates object
  lat number
  
  Minimum value is -90, maximum value is 90.
  
  lng number
  
  Minimum value is -180, maximum value is 180.
destination_contact object
- name string
- email string(email)
- phone string(phone)
  
  Contact's phone number in E.164 international format
collections array[object]
- amount number
  
  Minimum value is 0.
- currency string
  
  Currency in ISO-3 format
- type string
  
  Collection's payment method
  
  Values are CASH, CHEQUE, or CREDIT_CARD.
packages array[object] Required
- type string
  
  Values are ENVELOPE, BAG, or BOX.
- length number
  Imperial System: in
  
  Metric System: cm
  Minimum value is 0.
- width number
  Imperial System: in
  
  Metric System: cm
  Minimum value is 0.
- height number
  Imperial System: in
  
  Metric System: cm
  Minimum value is 0.
- weight number
  Imperial System: oz
  
  Metric System: kg
  Minimum value is 0.
proof_of_delivery object
- signature boolean
  
  Indicate whether to require a signature upon delivery
- image boolean
  
  Indicate whether to require a picture to be taken upon delivery
pickup_schedule object
- from string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
- to string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
delivery_schedule object
- from string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
- to string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
is_return boolean

Indicates that the order is using the return workflow (sourced from a customer)
notes string

Responses

• 200 object
- message string
- data object
  order_uuid string(uuid)
  
  The order's generated unique identifier

POST /orders

curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/orders \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"external_id":"XYZ987","customer":{"external_id":"ABCDE12345","first_name":"John","last_name":"Ondricka","email":"john.ondricka@example.com","phone":"+12163547758","notes":"Some notes here..."},"source_location":{"uuid":"27df9695-5565-4091-b888-ca321b8566ff"},"source_contact":{"name":"Amanda Murrin","email":"amanda.murrin@example.com","phone":"+12025550159"},"destination_location":{"name":null,"line_1":"4840 Sun Valley Road","line_2":"Flat 302","city":"Prescott","region":"Washington","country":"US","zip_code":"99348","coordinates":{"lat":46.371826,"lng":-118.496391}},"destination_contact":{"name":"John Ondricka","email":"john.ondricka@example.com","phone":"+12163547758"},"collections":[{"amount":120.75,"currency":"USD","type":"CASH"}],"packages":[{"type":"BAG","length":20,"width":30,"height":1,"weight":0.25}],"proof_of_delivery":{"signature":true,"image":false},"pickup_schedule":{"from":"2022-01-20 13:30","to":"2022-01-20 15:00"},"delivery_schedule":{"from":"2022-01-23 09:00","to":"2022-01-23 11:30"},"is_return":false,"notes":"These notes are internal and not visible to customers..."}'

Request examples

{
  "external_id": "XYZ987",
  "customer": {
    "external_id": "ABCDE12345",
    "first_name": "John",
    "last_name": "Ondricka",
    "email": "john.ondricka@example.com",
    "phone": "+12163547758",
    "notes": "Some notes here..."
  },
  "source_location": {
    "uuid": "27df9695-5565-4091-b888-ca321b8566ff"
  },
  "source_contact": {
    "name": "Amanda Murrin",
    "email": "amanda.murrin@example.com",
    "phone": "+12025550159"
  },
  "destination_location": {
    "name": null,
    "line_1": "4840 Sun Valley Road",
    "line_2": "Flat 302",
    "city": "Prescott",
    "region": "Washington",
    "country": "US",
    "zip_code": "99348",
    "coordinates": {
      "lat": 46.371826,
      "lng": -118.496391
    }
  },
  "destination_contact": {
    "name": "John Ondricka",
    "email": "john.ondricka@example.com",
    "phone": "+12163547758"
  },
  "collections": [
    {
      "amount": 120.75,
      "currency": "USD",
      "type": "CASH"
    }
  ],
  "packages": [
    {
      "type": "BAG",
      "length": 20,
      "width": 30,
      "height": 1,
      "weight": 0.25
    }
  ],
  "proof_of_delivery": {
    "signature": true,
    "image": false
  },
  "pickup_schedule": {
    "from": "2022-01-20 13:30",
    "to": "2022-01-20 15:00"
  },
  "delivery_schedule": {
    "from": "2022-01-23 09:00",
    "to": "2022-01-23 11:30"
  },
  "is_return": false,
  "notes": "These notes are internal and not visible to customers..."
}

{
  "external_id": "XYZ987",
  "customer": {
    "uuid": "69e93118-a581-4a13-afea-b6d4a2d2c40c"
  },
  "source_location": {
    "uuid": "27df9695-5565-4091-b888-ca321b8566ff"
  },
  "source_contact": {
    "name": "Amanda Murrin",
    "email": "amanda.murrin@example.com",
    "phone": "+12025550159"
  },
  "destination_location": {
    "uuid": "84e249df-8d50-4212-8329-6059fc002563"
  },
  "destination_contact": {
    "name": "John Ondricka",
    "email": "john.ondricka@example.com",
    "phone": "+12163547758"
  },
  "collections": [
    {
      "amount": 120.75,
      "currency": "USD",
      "type": "CASH"
    }
  ],
  "packages": [
    {
      "type": "BAG",
      "length": 20,
      "width": 30,
      "height": 1,
      "weight": 0.25
    }
  ],
  "proof_of_delivery": {
    "signature": true,
    "image": false
  },
  "pickup_schedule": {
    "from": "2022-01-20 13:30",
    "to": "2022-01-20 15:00"
  },
  "delivery_schedule": {
    "from": "2022-01-23 09:00",
    "to": "2022-01-23 11:30"
  },
  "is_return": false,
  "notes": "These notes are internal and not visible to customers..."
}

Response example (200)

{
  "message": "success",
  "data": {
    "order_uuid": "20c48af2-cb48-40e7-9d1f-372f9ec5bfbc"
  }
}

Update Order

PATCH /orders/{order_uuid}

Update the information of an existing order

Body

external_id string

The order ID generated from a third-party system such as a CRM, POS, or accounting software
proof_of_delivery object
- signature boolean
  
  Indicate whether to require a signature upon delivery
- image boolean
  
  Indicate whether to require a picture to be taken upon delivery
pickup_schedule object
- from string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
- to string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
delivery_schedule object
- from string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
- to string(date-time)
  
  Should be in UTC timezone
  
  Format should match the following pattern: YYYY-MM-DD HH:MM.
notes string

Responses

• 200 object
- message string

PATCH /orders/{order_uuid}

curl \
 -X PATCH https://{workspace}.fleetrunnr.com/api/v1/orders/{order_uuid} \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"external_id":"DEF456","proof_of_delivery":{"signature":true,"image":true},"pickup_schedule":{"from":"2022-01-20 13:30","to":"2022-01-20 15:00"},"delivery_schedule":{"from":"2022-01-23 09:00","to":"2022-01-23 11:30"},"notes":"string"}'

Request example

{
  "external_id": "DEF456",
  "proof_of_delivery": {
    "signature": true,
    "image": true
  },
  "pickup_schedule": {
    "from": "2022-01-20 13:30",
    "to": "2022-01-20 15:00"
  },
  "delivery_schedule": {
    "from": "2022-01-23 09:00",
    "to": "2022-01-23 11:30"
  },
  "notes": "string"
}

Response example (200)

{
  "message": "success"
}

Assign Carrier

POST /orders/{order_uuid}/assign

Assign an order to one of your connected carriers

Body

You may retrieve the carrier_uuid and the shipping_method_uuid from the Get Carriers endpoint.

carrier_uuid string(uuid) Required

The carrier's uuid.
shipping_method_uuid string(uuid) Required

The shipping method uuid

This shipping method must be assigned to you by the specified carrier.

Responses

• 200 object
- message string

POST /orders/{order_uuid}/assign

curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/orders/{order_uuid}/assign \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"carrier_uuid":"fd5bcc10-1feb-40c1-9ce7-a3001c6dbed3","shipping_method_uuid":"8a316441-72e9-44sa-b31e-60aff566c8a0"}'

Request example

{
  "carrier_uuid": "fd5bcc10-1feb-40c1-9ce7-a3001c6dbed3",
  "shipping_method_uuid": "8a316441-72e9-44sa-b31e-60aff566c8a0"
}

Response example (200)

{
  "message": "success"
}

Cancel Order

POST /orders/{order_uuid}/cancel

Cancel an existing order

Responses

• 200 object
- message string

POST /orders/{order_uuid}/cancel

curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/orders/{order_uuid}/cancel \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Response example (200)

{
  "message": "success"
}

Generate Labels

POST /orders/generate-labels

Generate labels for a list of orders

Body

orders array Required

The array of order UUIDs
size string Required

The shipping label size.

Values are A4, A5, A6, PAPER_ROLL, or TAG.

Responses

• 200 object

Generated.
- message string
- data object
  url string
  
  The url of the generated labels.

POST /orders/generate-labels

curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/orders/generate-labels \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"orders":["8eb8168d-07e3-4bf9-a678-636689d1a876"],"size":"A6"}'

Request example

{
  "orders": [
    "8eb8168d-07e3-4bf9-a678-636689d1a876"
  ],
  "size": "A6"
}

Response example (200)

{
  "message": "success",
  "data": {
    "url": "https://s3.eu-west-1.amazonaws.com/media.fleetrunnr/6e92736d-7f41-46de-9c72-6c8b74990722.pdf?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3GLSPZCROCOCUP7S%2F20220401%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220401T094455Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Signature=51eda1ef262f8a0e21786814735a6144e6e157b867250892182fcbf0f04ca414"
  }
}

FleetRunnr API 1.0

FleetRunnr API
1.0