Developers
Glossary
The fuel-trade and Demurly words the API uses, and where each one shows up.
On this page
The trade
- Demurrage
- A charge for a driver's time waiting beyond the free time, at a terminal (loading) or at the drop (delivering). Demurly records the wait and bills it.
- In the API: A record is one demurrage charge;
amountis what's billed. - Detention
- Another name, common in trucking, for the same thing: paid waiting time past the free time. Some contracts use detention for the delivery end and demurrage for the terminal end; Demurly treats both as a wait.
- In the API: Records cover both; there's no separate detention type.
- Free time
- The waiting time the fuel buyer doesn't pay for (often 60 or 120 minutes). Only the time after it is billed.
- In the API:
free_time_minutes, stamped on the record from the carrier's setting when it's made. - Billable time
- The wait minus free time, charged in 15-minute steps, rounded up.
- In the API:
billable_minutes - Rate
- What the carrier charges per hour of billable time: its rate for that buyer, else its default rate.
- In the API:
hourly_rate(US dollars per hour) - Maximum rate
- The most per hour a fuel buyer will pay a carrier; a charge above it is flagged, and sending it needs the carrier's confirmation.
- In the API:
maximum_rateon a buyer's connection;max_ratepayment-rules problems - Terminal
- A fuel terminal (or another site) where trucks load and drivers wait, with a geofence around it and a time zone.
- In the API:
terminalon a record; the terminals list - Rack
- The loading rack at a terminal, where the truck fills. "Rack time" is the wait to load; Demurly calls the site a terminal.
- Drop
- The delivery point (a station or bulk plant) where the load is dropped; drivers can wait there too.
- BOL
- Bill of lading: the shipping document for the load, with its own number. Often photographed as evidence.
- In the API:
bol_number; attach the photo with the photos endpoint - Load number
- The carrier's (or buyer's) number for the load or order, used to match the charge to an invoice.
- In the API:
load_number - Carrier
- The trucking company whose driver waited. It records and bills the charge.
- In the API:
carrieron a record; a carrier's key sees its own records - Fuel buyer
- The company that ordered the fuel and pays the charge (a distributor, retailer or fleet). The API calls it the customer.
- In the API:
customerandcustomer_id; a buyer's key sees records sent to it - Driver
- The person who waited. Drivers record waits in the Demurly driver app; reported waits name the driver too.
- In the API:
driver_idordriver_numberwhen reporting a wait - ELD
- Electronic logging device: the truck's gateway (Samsara, Motive). Demurly can take arrival and departure from it (in development).
- In the API:
source: eld,vehicle,evidence_hash - EDI 214 and 210
- Standard electronic messages: a 214 reports shipment status (arrived, departed), a 210 is a freight invoice. Carriers can open and stop records with 214s and get 210s for approved ones.
- In the API:
source: edi
In Demurly
- Record
- One wait, from start to end, with its evidence and its charge. It moves through statuses from recording to paid.
- In the API: The record object; see the record lifecycle
- Charge
- A record as the fuel buyer sees it: an amount to approve, dispute and pay.
- Record number
- The human-readable number (DMR- and 8 digits) people quote. Use the id in API calls.
- In the API:
record_number - Connection
- A carrier and a fuel buyer that bill each other through Demurly. A carrier sends records only to connected buyers.
- In the API: The connections list;
partner.idis thecustomer_idto send to - Review
- The carrier's check of its driver's record before it goes to the buyer.
- In the API:
pending_review;rejected_by_employerif rejected - Dispute
- The buyer questions a charge, with a reason and optionally a counter-offer. The carrier corrects and resends it, accepts the offer, escalates or closes it.
- In the API:
disputed,escalated; the dispute endpoint - Counter-offer
- The amount a buyer proposes in a dispute. If the carrier accepts, the charge goes back to the buyer at that amount.
- In the API:
proposed_amount;record.offer_accepted - Round
- One sending of a charge to a buyer. Resending after a dispute, or sending it again after it was withdrawn, starts a new round; a buyer sees the history of its own rounds only.
- In the API:
record.sentstarts a round - Withdrawn
- What a buyer sees of a charge the carrier cancelled, sent to another buyer, or took back for review: a short tombstone, never a disappearance.
- In the API:
status: withdrawn,withdrawn_reason;record.withdrawn - GPS evidence
- The check of the driver's GPS trail (or the truck's) against the times: complete, incomplete with the issues, or not tracked for reported waits.
- In the API:
gps_evidence - Geofence
- The circle (or shape) around a terminal; positions inside it show the driver was there.
- Pro
- The carrier plan that includes the API and webhooks. Fuel buyers use them free.
API terms
- API key
- A secret (dmrl_...) an admin creates; it acts as that admin, with the scopes chosen. Creating one needs two-step sign-in.
- In the API:
Authorization: Bearer dmrl_... - Scope
- What a key may do: records:read, records:write, drivers:read, terminals:read, connections:read, reports:read, webhooks:read, webhooks:write.
- Idempotency key
- A unique string you send with a write so a retry can't act twice.
- In the API:
Idempotency-Keyheader; see idempotency - Cursor
- An opaque token for the next page of a list.
- In the API:
next_cursorin,cursorout - Webhook
- A POST Demurly sends to your server when a record changes, signed with the endpoint's signing secret (whsec_...).
- In the API: See the webhooks guide
- Tombstone
- The short record a buyer gets in place of a withdrawn charge.
- In the API: The record tombstone object
- Sequence
- An event's place in its record's history; it only goes up, so you can order events.
- In the API:
sequenceon webhooks and on history events