Bookly Support API

Liveness probe plus database connectivity check and API version.

Agent guidance: Call once at startup to confirm the API and dataset are reachable.

Row counts, live sample identifiers (order numbers, emails, RMAs, tracking numbers), every enum value and the business-rule constants. This is the recommended bootstrap call for an agent.

Agent guidance: Fetch first so you can use real identifiers in later calls instead of guessing.

Paginated order list with filters. Use `email` when a customer contacts support without an order number.

Agent guidance: Primary lookup when the customer gives an email address rather than an order number.

Full order with customer, line items, shipments, returns, refunds and transactions embedded.

Agent guidance: The single richest call for answering 'where is my order?'.

Line items with the joined book record (format matters for return eligibility).

Agent guidance: Use the returned order_item_id values when creating a partial return.

Cancels an order and voids the authorization. Only allowed while the status is processing or backordered.

Agent guidance: Use for 'cancel my order'. If it returns 409, offer a return instead.

All shipments for the order, each with its full tracking event history.

Agent guidance: Answer delivery-timing questions and detect stalled tracking.

Generates a new shipment and tracking number. Allowed when the order is lost_in_transit or shipped.

Agent guidance: Use for lost-in-transit packages after confirming tracking is stalled.

Fetch a shipment by tracking number or UUID, with its events and parent order.

Agent guidance: Direct tracking lookup when the customer pastes a tracking number.

Chronological scan events for a shipment.

Agent guidance: Detect a stalled package: no new scan for 7+ days means offer a reship.

Deterministic eligibility check. Standard window is 30 days from delivery; damaged or wrong-item claims get 90 days and waive the $4.99 label fee. Ebooks are non-returnable.

Agent guidance: Always call this before creating a return so you can explain the outcome to the customer.

Paginated returns with their items and parent order.

Agent guidance: Check whether a return already exists before creating a duplicate.

Creates an RMA with a prepaid label and computes the expected refund. Rejects with 409 when the order is not eligible unless `override_eligibility` is true.

Agent guidance: 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.

Fetch a return by RMA number (RMA-12345) or UUID.

Agent guidance: Answer 'what is the status of my return?'.

Moves the return to `received`, optionally issuing the refund immediately.

Agent guidance: Warehouse-side action; set auto_refund to close the loop in one call.

Cancels an open RMA. Fails with 409 once the return is refunded.

Agent guidance: Use when the customer decides to keep the item.

Paginated refunds with their parent order.

Agent guidance: Confirm whether money already went back before promising a new refund.

Issues a full or partial refund, records the matching ledger transaction, credits store credit when requested and flips the order to `refunded` once fully covered. Over-refunding is rejected.

Agent guidance: Use for goodwill refunds and post-return settlements.

Fetch a refund by refund number (RF-12345) or UUID.

Agent guidance: Give the customer the exact refund amount and timing.

Moves a refund to any status. Settling (`succeeded`) writes the ledger transaction, applies store credit and flips the order to refunded once fully covered; cancelling or failing a settled refund writes a reversal. Every change appends to the refund timeline (`events`).

Agent guidance: Use to release a `pending_return` refund early for a loyal customer, or to cancel a refund the customer no longer wants.

Immutable money ledger: charges, refunds and voids.

Agent guidance: Reconcile what the customer was actually charged.

Search customers by email, fuzzy name/email query or loyalty tier.

Agent guidance: Identity resolution before touching order data.

Fetch by UUID or email (URL-encoded), including saved addresses and store credit.

Agent guidance: Check store credit balance before offering it as a refund method.

Order history for a customer, newest first. Accepts UUID or email.

Agent guidance: Use when the customer says 'my last order' without a number.

Search books by title, author or ISBN with category, format and stock filters.

Agent guidance: Recommend replacements or confirm stock before promising a reship.

Fetch a book by UUID or ISBN-13.

Agent guidance: Confirm format — ebooks cannot be returned.

Shipping, returns, refunds, privacy and account policies in full text.

Agent guidance: Ground policy answers in this text instead of improvising.

Fetch a single policy document by slug, e.g. `returns`.

Agent guidance: Quote the exact clause back to the customer.

Curated question/answer pairs for common support topics.

Agent guidance: First stop for general questions that need no account data.

Paginated support tickets with customer and order context.

Agent guidance: Check for an existing open ticket before creating another.

Opens a ticket, linking the customer by email and optionally an order.

Agent guidance: Escalation path when you cannot resolve the request with the other endpoints.

Change status, priority or record a resolution. Accepts TCK number or UUID.

Agent guidance: Close the ticket once the customer confirms the issue is resolved.

Simulates sending a reset email. Always returns success so account existence is never leaked.

Agent guidance: Standard answer for 'I can't log in'.

Updates the shipping address while the order is still pending or processing.

Agent guidance: Use before the order ships; afterwards offer a return or intercept instead.