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.

Creates an order for an existing customer (or a brand-new one) and charges it. Books are matched by book_id, isbn or partial title; prices come from the catalog, so never send prices. Shipping: ground is free over $35.00 otherwise $4.99, expedited $12.99, overnight $24.99. Tax is 8.25% of the discounted subtotal. Stock is decremented, a charge transaction is written, and the response includes the full order plus a pricing breakdown.

Agent guidance: Use when a caller wants to buy or re-order a title. Load GET /api/public/v1/inventory first to confirm the exact ISBN and stock, then place the order. If a title is short on stock you get 409 conflict — read back the shortfall and retry with allow_backorder: true only after the customer agrees.

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.

Returns the entire book catalog in one call — every title with author, format, category, price and current stock — plus per-author rollups and totals in `meta`. No search or pagination.

Agent guidance: Call this once at the start of a conversation to load the whole catalog into context; then answer stock, author and price questions without further lookups.

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, filterable ticket history with customer, order and full event history embedded — the record of every previous support interaction.

Agent guidance: Search this before acting: check for an existing open ticket and read what was already promised to the customer.

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.

Full ticket with customer, order and the complete event history (messages, notes, resolutions).

Agent guidance: Read the ticket history before replying so you do not repeat or contradict a previous agent.

Records one CX-agent conversation (every turn plus every tool call) so Bookly staff can audit what the agent did. Call this at the end of every conversation. Formatting contract: each message carries `role`, an optional bold `speaker`, an ISO-8601 `occurred_at` timestamp, markdown `content`, and — for tool turns — `tool_name`, `tool_input` and `tool_output`. Anything structured goes in `metadata`.

Agent guidance: Mandatory after every customer interaction. Include a plain-language `summary` explaining the reasoning behind any refund, return or escalation.

Paginated, searchable history of every logged CX-agent conversation, with all messages and tool calls embedded.

Agent guidance: Check this before answering: if you already promised something to this customer, honour it instead of re-deciding.

Full trace with customer, order, ticket and the ordered message list including tool inputs/outputs.

Agent guidance: Pull the exact wording of a previous promise before continuing a follow-up conversation.

Adds more messages to an existing trace, in order, and recomputes counts, duration and the transcript.

Agent guidance: Use for long-running conversations you logged with status in_progress.

Revise the summary, outcome, sentiment, tags or status of an already-logged conversation.

Agent guidance: Close out an in_progress trace or correct the recorded outcome.