Importing Invoiced Routes¶

You can import invoiced routes by using the import invoiced routes endpoint. The endpoint creates a route with invoices at each stop. After importing an invoiced route, you will need to check for the import status. See example

Models¶

Here are the models needed to import an invoiced route.

Invoiced Route¶

Important

In order for a driver to receive a route, it must be activated after a successful import or you can set the activate_after_successful_import flag to true during route creation.

Note

You can control the start and end location of a route by specifying a warehouse. If you want to define different start and end locations for a route, use the start_warehouse and end_warehouse parameters. If a warehouse or start_warehouse and end_warehouse are not supplied, Foxtrot will use the default warehouse location for that DC (Under Account > Settings > DC > Warehouse).

Important

Route id has to be globally unique. You cannot have multiple routes with the same id.

Important

If you are not sure the driver has been imported into Foxtrot, pass in the driver parameter and the driver will be imported if the driver does not exist. driver_id and driver cannot be used together.

Property	Type	Required	Description
id	string	true	The globally unique id of the route.
name	string	false	The name of the route, can be the same as the id.
driver_id	string	false	The id of the driver to be assigned to this route. Note that a route can also be assigned to a driver after import.
driver	Driver	false	The driver assigned to this route. If this driver does not exist in Foxtrot, it will be created.
activate_after_successful_import	boolean	false	Setting to automatically activate a route after a successful import.
start_time	long	true	The start time of the route as a UNIX epoch since January 1st, 1970 in milliseconds.
warehouse	Warehouse	false	The route start and end location. If this is specified, you cannot use start_warehouse and end_warehouse
start_warehouse	Warehouse	false	The route starting location. end_warehouse is required if specified.
end_warehouse	Warehouse	false	The route ending location. start_warehouse is required if specified.
waypoints	Array[Invoiced Waypoint]	true	An array of waypoint objects.
vehicle	Vehicle	false	The vehicle to be associated to this route.

{
  "id": "globally unique route id",
  "name": "route name",
  "driver_id": "globally unique driver id",
  "activate_after_successful_import": false,
  "start_time": 1510860915000,
  "start_warehouse": {
    "id": "globally unique warehouse id",
    "name": "warehouse name",
    "address": "physical address",
    "location": {
      "latitude": 3.0,
      "longitude": 4.0
    }
  },
  "end_warehouse": {
    "id": "globally unique warehouse id",
    "name": "warehouse name",
    "address": "physical address",
    "location": {
      "latitude": 3.0,
      "longitude": 4.0
    }
  },
  "waypoints": [{
      "id": "globally unique waypoint id",
      "customer_id": "customer id",
      "name": "waypoint name",
      "address": "physical address",
      "location": {
        "latitude": 1.0,
        "longitude": 2.0
      },
      "service_time_minutes": 999,
      "time_windows": [{
        "start": 1510864915000,
        "end": 1510868515000
      }],
      "invoices": [{
        "id": "globally unique invoice id",
        "payment_method": "CASH",
        "invoice_name_attributes": [{"key": "key1", "value": "value2"}],
        "items": [{
          "id": "globally unique item id",
          "sku": "sku A",
          "name": "name A",
          "quantity": 123.0,
          "display_unit_of_measure": "bottles",
          "total_price_cents": 9999,
          "currency": "USD"
        }]
      }],
    },
    {
      "id": "globally unique waypoint id",
      "customer_id": "customer id",
      "name": "waypoint name",
      "address": "physical address",
      "location": {
        "latitude": 3.0,
        "longitude": 4.0
      },
      "service_time_minutes": 999,
      "time_windows": [],
      "invoices": [{
        "id": "globally unique invoice id",
        "payment_method": "PREPAID",
        "invoice_name_attributes": [{"key": "key1", "value": "value2"}],
        "items": [{
          "id": "globally unique item id",
          "sku": "sku B",
          "name": "name B",
          "quantity": 123.0,
          "display_unit_of_measure": "bottles",
          "total_price_cents": 9999,
          "currency": "USD"
        }]
      }],
    }
  ],
  "vehicle": {
    "id": "globally unique vehicle id"
  }
}

Driver¶

Property	Type	Required	Description
id	string	true	The dc unique id of the driver.
name	string	false	The name of the driver.
phone	string	false	The phone number to contact the driver.

{
  "id": "globally unique driver id",
  "name": "driver name",
  "phone": "driver's phone"
}

Invoiced Waypoint¶

Important

The waypoint id, is later used to submit attempts via our SDK. If a waypoint id is supplied, it must be globally unique. You cannot have multiple waypoints share an id across routes or in the same route. If you don’t uniquely identify stops, a good technique might be to concatenate your unique route id with the customer id.

Property	Type	Required	Description
id	string	false	The globally unique id of the waypoint. If not specified, a random id will be generated.
customer_id	string	true	The id of the customer at this waypoint.
name	string	false	The name of the waypoint.
address	string	false	Physical address of the waypoint
location	Location	false	The location of the waypoint
service_time_minutes	integer	false	The approximate service time needed to service this stop in minutes.
time_windows	Array[TimeWindow]	false	An array of time windows for time restriction to visit this stop.
invoices	Array[Invoice]	true	An array of invoices at this stop. There must be at least one invoice.

{
  "id": "globally unique waypoint id",
  "customer_id": "customer id",
  "name": "customer name",
  "address": "physical address",
  "location": {
    "latitude": 1.0,
    "longitude": 2.0
  },
  "service_time_minutes": 999,
  "time_windows": [{
    "start": 1510864915000,
    "end": 1510868515000
  }],
  "invoices": [{
    "id": "globally unique invoice id",
    "payment_method": "CASH",
    "invoice_name_attributes": [{"key": "key1", "value": "value2"}],
    "items": [{
      "id": "globally unique item id",
      "sku": "sku A",
      "name": "name A",
      "quantity": 123.0,
      "total_price_cents": 9999,
      "currency": "USD"
    }]
  }],
}

Invoice¶

Important

If an invoice id is supplied, it must be globally unique. You cannot have multiple invoices share an id across routes or in the same route.

Property	Type	Required	Description
id	string	false	The globally unique id of this invoice. If not specified, a random id will be generated.
payment_method	Payment Method	true	The payment method for this invoice.
invoice_name_attributes	Array[Invoice Name Attribute]	false	Extra attributes for this invoice to give your operation more context. For example: {“key”: “Invoice Tax ID”, “value”: “432-22”}
items	Array[Invoice Item]	true	An array of invoice items for this invoice. There must be at least one invoice item.

{
  "id": "globally unique invoice id",
  "payment_method": "CASH",
  "invoice_name_attributes": [{"key": "Customer TAX ID", "value": "A-1232-001"}],
  "items": [{
    "id": "globally unique item id",
    "sku": "sku A",
    "name": "name A",
    "quantity": 123.0,
    "display_unit_of_measure": "bottles",
    "total_price_cents": 9999,
    "currency": "USD"
  }]
}

Payment Method¶

An enumeration of possible payment methods.

Method	Description
CASH	Payment is onsite with cash.
CREDIT_CARD	Payment is onsite with credit card.
DEBIT_CARD	Payment is onsite with debit card.
BILLED	Customer billed and payment will be received in the future.
PREPAID	Payment has already been received.

Invoice Name Attribute¶

Key-value object for additional information you would like to add to the invoice.

Property	Type	Required	Description
key	string	true	The name of the attribute.
value	string	true	The value of the attribute.

{
  "key": "Customer TAX ID",
  "value": "A-1232-001"
}

Invoice Item¶

Important

If an invoice item id is supplied, it must be globally unique. You cannot have multiple invoice items share an id across routes or in the same route.

Property	Type	Required	Description
id	string	false	The globally unique id of this invoice item. If not specified, a random id will be generated.
sku	string	true	The SKU of this product.
name	string	true	The name of this product.
quantity	float	true	The quantity.
display_unit_of_measure	string	false	The units to display next to quantity (eg. bottles, cases). If not specified, it will not be shown.
total_price_cents	integer	true	The total price for this line item including quantities, in cents.
currency	string	false	The currency code representing the currency used to pay for the item. If none is specified it defaults to ‘$’

{
  "id": "globally unique item id",
  "sku": "sku A",
  "name": "name A",
  "quantity": 123.0,
  "display_unit_of_measure": "bottles",
  "total_price_cents": 9999,
  "currency": "USD"
}