# HopTire agent booking API

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 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.

```bash
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.

```bash
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.
