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:
- OpenAPI 3.1: https://hoptire.com/docs/agents/openapi.json
- Live fields, values and limits: https://hoptire.com/api/agent/v1/schema
- This guide as HTML: https://hoptire.com/docs/agents
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 alsoaccept_termsandsubmit_paymentif 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
- Read
GET /api/agent/v1/schemafor the current fields and values. - Collect answers from the customer. Never guess a missing answer. Use a field's "not sure" value only when the customer is not sure.
- Call
POST /api/agent/v1/quoteas often as you need. Fix each issue it returns. - Confirm the total, the conditions and the requested times with the customer.
- Call
POST /api/agent/v1/draftswith anIdempotency-Keyheader and the authorization. - Open
draft.checkoutUrl. The customer or you review the details, accept the terms and pay in the Stripe form on that page. - Read
GET draft.status.urlwithAuthorization: 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-Keyis 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.statecomes from HopTire's server record of the verified Stripe payment. A return to the page is not proof of payment.appointment.confirmedstays 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 |
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.