Create a Quote

Overview

The Create a Quote endpoint generates a new quote draft. Provide customer details, items, discounts, and notes. The quote is assigned a unique number (e.g., QT-001) and starts in draft status. You can later send it via email or convert to an invoice.

HTTP Method

POST

Endpoint URL

https://koteshen.com/api/v1/quotes

Path Parameters

None.

Query Parameters

None.

Request Headers

Authorization: Bearer <your_oauth2_token> (handled separately)
Content-Type: application/json
Accept: application/json

Request Body

A JSON object representing the quote creation payload.

Schema

Field	Type	Required	Description
`issued_at`	String	Yes	ISO 8601 date when the quote was issued (e.g., “2025-10-12T10:00:00.000Z”).
`expires_at`	String	Yes	ISO 8601 expiration date (e.g., “2025-10-28T10:00:00.000Z”).
`currency`	String	Yes	ISO 4217 currency code (e.g., “USD”, “ZAR”).
`customer_id`	Integer	Yes	ID of the existing customer.
`summary`	String	No	Brief description of the quote.
`items_attributes`	Array	Yes	Array of line items (see below).
`discount_type`	String	No	“fixed” or “percent”.
`discount_value`	Number	No	Discount amount or percentage (requires `discount_type`).
`notes`	String	No	Additional notes or terms.

Items Attributes Schema (per item)

Field	Type	Required	Description
`name`	String	Yes	Item description.
`quantity`	Number	Yes	Quantity (e.g., 12).
`unit_price`	Number	Yes	Price per unit (e.g., 340.00).
`total`	Number	No	Optional; auto-calculated if omitted.

Example Request Body

{
  "quote": {
    "issued_at": "2025-10-12T10:00:00.000Z",
    "expires_at": "2025-10-28T10:00:00.000Z",
    "currency": "USD",
    "customer_id": 13,
    "summary": "this is an estimate",
    "items_attributes": [
      {
        "name": "Design and development",
        "quantity": 12,
        "unit_price": 340,
        "total": 4080.0
      }
    ],
    "discount_type": "percent",
    "discount_value": 10,
    "notes": "Valid for 30 days."
  }
}

Success Response

Status Code

201 Created

Response Body

The newly created quote resource.

{
  "data": {
    "id": 25,
    "number": "QOT-E4BE-5322",
    "expires_at": "2025-10-28T00:00:00.000Z",
    "issue_date": null,
    "currency": "USD",
    "business_id": 1,
    "customer_id": 13,
    "notes": "",
    "summary": "this is an estimate",
    "subtotal": {
      "cents": 408000,
      "currency_iso": "USD"
    },
    "total": {
      "cents": 408000,
      "currency_iso": "USD"
    },
    "discount_type": "percent",
    "discount_value": null,
    "status": "draft",
    "emailed_at": null,
    "accepted_at": null,
    "rejected_at": null,
    "viewd_at": null,
    "invoiced_at": null,
    "issued_at": "2025-10-12T00:00:00.000Z",
    "created_at": "2025-10-21T04:34:18.935Z",
    "updated_at": "2025-10-21T04:34:18.935Z",
    "url": "http://localhost:3000/api/v1/quotes/25.json",
    "items": [
      {
        "id": 185,
        "name": "Design and development",
        "unit_price": "340.0",
        "quantity": 12,
        "total": "4080.0",
        "created_at": "2025-10-21T04:34:18.951Z",
        "updated_at": "2025-10-21T04:34:18.951Z"
      }
    ],
    "business": {
      "id": 1,
      "user_id": 1,
      "name": "Flixtechs",
      "slug": "flixtechs",
      "phone": "+27675711214",
      "phone_country": null,
      "discarded_at": null,
      "created_at": "2025-08-17T09:26:59.612Z",
      "updated_at": "2025-08-29T13:30:08.427Z",
      "address": {
        "id": 9,
        "line": "1 Mahem Place",
        "line2": "",
        "post_code": "5256",
        "city": "East London",
        "country": "ZA",
        "created_at": "2025-08-29T13:30:08.441Z",
        "updated_at": "2025-08-29T13:30:08.441Z"
      },
      "logo": "<logo_url>"
    },
    "customer": {
      "id": 13,
      "name": "Texas Ins",
      "company": "Texas Ins",
      "customer_type": "business",
      "phone": "+27675711214",
      "phone_country": "za",
      "currency": "zar",
      "email": "procurement@texas.com",
      "website": "https://texas.com",
      "business_id": 1,
      "notes": "notesy",
      "created_at": "2025-10-12T19:00:37.057Z",
      "updated_at": "2025-10-12T19:09:27.293Z",
      "address": {
        "id": 26,
        "line": "1 Mahem Pl",
        "line2": "Unit 23",
        "post_code": "5256",
        "city": "East London",
        "country": "South Africa",
        "created_at": "2025-10-12T19:09:27.300Z",
        "updated_at": "2025-10-12T19:09:27.300Z"
      },
      "url": "http://localhost:3000/api/v1/customers/13.json"
    }
  }
}

Response Headers

Content-Type: application/json
Location: https://api.koteshen.com/api/v1/quotes/1

Error Responses

401 Unauthorized

If the token is invalid or expired.

{
  "error": "Unauthorized",
  "message": "Invalid access token"
}

422 Unprocessable Entity

Validation errors (e.g., missing required fields, invalid dates).

{
  "error": "Unprocessable Entity",
  "message": "issued_at must be a valid ISO 8601 date",
  "errors": {
    "issued_at": ["is invalid"]
  }
}

Example Request (cURL)

curl -X POST "https://api.koteshen.com/api/v1/quotes" \
  -H "Authorization: Bearer <your_oauth2_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": {
      "issued_at": "2025-10-12T10:00:00.000Z",
      "expires_at": "2025-10-28T10:00:00.000Z",
      "currency": "USD",
      "customer_id": 13,
      "summary": "this is an estimate",
      "items_attributes": [
        {
          "name": "Design and development",
          "quantity": 12,
          "unit_price": 340
        }
      ],
      "discount_type": "percent",
      "discount_value": 10,
      "notes": "Valid for 30 days."
    }
  }'

Example Response (cURL)

See Success Response above.

Usage Notes

Taxes are auto-applied based on business settings; specify tax_ids in items if custom.
After creation, use the Update endpoint to edit or the Send endpoint (not in this collection) to email it.
Maximum 100 items per quote.

We are using cookies to improve your experience!