Skip to navigation
API ReferenceBookings

Add a charge (tolls, violations, fees)

View as Markdown

Scope: charges:write

For a toll or violation service the host connected with an API token: add one toll, violation or fee to a booking. It’s billed on the booking’s invoices and the host collects it from the renter. If the booking’s invoice is already paid, it goes on a new invoice for that booking rather than reopening the paid one. (Services working with many hosts should use the Fleetwire Partner API instead: one key, no per-host tokens.)

  • provider (string, required) — your service’s short id, e.g. myeztoll (lowercase letters, digits, -, _)
  • external_id (string, required) — your id for the charge. Idempotent: sending the same external_id with the same amount and kind returns the original with 200 and never bills twice. Different details under the same id return 409.
  • kind (required) — toll, violation or fee
  • amount_cents (integer, required) — the road cost or fine
  • provider_fee_cents (integer) — your fee, billed as its own line next to the charge
  • occurred_at (ISO 8601, required except for fee) — when the toll was passed or the violation issued
  • description (string) — shown to the renter on the invoice line, e.g. E-ZPass NY — 3 tolls, Oct 10
  • listing_id, plate, plate_state — cross-checked against the booking’s vehicle
  • authority, location, citation_number, violation_type (parking, red_light, speed, other), due_at
  • document (PDF file, multipart), document_pdf (base64) or document_url (public https link) — an itemized receipt, up to 5 MB
  • currency (default USD)

Refused (422) when the charge isn’t for that booking: a different listing_id or plate, or an occurred_at outside the trip. 404 for a booking that isn’t yours. 409 when the booking has no order to bill, or the external_id conflicts.

status is unbilled, billed (on an unpaid invoice), paid or voided.

Authentication

AuthorizationBearer

An API token from Settings → API tokens in Fleetwire, sent as Authorization: Bearer …. Each token carries scopes: read for every GET, plus write scopes such as bookings:write.

Path parameters

b_idstringRequired
Booking ID

Request

This endpoint expects an object.
providerstringRequiredformat: "^[a-z0-9_-]{2,40}$"

Your service’s short id, e.g. myeztoll.

external_idstringRequired<=191 characters
Your id for the charge. The idempotency key.
kindenumRequired
Allowed values:
amount_centsintegerRequired1-10000000
The road cost or fine.
provider_fee_centsintegerOptional0-10000000Defaults to 0
Your fee, billed as its own line.
currencystringOptional=3 charactersDefaults to USD
occurred_atdatetimeOptional

Required unless kind is fee.

listing_idstringOptional<=64 characters

Cross-checked against the booking’s vehicle.

platestringOptional<=20 characters

Cross-checked against the booking’s vehicle.

plate_statestringOptional<=10 characters
authoritystringOptional<=191 characters
locationstringOptional<=250 characters
descriptionstringOptional<=200 characters
Shown on the renter's invoice line.
citation_numberstringOptional<=100 characters
violation_typeenumOptional
Allowed values:
due_atdateOptional
document_pdfstringOptional
Itemized receipt PDF, base64. Up to 5 MB.
document_urlstringOptionalformat: "uri"<=2000 characters
A public https link to the receipt PDF.

Response

OK
charge_idstringOptional
external_idstringOptional
providerstringOptional
kindstringOptional
statusstringOptional
amount_centsintegerOptional
provider_fee_centsintegerOptional
currencystringOptional
occurred_atstringOptional
descriptionstringOptional
has_documentbooleanOptional
created_atstringOptional
voided_atstring or nullOptional

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error