Skip to the main content
HopTireGet my price

For developers and agents

HopTire agent booking API

Authorized agents can prepare a booking, accept the terms and pay for a customer, within the authority the customer gives. Also as Markdown and OpenAPI.

Version hoptire-agent-booking-v1. Terms version 2026-11-09.2. Booking flow version 9.

HopTire welcomes authorized agents. An agent can collect the booking details, get a price, prepare the booking, fill the checkout, accept the terms and pay for a customer. It must stay within the authority the customer gave it. The customer can also take over at any step.

HopTire sells mobile tire service at the customer's parked car: new tires, fitted, mobile puncture repair, seasonal swap. A local partner does the work. HopTire takes the booking and stays the customer's contact.

Machine-readable files:

The older read-only guide API is unchanged: https://hoptire.com/openapi.json and https://hoptire.com/developers.

Authority and terms

The HopTire terms (https://hoptire.com/terms, version 2026-11-09.2) expressly let a customer authorize an agent to book, accept the terms, complete checkout fields and pay for them, within the authority the customer grants.

  • Act only for a customer who asked you to. Send authorization.declaration: "customer_authorized" only when that is true.
  • Record the authority you hold in grantedActions: prepare_booking, and also accept_terms and submit_payment if the customer gave them.
  • Record the highest total the customer approved in maxAmountMinor (US cents, tax included). If you leave it out, your authority covers the drafted total only.
  • HopTire records the declaration, its scope, the time and the terms version with the booking. A declaration is not identity verification.
  • A higher price or a different service, tire count or tire choice is outside your authority. The customer must approve it. Give the customer the checkout link.
  • Do not say you are the customer on the checkout page if you are not.
  • Booking authority is not consent to text messages. Leave the optional text box clear unless the customer asked for HopTire texts. The customer can reply STOP to any text.

Human handoff

You do not need a person only because you are an agent. Give the checkout link to the customer when:

  • the payment form asks for 3-D Secure, a CAPTCHA, a Link code or another check that only the customer can pass. Never try to get around it;
  • your authority does not cover the price, the scope, the terms or the payment;
  • the customer wants to review or pay;
  • the API returns needs_human_review. Then the customer can use https://hoptire.com/book or write to support@hoptire.com.

In some ZIP areas the agent quote returns status: "needs_human_review", checkAvailability: true, no price and the reason in humanReview. The agent API does not draft or take payment for these bookings. Send the customer to the regular booking form at https://hoptire.com/book. Where eligible, the customer can confirm a permitted work site and review the price. Otherwise the form accepts a request without payment. Do not try another ZIP to get a price.

The checkout link works in any browser on any device until it expires. Treat it as a secret.

Steps

  1. Read GET /api/agent/v1/schema for the current fields and values.
  2. Collect answers from the customer. Never guess a missing answer. Use a field's "not sure" value only when the customer is not sure.
  3. Call POST /api/agent/v1/quote as often as you need. Fix each issue it returns.
  4. Confirm the total, the conditions and the requested times with the customer.
  5. Call POST /api/agent/v1/drafts with an Idempotency-Key header and the authorization.
  6. Open draft.checkoutUrl. The customer or you review the details, accept the terms and pay in the Stripe form on that page.
  7. Read GET draft.status.url with Authorization: Bearer <draft.status.token>.

Quote

The quote endpoint stores nothing and sends nothing. It accepts partial answers.

curl --silent --show-error -X POST 'https://hoptire.com/api/agent/v1/quote' \
  -H 'Content-Type: application/json' \
  -d '{"answers":{"service":"repair","qty":"1","zip":"80206"}}'

The response has status, quote (null until every price answer is valid), issues, conditions, requestedTimes and derived. Each issue has field, code (missing, invalid, unknown_field or not_accepted), message and requiredFor (quote or booking).

HopTire derives the time zone, metro and coverage from the ZIP. If you send them, HopTire ignores them and lists them in ignoredFields.

Example: the answers in the draft example below price at $169, tax included (quote revision qr_f05018270bdcbd7c29a21029, computed when this page was built).

Draft

A draft needs every booking answer. It does not take terms acceptance or text consent. Those are chosen on the checkout page.

curl --silent --show-error -X POST 'https://hoptire.com/api/agent/v1/drafts' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: b7f3c1e2-4a9d-4c55-9e1f-2d8a6c0b9f41' \
  -d '{"answers":{"service":"repair","qty":"1","zip":"80206","vehicleType":"suv","year":"2021","make":"Toyota","model":"RAV4","positions":"rear-left","repairDamageLocation":"tread","repairDrivenFlat":"no","address":"1450 Gaylord St, Denver, CO 80206","availability":[{"date":"2026-11-22","start":"09:00","end":"12:00"},{"date":"2026-11-23","start":"13:00","end":"17:00"}],"name":"Sam Rivera","email":"sam@example.com","phone":"+13035550147"},"authorization":{"declaration":"customer_authorized","agentName":"Example Assistant","agentOperator":"Example Labs","grantedActions":["prepare_booking","accept_terms","submit_payment"],"maxAmountMinor":16900},"expectedQuoteRevision":"qr_f05018270bdcbd7c29a21029"}'

A new draft returns 201. The response has draft.checkoutUrl, draft.status.url, draft.status.token, draft.quote, draft.conditions, draft.agentMayApprove and draft.customerApprovalNeededFor. The checkout link expires after 24 hours. The status token works for 30 days.

Send expectedQuoteRevision or expectedAmountMinor from the quote the customer saw. If the price changed, you get 409 quote_changed and nothing is stored.

Use "source": "synthetic_qa" for tests. HopTire counts those drafts as test traffic, and live payment is disabled for them.

Idempotency and retries

  • Idempotency-Key is required on drafts: 16 to 128 letters, digits, _ or -. Use a new key for each new booking.
  • The same key with the same body returns the same draft and the same links, with status 200 and Idempotent-Replayed: true. It never makes a second draft.
  • The same key with a different body returns 409 idempotency_conflict.
  • After a timeout or a 503, retry with the same key and the same body. Use exponential backoff.
  • After a 429, wait for Retry-After.
  • Do not retry 400, 409, 413, 415 or 422 without a change.

Checkout page

The page shows the exact service, the tax-inclusive total, the conditions and the requested times. The person on the page can correct details first. HopTire prices the booking again before it reserves checkout.

  • The approval binds to the exact details and the quote revision on the screen. If the price changes, the page shows the new total and asks again.
  • The page asks who approves: the customer, or the authorized agent. An agent can approve only within the recorded authority.
  • The approver accepts the terms, version 2026-11-09.2. Text messages are an optional, separate choice.
  • After approval, the saved amount and the payment are fixed. A reload or a second device continues the same payment and never makes a second one.
  • Payment details go only into the Stripe payment form. Never send card data to the API, in a chat or in a URL.
  • Payment submits a service request. It does not confirm an appointment. HopTire confirms the technician and the arrival window separately.

Conditions you must show the customer

  • Puncture repair: $169 for the first eligible tire and $50 for each more tire. A technician must inspect the tire. If an attended inspection finds it unrepairable, $99 is retained and the rest is refunded.
  • Same day: a $75 fee is added once when a requested range is on the service-local today. It does not guarantee same-day service.
  • New tires: HopTire confirms the exact tire and fit before ordering. No substitution without the customer's approval.
  • Requested times are preferences, not confirmed availability.
  • If HopTire cannot fulfill a paid request, the payment is refunded.

The quote and draft responses list the conditions that apply to each booking. Show them all.

Status

GET /api/agent/v1/drafts/{draftId} with Authorization: Bearer <status token> returns the draft state, the approval and the payment state. It never returns answers or contact details.

  • Draft states: ready_for_checkout, checkout_opened, expired, payment_pending, paid, partially_refunded, refunded, canceled.
  • payment.state comes from HopTire's server record of the verified Stripe payment. A return to the page is not proof of payment.
  • appointment.confirmed stays false until HopTire schedules the visit.
  • An unknown draft, a wrong token and an expired grant all return 404.

Fields

The live list is at https://hoptire.com/api/agent/v1/schema. "Needed for" says whether the field blocks a price or only the booking.

Field Label Required Needed for Values
service What do you need? yes quote replace-supplied, repair, seasonal-changeover.
qty How many tires? yes quote 1, 2, 3, 4, other.
qtyExact Exact number of tires when qty is other quote integer 1 to 4.
size Tire size when service is replace-supplied quote text, see schema pattern. Not sure: unknown.
sizeSource Where the size came from no quote oe-lookup, manual, photo, unknown.
sizeRear Rear tire size no quote text, see schema pattern.
zip ZIP code yes quote text.
vehicleType Vehicle type yes quote car, suv, pickup, heavy.
vehicleTypeSource Where the vehicle type came from no quote vpic, customer.
year Year yes quote 2027, 2026, 2025, 2024, 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012, 2011, 2010, 2009, 2008, 2007, 2006, 2005, 2004, 2003, 2002, 2001, 2000, 1999, 1998, 1997, 1996, Other, unknown.
yearOther Vehicle year no quote integer 1900 to 2027.
make Make yes quote Acura, Audi, BMW, Buick, Cadillac, Chevrolet, Chrysler, Dodge, Ford, Genesis, GMC, Honda, Hyundai, Infiniti, Jaguar, Jeep, Kia, Land Rover, Lexus, Lincoln, Mazda, Mercedes-Benz, Mini, Mitsubishi, Nissan, Polestar, Porsche, Ram, Rivian, Subaru, Tesla, Toyota, Volkswagen, Volvo, Other, unknown.
makeOther Vehicle make no quote text, up to 40.
model Model yes quote text, up to 40.
trim Trim (if you know it) no quote text, up to 40.
repairDamageLocation Where is the tire damage? no quote tread, sidewall, not-visible, not-sure. Not sure: not-sure.
repairDrivenFlat Was the vehicle driven with this tire flat? no quote yes, no, not-sure. Not sure: not-sure.
positions Which positions? no quote front-left, front-right, front-left,front-right, rear-left, front-left,rear-left, front-right,rear-left, front-left,front-right,rear-left, rear-right, front-left,rear-right, front-right,rear-right, front-left,front-right,rear-right, rear-left,rear-right, front-left,rear-left,rear-right, front-right,rear-left,rear-right, all, front-pair, rear-pair, mixed, not-sure.
staggered Different front and rear tire sizes no quote yes, no, not-sure. Not sure: not-sure.
customerTireState What kind of tires do you have? when service is seasonal-changeover quote mounted-wheels, new-loose, used, not-sure.
tirePref Tire preference when service is replace-supplied quote budget, mid, premium.
specificTire Which tire? when service is replace-supplied and tirePref is specific quote text, up to 80.
damage A wheel is bent or cracked, or a lug nut is seized no quote no, yes, not-sure.
address Street address yes booking text, up to 160.
lockKey Do you have the wheel-lock key? no booking yes, no, not-sure. Not sure: not-sure.
availability Your availability yes quote array of {date, start, end}.
visitConstraintKind Do you have an arrival or finish deadline? no booking none, arrive-by, finish-by.
visitConstraintDate Requested deadline date when visitConstraintKind is arrive-by or finish-by booking text.
visitConstraintTime Requested deadline time (AM or PM) when visitConstraintKind is arrive-by or finish-by booking text, up to 12.
directions Anything the technician should know? no booking text, up to 600.
name Your name yes booking text, up to 80.
email Email yes booking text, up to 120.
phone Mobile number yes booking text, up to 24.

Requested times: availability is an array of up to 84 ranges {"date": "YYYY-MM-DD", "start": "09:00", "end": "12:00"}. Use whole hours from 08:00 to 20:00 in the service-local time zone, from today to 90 days ahead. A range must start in the future.

Not accepted by the API: contactOk, orderSmsConsent, smsConsent, checkoutReminderSms, bookingHelpSms, tirePhoto, sizeHelp, workSiteConfirmed.

Errors

Errors use {"ok": false, "error": {"code", "message", "retryable", ...}}.

Status Code Meaning
400 bad_json, invalid_request, idempotency_key_required Fix the request.
401 unauthorized Send the status token as a Bearer token.
404 not_found Unknown draft, wrong token or expired grant.
409 idempotency_conflict The key was used with another body. Use a new key.
409 quote_changed The price changed. Confirm the new quote with the customer.
413 too_large The body is too large.
415 unsupported_media_type Send Content-Type: application/json.
422 invalid_answers Fix each item in error.issues. Nothing was stored.
422 needs_human_review HopTire must review this booking, for example in a check-availability ZIP. Hand it to the customer at /book.
409 check_availability (Checkout page) The saved booking is now in a check-availability ZIP. No payment is taken.
429 rate_limited Wait for Retry-After.
503 *_unavailable Retry later with the same key and body.

Side effects

Call Stores Sends Payment
GET /api/agent/v1/schema nothing nothing none
POST /api/agent/v1/quote nothing nothing none
POST /api/agent/v1/drafts a draft nothing none
GET /api/agent/v1/drafts/{id} nothing nothing none
Open the checkout link a link-opened time nothing none
Approve on the checkout page the service request and the approval HopTire's normal booking notices opens one Stripe payment session
Pay in the Stripe form the verified payment the payment receipt one charge

Limits

  • New drafts: 20 per client per hour, and 300 per hour for all clients. Replays do not count.
  • Quotes: 30 per client per minute. Status reads: 120 per client per minute.
  • Approval attempts: 20 per draft.
  • Request body: 24000 bytes.
  • No API key is needed. HopTire may change these limits to stop abuse.

Privacy and security

  • Send customer details only in request bodies, never in URLs or query strings.
  • The checkout token is in the link fragment, so it does not reach server logs or referrers. Do not paste the link in public places.
  • The status token reads state only. Keep it with your records for this booking.
  • Privacy policy: https://hoptire.com/privacy. Questions: support@hoptire.com.