Record lifecycle

A record's status is one of these. Carriers see every status; a fuel buyer's key sees a record only once it was sent to them. New statuses may be added, so treat one you don't know as still in progress.

Each move is an event in the record's history (its type is the first column) and sends the webhook in the last column to every endpoint subscribed to it. Moves marked with an endpoint can be made through the API; the rest happen in the web app, the driver app, or by themselves.

• (new record)→torecording

  A driver starts the clock in the driver app; a reported wait (API, EDI 214, import) is created and passes straight through to pending_review

  Event record_createdWebhook record.createdAPI POST /api/v1/records

• recording→todraft

  The driver stops the clock, or it stops itself (the truck drove off); a reported wait stops at its end_time

  Event gps_tracking_stoppedWebhook record.stoppedAPI POST /api/v1/records

• draft→topending_review

  The driver submits it for review; a reported wait is submitted at once

  Event record_submittedWebhook record.submittedAPI POST /api/v1/records

• pending_review→torejected_by_employer

  A carrier admin rejects the driver's record in review (web app)

  Event employer_rejectedWebhook record.rejected_internal

• rejected_by_employer→topending_review

  A carrier admin takes a review rejection back (web app)

  Event record_reopenedWebhook record.reopened

• pending_review | disputed→tosent_to_customer

  The carrier sends it to the fuel buyer, or resends it after correcting a disputed charge (send: true on create does it in the same call)

  Event record_sent_to_customerWebhook record.sentAPI POST /api/v1/records/{id}/send

• disputed→tosent_to_customer

  The carrier accepts the buyer's counter-offer from a dispute: back to the buyer at that amount (web app)

  Event dispute_offer_acceptedWebhook record.offer_accepted

• sent_to_customer | disputed | escalated→tocustomer_approved

  The fuel buyer approves it (API, web app, or an emailed review link)

  Event record_approvedWebhook record.approvedAPI POST /api/v1/records/{id}/approve

• sent_to_customer | disputed | escalated→tocustomer_approved

  The fuel buyer approves a lower amount (web app)

  Event record_partially_approvedWebhook record.approved

• sent_to_customer→todisputed

  The fuel buyer rejects it (the older form of a dispute)

  Event record_rejectedWebhook record.disputed

• sent_to_customer→todisputed

  The fuel buyer disputes it with a reason (API, web app, or an emailed review link)

  Event record_disputedWebhook record.disputedAPI POST /api/v1/records/{id}/dispute

• disputed→toescalated

  The carrier escalates the dispute (web app)

  Event record_escalatedWebhook record.escalated

• disputed→toescalated

  The carrier escalates the dispute (web app)

  Event dispute_escalatedWebhook none

• disputed | escalated→toclosed

  The carrier accepts the buyer's dispute, or the buyer rejects an escalated charge (web app): closed unpaid

  Event record_closedWebhook record.closed

• draft→toclosed

  A past record from the carrier's spreadsheet import lands closed, or paid outside Demurly when its row says so

  Event record_importedWebhook none

• draft→topaid_external

  A past record from the carrier's spreadsheet import lands closed, or paid outside Demurly when its row says so

  Event record_importedWebhook none

• recording | draft | pending_review | sent_to_customer→tocancelled

  A carrier admin cancels it, before the buyer has answered (web app)

  Event record_cancelledWebhook record.cancelled

• customer_approved→topayment_pending

  The buyer starts a bank payment in Demurly, or hands it to its accounts payable

  Event payment_processingWebhook record.payment_pending

• payment_pending→tocustomer_approved

  A payment fails: the record is approved and unpaid again

  Event payment_failedWebhook record.payment_failed

• customer_approved | payment_pending→topaid_stripe

  A card or bank payment through Demurly completes

  Event payment_completedWebhook record.paid

• customer_approved→topayment_pending

  The buyer marks it paid outside Demurly (web app, or its accounting system's bill was paid)

  Event external_payment_markedWebhook record.payment_pending

• customer_approved | payment_pending→topaid_external

  The carrier confirms the outside payment arrived

  Event external_payment_confirmedWebhook record.paid

• customer_approved→topaid_external

  The carrier records an outside payment, or its accounting system shows the invoice paid

  Event external_payment_recordedWebhook record.paid

• payment_pending→tocustomer_approved

  The carrier says the outside payment never arrived

  Event external_payment_rejectedWebhook record.payment_failed

• paid_stripe→tocustomer_approved

  A card payment is fully refunded or lost to a chargeback

  Event payment_reversedWebhook record.payment_reversed

Some webhooks don't follow a status change: record.withdrawn (a charge you were sent was sent to another buyer or taken back for review by the carrier; data.record is the tombstone the API shows you (buyers only)), record.updated (a record's details or billed times changed (a field edit, or times adjusted, which changes the amount); data.event.type says which) and record.comment_added (someone on the carrier or the buyer side commented on a record).

A wait reported through POST /api/v1/records runs its first moves in one call: it's created, stopped at its end_time, calculated and submitted, so a carrier's endpoint gets record.created, record.stopped and record.submitted (and record.sent with send: true).

For an accounts payable or receivable system, group the statuses like this:

• Owed (approved, not paid yet): customer_approved, payment_pending. Use amount_approved.
• Waiting for the buyer: sent_to_customer; in dispute: disputed, escalated.
• Paid: paid_stripe, paid_external (paid_at). A card payment can still be reversed, which brings the record back to customer_approved with a record.payment_reversed webhook.
• Never billed: cancelled, closed, rejected_by_employer, and a buyer's tombstones (below).

A charge a fuel buyer was sent never just disappears from the buyer's view. If the carrier cancels it, sends it to another buyer or takes it back for review, the buyer's key gets a tombstone in its place: status: "withdrawn" with withdrawn_reason and withdrawn_at (the record tombstone object). withdrawn isn't one of the record's statuses: it's what that buyer sees. The buyer gets record.withdrawn (or record.cancelled for a cancellation). If the charge is sent back to them, it's an ordinary record again.

GET /api/v1/records/{id} with include=events lists a record's history, oldest first; a webhook names the event behind it in data.event.type. These are the types. New ones may be added.