Quotes

Create a quote

Creates a draft quote header (source: joinways) on an event, with the billed party of the event frozen on it and a timeline entry. Add line items with POST /quotes/{id}/items. Fires quote.created. Role permission: quotes.manage.

post/quotes

Request

Base URL: https://joinways.app/api/v1
URL: https://joinways.app/api/v1/quotes
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://joinways.app/oauth/authorize, token URL https://joinways.app/api/oauth/token, scopes: mcp.write)

Headers

Idempotency-Keystring

Optional client-generated key (1 to 255 characters, e.g. a UUID v4) that makes the request idempotent for 24 hours: a retry with the same key replays the recorded response (marked Idempotency-Replayed: true) instead of executing the operation again. Same key with another body: 422 idempotency_key_reuse; while the first request runs: 409 idempotency_conflict. See the Idempotency section.

Request body

event_idstring uuid required

titlestring required

currency'EUR' | 'USD' | 'GBP' | 'CHF' | 'CAD' | 'AUD' | 'JPY' | 'CNY' | 'INR' | 'KRW' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'CZK' | 'HUF' | 'RON' | 'RUB' | 'MXN' | 'BRL' | 'ARS' | 'CLP' | 'COP' | 'PEN' | 'SGD' | 'THB' | 'PHP' | 'IDR' | 'MYR' | 'VND' | 'AED' | 'SAR' | 'ILS' | 'TRY' | 'NZD' | 'ZAR' | 'NGN' | 'KES' | 'MAD' | 'TND' | 'DZD'

ISO 4217 currency code.

Example request

{
  "currency": "EUR"
}

Response

The created quote.

idstring uuid

event_idstring uuid

quote_numberstring nullable

titlestring

draft = not sent yet; pending = sent, awaiting the client; accepted / signed = client agreement (signed = signature recorded); rejected = refused; invoiced = at least one invoice issued (a deposit included); paid = fully settled; cancelled = withdrawn. accepted, signed, invoiced and paid are live contracts counted in the event's confirmed amount (unless replaced, see superseded_by_quote_id).

currencystring

total_excl_taxnumber

total_taxnumber

total_incl_taxnumber

is_signedboolean nullable

signed_atstring date-time nullable

signature_mode'manual' | 'public' | 'null' nullable

signer_namestring nullable

signer_emailstring nullable

is_invoicedboolean nullable

invoice_numberstring nullable

invoice_datestring date-time nullable

due_datestring date-time nullable

payment_datestring date-time nullable

is_reverse_chargeboolean nullable

sent_atstring date-time nullable

When the quote was sent (for a platform quote, when the platform transmitted it).

viewed_atstring date-time nullable

last_viewed_atstring date-time nullable

view_countinteger

expires_atstring date-time nullable

Validity end of the offer.

created_atstring date-time

author_idstring uuid

billing_profile_idstring uuid nullable

source'joinways' | 'platform'

joinways = written in Joinways. platform = a booking platform's own document recorded in Joinways, mostly read from the platform's emails (quote transmitted, with its PDF), or imported once signed. A platform quote is read-only: its amounts, discounts, currency and lines are never edited, it is never deleted nor duplicated, and its status only takes accepted or rejected through the API; its PDF is the platform's.

source_platformstring nullable

Booking platform the document comes from (platform quote), or the one a Joinways quote was deposited to (e.g. Kactus).

external_referencestring nullable

The platform's own quote number (a platform that renumbers each revision gives each version its own). Unique per event.

platform_pushed_atstring date-time nullable

When a Joinways quote was deposited on the platform (first deposit only).

superseded_by_quote_idstring uuid nullable

Set when this quote was replaced: by a later version the booking platform sent, or by a signed amendment. A replaced quote keeps its status but never counts in the event's confirmed amount; only quotes where this is null are live. Set by Joinways only.

superseded_atstring date-time nullable

When the quote was replaced (null while it is live).

account_idstring uuid

totals_updated_atstring date-time nullable

discount_percentnumber nullable

discount_amountnumber nullable

invoiced_atstring date-time nullable

invoiced_bystring uuid nullable

invoice_pdf_pathstring nullable

invoice_snapshotobject nullable

payment_termsstring nullable

cancellation_termsstring nullable

postponement_termsstring nullable

purchase_orderstring nullable

client_first_namestring nullable

client_last_namestring nullable

client_emailstring nullable

client_phonestring nullable

client_is_individualboolean nullable

client_company_namestring nullable

client_addressstring nullable

client_postal_codestring nullable

client_citystring nullable

client_statestring nullable

client_countrystring nullable

client_vat_numberstring nullable

client_registration_numberstring nullable

client_purchase_orderstring nullable

parent_quote_idstring uuid nullable

The quote this one amends (amendment).

amendment_sequenceinteger

platform_request_tokenstring nullable

translationsobject

space_plan_snapshotobject nullable

space_plan_snapshot_atstring date-time nullable

ai_generatedboolean

ai_source_lead_idstring uuid nullable

ai_modelstring nullable

ai_confidencenumber nullable

ai_reasoningstring nullable

ai_warningsstring[]

ai_generated_atstring date-time nullable

Where the reading of the platform PDF stands. Null = not asked (only won platform quotes are read automatically).

document_lines_extracted_atstring date-time nullable

rejected_with_eventboolean

is_demoboolean

Example response

{
  "quote_number": "DEVIS-0042",
  "status": "pending",
  "currency": "EUR",
  "total_excl_tax": 9500,
  "total_tax": 1900,
  "total_incl_tax": 11400,
  "document_lines": [
    {
      "title": "Petit déjeuner d'accueil",
      "quantity": 85,
      "unit": "pers."
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.