openapi: 3.0.0
info:
  title: Nutshell Quotes API
  description: The most powerful API in the world
  version: 2.0.0
  contact:
    name: Nutshell Developers
    url: https://developers.nutshell.com
servers:
- url: https://app.nutshell.com/rest
  description: Nutshell REST API
tags:
- name: Quotes
paths:
  /quotes/{id}:
    get:
      tags:
      - Quotes
      summary: Get a quote
      description: Get a single quote by the ID provided.
      operationId: 4c251930a518927960cce7d1211a0945
      parameters:
      - name: id
        in: path
        description: Quote ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Quote
          content:
            application/json:
              schema:
                properties:
                  quotes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Quote'
                    example:
                    - id: 123-quotes
                      type: quotes
                      number: 1000-01
                      displayStatus: SENT
                      total:
                        amount: '5000.00'
                        currency: USD
                        formatted: $5,000.00
                      productLineItems:
                      - id: 1-quoteProductLineItems
                        position: 0
                        product: 100-products
                        name: Consulting Services
                        description: Monthly consulting retainer
                        sku: CONS-001
                        quantity: 2
                        term: null
                        price:
                          amount: '2500.00'
                          currency: USD
                          formatted: $2,500.00
                        total:
                          amount: '5000.00'
                          currency: USD
                          formatted: $5,000.00
                        discountUnit: null
                        discountNumber: null
                      subtotalLineItems:
                      - id: 1-quoteSubtotalLineItems
                        position: 0
                        label: Discount
                        modifierUnit: '%'
                        modifierValue: 10
                        operation: '-'
                        total:
                          amount: '500.00'
                          currency: USD
                          formatted: $500.00
                      recipient:
                        id: 321-contacts
                        name: Jane Doe
                        email: jane@example.com
                      validThroughTime: '2024-12-31T23:59:59Z'
                      createdTime: '2024-01-15T10:30:00Z'
                      publishedTime: '2024-01-16T14:20:00Z'
                      sentTime: '2024-01-17T09:15:00Z'
                      acceptedTime: null
                      acceptedName: null
                      acceptedEmail: null
                      deletedTime: null
                      links:
                        lead: 456-leads
                type: object
      security:
      - basicAuth: []
  /quotes/{id}/status:
    post:
      tags:
      - Quotes
      summary: Update the status of a quote
      description: Updates a quote to a native Nutshell status (READY, SENT, REVOKED, ACCEPTED, ARCHIVED).
        Odoo-specific fulfillment states should be stored on the lead via custom fields.
      operationId: 9809f001604e5cbe8f478e14b6ec6295
      parameters:
      - name: id
        in: path
        description: Quote ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - status
              properties:
                status:
                  type: string
                  enum:
                  - READY
                  - SENT
                  - REVOKED
                  - ACCEPTED
                  - ARCHIVED
                  example: SENT
                acceptedName:
                  description: Optional name recorded when accepting the quote
                  type: string
                acceptedEmail:
                  description: Optional email recorded when accepting the quote
                  type: string
              type: object
      responses:
        '200':
          description: Quote
          content:
            application/json:
              schema:
                properties:
                  quotes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Quote'
                    example:
                    - id: 123-quotes
                      type: quotes
                      number: 1000-01
                      total:
                        amount: '5000.00'
                        currency: USD
                        formatted: $5,000.00
                      validThroughTime: '2024-12-31T23:59:59Z'
                      createdTime: '2024-01-15T10:30:00Z'
                      publishedTime: '2024-01-16T14:20:00Z'
                      sentTime: '2024-01-17T09:15:00Z'
                      acceptedTime: '2024-01-20T16:45:00Z'
                      acceptedName: Jane Customer
                      acceptedEmail: jane@example.com
                      deletedTime: null
                      links:
                        lead: 456-leads
                type: object
      security:
      - basicAuth: []
  /quotes/{id}/invoice:
    post:
      tags:
      - Quotes
      summary: Create an invoice from a quote
      description: Creates a new invoice by duplicating the quote (same as in-app create invoice from
        quote). Line items, recipient, and most document fields are copied from the quote; invoice template
        defaults apply for payment/body/footer fields. No request body is required.
      operationId: 8ce989ecb071d43420747aa852f155db
      parameters:
      - name: id
        in: path
        description: Quote ID
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Invoice
          content:
            application/json:
              schema:
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                type: object
      security:
      - basicAuth: []
  /quotes:
    get:
      tags:
      - Quotes
      summary: Get a list of quotes
      operationId: 1aee48fe1472d38116c60c87e2ca4161
      parameters:
      - name: filter[lead]
        in: query
        description: Filter quotes by lead
        required: false
        schema:
          type: string
      - name: filter[dateMin]
        in: query
        description: Filter quotes created after this date. Date expected in the format YYYY-MM-DD
        required: false
        schema:
          type: string
      - name: filter[dateMax]
        in: query
        description: Filter quotes created before this date. Date expected in the format YYYY-MM-DD
        required: false
        schema:
          type: string
      - name: page[limit]
        in: query
        description: Limit the number of results returned, for pagination.
        required: false
        schema:
          type: string
      - name: page[page]
        in: query
        description: Request a specific page of results, for pagination. Used in conjunction with the
          page[limit] parameter. Indexing is 0-based.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A list of quotes
          content:
            application/json:
              schema:
                properties:
                  quotes:
                    description: An array of quote objects
                    type: array
                    items:
                      $ref: '#/components/schemas/Quote'
                    example:
                    - id: 123-quotes
                      type: quotes
                      number: 1000-01
                      displayStatus: SENT
                      total:
                        amount: '5000.00'
                        currency: USD
                        formatted: $5,000.00
                      productLineItems:
                      - id: 1-quoteProductLineItems
                        position: 0
                        product: 100-products
                        name: Consulting Services
                        description: Monthly consulting retainer
                        sku: CONS-001
                        quantity: 2
                        term: null
                        price:
                          amount: '2500.00'
                          currency: USD
                          formatted: $2,500.00
                        total:
                          amount: '5000.00'
                          currency: USD
                          formatted: $5,000.00
                        discountUnit: null
                        discountNumber: null
                      subtotalLineItems:
                      - id: 1-quoteSubtotalLineItems
                        position: 0
                        label: Discount
                        modifierUnit: '%'
                        modifierValue: 10
                        operation: '-'
                        total:
                          amount: '500.00'
                          currency: USD
                          formatted: $500.00
                      recipient:
                        id: 321-contacts
                        name: Jane Doe
                        email: jane@example.com
                      validThroughTime: '2024-12-31T23:59:59Z'
                      createdTime: '2024-01-15T10:30:00Z'
                      publishedTime: '2024-01-16T14:20:00Z'
                      sentTime: '2024-01-17T09:15:00Z'
                      acceptedTime: null
                      acceptedName: null
                      acceptedEmail: null
                      deletedTime: null
                      links:
                        lead: 456-leads
                    - id: 124-quotes
                      type: quotes
                      number: 1000-02
                      displayStatus: READY
                      total:
                        amount: '7500.00'
                        currency: USD
                        formatted: $7,500.00
                      productLineItems:
                      - id: 2-quoteProductLineItems
                        position: 0
                        product: 101-products
                        name: Implementation
                        description: Onboarding package
                        sku: IMPL-001
                        quantity: 1
                        term: null
                        price:
                          amount: '7500.00'
                          currency: USD
                          formatted: $7,500.00
                        total:
                          amount: '7500.00'
                          currency: USD
                          formatted: $7,500.00
                        discountUnit: null
                        discountNumber: null
                      subtotalLineItems: []
                      recipient: null
                      validThroughTime: '2024-11-30T23:59:59Z'
                      createdTime: '2024-02-01T08:00:00Z'
                      publishedTime: '2024-02-02T10:00:00Z'
                      sentTime: null
                      acceptedTime: null
                      acceptedName: null
                      acceptedEmail: null
                      deletedTime: null
                      links:
                        lead: 457-leads
                  meta:
                    $ref: '#/components/schemas/meta'
                  links:
                    description: Pagination links
                    type: object
                    example:
                      self: /rest/quotes?page[page]=0&page[limit]=25
                      first: /rest/quotes?page[page]=0&page[limit]=25
                      last: /rest/quotes?page[page]=0&page[limit]=25
                type: object
      security:
      - basicAuth: []
components:
  schemas:
    Invoice:
      type: object
      allOf:
      - $ref: '#/components/schemas/SalesDocument'
      - properties:
          number:
            description: The invoice number
            type: string
            example: 1000-01
          total:
            $ref: '#/components/schemas/value'
          validThroughTime:
            description: The date and time when the invoice expires or is due
            type: string
            example: '2024-12-31T23:59:59Z'
          createdTime:
            description: The date and time when the invoice was created
            type: string
            example: '2024-01-15T10:30:00Z'
          publishedTime:
            description: The date and time when the invoice was published
            type: string
            example: '2024-01-16T14:20:00Z'
          sentTime:
            description: The date and time when the invoice was sent to the customer
            type: string
            example: '2024-01-17T09:15:00Z'
          paidTime:
            description: The date and time when the invoice was paid by the customer
            type: string
            example: '2024-01-20T16:45:00Z'
          completionComment:
            description: Payment or completion note when the invoice was marked paid or revoked
            type: string
            example: Paid via ACH
            nullable: true
          deletedTime:
            description: The date and time when the invoice was deleted
            type: string
            example: '2024-02-01T12:00:00Z'
        type: object
    Quote:
      type: object
      allOf:
      - $ref: '#/components/schemas/SalesDocument'
      - properties:
          number:
            description: The quote number
            type: string
            example: 1000-01
          total:
            $ref: '#/components/schemas/value'
          validThroughTime:
            description: The date and time when the quote expires or is no longer valid
            type: string
            example: '2024-12-31T23:59:59Z'
          createdTime:
            description: The date and time when the quote was created
            type: string
            example: '2024-01-15T10:30:00Z'
          publishedTime:
            description: The date and time when the quote was published
            type: string
            example: '2024-01-16T14:20:00Z'
          sentTime:
            description: The date and time when the quote was sent to the customer
            type: string
            example: '2024-01-17T09:15:00Z'
          acceptedTime:
            description: The date and time when the quote was accepted by the customer
            type: string
            example: '2024-01-20T16:45:00Z'
          deletedTime:
            description: The date and time when the quote was deleted
            type: string
            example: '2024-02-01T12:00:00Z'
        type: object
    SalesDocument:
      properties:
        id:
          description: The API ID of this entity, formatted {integer}-{entityType}
          type: string
          example: 3-contacts
        displayStatus:
          description: The current status of the sales document. For invoices, ACCEPTED means paid.
          type: string
          enum:
          - DRAFT
          - READY
          - SENT
          - REVOKED
          - ACCEPTED
          - ARCHIVED
          - EXPIRED
          example: SENT
        productLineItems:
          $ref: '#/components/schemas/salesDocumentProductLineItems'
        subtotalLineItems:
          $ref: '#/components/schemas/salesDocumentSubtotalLineItems'
        recipient:
          $ref: '#/components/schemas/SalesDocumentRecipient'
        acceptedName:
          description: Name recorded when the document was accepted or marked paid
          type: string
          example: Jane Customer
          nullable: true
        acceptedEmail:
          description: Email recorded when the document was accepted or marked paid
          type: string
          example: jane@example.com
          nullable: true
      type: object
    SalesDocumentProductLineItem:
      title: Product line item
      properties:
        id:
          description: The line item ID
          type: string
          example: 1-quoteProductLineItems
        position:
          description: Sort order of the line item on the document
          type: integer
          example: 0
        product:
          description: The product ID this line item references, if any
          type: string
          example: 100-products
          nullable: true
        name:
          description: Display name of the line item
          type: string
          example: Consulting Services
        description:
          description: Description of the line item
          type: string
          example: Monthly consulting retainer
        sku:
          description: SKU of the line item
          type: string
          example: CONS-001
        quantity:
          description: Quantity of the line item
          type: number
          format: float
          example: 2
        term:
          description: Billing period unit for the line item, if any (minute, hour, day, week, month,
            quarter, or year)
          type: string
          example: month
          nullable: true
        price:
          $ref: '#/components/schemas/value'
        total:
          $ref: '#/components/schemas/value'
        discountUnit:
          description: 'Discount unit: ''$'' for a fixed amount, or ''%'' for a percentage'
          type: string
          example: '%'
          nullable: true
        discountNumber:
          description: Discount amount or percentage, depending on discountUnit
          type: number
          format: float
          example: 10
          nullable: true
      type: object
    SalesDocumentRecipient:
      description: The contact or company selected as the document recipient
      properties:
        id:
          description: The recipient entity ID; entity type is encoded in the API id suffix (e.g. contacts
            or accounts)
          type: string
          example: 321-contacts
        name:
          description: Display name of the recipient
          type: string
          example: Jane Doe
        email:
          description: Email address used for the recipient on this document
          type: string
          example: jane@example.com
          nullable: true
      type: object
      nullable: true
    SalesDocumentSubtotalLineItem:
      title: Subtotal line item
      properties:
        id:
          description: The subtotal line item ID
          type: string
          example: 1-quoteSubtotalLineItems
        position:
          description: Sort order of the adjustment on the document
          type: integer
          example: 0
        label:
          description: Display label for the adjustment
          type: string
          example: Tax
        modifierUnit:
          description: 'Modifier unit: ''$'' for a fixed amount, or ''%'' for a percentage'
          type: string
          example: '%'
        modifierValue:
          description: Modifier amount or percentage, depending on modifierUnit
          type: number
          format: float
          example: 6.5
        operation:
          description: Whether the modifier is added (+) or subtracted (-)
          type: string
          enum:
          - +
          - '-'
          example: +
        total:
          $ref: '#/components/schemas/value'
      type: object
    meta:
      description: Information about the Nutshell instance making the request
      properties:
        instanceId:
          description: The Nutshell instance ID
          type: string
          example: '12345'
        siteId:
          description: Site ID for WebFX customers
          type: string
      type: object
    salesDocumentProductLineItems:
      description: The products and services included in the sales document.
      type: array
      items:
        allOf:
        - $ref: '#/components/schemas/SalesDocumentProductLineItem'
    salesDocumentSubtotalLineItems:
      description: Adjustments applied after the product subtotal, such as tax, shipping, or discounts.
      type: array
      items:
        allOf:
        - $ref: '#/components/schemas/SalesDocumentSubtotalLineItem'
    value:
      properties:
        formatted:
          description: The value formatted as a string
          type: string
          example: $100.00
        amount:
          description: The value as a number
          type: string
          example: '100.00'
        currency:
          description: The currency code
          type: string
          example: USD
      type: object
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic