> ## Documentation Index
> Fetch the complete documentation index at: https://docs.printools.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List pre-built items

> Requires the scope prebuiltitems.read.

Required scopes: `prebuiltitems.read`.


## OpenAPI

````yaml GET /v1/prebuilt-items
openapi: 3.1.0
info:
  title: PRINTOOLS API
  version: 1.0.0
  description: >-
    The PRINTOOLS public REST API. This document is generated from the live
    route table and service GraphQL SDL; do not edit it by hand.


    Every 2xx response has {status, message, data}. Every non-2xx response has
    {error, message, status: false}.


    Tenant credential: send X-API-Key only. It is bound to one shop.
    X-PrintTools-Organization-Id is optional for that credential and, if sent,
    must match its shop.


    Partner credential: send X-API-Key, X-API-Secret, Authorization: Bearer
    <Cognito access token>, and X-PrintTools-Organization-Id. The OAuth flow is
    documented at https://app.printools.io/api/index.html#partner-auth.


    Read live limits from GET /v1/reference/limits. Field shapes are projected
    from operation declarations; local endpoints have explicit handler-derived
    schemas.
servers:
  - url: https://api.printools.io
    description: Production
security: []
externalDocs:
  description: Getting started, OAuth and webhook guidance
  url: https://app.printools.io/api/index.html
paths:
  /v1/prebuilt-items:
    get:
      tags:
        - prebuilt-items
      summary: List pre-built items.
      description: Requires the scope prebuiltitems.read.
      operationId: get_v1_prebuilt_items
      parameters:
        - name: X-PrintTools-Organization-Id
          in: header
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            Tenant credential: optional and, when sent, must equal the shop
            bound to the key. Partner credential: required; it selects an
            organisation the user previously authorised.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Output_PreBuiltItem'
        '400':
          description: >-
            Validation or request-shape error. Correct the request before
            retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Credential authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            WWW-Authenticate:
              schema:
                type: string
                example: ApiKey
        '403':
          description: >-
            The credential lacks a required scope, or its actor lacks
            permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The resource or endpoint was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Conflict, including idempotency-key reuse or an in-flight idempotent
            request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: The JSON request body exceeds the published size limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited. Retry after the returned delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Whole seconds to wait.
              schema:
                type: integer
                minimum: 0
        '500':
          description: An unexpected server error. A retry can be appropriate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - tenantApiKey: []
        - partnerApiKey: []
          partnerApiSecret: []
          partnerBearer: []
      x-codeSamples:
        - lang: curl
          label: Tenant credential
          source: |-
            curl --request GET 'https://api.printools.io/v1/prebuilt-items' \
              --header 'X-API-Key: $PRINTOOLS_API_KEY'
components:
  schemas:
    Success:
      type: object
      required:
        - status
        - message
        - data
      properties:
        status:
          type: boolean
          description: >-
            The actual resolver result. It can be false when an operation
            returns false or null without throwing.
        message:
          type: string
          example: OK
        data: {}
      description: Every 2xx response uses this envelope.
    Output_PreBuiltItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        status:
          $ref: '#/components/schemas/Enum_PreBuiltItemStatus'
        notes:
          type:
            - string
            - 'null'
        thumbnailUrl:
          type:
            - string
            - 'null'
        tags:
          type: array
          items:
            type: string
        computedUnitPriceExGst:
          type: number
        computedTotalQuantity:
          type: integer
        totalQuantity:
          type: integer
          description: >-
            The AUTHORED quantity, as a quote group carries one (CU-86d45h8cw) —
            distinct

            from `computedTotalQuantity`, which is a cached sum of what the
            contents add

            up to. This is the number an insert copies onto the new group, so a
            pack meant

            as "25 polos" arrives as 25 rather than as whatever the lines happen
            to total.
        lines:
          type: array
          items:
            $ref: '#/components/schemas/Output_PreBuiltItemLine'
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Output_PreBuiltItemVariant'
        decorations:
          type: array
          items:
            $ref: '#/components/schemas/Output_PreBuiltItemDecoration'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - status
        - tags
        - computedUnitPriceExGst
        - computedTotalQuantity
        - totalQuantity
        - lines
        - variants
        - decorations
        - createdAt
        - updatedAt
    Error:
      type: object
      required:
        - error
        - message
        - status
      properties:
        error:
          type: string
          description: Stable machine-readable error code.
        message:
          type: string
        status:
          type: boolean
          const: false
      description: Every non-2xx response uses this envelope.
    Enum_PreBuiltItemStatus:
      type: string
      enum:
        - draft
        - active
        - inactive
    Output_PreBuiltItemLine:
      type: object
      properties:
        id:
          type: string
        preBuiltItemId:
          type: string
        lineType:
          $ref: '#/components/schemas/Enum_PreBuiltLineType'
        garmentCatalogueItemId:
          type:
            - string
            - 'null'
        productName:
          type:
            - string
            - 'null'
        productSku:
          type:
            - string
            - 'null'
        title:
          type:
            - string
            - 'null'
          description: JB-13's standalone charge is a TITLE with no product behind it.
        description:
          type:
            - string
            - 'null'
        quantity:
          type: number
        unitPriceExGst:
          type: number
        valueType:
          anyOf:
            - $ref: '#/components/schemas/Enum_PreBuiltLineValueType'
            - type: 'null'
          description: >-
            A discount or surcharge expressed as a RATE rather than a dollar
            amount

            (CU-86d45h8cw). Same pair, same spelling, as `QuoteLine.valueType` /

            `percentage` — the insert copies a pre-built line straight onto a
            quote line,

            so two spellings of the same two words would only be somewhere to
            drift.


            Without these a 10% discount authored on a pre-built item
            round-tripped as $0.
        percentage:
          type:
            - number
            - 'null'
        customImageUrl:
          type:
            - string
            - 'null'
        sortOrder:
          type: integer
      required:
        - id
        - preBuiltItemId
        - lineType
        - quantity
        - unitPriceExGst
        - sortOrder
    Output_PreBuiltItemVariant:
      type: object
      properties:
        id:
          type: string
        preBuiltItemLineId:
          type: string
        size:
          type:
            - string
            - 'null'
        colour:
          type:
            - string
            - 'null'
        quantity:
          type: number
        buyPrice:
          type: number
          description: Present only when the credential includes the costs.read scope.
        extraCost:
          type: number
          description: Present only when the credential includes the costs.read scope.
        markupType:
          $ref: '#/components/schemas/Enum_PreBuiltMarkupType'
        markupValue:
          type: number
        markupSource:
          $ref: '#/components/schemas/Enum_MarkupSource'
          description: >-
            Who owns the markup above — see `MarkupSource`. A pre-built item is
            inserted

            into a quote at a different quantity from the one it was built at,
            so a

            group-owned markup is exactly the kind that should re-band on the
            way in

            (CU-86d46hu37). Rows saved before this read `manual`.
        unitPriceExGst:
          type: number
        sortOrder:
          type: integer
          description: The order the operator authored, not the order the sizes sort in.
        isCustomLine:
          type: boolean
          description: >-
            QU-02's pair (CU-86d45h8cw). A CUSTOM variant is a cost attached to
            the

            garment — a courier fee, a rush charge — that rolls into its price;

            `showOnDocuments` is whether it is itemised on the customer's copy.
            Neither

            survived a pre-built save before, so a rush charge came back as an
            ordinary

            size row called nothing.
        showOnDocuments:
          type: boolean
      required:
        - id
        - preBuiltItemLineId
        - quantity
        - markupType
        - markupValue
        - markupSource
        - unitPriceExGst
        - sortOrder
        - isCustomLine
        - showOnDocuments
    Output_PreBuiltItemDecoration:
      type: object
      properties:
        id:
          type: string
        preBuiltItemId:
          type: string
        decorationItemId:
          type:
            - string
            - 'null'
        method:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        position:
          type:
            - string
            - 'null'
        quantity:
          type: number
        unitCost:
          type: number
          description: Present only when the credential includes the costs.read scope.
        setupCost:
          type: number
          description: Present only when the credential includes the costs.read scope.
        baseUnitCost:
          type:
            - number
            - 'null'
          description: Cost per unit (COGS basis, margin correctness); null -> 0.
        baseSetupCost:
          type:
            - number
            - 'null'
          description: One-off setup cost basis; null -> 0.
        includeSetupCost:
          type: boolean
        markupType:
          $ref: '#/components/schemas/Enum_PreBuiltMarkupType'
          description: >-
            How the CHARGE is derived from the cost basis (CU-86d45h8cw).
            Variants have

            always carried these; decorations did not, which is why a pre-built
            decoration

            was charged at cost with no margin. Rows written before this read
            `Flat` / `0`

            — their stored `unitCost` is already the charge and stays
            authoritative, so

            their margin reads as zero until the item is re-saved.
        markupValue:
          type: number
        markupSource:
          $ref: '#/components/schemas/Enum_MarkupSource'
          description: >-
            Who owns the markup above — see `MarkupSource`. A pre-built item is
            inserted

            into a quote at a different quantity from the one it was built at,
            so a

            group-owned markup is exactly the kind that should re-band on the
            way in

            (CU-86d46hu37). Rows saved before this read `manual`.
        notes:
          type:
            - string
            - 'null'
        widthCm:
          type:
            - number
            - 'null'
          description: >-
            The print spec, field-for-field as `QuoteGroupDecoration` carries it

            (CU-86d45h8cw). The pre-built builder opens the quote's own
            decoration

            dialog, which collects every one of these; before this they were
            collected

            and then dropped on save.


            Dimensions are CENTIMETRES and nullable — a decoration with no
            measured print

            keeps null rather than gaining a confident 0.
        lengthCm:
          type:
            - number
            - 'null'
        necklineDropCm:
          type:
            - number
            - 'null'
        screenCount:
          type:
            - integer
            - 'null'
        screenMeshGrade:
          type:
            - string
            - 'null'
        colourCount:
          type:
            - integer
            - 'null'
        colours:
          type: array
          items:
            $ref: '#/components/schemas/Output_DecorationColour'
        specialInstructions:
          type:
            - string
            - 'null'
          description: Internal shop notes — never customer-facing.
        artworkFileUrl:
          type:
            - string
            - 'null'
        separationFileUrl:
          type:
            - string
            - 'null'
        rollUp:
          type: boolean
          description: >-
            The three display answers CU-86d416yvz moved onto the decoration
            row: fold the

            unit charge into the garment price, fold the setup charge, and
            whether the row

            is drawn on customer-facing documents at all. Stored here so a
            decoration

            authored as folded stays folded through save and insert.
        rollUpSetup:
          type: boolean
        showOnDocuments:
          type: boolean
        sortOrder:
          type: integer
      required:
        - id
        - preBuiltItemId
        - quantity
        - includeSetupCost
        - markupType
        - markupValue
        - markupSource
        - colours
        - rollUp
        - rollUpSetup
        - showOnDocuments
        - sortOrder
    Enum_PreBuiltLineType:
      type: string
      enum:
        - garment
        - other
        - discount
        - surcharge
    Enum_PreBuiltLineValueType:
      type: string
      enum:
        - Flat
        - Percentage
    Enum_PreBuiltMarkupType:
      type: string
      enum:
        - percentage
        - flat
        - flat_rate
    Enum_MarkupSource:
      type: string
      description: >-
        WHO owns a markup, and therefore whether it may be re-resolved through
        its

        markup group's matrix (CU-86d46hu37).


        `group` — a markup group resolved the number, so it re-bands on every
        quantity

        or cost change, on create and on reopen alike; the sell price moves with
        it.

        `manual` — an operator typed the markup, flipped its \$/% toggle, or
        overrode

        the sell price. Never re-banded, and a cost edit back-solves to hold the
        saved

        sell fixed, which is the edit-lock that stops a live quote repricing
        itself.


        Stored `not null default 'manual'`, so every row written before this
        existed is

        operator-owned and behaves exactly as it did. A create path that means
        `group`

        must SAY `group` — relying on the default silently reintroduces the bug
        the

        enum exists to fix.
      enum:
        - group
        - manual
    Output_DecorationColour:
      type: object
      properties:
        name:
          type: string
        isBase:
          type: boolean
      required:
        - name
        - isBase
  securitySchemes:
    tenantApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Tenant credential. This is sufficient by itself.
    partnerApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Partner application client ID.
    partnerApiSecret:
      type: apiKey
      in: header
      name: X-API-Secret
      description: Partner application secret.
    partnerBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Cognito access token obtained through OAuth.

````