Developer quickstart

This guide walks through creating a Test API key in the Console, creating your first Quote with POST /v1/quotes, and reading the Receipt.

Before you start

A Kordless Workspace with a Project (Test and Live Environments are provisioned with it).
A Business connected to that Project with a Book published to the Test Environment.
The Business ID and Book ID — visible in the Console and Business Portal.

Quoting always runs against a published Book Version. If nothing is published in the key’s Environment, the quote completes with a terminal failed Receipt (no_published_version) instead of a price.

Create a Test API key

Open your Workspace in the Console and go to Developers.
Select your Project and the Test Environment.
Name the key (for example, Quickstart test) and choose Create Test secret.
Copy the secret immediately — it is shown exactly once and stored only as a SHA-256 digest.

The secret starts with sk_test_, which binds it to the Test Environment. Test traffic is never billed and never touches Live data.

Create your first quote

Call POST /v1/quotes with the Business, Book, offering, and factor selections:

curl -X POST https://your-kordless-instance.com/v1/quotes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "9d2c7f1e-…",
    "bookId": "b3a1…",
    "offeringId": "ceramic-pro",
    "factors": { "vehicle_size": "large", "condition": null },
    "idempotencyKey": "quickstart-001"
  }'

The response is 201 with the created Quote Intent and its Receipt:

{
  "data": {
    "quoteIntent": {
      "id": "f47ac10b-…",
      "status": "succeeded",
      "source": "api",
      "idempotencyKey": "quickstart-001",
      "inputs": { "offeringId": "ceramic-pro", "factors": { "vehicle_size": "large", "condition": null } }
    },
    "quoteReceipt": {
      "id": "0d4f…",
      "outcome": "succeeded",
      "bookVersionId": "7c9e…",
      "computation": {
        "currency": "CAD",
        "lineItems": [
          { "kind": "base", "label": "Ceramic Pro", "amountMinor": 89900, "ruleId": null },
          { "kind": "surcharge", "label": "Vehicle size: large", "amountMinor": 27500, "ruleId": "…" }
        ],
        "totalMinor": 117400,
        "paymentTerms": { "depositBasisPoints": 2000, "depositMinor": 23480, "balanceDueMinor": 93920 },
        "conditions": ["…"],
        "derivation": [{ "phase": "base", "status": "applied", "reason": "…", "deltaMinor": 89900, "runningTotalMinor": 89900 }]
      },
      "missingInputs": [],
      "failure": null
    }
  },
  "requestId": "req_…"
}

All amounts are integer minor units (cents). The Receipt pins the exact Book Version used, so the quote stays reproducible even after you publish a newer version.

Or use the SDK

@kordless/sdk is a dependency-free client for the same two routes:

npm i @kordless/sdk

import { Kordless } from "@kordless/sdk";

const kordless = new Kordless({ apiKey: "sk_test_..." });

const { quoteIntent, quoteReceipt, requestId } = await kordless.quotes.create({
  businessId: "9d2c7f1e-…",
  bookId: "b3a1…",
  offeringId: "ceramic-pro",
  factors: { vehicle_size: "large", condition: null },
  // idempotencyKey is optional — the SDK generates a qi_<uuid> key for you
});

The result is the same Intent and Receipt as the curl call above, with the three outcomes (succeeded, requires_input, failed) carried on quoteReceipt.outcome. Retrieve later with await kordless.quotes.retrieve(quoteIntent.id). API failures throw typed errors (AuthenticationError, NotFoundError, IdempotencyConflictError, RateLimitedError, …) that carry the envelope code and requestId.

Read the receipt outcomes

Every create returns a Receipt with one of three outcomes:

Outcome	Meaning	What you get
`succeeded`	The engine priced the request.	Full `computation`: line items, total, payment terms, conditions, derivation.
`requires_input`	Required inputs are missing.	`missingInputs` dotted paths (for example `factors.vehicle_size`). Never an amount.
`failed`	The request could not be priced.	Machine-readable `failure.code` such as `unknown_offering` or `no_published_version`.

A requires_input or failed result is a successful API call (HTTP 201) with an unpriced Receipt — handle it in your integration logic, not your error handling.

Retrieve the quote later

curl https://your-kordless-instance.com/v1/quotes/f47ac10b-… \
  -H "Authorization: Bearer sk_test_..."

Returns { "data": { "intent": …, "receipt": … }, "requestId": … } scoped to the same key.

Prefer no code? Use the hosted path

If you do not want to call the API at all, the hosted path lets a Business publish and share a quote link directly from the Business Portal — see Hosted quote path. Anonymous end customers can also be quoted programmatically through POST /v1/public_quotes, which resolves the Business’s Live Environment server-side.

Next steps

Authentication — API keys, member sessions, and anonymous routes.
Idempotency — safe retries with idempotencyKey.
Errors — the error envelope and codes.
Test and Live — environment isolation rules.
Components and embeds — drop-in React quote components.
Browse the full API reference for request and response schemas.

Start here

Core concepts

Distribution

Operations

Developer quickstart

Before you start

Create a Test API key

Create your first quote

Or use the SDK

Read the receipt outcomes

Retrieve the quote later

Prefer no code? Use the hosted path

Next steps

​Before you start

​Create a Test API key

​Create your first quote

​Or use the SDK

​Read the receipt outcomes

​Retrieve the quote later

​Prefer no code? Use the hosted path

​Next steps

Before you start

Create a Test API key

Create your first quote

Or use the SDK

Read the receipt outcomes

Retrieve the quote later

Prefer no code? Use the hosted path

Next steps