feat(quotes): document the Quotes REST API and webhooks

src/parameters/lago_quote_id.yaml

@@ -0,0 +1,8 @@
+name: lago_id
+in: path
+description: Unique identifier assigned to the quote within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the quote's record within the Lago system.
+required: true
+schema:
+  type: string
+  format: "uuid"
+  example: "1a901a90-1a90-1a90-1a90-1a901a901a90"

src/parameters/lago_quote_version_id.yaml

@@ -0,0 +1,8 @@
+name: lago_id
+in: path
+description: Unique identifier assigned to the quote version within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the quote version's record within the Lago system.
+required: true
+schema:
+  type: string
+  format: "uuid"
+  example: "1a901a90-1a90-1a90-1a90-1a901a901a90"

src/resources/quote.yaml

@@ -0,0 +1,23 @@
+parameters:
+  - $ref: "../parameters/lago_quote_id.yaml"
+get:
+  tags:
+    - quotes
+  summary: Retrieve a quote
+  description: |-
+    This endpoint retrieves a specific quote, along with its owners and its current version.
+    This is a premium feature.
+  operationId: findQuote
+  responses:
+    "200":
+      description: Quote
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/Quote.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "403":
+      $ref: "../responses/Forbidden.yaml"
+    "404":
+      $ref: "../responses/NotFound.yaml"

src/resources/quote_version.yaml

@@ -0,0 +1,23 @@
+parameters:
+  - $ref: "../parameters/lago_quote_version_id.yaml"
+get:
+  tags:
+    - quotes
+  summary: Retrieve a quote version
+  description: |-
+    This endpoint retrieves a specific quote version, along with its document `content` and its `billing_items`.
+    This is a premium feature.
+  operationId: findQuoteVersion
+  responses:
+    "200":
+      description: Quote version
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/QuoteVersion.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "403":
+      $ref: "../responses/Forbidden.yaml"
+    "404":
+      $ref: "../responses/NotFound.yaml"

src/resources/quote_version_approve.yaml

@@ -0,0 +1,35 @@
+parameters:
+  - $ref: "../parameters/lago_quote_version_id.yaml"
+post:
+  tags:
+    - quotes
+  summary: Approve a quote version
+  description: |-
+    This endpoint approves a quote version and generates the order form to send to the customer for signature.
+    Only a `draft` version can be approved, and its `billing_items` must be complete: approval validates them against the catalog and against the customer, and returns a `422` when the deal cannot be executed as quoted.
+    The `expires_at` of the generated order form is bounded by the deal's own term, so a signing window reaching beyond the day the deal stops being executable is rejected.
+    A concurrent write on the same quote is reported as a `422` rather than retried, so a duplicated call can fail while the first one is still in flight.
+    This is a premium feature.
+  operationId: approveQuoteVersion
+  requestBody:
+    description: Approve quote version payload
+    content:
+      application/json:
+        schema:
+          $ref: "../schemas/QuoteVersionApproveInput.yaml"
+    required: false
+  responses:
+    "200":
+      description: Quote version approved
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/QuoteVersion.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "403":
+      $ref: "../responses/Forbidden.yaml"
+    "404":
+      $ref: "../responses/NotFound.yaml"
+    "422":
+      $ref: "../responses/UnprocessableEntity.yaml"

src/resources/quote_version_clone.yaml

@@ -0,0 +1,27 @@
+parameters:
+  - $ref: "../parameters/lago_quote_version_id.yaml"
+post:
+  tags:
+    - quotes
+  summary: Clone a quote version
+  description: |-
+    This endpoint copies a quote version into a new `draft` version of the same quote, so that the deal can be renegotiated.
+    Any version of the quote can be cloned, but a quote can only carry one active version: the draft the quote currently holds, if any, is voided with the `superseded` reason. Cloning is therefore rejected with a `422` once a version of the quote has been approved.
+    A concurrent write on the same quote is reported as a `422` rather than retried, so a duplicated call can fail while the first one is still in flight.
+    This is a premium feature.
+  operationId: cloneQuoteVersion
+  responses:
+    "200":
+      description: Quote version cloned
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/QuoteVersion.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "403":
+      $ref: "../responses/Forbidden.yaml"
+    "404":
+      $ref: "../responses/NotFound.yaml"
+    "422":
+      $ref: "../responses/UnprocessableEntity.yaml"

src/resources/quote_version_void.yaml

@@ -0,0 +1,27 @@
+parameters:
+  - $ref: "../parameters/lago_quote_version_id.yaml"
+post:
+  tags:
+    - quotes
+  summary: Void a quote version
+  description: |-
+    This endpoint voids a quote version, which makes it definitive: a voided version can neither be edited nor approved again.
+    Only a `draft` version can be voided through this endpoint, and the resulting `void_reason` is `manual`. An `approved` version is voided by Lago itself, through the order form generated from it.
+    A concurrent write on the same quote is reported as a `422` rather than retried, so a duplicated call can fail while the first one is still in flight.
+    This is a premium feature.
+  operationId: voidQuoteVersion
+  responses:
+    "200":
+      description: Quote version voided
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/QuoteVersion.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "403":
+      $ref: "../responses/Forbidden.yaml"
+    "404":
+      $ref: "../responses/NotFound.yaml"
+    "422":
+      $ref: "../responses/UnprocessableEntity.yaml"

src/resources/quote_versions.yaml

@@ -0,0 +1,27 @@
+parameters:
+  - $ref: "../parameters/lago_quote_id.yaml"
+get:
+  tags:
+    - quotes
+  summary: List all versions of a quote
+  description: |-
+    This endpoint is used to list all the versions of a specific quote, from the most recent to the oldest.
+    The `content` and `billing_items` of each version are omitted; retrieve a version to get them.
+    This is a premium feature.
+  operationId: findAllQuoteVersions
+  parameters:
+    - $ref: "../parameters/page.yaml"
+    - $ref: "../parameters/per_page.yaml"
+  responses:
+    "200":
+      description: Quote versions
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/QuoteVersionsPaginated.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "403":
+      $ref: "../responses/Forbidden.yaml"
+    "404":
+      $ref: "../responses/NotFound.yaml"

src/resources/quotes.yaml

@@ -0,0 +1,105 @@
+get:
+  tags:
+    - quotes
+  summary: List all quotes
+  description: |-
+    This endpoint is used to list all existing quotes.
+    Quotes are ordered by creation date, from the most recent to the oldest.
+    This is a premium feature.
+  operationId: findAllQuotes
+  parameters:
+    - $ref: "../parameters/page.yaml"
+    - $ref: "../parameters/per_page.yaml"
+    - name: status[]
+      in: query
+      description: Filter quotes by the status of their current version. Possible values are `draft`, `approved` and `voided`.
+      required: false
+      explode: true
+      schema:
+        type: array
+        items:
+          type: string
+          enum:
+            - draft
+            - approved
+            - voided
+    - name: order_type[]
+      in: query
+      description: Filter quotes by order type. Possible values are `subscription_creation`, `subscription_amendment` and `one_off`.
+      required: false
+      explode: true
+      schema:
+        type: array
+        items:
+          type: string
+          enum:
+            - subscription_creation
+            - subscription_amendment
+            - one_off
+    - name: number[]
+      in: query
+      description: Filter quotes by their number, as assigned by Lago.
+      required: false
+      explode: true
+      schema:
+        type: array
+        items:
+          type: string
+          pattern: '^QT-\d{4}-\d{4,}$'
+        example:
+          - QT-2026-0001
+          - QT-2026-0002
+    - name: owner_id[]
+      in: query
+      description: Filter quotes by the Lago identifiers of the users owning them.
+      required: false
+      explode: true
+      schema:
+        type: array
+        items:
+          type: string
+          format: "uuid"
+        example:
+          - 1a901a90-1a90-1a90-1a90-1a901a901a90
+    - name: external_customer_id[]
+      in: query
+      description: Filter quotes by the external unique identifiers of their customers (provided by your own application).
+      required: false
+      explode: true
+      schema:
+        type: array
+        items:
+          type: string
+        example:
+          - external_id_1234
+    - name: from_date
+      in: query
+      description: Filter quotes created from a specific date.
+      required: false
+      explode: true
+      schema:
+        type: string
+        format: "date"
+        example: "2026-01-01"
+    - name: to_date
+      in: query
+      description: Filter quotes created up to a specific date.
+      required: false
+      explode: true
+      schema:
+        type: string
+        format: "date"
+        example: "2026-12-31"
+  responses:
+    "200":
+      description: Quotes
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/QuotesPaginated.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "403":
+      $ref: "../responses/Forbidden.yaml"
+    "422":
+      $ref: "../responses/UnprocessableEntity.yaml"

src/schemas/Quote.yaml

@@ -0,0 +1,6 @@
+type: object
+required:
+  - quote
+properties:
+  quote:
+    $ref: "./QuoteObjectExtended.yaml"

src/schemas/QuoteBaseObject.yaml

@@ -0,0 +1,49 @@
+type: object
+required:
+  - lago_id
+  - number
+  - order_type
+  - lago_customer_id
+  - lago_subscription_id
+  - lago_organization_id
+  - created_at
+  - updated_at
+properties:
+  lago_id:
+    type: string
+    format: "uuid"
+    description: Unique identifier of the quote, created by Lago.
+    example: "1a901a90-1a90-1a90-1a90-1a901a901a90"
+  number:
+    type: string
+    description: The unique number assigned to the quote by Lago.
+    example: "QT-2026-0001"
+  order_type:
+    $ref: "./QuoteOrderTypeEnum.yaml"
+  lago_customer_id:
+    type: string
+    format: "uuid"
+    description: Unique identifier of the customer the quote is addressed to, created by Lago.
+    example: "1a901a90-1a90-1a90-1a90-1a901a901a90"
+  lago_subscription_id:
+    type:
+      - string
+      - "null"
+    format: "uuid"
+    description: Unique identifier of the subscription the quote amends, created by Lago. It is set only when the `order_type` is `subscription_amendment`.
+    example: "1a901a90-1a90-1a90-1a90-1a901a901a90"
+  lago_organization_id:
+    type: string
+    format: "uuid"
+    description: Unique identifier of the organization, created by Lago.
+    example: "1a901a90-1a90-1a90-1a90-1a901a901a90"
+  created_at:
+    type: string
+    format: "date-time"
+    description: The date and time in UTC (ISO 8601) when the quote was created.
+    example: "2026-04-29T08:59:51Z"
+  updated_at:
+    type: string
+    format: "date-time"
+    description: The date and time in UTC (ISO 8601) when the quote was last updated.
+    example: "2026-04-29T08:59:51Z"