NAV Navbar
JavaScript SDK

Gofleetly API Reference

You can install our JavaScript SDK via npm:

$ npm install @gofleetly/api
/* ES6+ */
import Gofleetly from '@gofleetly/api';

/* CommonJS */
const Gofleetly = require('@gofleetly/api');

/* AMD */
require(['@gofleetly/api'], function(Gofleetly) {
  // ...
});

The Gofleetly API Reference describes the endpoints in our REST API.

We currently offer an SDK for JavaScript (Node.js). Although this SDK can be used from browser-facing code, we do not recommend this due to the potential to leak your API keys. Additional SDKs in other languages are available upon request.

Example code for any SDKs will be shown on the right pane. This center pane will document endpoints for language-independent use (e.g. cURL).

Postman Collection

You can also leverage our Postman collection for easily testing out API routes.

Run in Postman

Make sure to enter in your API key in the collection's authorization settings. Note that not all optional params are included in the colllection; see each endpoint doc for more details.

Authentication

Pass your API key to the Gofleetly constructor to create an API client

const gofleetly = new Gofleetly('YOUR_API_KEY_HERE');

Gofleetly uses API Keys to securely authenticate requests. If a Gofleetly API key is not included when making a request, or an invalid key is used, Gofleetly will return an error.

You will be provided with seperate keys for testing and running live deliveries.

API keys should be included in the following HTTP header, where {{apiKey}} is your API key:
Authorization: Bearer {{apiKey}}

Obtaining your API keys

API keys can be created by signing up for an account on the Gofleetly dashboard or by reaching out to your Gofleetly representative.

Test and live modes

When obtaining your API keys, you will be provided with a test key and a production key. All properties of deliveries made using your test key will mimic those of a live delivery, except for an actual courier fulfilling the delivery. Responses that are variable will be randomized within reasonable parameters and should not be considered representative of anticipated production values.

Gofleetly partners

Our API is consumable by Gofleetly partners and non-partners.

When signing up to our dashboard, you will start out as a non-partner. This means that you will need to pay for each Gofleetly delivery at the time of scheduling.

The only payment option currently available for non-partners is Stripe. In practice, this means you will need to include a tokenized credit card every time you hit our schedule endpoint. We'll charge this card if the delivery is successfully scheduled. Likewise, we'll refund this card if you cancel a refundable delivery. See your keys page for information on getting started with Stripe.

For Gofleetly partners, Stripe is not required. Partners enjoy more flexibility and better rates while using Gofleetly services.

Interested in becoming a Gofleetly partner? Contact us!

Requests

The base URL for requests is https://api.go-fleetly.com.
All requests must be made over HTTPS.

HTTP Methods

We leverage HTTP message formatting as the method of communication with our interface. The most-commonly-used HTTP verbs are POST, GET, PUT, and DELETE. In our interface, these correspond to create, read, update, and delete (or CRUD) operations, respectively.

Versioning

The current major version is 1.
To avoid breaking changes, pass an X-Gofleetly-Version header specifying your desired API version.

The API SDKs handle this for you.

Rate limiting

To protect our endpoints and keep high availability, we rate limit requests to the API. General routes are protected by a rate limit of 3 requests per second. If you have concerns about your application exceeding this limit, please contact us.

API consumers that pass the limit will be responded to with a 429 error (see the Error section).

All responses from the API include the following headers:

Request bodies

Request bodies can be sent as either application/x-www-form-urlencoded or application/json. The examples in these docs use the latter.

Make sure you set the Content-Type header appropriately. The API SDKs handle this for you.

Responses

All Gofleetly responses are in JSON.

Dates, times, and currency

Dates are formatted in ISO 8061 with a UTC offset that the standard denotes with 'Z'. Currency is interpreted as USD and represented as a whole number integer with the leftmost two digits being cents.

Units Format Example
Dates ISO 8601 10-10-10
Times ISO 8061 10-10-10T15:46:20Z
Currency USD Integer 1499 ($14.99)

Status codes

Gofleetly responds to requests with HTTP status codes allowing for easy programming between interfaces.

For successful requests, we send back a 200 (or a 201 if a resource was created).

See the Errors section for our error codes.

Webhooks

Webhooks allow you to build or set up integrations which subscribe to certain Gofleetly events. Whenever an event below is triggered, we'll send an HTTP POST request to your configured webhook URL.

By using webhooks you can mitigate repeatedly polling endpoints (such as Get Delivery Details) for up-to-date info. You can configure your webhook URLs in your dashboard where you can specify different URLs for test vs live mode.

Events

{
  "event": "delivery_update",
  "data": {
    "delivery": {
      "id": "HKJ2KJ2",
      // ...
    }
  }
}

{
  "event": "offer_redemption",
  "data": {
    "offer": {
      "id": "OA5m3vvxD",
      // ...
    },
    "delivery": {
      "id": "HKJ2KJ2",
      // ...
    }
  }
}

{
  "event": "example",
  "data": {
    "example": "Hello from Gofleetly!"
  }
}

On the right pane is an example request body for a delivery_update event. When properties of a delivery are changed for any reason, we'll trigger a POST request to your specified webhook URL with the updated delivery as the payload.

Event Description Data
delivery_update Sent any time information about a delivery changes (e.g. status, ETA, etc.) Delivery
offer_redemption Sent any time an offer you created is redeemed (meaning a customer successfully schedules a delivery using the offer link). Offer, Delivery
example Sent through your dashboard when testing webhook URLs. "Hello from Gofleetly!"

Local development

We recommend ngrok for local development. ngrok allows you to set up a tunnel to any localhost port running on your machine. To use ngrok for local development and testing, simply:

  1. Download and install ngrok.
  2. Run your local server & note the used port number (e.g. 80).
  3. Tunnel your traffic from ngrok to your localhost $ ./ngrok http 80.
  4. Copy the link ngrok produces (e.g. http://2kjl3.ngrok.io) and paste it into the test webhook URL field in your Gofleetly dashboard.
  5. Save your changes on the page.
  6. Trigger a webhook event using the 'Test Webhook' button on the same page.

From there you should see an HTTP POST request being made to your server by Gofleetly with a sample webhook payload.

Security

import crypto from 'crypto';

// pick up API key from environment (never commit keys to source control)
const GOFLEETLY_API_KEY = process.env.GOFLEETLY_API_KEY;

/**
 * Checks if a webhook request actually came from Gofleetly.
 * @param {String} payload The raw body of the request
 * @param {String} signature The `X-Gofleetly-Signature` header
 * @return {Boolean} True if valid, false otherwise
 * @see https://docs.go-fleetly.com/#webhooks
 */
export const isLegitimateGofleetlyRequest(payload, signature) {
  const encryptedPayload = crypto
    .createHmac('sha256', GOFLEETLY_API_KEY)
    .update(payload)
    .digest('hex');

  return encryptedPayload === signature;
}

// Example implementation:
// if (!isLegitimateGofleetlyRequest(payload, signature)) throw new Error('Invalid Request!');

To verify whether or not a webhook request is legitimate (i.e. came from Gofleetly and not a malicious actor), you can verify the X-Gofleetly-Signature header in the webhook request.

A valid signature will be the request body string encrypted using SHA-256 with your Gofleetly API key as the encryption key.

See the right pane for an example of how to perform this check in Node.js.

Quotes

Quote a delivery

const params = {
  "store": {
    "name": "string",
    "id": "string",
    "phone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "latitude": -180,
      "longitude": -180
    }
  },
  "dropoffAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "latitude": -180,
    "longitude": -180
  },
  "items": [
    {
      "id": "string",
      "sku": "string",
      "name": "string",
      "price": 0,
      "quantity": 1,
      "storeId": "string",
      "weight": 0,
      "height": 0,
      "width": 0,
      "length": 0,
      "size": "string",
      "color": "string",
      "imageURL": "http://example.com",
      "productURL": "http://example.com"
    }
  ],
  "pickupReadyByTime": "2019-02-10T02:17:48Z"
};

gofleetly.quoteDelivery(params)
  .then(quote => {
    console.log(quote.id);
  })
  .catch(err => {
    console.error(err);
  });

POST /quotes

Generates a quote for a delivery.

Parameters

Name In Type Required Description
store body Store true The physical store where the items will be picked up from.
dropoffAddress body Address true The customer's address for delivery.
items body [Item] true The items that will be delivered from the store to the dropoffAddress. At least one item is required.
pickupReadyByTime body string false Timestamp corresponding to when the items will be ready for pickup. The current time is used if omitted.

Responses

Status Meaning Description Schema
201 Created A new delivery quote. Quote
default Default See the errors documentation page. Error

Update items

const params = {
  "id": "string",
  "items": [
    {
      "id": "string",
      "sku": "string",
      "name": "string",
      "price": 0,
      "quantity": 1,
      "storeId": "string",
      "weight": 0,
      "height": 0,
      "width": 0,
      "length": 0,
      "size": "string",
      "color": "string",
      "imageURL": "http://example.com",
      "productURL": "http://example.com"
    }
  ]
};

gofleetly.updateItems(params)
  .then(quote => {
    console.log(quote.items);
  })
  .catch(err => {
    console.error(err);
  });

PUT /quotes/{id}/items

Updates the items associated with an existing delivery. This will overwrite the array.

Parameters

Name In Type Required Description
id path string true ID of an existing quote.
items body [Item] true The items that will overwrite those associated with this quote. At least one item is required.

Responses

Status Meaning Description Schema
200 OK The updated quote. Quote
default Default See the errors documentation page. Error

Refresh a quote

const params = {
  "id": "string"
};

gofleetly.refreshQuote(params)
  .then(quote => {
    console.log(quote.id);
  })
  .catch(err => {
    console.error(err);
  });

POST /quotes/{id}/refresh

Refreshes an expired quote.

Parameters

Name In Type Required Description
id path string true ID of an existing quote.

Responses

Status Meaning Description Schema
201 Created A new delivery quote based on the properties of the original one. Quote
default Default See the errors documentation page. Error

Deliveries

Get delivery details

const params = {
  "id": "string"
};

gofleetly.getDelivery(params)
  .then(delivery => {
    console.log(delivery.status);
  })
  .catch(err => {
    console.error(err);
  });

GET /deliveries/{id}

Gets the most up-to-date details about an existing delivery.

Parameters

Name In Type Required Description
id path string true ID of an existing delivery.

Responses

Status Meaning Description Schema
200 OK The delivery identified by the provided ID. Delivery
default Default See the errors documentation page. Error

Schedule a delivery

const params = {
  "quoteId": "string",
  "orderNumber": "string",
  "dropoffName": "string",
  "dropoffPhone": "string"
};

gofleetly.scheduleDelivery(params)
  .then(delivery => {
    console.log(delivery.status);
  })
  .catch(err => {
    console.error(err);
  });

POST /deliveries

Schedules a delivery.

Parameters

Name In Type Required Description
quoteId body string true ID of an existing quote.
orderNumber body string true A unique ID given to the customer identifying their order with your store.
dropoffName body string true The full name of the customer.
dropoffPhone body string true The customer's phone number in E.164 format (e.g. "+15051234567").
shouldSendSMS body boolean false Whether or not SMS updates should be sent to the provided dropoffPhone when this delivery's status changes. If omitted, we'll use your global setting for deliveries.
pickupInstructions body string false Optional pickup instructions. Up to 255 characters. If omitted, we instruct the courier to pick items up from the customer service desk.
dropoffInstructions body string false Optional dropoff instructions (e.g. "gate code is 123"). Up to 255 characters.
preferredETA body string false Timestamp corresponding to when the customer would prefer the delivery to be completed. Must be at least an hour after the pickupReadyByTime and at least an hour in the future. If omitted, the delivery will be completed ASAP after the items are ready for pickup.
stripeId body string If you are a Gofleetly partner, you do not need to provide this parameter since deliveries are collectively invoiced per your subscription plan and tier. If you are not a Gofleetly partner, you must provide this parameter. More info...

Responses

Status Meaning Description Schema
201 Created A new delivery based on the provided quote ID. Delivery
default Default See the errors documentation page. Error

Edit a delivery

const params = {
  "orderNumber": "string",
  "dropoffName": "string",
  "dropoffPhone": "string",
  "store": {
    "name": "string",
    "id": "string",
    "phone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "latitude": -180,
      "longitude": -180
    }
  },
  "dropoffAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "latitude": -180,
    "longitude": -180
  },
  "items": [
    {
      "id": "string",
      "sku": "string",
      "name": "string",
      "price": 0,
      "quantity": 1,
      "storeId": "string",
      "weight": 0,
      "height": 0,
      "width": 0,
      "length": 0,
      "size": "string",
      "color": "string",
      "imageURL": "http://example.com",
      "productURL": "http://example.com"
    }
  ],
  "shouldSendSMS": true,
  "pickupInstructions": "string",
  "dropoffInstructions": "string",
  "stripeId": "string",
  "preferredETA": "2019-02-10T02:17:48Z"
  "pickupReadyByTime": "2019-02-10T02:17:48Z"
};

gofleetly.editDelivery(params)
  .then(delivery => {
    console.log(delivery.status);
  })
  .catch(err => {
    console.error(err);
  });

PATCH /deliveries/{id}

Makes a best effort to edit an existing delivery. Note that this endpoint does not support clearing optional parameters such as pickupReadyByTime and preferredETA; any fields not provided will use those previously provided to create the delivery resource.

Parameters

Name In Type Required Description
orderNumber body string false Changes order number referenced in delivery. If past point of editing will return an error.
store body Store false The physical store where the items will be picked up from. If past point of editing will return an error.
dropoffAddress body Address false The customer's address for delivery. If past point of editing will return an error.
dropoffName body string false Changes name for dropoff referenced in delivery. If past point of editing will return an error.
dropoffPhone body string false Changes phone for dropoff referenced in delivery. If past point of editing will return an error.
items body [Item] false Changes items referenced in delivery. IMPORTANT: If items do not meet the restrictions of the currently scheduled courier or past point of editing will return an error.
shouldSendSMS body boolean false Changes whether or not a customer receives SMS updates. If past point of editing will return an error.
pickupInstructions body string false Changes pickup instructions referenced in delivery. If past point of editing will return an error.
dropoffInstructions body string false Changes dropoff instructions referenced in delivery. If past point of editing will return an error.
stripeId body string false This field is for non-partners only. Stripe ID to charge in the case of new delivery fees. IMPORTANT: If omitted and new charges are incurred, will return an error.
preferredETA body date false Changes preferredETA of a delivery. IMPORTANT: If delivery cannot be canceled, an error will be returned.
pickupReadyByTime body date false Changes the pickupReadyByTime of a delivery. If past point of editing will return an error.

Responses

Status Meaning Description Schema
200 OK An updated delivery based on the provided parameters. Delivery
201 OK A new delivery based on the provided parameters. This response is triggered if the existing delivery had to be canceled to make the change. Delivery
default Default See the errors documentation page. Error

Cancel a delivery

const params = {
  "id": "string"
};

gofleetly.cancelDelivery(params)
  .then(canceledDelivery => {
    console.log(canceledDelivery);
  })
  .catch(err => {
    console.error(err);
  });

DELETE /deliveries/{id}

Depending on needs, deliveries have the ability to be both canceled and refunded. To query whether or not a delivery is available for such options, use the GET Delivery Endpoint endpoint. You may then confirm the cancelation using the endpoint listed here.

Parameters

Name In Type Required Description
id path string true ID of an existing delivery.

Responses

Status Meaning Description Schema
200 OK The canceled delivery identified by the provided ID. Delivery
default Default See the errors documentation page. Error

Submit feedback

const params = {
  "id": "string",
  "score": 100
};

gofleetly.submitFeedback(params)
  .then(delivery => {
    console.log(delivery.feedbackScore);
  })
  .catch(err => {
    console.error(err);
  });

PUT /deliveries/{id}/feedback

Assigns a 0-100 feedback score for an existing delivery.

Parameters

Name In Type Required Description
id path string true ID of an existing delivery.
score body integer true Customer's 0 to 100 score for this delivery.

Responses

Status Meaning Description Schema
200 OK The delivery identified by the provided ID. Delivery
default Default See the errors documentation page. Error

Save the sale with Offers

Offers are the easiest way to get started with Gofleetly. An "offer" can be thought of as an offer for delivery that gets sent to a customer after they have already placed an order at your store. By default, Gofleetly handles any necessary forms, logistics, and communication with the customer - all you need to do is provide the order information.

Offer workflow

If you currently support in-store pickup for your store orders, this is a perfect way to add additional fulfillment capabilities to your brand and reduce in-store pickup abandonment.

One example use case:

  1. A customer places a BOPIS order at your store.
  2. A store associate picks/packs the customer's order.
  3. The customer receives an email stating that their order is ready for pickup and that they have 7 days to pick it up before their order is cancelled.
  4. Six days pass and the customer has yet to pick up their order (maybe they're too busy to swing by!)
  5. You hit Gofleetly's create a delivery offer endpoint.
  6. The customer receives an email offering them same-day delivery for their order.
  7. The customer opts-in for same-day delivery using the link within that email.
  8. A Gofleetly courier picks up and delivers customer's order.
  9. You've saved an otherwise lost sale!

Get offer details

const params = {
  "id": "string"
};

gofleetly.getOffer(params)
  .then(offer => {
    console.log(offer.url);
  })
  .catch(err => {
    console.error(err);
  });

GET /offers/{id}

Gets the most up-to-date details about an existing offer.

Parameters

Name In Type Required Description
id path string true ID of an existing offer.

Responses

Status Meaning Description Schema
200 OK The offer identified by the provided ID. Offer
default Default See the errors documentation page. Error

Create an offer

const params = {
  "store": {
    "name": "string",
    "id": "string",
    "phone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "latitude": -180,
      "longitude": -180
    }
  },
  "dropoffAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "latitude": -180,
    "longitude": -180
  },
  "items": [
    {
      "id": "string",
      "sku": "string",
      "name": "string",
      "price": 0,
      "quantity": 1,
      "storeId": "string",
      "weight": 0,
      "height": 0,
      "width": 0,
      "length": 0,
      "size": "string",
      "color": "string",
      "imageURL": "http://example.com",
      "productURL": "http://example.com"
    }
  ],
  "pickupReadyByTime": "2019-02-10T02:17:48Z",
  "orderNumber": "string",
  "dropoffName": "string",
  "dropoffPhone": "string",
  "shouldSendSMS": true,
  "pickupInstructions": "string",
  "dropoffInstructions": "string",
  "eligibleDeliveryTimes": [
    "2019-02-10T02:17:48Z"
  ],
  "expiration": "2019-02-10T02:17:48Z",
  "pageProperties": {
    "title": "string",
    "description": "string",
    "color": "string",
    "logoURL": "string",
    "expirationMessage": "string",
    "googleAnalyticsId": "string",
  },
  "notification": {
    "type": "string",
    "email": "string",
    "phone": "string",
    "subject": "string",
    "body": "string"
  },
  "readOnlyProperties": ["dropoffAddress", "dropoffName", "dropoffPhone", "shouldSendSMS"],
};

gofleetly.createOffer(params)
  .then(offer => {
    console.log(offer.id);
  })
  .catch(err => {
    console.error(err);
  });

POST /offers

Generates a delivery offer.

Depending on whether or not you provide a notification parameter, Gofleetly may send an email or a text message to the user containing the offer link upon offer creation. This functionality is strictly opt-in through that parameter, so feel free to omit it if you'd rather send the URL yourself.

Parameters

Name In Type Required Description
store body Store true The physical store where the items will be picked up from.
dropoffAddress body Address false The customer's address for delivery.
items body [Item] true The items that will be delivered from the store to the dropoffAddress. At least one item is required.
pickupReadyByTime body string false Timestamp corresponding to when the items will be ready for pickup. If omitted, we'll assume the items are immediately ready for pickup.
orderNumber body string true A unique ID given to the customer identifying their order with your store.
dropoffName body string false The full name of the customer.
dropoffPhone body string false The customer's phone number in E.164 format (e.g. "+15051234567").
shouldSendSMS body boolean false Whether or not SMS updates should be sent to the provided dropoffPhone when a delivery created based on this offer changes statuses. If omitted, we'll use your global setting for deliveries at the time of offer creation.
pickupInstructions body string false Optional pickup instructions. Up to 255 characters. If omitted, we instruct the courier to pick items up from the customer service desk.
dropoffInstructions body string false Optional dropoff instructions (e.g. "gate code is 123"). Up to 255 characters.
eligibleDeliveryTimes body [Date] false Array of timestamps that the customer can choose from; to be used as the delivery's preferredETA. If you do provide eligible delivery times, all times must be a minimum of one hour past the provided pickupReadyByTime as well as one hour from the time of offer creation. The offer will expire once all eligibleDeliveryTimes have passed. If omitted, delivery will be performed ASAP.
expiration body string false Timestamp corresponding to when this offer should expire. A customer navigating to the offer page past this point will receive an error UI (see pageProperties).
pageProperties body OfferPageProperties false Customizations to the offer page.
notification body OfferNotification false Configuration for a notification sent to the customer containing the offer URL. If omitted, no notification will be sent to the customer. You will need to do so manually using the returned offer's url property.
readOnlyProperties body [string] false An array of property names that the customer will not allowed to change on the offer page. Valid keys are dropoffAddress, dropoffName, dropoffPhone, and shouldSendSMS. Any value provided here except shouldSendSMS must have also been provided in request body.

Responses

Status Meaning Description Schema
201 Created A new delivery offer. Offer
default Default See the errors documentation page. Error

Update an offer

const params = {
  "id": "string",
  "eligibleDeliveryTimes": [
    "2019-02-10T02:17:48Z"
  ],
  "expiration": "2019-02-10T02:17:48Z",
  "shouldSendSMS": false,
  "dropoffAddress": null
};

gofleetly.updateOffer(params)
  .then(updatedOffer => {
    console.log(updatedOffer.id);
  })
  .catch(err => {
    console.error(err);
  });

PATCH /offers/{id}

Updates a delivery offer.

Redeemed or canceled offers cannot be updated. If the existing offer has expired, its status will be re-evaluated if a new expiration and/or eligibleDeliveryTimes is provided (e.g. if an offer is expired due all eligibleDeliveryTimes passing and you hit this endpoint with a valid set of new eligibleDeliveryTimes, the offer's status will change to created).

Parameters

Name In Type Required Description
id path string true ID of an existing offer.
store body Store false The physical store where the items will be picked up from.
dropoffAddress body Address false The customer's address for delivery. Pass null to clear the existing value.
items body [Item] false The items that will be delivered from the store to the dropoffAddress. At least one item is required if provided (will overwrite previous items).
pickupReadyByTime body string false Timestamp corresponding to when the items will be ready for pickup.
orderNumber body string false A unique ID given to the customer identifying their order with your store.
dropoffName body string false The full name of the customer. Pass null to clear the existing value.
dropoffPhone body string false The customer's phone number in E.164 format (e.g. "+15051234567"). Pass null to clear the existing value.
shouldSendSMS body boolean false Whether or not SMS updates should be sent to the provided dropoffPhone when a delivery created based on this offer changes statuses.
pickupInstructions body string false Optional pickup instructions. Up to 255 characters.
dropoffInstructions body string false Optional dropoff instructions (e.g. "gate code is 123"). Up to 255 characters.
eligibleDeliveryTimes body [Date] false Array of timestamps that the customer can choose from; to be used as the delivery's preferredETA. See creation endpoint for docs. Pass null to clear the existing value (and thus revert to ASAP delivery).
expiration body string false Timestamp corresponding to when this offer should expire. A customer navigating to the offer page past this point will receive an error UI (see pageProperties). Pass null to clear the existing value.
pageProperties body OfferPageProperties false Customizations to the offer page. Pass null to clear the existing value.
notification body OfferNotification false Configuration for a notification sent to the customer containing the offer URL. Pass null to clear the existing value.
readOnlyProperties body [string] false An array of property names that the customer will not allowed to change on the offer page. Valid keys are dropoffAddress, dropoffName, dropoffPhone, and shouldSendSMS. Any value in this array except shouldSendSMS must either already exist on the offer or be provided in the request body.

Responses

Status Meaning Description Schema
200 OK The updated offer. Offer
default Default See the errors documentation page. Error

Cancel an offer

const params = {
  "id": "string"
};

gofleetly.cancelOffer(params)
  .then(canceledOffer => {
    console.log(canceledOffer);
  })
  .catch(err => {
    console.error(err);
  });

DELETE /offers/{id}

Cancels a delivery offer. An offer cannot be canceled once it has been redeemed by the customer. If the offer gets canceled before this point, any customer visiting the offer link will be shown messaging explaining that the offer has expired.

Parameters

Name In Type Required Description
id path string true ID of an existing offer.

Responses

Status Meaning Description Schema
200 OK The canceled offer identified by the provided ID. Offer
default Default See the errors documentation page. Error

Schemas

Quote

{
  "items": [
    {
      "id": "string",
      "sku": "string",
      "name": "string",
      "price": 0,
      "quantity": 1,
      "storeId": "string",
      "weight": 0,
      "height": 0,
      "width": 0,
      "length": 0,
      "size": "string",
      "color": "string",
      "imageURL": "http://example.com",
      "productURL": "http://example.com"
    }
  ],
  "pickupReadyByTime": "2019-02-10T02:17:48Z",
  "store": {
    "name": "string",
    "id": "string",
    "phone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "latitude": -180,
      "longitude": -180
    }
  },
  "dropoffAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "latitude": -180,
    "longitude": -180
  },
  "expiration": "2019-02-10T02:17:48Z",
  "earliestDropoffWindow": {
    "start": "2019-02-10T02:17:48Z",
    "end": "2019-02-10T02:17:48Z"
  },
  "createdAt": "2019-02-10T02:17:48Z",
  "updatedAt": "2019-02-10T02:17:48Z",
  "id": "string",
  "total": 0,
  "isLive": true
}

Properties

Name Type Required Description
items [Item] true The items that will be delivered from the store to the dropoffAddress.
pickupReadyByTime string true Timestamp corresponding to when the items will be ready for pickup.
store Store true The physical store where the items will be picked up from.
dropoffAddress Address true The customer's address for delivery.
expiration string true Timestamp corresponding to when this quote can no longer be scheduled.
earliestDropoffWindow DateRange true Earliest estimated dropoff ETA if this quote were to be scheduled.
createdAt string true Timestamp corresponding to when this quote was created.
updatedAt string true Timestamp corresponding to the last time this quote was updated.
id string true Unique identifier for this quote.
total number true Total billable cost for this delivery.
isLive boolean true Whether or not this quote was created in live mode.

Delivery

{
  "status": "created",
  "orderNumber": "string",
  "dropoffName": "string",
  "dropoffPhone": "string",
  "shouldSendSMS": true,
  "createdAt": "2019-02-10T02:17:48Z",
  "updatedAt": "2019-02-10T02:17:48Z",
  "deliveredAt": "2019-02-10T02:17:48Z",
  "id": "string",
  "feedbackScore": 0,
  "pickupInstructions": "string",
  "dropoffInstructions": "string",
  "preferredETA": "2019-02-10T02:17:48Z",
  "estimatedDropoffWindow": {
    "start": "2019-02-10T02:17:48Z",
    "end": "2019-02-10T02:17:48Z"
  },
  "isCancelable": true,
  "isRefundAvailable": false,
  "quote": {
    // ...
  }
}

Properties

Name Type Required Description
status string true See the status values below
orderNumber string true A unique ID given to the customer identifying their order with your store.
dropoffName string true The full name of the customer.
dropoffPhone string true The customer's phone number in E.164 format (e.g. "+15051234567").
shouldSendSMS boolean true Whether or not SMS updates are sent to the dropoffPhone whenever this delivery's status changes.
createdAt string true Timestamp corresponding to when this delivery was created.
updatedAt string true Timestamp corresponding to the last time this delivery was updated.
deliveredAt string false Timestamp corresponding to when this delivery was marked as dropped off.
id string true Unique identifier for this delivery.
feedbackScore number false Optional 0-100 score for this delivery.
pickupInstructions string false Optional instructions given to the driver when at the store.
dropoffInstructions string false Optional instructions given to the driver when at the dropoff address.
preferredETA string false Timestamp corresponding to when the customer would prefer the delivery to be completed.
estimatedDropoffWindow DateRange true The current estimated delivery window.
isCancelable boolean true Whether or not this delivery can be canceled.
isRefundAvailable boolean true Whether or not charges would still apply if this delivery were to be canceled.
quote Quote true The quote this delivery was scheduled with.

Status Enum

Value Description
created Delivery has been created but has not been assigned a driver.
assigned A driver has been assigned but isn't en-route.
in_transit A driver is en-route.
delivered The items have been dropped off.
canceled The delivery has been canceled.

Item

{
  "id": "string",
  "sku": "string",
  "name": "string",
  "price": 0,
  "quantity": 1,
  "storeId": "string",
  "weight": 0,
  "height": 0,
  "width": 0,
  "length": 0,
  "size": "string",
  "color": "string",
  "imageURL": "http://example.com",
  "productURL": "http://example.com"
}

Properties

Name Type Required Description
id string true none
sku string true none
name string true none
price number true none
quantity number true none
storeId string false none
weight number false In pounds
height number false In inches
width number false In inches
length number false In inches
size string false none
color string false none
imageURL string false none
productURL string true none

Store

{
  "name": "string",
  "id": "string",
  "phone": "string",
  "address": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "latitude": -180,
    "longitude": -180
  },
  "organizationName": "string"
}

Properties

Name Type Required Description
name string true Name of the store (e.g. "CoolCity at The Domain")
id string true Unique identifier for this store.
phone string true The store's phone number.
address Address true The store's physical address.
organizationName string false Organization name (e.g. "CoolCity")

Address

{
  "addressLine1": "string",
  "addressLine2": "string",
  "city": "string",
  "state": "string",
  "zipcode": "string",
  "latitude": -180,
  "longitude": -180
}

Properties

Name Type Required Description
addressLine1 string true none
addressLine2 string false none
city string true none
state string true One of 50 state abbreviations or DC
zipcode string true Maximum 12 digits.
latitude number false none
longitude number false none

DateRange

{
  "start": "2019-02-10T02:17:48Z",
  "end": "2019-02-10T02:17:48Z"
}

Properties

Name Type Required Description
start string true Timestamp corresponding to the beginning of this span of time.
end string true Timestamp corresponding to the end of this span of time.

Offer

{
  "id": "string",
  "url": "string",
  "status": "string",
  "isOpened": true,
  "store": {
    "name": "string",
    "id": "string",
    "phone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "latitude": -180,
      "longitude": -180
    }
  },
  "dropoffAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zipcode": "string",
    "latitude": -180,
    "longitude": -180
  },
  "items": [
    {
      "id": "string",
      "sku": "string",
      "name": "string",
      "price": 0,
      "quantity": 1,
      "storeId": "string",
      "weight": 0,
      "height": 0,
      "width": 0,
      "length": 0,
      "size": "string",
      "color": "string",
      "imageURL": "http://example.com",
      "productURL": "http://example.com"
    }
  ],
  "pickupReadyByTime": "2019-02-10T02:17:48Z",
  "orderNumber": "string",
  "dropoffName": "string",
  "dropoffPhone": "string",
  "shouldSendSMS": true,
  "pickupInstructions": "string",
  "dropoffInstructions": "string",
  "eligibleDeliveryTimes": [
    "2019-02-10T02:17:48Z"
  ],
  "expiration": "2019-02-10T02:17:48Z",
  "pageProperties": {
    "title": "string",
    "description": "string",
    "color": "string",
    "logoURL": "string",
    "expirationMessage": "string",
    "googleAnalyticsId": "string",
  },
  "notification": {
    "type": "string",
    "email": "string",
    "phone": "string",
    "subject": "string",
    "body": "string"
  },
  "generatedQuoteIds": [
    "string"
  ],
  "deliveryId": "string",
  "readOnlyProperties": ["dropoffAddress", "dropoffName", "dropoffPhone", "shouldSendSMS"],
  "shouldCollectPayment": true,
  "createdAt": "2019-02-10T02:17:48Z",
  "updatedAt": "2019-02-10T02:17:48Z",
  "isLive": true
}

Properties

Name Type Required Description
id string true Unique identifier for this offer.
url string true Offer URL sent to the user if notification property was provided.
status string true See the status values below.
isOpened boolean true Whether or not the customer has opened the offer URL.
store Store true The physical store where the items will be picked up from.
dropoffAddress Address false The customer's address for delivery.
items [Item] true The items that will be delivered from the store to the dropoffAddress.
pickupReadyByTime string true Timestamp corresponding to when the items will be ready for pickup.
orderNumber string true A unique ID given to the customer identifying their order with your store.
dropoffName string false The full name of the customer.
dropoffPhone string false The customer's phone number in E.164 format (e.g. "+15051234567").
shouldSendSMS boolean false Whether or not SMS updates are sent to the dropoffPhone whenever the delivery created based on this offer changes statuses.
pickupInstructions string false Optional instructions given to the driver when at the store.
dropoffInstructions string false Optional instructions given to the driver when at the dropoff address.
eligibleDeliveryTimes [Date] false Array of timestamps that the customer can choose from; to be used as the delivery's preferredETA.
expiration string false Timestamp corresponding to when this offer should expire. A customer navigating to the offer page past this point will receive an error UI (see pageProperties).
pageProperties OfferPageProperties false Customizations to the offer page.
notification OfferNotification false Configuration for a notification sent to the customer containing the offer URL.
generatedQuoteIds [string] true An array of Quote IDs that have been generated by the customer through this offer. Either zero or one of these IDs will have been used to schedule a delivery.
deliveryId string false The ID of a Delivery that has been scheduled through this offer.
readOnlyProperties [string] true An array of property names that the customer is not allowed to change on the offer page.
shouldCollectPayment boolean true Whether or not the offer page will include a credit card input for the customer to fill out. This value is always true for non-partners.
createdAt string true Timestamp corresponding to when this offer was created.
updatedAt string true Timestamp corresponding to the last time this offer was updated.
isLive boolean true Whether or not this quote was created in live mode.

Offer Status enum

Value Description
created The offer has not yet been redeemed, canceled, or expired.
redeemed The offer was redeemed by the customer.
expired The offer expired (either because the expiration passed or all eligibleDeliveryTimes have passed).
canceled The offer was canceled through the cancellation endpoint.

OfferPageProperties

{
  "title": "Same-day delivery at CoolCity",
  "description": "Fill out the form below to get your CoolCity order delivered to you!",
  "color": "#000000",
  "logoURL": "https://docs.go-fleetly.com/images/coolcity.png",
  "expirationMessage": "Sorry! Same-day delivery is no longer available for your order. Please reach out to CoolCity support.",
  "googleAnalyticsId": "UA-123456",
}

Below is an example of an offer page using the example configuration in the right pane.

Properties

Name Type Required Description
title string false Title used for the offer page HTML
description string false Description used for the offer page HTML
color string false Hexadecimal accent color used for the offer page HTML
logoURL string false Image URL used for the offer page HTML
expirationMessage string false A message to show the customer if they view the offer page when the offer has expired.
googleAnalyticsId string false Google Analytics ID used to load the Google Analytics script on the offer page.

OfferNotification

{
  "type": "string",
  "email": "string",
  "phone": "string",
  "subject": "string",
  "body": "string"
}

Below is an example of an sms notification configuration.

Properties

Name Type Required Description
type string true See the type values below.
email string The customer's email address. Required if type is email.
phone string The customer's phone number in E.164 format. Required if type is sms.
subject string The subject to use for the email. Unused if type is sms. Required if type is email.
body string true The plaintext content of the email or text message to send along with the offer link.

OfferNotification Type enum

Value Description
sms The offer URL will be sent to the customer in an email from Gofleetly.
email The offer URL will be sent to the customer in a text message from Gofleetly.

Error

{
  "status": 0,
  "kind": "string",
  "message": "string",
  "ref": "string",
  "params": {}
}

Properties

Name Type Required Description
status integer true HTTP status code.
kind string true See the error codes below.
message string true Developer-targeted error message.
ref string true Unique identifier for this error.
params object false If parameter validation failed, the faulty parameters are included in a hashmap along with the failure reason.

Error codes

Status Code Kind Description
400 invalid_params Used when a request is caught with invalid parameters given by the client.
400 outside_covered_areas Used when a quote cannot be provided because either the depot address or the dropoff address is outside the deliverable range.
400 quote_expired Used when a quote cannot be scheduled because its expiration date has passed.
400 non_cancelable_delivery Used when a delivery can no longer be canceled. Typically this happens when the courier has already picked up the item(s).
401 model_exists Used when trying to create a model that already exists in requests for creation.
401 unauthorized Used when the request requires client authentication.
403 forbidden Used when the request is attempting to access a resource that is not permitted for reasons other than authentication.
404 model_not_found Used when an identifier given by a client was used but did not turn up any models when querying a collection
404 resource_not_found Used when a resource is requested by a client that was not found in the server.
429 rate_limit_reached Used to indicate a client that is requesting a resource too often.
500 internal_server_error General error used by servers when something unanticipated goes wrong. Typically accompanied by a reference error for auditing.
500 couriers_busy Used when a quote cannot be provided because the courier is busy.
400 non_cancelable_offer Used when an offer can no longer be canceled. Typically this happens when the customer has already redeemed the delivery.
400 non_updatable_offer Used when an offer can no longer be updated. Typically this happens when the offer has been canceled.

Changelog

This format is based on Keep a Changelog, and adheres to Semantic Versioning.

[1.6.0] - 2019-07-30

[1.5.0] - 2019-07-26

[1.1.0] - 2019-05-29

[1.0.0] - 2019-02-08

Gofleetly Elements

Gofleetly Elements are general use UI components specifically designed to enable a seamless same-day delivery experience on any eCommerce platform. Thorough user testing and refinement has culminated in UI elements that allow instant integration into Gofleetly services.

Gofleetly elements are opinionated, but flexible and allow for customization for advanced users. We've elimintated the need for our customers to design and build out the elements required to provide their customers with a same-day delivery experience that works for them.

Gofleetly Elements requires an API key. Please see the Authentication section.

Setup

Include the Gofleetly Elements script on every page where you want to use elements.

<script src="https://go-fleetly.com/elements.js"></script>

Step 1: Obtain your delivery quote

The simplest way for you to securely collect quote information is adding our same-day delivery button. This button combines HTML, Javascript, and CSS to automatically collect item information. When your customer adds an item to their bag this item automatically starts a gofleetly quote that can later be turned into a delivery.

<style>
.gofleetly-button {
  width: "100px";
  color: "coral-blue";
}
</style>

<button
  id="gofleetly-cart-button"
  class="gofleetly-button"
  data-key="apk_testing_TjfdKJ3jfkdSJ3kj2ljx"
  data-label="Add Same Day Delivery"
  data-callback="onUserAddsToSameDayDelivery"
  data-store-name="CoolCity North Austin"
  data-store-id="509"
  data-store-phone="+15551234567"
  data-store-address-addressLine1="44 Riverrock Ave"
  data-store-address-city="Austin"
  data-store-address-state="TX"
  data-store-address-zipcode="78758"
  data-store-address-latitude="-180.0"
  data-store-address-longitude="-180.0"
  data-dropoffAddress-addressLine1="1501 Esperanza Xing"
  data-dropoffAddress-city="Austin"
  data-dropoffAddress-state="TX"
  data-dropoffAddress-zipcode="78758"
  data-item-id="149042"
  data-item-sku="149042-bfc"
  data-item-name="VANS Classic Grey M 12"
  data-item-price="5999"
  data-item-storeId="509"
  data-item-quantity="1"
>
</button>
<!-- ...later in your HTML -->
<script>
  /**
   * Call back function that occurs when a user adds an item
   * to the bag for same-day delivery.
   * @param {Quote} quote
   * @param {Item} item
   * @param {Error} err
   */ 
  window.onUserAddsToSameDayDelivery = function (quote, item, err) {
    if (err) {
      // do not add to bag
      // display appropriate UI to customer
    } else {
      // use quote information as you see fit.
      window.product.addToBag(); // EXAMPLE
      alert('Added product to bag with a delivery fee of: ' + quote.fee);

      // IMPORTANT: Save the quote id returned from Gofleetly for future use.
      // to understand why, see Step 2 below.
      window.client.saveQuoteIdForCustomer(window.customer, quote.id); // EXAMPLE
    }
  }
</script>

Step 2: Cart review and editing

This step loads in flexible form box ("inlay") that will contain all the items in your customer's order. This step is optional, but allows for easy cart management through Gofleetly.

<div
  class="gofleetly-inlay"
  data-key="apk_testing_TjfdKJ3jfkdSJ3kj2ljx"
  data-quote-id="YOUR_QUOTE_ID_FROM_ABOVE"
  data-optional-item-quantity-edit-callback="onGofleetlyItemEdit"
  data-optional-item-removal-callback="onGofleetlyItemRemove"
  data-optional-customer-phone-number="+13213453007"
  data-optional-customer-preferred-eta="2019-02-10T02:17:48Z"
>
</div>
<!-- ...later in your HTML -->
<script>
  /**
   * Callback function that invoked when a customer requests a quantity change on an item associated with their Gofleetly quote.
   * 
   * @param {Quote} quote
   * @param {Item} item This will contain the user's requested quantity.
   * @return {Boolean}
   * Return true to reflect the `item`'s new quantity in the Gofleetly quote.
   * Return false to negate the user's change and preserve the original quantity.
   */  
  window.onGofleetlyItemQuantityEdit = function (quote, item) {
    if (window.cart.hasAvailable(item.id, item.quantity)) {
      window.cart.editQuantity(item.id, item.quantity);
      return true;
    } else {
      // provide error UI
      alert('Unable to update quantity due to stock-out.');                          
      return false;
    }
  }

  /** 
   * Callback function that returns an item that was removed.
   * Will be called after the user clicks on remove item, which will also
   * remove the item from the Gofleetly inlay.
   * 
   * Put typical logic for removing items within native cart. 
   * 
   * @param {Quote} quote
   * @param {Item} item
   * @return {Boolean} whether or not to accept users removal request
   */
  window.onGofleetlyItemRemove = function (quote, item) {
    window.cart.removeItem(item.id);
    return true;
  }
</script>

Step 3: Schedule the same-day delivery with Gofleetly

<button
  id="gofleetly-schedule-button" 
  class="gofleetly-schedule"
  data-key="apk_testing_TjfdKJ3jfkdSJ3kj2ljx"
  data-callback="scheduleDeliveryCallback"
  data-quoteId="quote-39753783"
  data-order-number="coolcity-873t362"
  data-dropoffName="John Freddy"
  data-dropoffPhone="+183293888"
>
</button>
<!-- ...later in your HTML -->
<script>
  /** 
   * Callback function that fires when a delivery is scheduled.
   * 
   * @param {Delivery} delivery
   */
  window.scheduleDeliveryCallback = function(delivery) {
    console.log(delivery.status);
  }
  // Schedule the delivery
  document.querySelector('#gofleetly-schedule-button').click();
</script>

Attributes

Our elements library is enabled by the different attributes you provide to us. Our Gofleetly services will use those attributes to enable same-day delivery capabilities on your website. If misconfigured it is possible that deliveries parameters can be incorrect, or incorrect rendering of Gofleetly elements on your page.

Below are examples of attribute types along with use case explanations.

Element Identifiers

Example: id="gofleetly-cart-button" Usage: Identify the element you'd like to inject onto the page. Also dictates how Gofleetly reads in adjacent parameters.

Styling Classes

Example: class="gofleetly-button" Usage: Add your own customized styles to elements imported into the page.

API Keys

Example: data-key="apk_testing_TjfdKJ3jfkdSJ3kj2ljx" Usage: Used to authorize valid requests. Safe to publish client side, this key validates your eCommerce site's requests.

Data Properties

Example: data-item-name="Google Home Mini" Usage: Used to provide data in Gofleetly service requests. Represents a property of the data represented in the element. Will typically be prefixed with the models name and postfixed with the specific field. Data can be any type (i.e. Number, String, etc.).

Element Parameters

Example: data-label="Add Same Day Delivery" Usage: Customizable inputs to Gofleetly element components. Such as inner text to buttons.

Event Callback Functions

Example: data-callback="onUserAddsToSameDayDelivery" Usage: Defined somewhere else in your HTML code, this will be the identifier used to invoke a custom logic within a callback function when a Gofleetly request is made.

UI Frameworks

Components for popular UI frameworks (e.g. React, Vue) will be available at a later date.

Gofleetly Complete

Gofleetly Complete is our consulting service. We'll work with you to determine your store's specific same-day delivery needs and then we'll build a custom integration tailored to your site.

The end deliverable is a script that enables same-day delivery for your customers when placed on your HTML template.

<html>
  <!-- ✂⸻ -->
  <body>
    <!-- ✂⸻ -->
    <script src="https://go-fleetly.com/your-script.js"></script>
  </body>
</html>