# Guide for AI Agents

WholesaleFromUSA helps buyers discover products stocked in U.S. warehouses, compare live offers with pre-computed Regular/Patriot pricing, and order. There is no quote flow: manufacturers set their net via POST /api/v1/wholesale/offers and the platform computes buyer prices server-side.

HomeServiceBooking helps customers discover service categories and providers, determine whether a provider supports instant booking or requires a quote, check availability, submit service requests, compare quotes, and create bookings.

## Safe read actions

GET product, offer, supplier, service, provider, availability, order, request, and booking resources. These do not create or change records.

## State-changing actions

Use explicit POST or PATCH endpoints. Send an `Idempotency-Key` on order creation, service request creation, booking creation, and quote acceptance. Retry the same request with the same key after a timeout rather than creating a new key.

## Determine the next action

- An offer with `type: instant` and `status: active` can be used with `POST /api/v1/wholesale/orders`.
- A provider with `capabilities.instant_booking: true` may accept a booking request.
- A provider without instant booking requires a service request and quote first.

## Authentication

Two ways to authenticate writes: (1) **Session token (preferred):** `POST /api/v1/auth/vendor/login` with `{email, password}` (or `/api/v1/auth/customer/login` with `{phone, password}`) returns a `sess_` bearer token valid 7 days; send as `Authorization: Bearer sess_...`. Register via `POST /api/v1/auth/vendor/register` (`{email, organization_name, password}`) or `/api/v1/auth/customer/register` (`{phone, name, password}`). (2) **Development token:** a temporary Bearer <redacted> beginning with `dev_`. Vendors manage products at `/vendor/` or via `POST`/`PATCH /api/v1/wholesale/products` (PATCH is restricted to the owning organization).

## Side effects

Creating an offer, request, order, quote, supplier, provider, listing, or booking changes state and may later notify people or charge money. GET requests are read-only. Every successful write returns the created resource, its ID, current status, and useful next actions.

## Errors

Errors are JSON objects with a stable `error.code`, human-readable `error.message`, and field or resource details when applicable. Do not infer success from HTTP 200 alone; inspect the resource status.
