Quotations API

Create and search quotations programmatically.

Create quotation

POST /api/v1/quotations

Scope required: write

Request body

Field	Type	Required	Description
customer_id	string (UUID)	Yes	Customer ID (must belong to your business)
items	array	Yes	At least one line item
quotation_number	string	No	Auto-generated as QT-00001 if not provided
issue_date	string (YYYY-MM-DD)	No	Defaults to today
valid_until	string (YYYY-MM-DD)	No	Expiry date of the quotation
status	string	No	draft, sent, accepted, rejected, expired, converted. Default: draft
currency	string	No	ISO 4217 code. Default: USD
notes	string	No	Notes visible on the quotation
terms	string	No	Terms and conditions
template_type	string	No	Quotation template. Default: modern

Line item fields

Field	Type	Required	Description
description	string	Yes	Item description
quantity	number	Yes	Quantity
unit_price	number	Yes	Price per unit
tax_rate	number	No	Tax rate as percentage
discount_rate	number	No	Discount rate as percentage
product_id	string (UUID)	No	Link to a saved product

Example request

curl -X POST https://onlineinvoicemaker.com/api/v1/quotations \
  -H "Authorization: Bearer oim_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "valid_until": "2026-05-01",
    "items": [
      {
        "description": "Full Brand Identity Package",
        "quantity": 1,
        "unit_price": 5000,
        "tax_rate": 10
      },
      {
        "description": "Business Card Design",
        "quantity": 1,
        "unit_price": 500,
        "discount_rate": 20
      }
    ]
  }'

Example response

{
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "business_id": "cb21efb1-fa40-434f-a1d3-e17c0bdb9aa6",
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "quotation_number": "QT-00001",
  "issue_date": "2026-04-01",
  "valid_until": "2026-05-01",
  "status": "draft",
  "subtotal": 5400.00,
  "tax_amount": 500.00,
  "total": 5900.00,
  "currency": "USD",
  "created_at": "2026-04-01T10:30:00.000Z",
  "items": [
    {
      "description": "Full Brand Identity Package",
      "quantity": 1,
      "unit_price": 5000,
      "tax_rate": 10,
      "tax_amount": 500.00,
      "discount_rate": 0,
      "amount": 5500.00
    },
    {
      "description": "Business Card Design",
      "quantity": 1,
      "unit_price": 500,
      "tax_rate": 0,
      "tax_amount": 0,
      "discount_rate": 20,
      "amount": 400.00
    }
  ]
}

Status: 201 Created

Webhook event

A quotation.created webhook event is emitted with the full quotation data after creation.

---

Search quotations

GET /api/v1/quotations

Scope required: read

Query parameters

Parameter	Type	Description
number	string	Filter by quotation number (partial match, case-insensitive)
status	string	Filter by status
customer_id	string (UUID)	Filter by customer
page	number	Page number. Default: 1
limit	number	Results per page. Default: 25, max: 100

Example request

curl -X GET "https://onlineinvoicemaker.com/api/v1/quotations?status=sent&limit=5" \
  -H "Authorization: Bearer oim_your_api_key"

Example response

{
  "data": [
    {
      "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "quotation_number": "QT-00001",
      "status": "sent",
      "total": 5900.00,
      "currency": "USD",
      "created_at": "2026-04-01T10:30:00.000Z",
      "quotation_items": [...],
      "customers": {
        "id": "550e8400",
        "name": "Acme Corp",
        "email": "billing@acme.com"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 18,
    "total_pages": 4
  }
}

Quotation statuses

Status	Description
draft	Quotation created but not sent
sent	Sent to customer
accepted	Customer accepted the quotation
rejected	Customer rejected the quotation
expired	Past the valid_until date
converted	Converted to an invoice