What this does
The Quotes API lets you manage the full quote lifecycle programmatically: create quotes, retrieve them individually or as a list, change status, send by email, and convert an accepted quote into an invoice.
When to use it
Use this endpoint when a customer needs a quote before any invoice is raised — for example, trades and service businesses quoting a job, or any sales process that goes from estimate to acceptance to invoice.
Authentication and scopes
Requests must include Authorization: Bearer rly_your_key_here. Each endpoint requires one of:
quotes:read— list and retrieve quotesquotes:write— create, update, send, and convert quotes
Endpoints
List quotes
GET /api/v1/quotes
Returns a paginated list of quotes. Supports ?page=1&limit=50 query parameters.
Create a quote
POST /api/v1/quotes
{
"customerId": "cust_abc123",
"clientName": "Acme Ltd",
"clientEmail": "[email protected]",
"validUntil": "2026-12-31",
"currency": "GBP",
"taxRate": 20,
"items": [
{
"description": "Kitchen refit — labour",
"quantity": 5,
"unitPrice": 450.00,
"taxRate": 20
}
]
}
clientName, validUntil, and at least one items entry are required. customerId, clientEmail, clientAddress, issueDate, currency, taxRate, and notes are optional.
Response (201 Created): the created quote object including id, quote_number, status: "draft", and totals.
Get a single quote
GET /api/v1/quotes/:id
Returns the quote with its items array.
Update quote status
PATCH /api/v1/quotes/:id
{ "status": "sent" }
Allowed values for status: draft, sent, accepted, declined, expired. Status is the only field that this endpoint updates — to change line items or other fields, create a new quote.
Send a quote by email
POST /api/v1/quotes/:id/send
Sends the quote by email to the address on the quote and sets status to sent. Returns the updated quote plus an emailId. Returns 400 validation_error if the quote has no client_email.
Convert a quote to an invoice
POST /api/v1/quotes/:id/convert
Creates a new invoice from the quote's line items and marks the quote accepted with converted_invoice_id set. Returns the new invoice (201 Created).
404 not_found— quote does not exist409 conflict— quote has already been converted
Test mode
Keys flagged as test mode validate request bodies but skip database writes. The response includes "test": true and a stubbed id/quote_number so you can exercise the integration safely.