Quotes

Create the quote

The quote is the offer's identity and the people who sign it. It holds no lines yet.

Code
curl -X POST https://api.kontier.eu/v1/quotes \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "kind":        "NEW_SUBSCRIPTION",
    "customer_id": "5b1c2a7e-8d3f-4e6a-9b0c-1d2e3f4a5b6c",
    "title":       "Premium Support 2027",
    "currency":    "CHF",
    "expires_at":  "2026-12-15T00:00:00Z"
  }'

The response is the quote in DRAFT. starts_at is optional: omit it and the offer begins on signature.

Put a subscription on the offer

Code
curl -X POST https://api.kontier.eu/v1/quotes/quo_01J9Z…/revisions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "kind": "new", "name": "Premium Support" }'

Response 201
{
  "data": {
    "id":              "…",
    "quote_id":        "quo_01J9Z…",
    "subscription_id": "sub_01J9Z…",
    "revision_id":     "…",
    "position":        0,
    "kind":            "new"
  }
}

kind: "new" mints a subscription in DRAFT for the quote's customer, holding an empty draft revision 1. name defaults to the quote's title.

To renegotiate an existing subscription instead, send {"kind": "renegotiation", "subscription_id": "…", "cut_at": "…"}: its live revision is cut at cut_at (omit it to cut now) and the draft that follows the cut is what the offer holds. adopt_draft: true binds a draft that is already open on the subscription, as it stands, instead of cutting a new one; with kind: "new" it adopts a subscription that was authored but never activated.

An offer may hold several subscriptions; position is the order the offer presents them in and the order the signature publishes them in. DELETE /v1/quotes/{id}/revisions/{subscription_id} takes one off again.

Author the deal on the subscription's draft

Use the subscription_id from the previous step with the subscription's revision routes. For a new subscription, write revision 1 whole:

Code
curl -X PUT https://api.kontier.eu/v1/subscriptions/sub_01J9Z…/revisions/draft \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "phases": [
      {
        "starts": { "kind": "fixed", "at": "2027-01-01T00:00:00Z" },
        "ends":   { "kind": "duration", "duration": { "count": 14, "unit": "day" } },
        "then":   "next",
        "reason": "Trial",
        "lines": [
          {
            "product_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            "origin": { "kind": "plan", "id": "0f8fad5b-d9cb-469f-a165-70867728950e", "version": 3 },
            "values": {
              "quantity": { "kind": "stated", "quantity": "12" },
              "price":    { "kind": "stated", "price": { "kind": "free" } }
            }
          }
        ]
      },
      {
        "starts": { "kind": "after_previous" },
        "ends":   { "kind": "never" },
        "then":   "open",
        "reason": "Paid",
        "lines": [
          {
            "product_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            "origin": { "kind": "plan", "id": "0f8fad5b-d9cb-469f-a165-70867728950e", "version": 3 },
            "values": {
              "quantity": { "kind": "stated", "quantity": "12" },
              "price":    { "kind": "stated", "price": { "kind": "agreed", "amount": "150.00" } }
            }
          }
        ]
      }
    ]
  }'

PUT replaces the draft, so sending the same body twice lands the same draft; it takes no Idempotency-Key. For a renegotiation, write the draft the cut opened the same way: send every active phase to the same PUT, with the elapsed part kept as it is (then: "next") and the new phases after it. POST /v1/subscriptions/{id}/revisions/draft/preview takes the same body and prices it without saving. See Editing a draft.

The signature publishes these drafts, not you. While an open quote holds a draft, publishing, activating or discarding it on the subscription is refused with 409 SUBSCRIPTION_DRAFT_ON_OFFER. Editing it is allowed while the quote is not out with the customer: an edit to the draft of a cleared quote sends the quote back to DRAFT, and once it is SENT an edit is refused until you withdraw the signature request. The phase, line and value model is described in full on Subscriptions.

GET /v1/quotes/{id}/revisions reads every subscription on the offer back, each with its draft's phases and every value resolved, and GET /v1/quotes/{id}/effects lists what signing would do to other subscriptions whose exit rules point at a phase this offer moves.

Send it

Code
curl -X POST https://api.kontier.eu/v1/quotes/quo_01J9Z…/send \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "recipients":  [ { "email": "procurement@example.com", "name": "Dana Weber" } ],
    "countersign": "SEAL"
  }'

The body is optional. Without it the offer goes to the customer's Quotes & contracts contacts, on the offer's own expiry, with no reminders. Named recipients replace that list for this send only: the first signs, the others are copied, at most three. expires_at can only narrow the deadline. reminder_every_days and reminder_max set automatic nudges. countersign says what your side does after the buyer signs: NONE, SEAL (applied automatically) or PERSON (wait for the countersigner you name).

A send answers 200 with the quote in SENT, or 202 with the approval request id when the send checkpoint parks it in PENDING_APPROVAL. An offer that holds no subscription is refused with 409 QUOTE_NO_REVISIONS, and one holding an empty revision cannot be signed.

Check that it can still be signed

Something the offer depends on can change after it was sent: the renegotiated subscription is cancelled or paused, a followed catalog version moves, a product is archived. GET /v1/quotes/{id}/signability rehearses the buyer's signature (rolled back) and answers signable, and when it is false a refusal with its code, message and the subscription_id, phase and product_id it is about. A refusal is also recorded on the quote's timeline, and signability_lost_at is set on the quote. Any other quote (a draft, or one already signed, declined, expired or voided) answers signable: true.

Signature

The buyer signs through the link in the mail (see below). Two other routes complete a signature:

• Countersign. When the send named a PERSON to countersign, that person signs for your organisation after the buyer with POST /v1/quotes/{id}/signature/countersign and {"consent": true}. It is refused with 409 SIGNING_COUNTERSIGN_NOT_READY before every party has signed, and with 403 SIGNING_NOT_COUNTERSIGNER when the request names somebody else.
• Mark signed. For a wet-ink or externally signed copy, POST /v1/quotes/{id}/mark-signed records the signature on an APPROVED or SENT quote. Upload the signed copy first with POST /v1/files (owner_kind=quote, category=uploaded_signed_copy) and confirm it with POST /v1/files/{id}/confirm, then send signer_name and the executed_file_id. Any live signature request is withdrawn first, so the buyer cannot also accept in the portal. A quote whose signature_mode is EXTERNAL is never sent; it is recorded this way.

Open the Quotes page

In the sidebar, under Sales, click Quotes. The command palette gets you there too: press ⌘K and start typing quotes.

Start the quote

Click Create Quote. The wizard runs in four stages: Customer & basics, Configuration, Document & signing and Review.

Write the deal

Configuration is where the products, quantities and agreed rates are written, and where later steps of the deal are added. What the wizard writes is the subscription's draft revision on the offer, the same one the API steps above author.

Review it, then create it

Review restates the offer before anything is written. Click Create quote.