Sales API

The Sales module manages your commercial pipeline from initial quotation through confirmed sale. It integrates with Contacts, Products, Orders, and Invoices to provide end-to-end deal tracking.

---

Endpoints

Method	Path	Description
GET	/api/sales/quotations	List quotations (paginated)
POST	/api/sales/quotations	Create a quotation
GET	/api/sales/quotations/:id	Get a quotation
PATCH	/api/sales/quotations/:id	Update a quotation
DELETE	/api/sales/quotations/:id	Delete a draft quotation
POST	/api/sales/quotations/:id/confirm	Convert quotation to sales order
POST	/api/sales/quotations/:id/send	Email quotation to customer
GET	/api/sales/orders	List confirmed sales orders
GET	/api/sales/pipeline	Pipeline summary by stage
GET	/api/sales/revenue	Revenue report (date range)
GET	/api/sales/team	Sales team performance

---

Quotations

List Quotations

GET /api/sales/quotations?status=draft&contactId=018e...&page=1&limit=20

Query Parameters

Parameter	Type	Description
status	draft | sent | confirmed | cancelled	Quotation status
contactId	string	Filter by contact
salesperson	string	Filter by salesperson employee ID
from	ISO 8601	Created from date

Response

{
  "data": [
    {
      "id": "018e1111-abcd-7000-8000-000000000001",
      "reference": "QO/2026/0018",
      "status": "sent",
      "contact": { "id": "...", "name": "Acme Corp", "email": "[email protected]" },
      "salesperson": { "id": "...", "name": "Jane Smith" },
      "validUntil": "2026-04-20T00:00:00Z",
      "lineItems": [
        {
          "productId": "018e5678-...",
          "productName": "ECOSIRE Shopify Connector",
          "quantity": 1,
          "unitPrice": 49900,
          "discount": 10,
          "total": 44910
        }
      ],
      "subtotal": 44910,
      "total": 44910,
      "currency": "usd",
      "createdAt": "2026-03-18T09:00:00Z"
    }
  ],
  "meta": { "total": 34, "page": 1, "limit": 20, "totalPages": 2 }
}

Create a Quotation

POST /api/sales/quotations
Content-Type: application/json

{
  "contactId": "018e1234-abcd-7000-8000-000000000001",
  "salespersonId": "018ecccc-abcd-7000-8000-000000000001",
  "validUntil": "2026-04-30T00:00:00Z",
  "lineItems": [
    {
      "productId": "018e5678-abcd-7000-8000-000000000001",
      "quantity": 1,
      "unitPrice": 49900,
      "discount": 0
    }
  ],
  "currency": "usd",
  "terms": "Payment due within 30 days of invoice."
}

Send a Quotation

Emails the quotation PDF to the customer and changes status to sent.

POST /api/sales/quotations/018e1111-abcd-7000-8000-000000000001/send
Content-Type: application/json

{
  "subject": "Quotation QO/2026/0018 from ECOSIRE",
  "message": "Please review the attached quotation. Valid until April 30, 2026."
}

Confirm to Sales Order

POST /api/sales/quotations/018e1111-abcd-7000-8000-000000000001/confirm

Creates a confirmed Order record (see Orders API) and transitions quotation to confirmed.

---

Pipeline Summary

GET /api/sales/pipeline?from=2026-01-01&to=2026-03-31

Response

{
  "stages": [
    { "stage": "draft", "count": 12, "value": 588000 },
    { "stage": "sent", "count": 8, "value": 392000 },
    { "stage": "confirmed", "count": 45, "value": 2205000 },
    { "stage": "cancelled", "count": 3, "value": 147000 }
  ],
  "totalPipeline": 3332000,
  "currency": "usd",
  "period": { "from": "2026-01-01", "to": "2026-03-31" }
}

Note: values in smallest currency unit (cents).

---

Revenue Report

GET /api/sales/revenue?from=2026-01-01&to=2026-03-31&groupBy=month

Query Parameters

Parameter	Type	Description
from	ISO 8601	Period start
to	ISO 8601	Period end
groupBy	day | week | month	Aggregation period

Response

{
  "data": [
    { "period": "2026-01", "revenue": 980000, "orders": 18 },
    { "period": "2026-02", "revenue": 1240000, "orders": 23 },
    { "period": "2026-03", "revenue": 1560000, "orders": 29 }
  ],
  "total": { "revenue": 3780000, "orders": 70 },
  "currency": "usd"
}

---

Status Codes

Code	Scenario
200	Get, list, or report succeeded
201	Quotation created
204	Draft quotation deleted
400	Attempt to delete a sent quotation
404	Quotation not found
409	Quotation already confirmed or cancelled