Resolving Invalid Meter Entries
Fleetio requires that odometer updates never go backwards since odometers are incremental in real life. This requirement allows Fleetio to make reports which accurately reflect reality by avoiding situations with impossible math. Consequently, this requirement introduces a few considerations when updating meter entries via the API.
Suppose we have a Vehicle with the following odometer readings:
| Date | Odometer |
|---|---|
| 2018-03-01 | 182,000 miles |
| 2018-02-01 | 181,000 miles |
| 2018-01-01 | 180,000 miles |
Valid Updates
Let's say we realized that the reading on February 1st should have actually been 181,500 miles instead of 181,000 miles. We will have no trouble updating this Meter Entry via the API because the modification we made, would not invalidate any subsequent odometer readings. We can go ahead and submit a PATCH request to our Meter Entry with the new value:
curl https://secure.fleetio.com/api/v1/meter_entries/16779437 --request PATCH --header 'Authorization: Token token="12345abcxyzhasggwllsirusy12345"' --header "Account-Token: 12345hbl78b" --header "Content-Type: application/json" --data '{"vehicle_id": "28865", "date": "2018-02-01", "value": "181500"}'
Invalid Updates
The only time we would run into an issue would be if we start to get things out of order.
Let's say that we actually want to update the value on February 1st to be 182,500 miles. That would be greater than the reading on March 1st, of 182,000 miles. Now we have a problem because its impossible for the odometer to go backwards like that. Fleetio can't do its reporting on these values because the math doesn't work.
If we try to submit a PATCH request to our Meter Entry with the new value, we will get an HTTP 422 error:
curl https://secure.fleetio.com/api/v1/meter_entries/16779437 --request PATCH --header 'Authorization: Token token="12345abcxyzhasggwllsirusy12345"' --header "Account-Token: 12345hbl78b" --header "Content-Type: application/json" --data '{"vehicle_id": "28865", "date": "2018-02-01", "value": "182500"}'
=> {"errors":{"value":["must be between 180,000 and 182,000 or marked as void"]}}
Voiding Meter Entries
The quick and dirty solution is to just set the February 1st meter entry as void. This signals to Fleetio that we should skip this entry during reporting.
curl https://secure.fleetio.com/api/v1/meter_entries/16779437 --request PATCH --header 'Authorization: Token token="12345abcxyzhasggwllsirusy12345"' --header "Account-Token: 12345hbl78b" --header "Content-Type: application/json" --data '{"vehicle_id": "28865", "date": "2018-02-01", "value": "182500", "void": "true"}'
Resolving Meter Entry Histories
The other solution is to edit the odometer readings in order so that the odometer is never out of incremental order. For example,
- Edit the reading on March 1st to be 183,000 miles.
- Then, edit the reading on February 1st to be 182,500 miles.
Doing this maintains the requirement and removes impossible values from your meter history. Now there is no need to void the Meter Entries, and you keep your reporting intact.
curl https://secure.fleetio.com/api/v1/meter_entries/16779438 --request PATCH --header 'Authorization: Token token="12345abcxyzhasggwllsirusy12345"' --header "Account-Token: 12345hbl78b" --header "Content-Type: application/json" --data '{"vehicle_id": "28865", "date": "2018-03-01", "value": "183000"}'
curl https://secure.fleetio.com/api/v1/meter_entries/16779437 --request PATCH --header 'Authorization: Token token="12345abcxyzhasggwllsirusy12345"' --header "Account-Token: 12345hbl78b" --header "Content-Type: application/json" --data '{"vehicle_id": "28865", "date": "2018-02-01", "value": "182500"}'
Now you know about editing odometers via the API. Happy metering!