# Bookly Support API

> Public, no-auth REST API for the fictional Bookly online bookstore. It powers a customer-support agent handling order status, returns/refunds, shipping, policies and account questions.

- Base URL: https://bookly.davidbusacker.com
- OpenAPI 3.1: https://bookly.davidbusacker.com/api/public/openapi.json
- Tool manifest (MCP-style): https://bookly.davidbusacker.com/api/public/tools.json
- Human docs: https://bookly.davidbusacker.com/docs
- Auth: none. CORS: open.

## Conventions
- Success: {"data": ..., "meta": {"request_id": "..."}}
- Error: {"error": {"type","title","status","code","detail","request_id"}} with codes invalid_request | not_found | conflict | internal_error
- Money is integer cents. Timestamps are ISO-8601 UTC.
- Identifiers are flexible: orders accept UUID or BK-#####, customers accept UUID or email, returns accept RMA-#####, refunds accept RF-#####, tickets accept TCK-#####, shipments accept tracking number.
- Lists paginate with ?limit (max 100) & ?offset; meta contains total/limit/offset/has_more.

## Business rules
- Return window: 30 days after delivery; 90 days for damaged or wrong-item.
- Return label fee $4.99, waived for damaged/wrong-item.
- Ebooks are non-returnable.
- Cancellation allowed while order is processing or backordered.
- Reship allowed when order is lost_in_transit or shipped; tracking with no scan for 7+ days is considered stalled.
- Free shipping over $35.00, otherwise $4.99 ground.

## Recommended agent flow
1. GET /api/public/v1/meta — discover live sample IDs and enums.
2. Identify the customer: GET /api/public/v1/customers?email=... or GET /api/public/v1/orders?email=...
3. Read the order: GET /api/public/v1/orders/{id}
4. Before promising a return: POST /api/public/v1/orders/{id}/returns/eligibility
5. Act: create the return, issue the refund, cancel, reship, or change the address.
6. Ground policy answers in /api/public/v1/policies and /api/public/v1/faqs.
7. Escalate with POST /api/public/v1/support/tickets when you cannot resolve it.

## Endpoints

### System — Health and discovery.
- GET /api/public/v1/health — Service health. Call once at startup to confirm the API and dataset are reachable.
- GET /api/public/v1/meta — Discovery metadata. Fetch first so you can use real identifiers in later calls instead of guessing.

### Orders — Order lookup, cancellation and line items.
- GET /api/public/v1/orders — List / search orders. Primary lookup when the customer gives an email address rather than an order number.
- GET /api/public/v1/orders/{id} — Get one order. The single richest call for answering 'where is my order?'.
- GET /api/public/v1/orders/{id}/items — List order line items. Use the returned order_item_id values when creating a partial return.
- POST /api/public/v1/orders/{id}/cancel — Cancel an order. Use for 'cancel my order'. If it returns 409, offer a return instead.

### Shipping — Shipments, tracking events and reshipments.
- GET /api/public/v1/orders/{id}/shipments — List shipments for an order. Answer delivery-timing questions and detect stalled tracking.
- POST /api/public/v1/orders/{id}/reship — Create a replacement shipment. Use for lost-in-transit packages after confirming tracking is stalled.
- GET /api/public/v1/shipments/{tracking} — Track a shipment. Direct tracking lookup when the customer pastes a tracking number.
- GET /api/public/v1/shipments/{tracking}/events — Tracking event history. Detect a stalled package: no new scan for 7+ days means offer a reship.

### Returns — Eligibility, RMA creation and lifecycle.
- POST /api/public/v1/orders/{id}/returns/eligibility — Check return eligibility. Always call this before creating a return so you can explain the outcome to the customer.
- GET /api/public/v1/returns — List returns. Check whether a return already exists before creating a duplicate.
- POST /api/public/v1/returns — Create a return (RMA). Call after eligibility passes. `items` is optional — omit it to return every line on the order, or match lines by order_item_id, isbn or title. Set initiate_refund to open the refund in the same call.
- GET /api/public/v1/returns/{rma} — Get a return. Answer 'what is the status of my return?'.
- POST /api/public/v1/returns/{rma}/receive — Mark a return received. Warehouse-side action; set auto_refund to close the loop in one call.
- POST /api/public/v1/returns/{rma}/cancel — Cancel a return. Use when the customer decides to keep the item.

### Refunds — Refunds, store credit and the money ledger.
- GET /api/public/v1/refunds — List refunds. Confirm whether money already went back before promising a new refund.
- POST /api/public/v1/refunds — Issue a refund. Use for goodwill refunds and post-return settlements.
- GET /api/public/v1/refunds/{id} — Get a refund. Give the customer the exact refund amount and timing.
- PATCH /api/public/v1/refunds/{id} — Update a refund status. Use to release a `pending_return` refund early for a loyal customer, or to cancel a refund the customer no longer wants.
- GET /api/public/v1/transactions — List ledger transactions. Reconcile what the customer was actually charged.

### Customers — Customer identity and order history.
- GET /api/public/v1/customers — List / search customers. Identity resolution before touching order data.
- GET /api/public/v1/customers/{id} — Get a customer. Check store credit balance before offering it as a refund method.
- GET /api/public/v1/customers/{id}/orders — List a customer's orders. Use when the customer says 'my last order' without a number.

### Catalog — Book catalog search.
- GET /api/public/v1/books — Search the catalog. Recommend replacements or confirm stock before promising a reship.
- GET /api/public/v1/books/{id} — Get a book. Confirm format — ebooks cannot be returned.

### Knowledge — Policies and FAQs for grounded answers.
- GET /api/public/v1/policies — List policies. Ground policy answers in this text instead of improvising.
- GET /api/public/v1/policies/{slug} — Get one policy. Quote the exact clause back to the customer.
- GET /api/public/v1/faqs — Search FAQs. First stop for general questions that need no account data.

### Support — Tickets and simulated support actions.
- GET /api/public/v1/support/tickets — List support tickets. Check for an existing open ticket before creating another.
- POST /api/public/v1/support/tickets — Create a support ticket. Escalation path when you cannot resolve the request with the other endpoints.
- PATCH /api/public/v1/support/tickets/{id} — Update a ticket. Close the ticket once the customer confirms the issue is resolved.
- POST /api/public/v1/support/actions/password-reset — Send a password reset link. Standard answer for 'I can't log in'.
- POST /api/public/v1/support/actions/address-change — Change a shipping address. Use before the order ships; afterwards offer a return or intercept instead.

## Quick examples
curl https://bookly.davidbusacker.com/api/public/v1/meta
curl "https://bookly.davidbusacker.com/api/public/v1/orders?email=ava.brooks@example.com"
curl https://bookly.davidbusacker.com/api/public/v1/orders/BK-10042
curl -X POST https://bookly.davidbusacker.com/api/public/v1/orders/BK-10042/returns/eligibility -H 'Content-Type: application/json' -d '{"reason":"damaged"}'

Total endpoints: 34.