"/admin/shop/test_order":
    post:
        tags: [Fabricator Orders]
        operationId: createTestOrder
        summary: Create a test Big Order
        description: |
            Creates a test Big Order (and a backing Shopify order with `origin = TestData`)
            from a small dummy payload. Used by integration tests and QA flows. Only works
            with test-origin orders — not a real-customer creation path.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [email, firstName, lastName]
                        properties:
                            email: { type: string, format: email }
                            firstName: { type: string }
                            lastName: { type: string }
                            name: { type: string }
                            purpose: { type: string }
                            priority: { type: integer }
                            ipd:
                                type: integer
                                description: IPD for lens jobs.
        responses:
            "200":
                description: Created Big Order.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrder.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "422":
                description: Validation error or "The job could not be created."
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/shopify_order":
    post:
        tags: [Fabricator Orders]
        operationId: createCustomShopifyOrder
        summary: Create a Shopify order via existing Big Order
        description: |
            Creates a custom Shopify order for an existing Bigscreen account by piggy-backing
            off one of that account's existing Big Orders. Used to make a follow-up order
            (e.g. a replacement lens) without re-entering customer details.

            Requires the customer to already exist in Bigscreen via an existing Big Order —
            cannot bootstrap a brand-new customer.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [originalBigOrderId, shopifyProducts, scanRequestAction]
                        properties:
                            originalBigOrderId: { type: string }
                            shopifyProducts:
                                type: array
                                items:
                                    type: object
                                    required: [productId, variantId]
                                    properties:
                                        productId: { type: string }
                                        variantId: { type: string }
                            scanRequestAction:
                                type: string
                                enum: [DuplicateMostRecentScanRequest, CreateNewScanRequest]
                            sendEmail: { type: boolean }
                            priority: { type: integer }
                            shopifyOrderMode:
                                type: string
                                enum: [TestOrder, Direct]
                                description: Forced to `TestOrder` outside the main network.
                            ipd: { type: integer, description: Triggers an `AdminOverrideIPD` action when present. }
                            convertToBigOrder: { type: boolean }
        responses:
            "200":
                description: Created Shopify order, optional Big Order, plus non-fatal errors.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                shopifyOrder: { $ref: "../components/schemas/ShopifyOrder.yaml" }
                                bigOrder: { $ref: "../components/schemas/BigOrder.yaml" }
                                errors:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            message: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big order, account, customer, product, or variant not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Validation error.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/shopify_order_2":
    post:
        tags: [Fabricator Orders]
        operationId: createCustomShopifyOrder2
        summary: Create a Shopify order by Bigscreen account
        description: |
            Creates a custom Shopify order for a Bigscreen account by id, without requiring
            an existing Big Order to piggy-back off. Supports per-variant quantities and
            presentment currency. Prefer this over `/shopify_order` for new integrations.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [ownerBigscreenAccountId, shopifyVariants, scanRequestAction]
                        properties:
                            ownerBigscreenAccountId: { type: string }
                            shopifyVariants:
                                type: array
                                items:
                                    oneOf:
                                        - type: string
                                          description: Bare variant id.
                                        - type: object
                                          required: [id]
                                          properties:
                                              id: { type: string }
                                              quantity: { type: integer, minimum: 1 }
                            scanRequestAction:
                                type: string
                                enum: [DuplicateMostRecentScanRequest, CreateNewScanRequest]
                            sendEmail: { type: boolean }
                            priority: { type: integer }
                            shopifyOrderMode:
                                type: string
                                enum: [TestOrder, Direct]
                            presentmentCurrency: { type: string, description: "e.g. `USD`." }
        responses:
            "200":
                description: Created Shopify order, optional Big Order, plus non-fatal errors.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                shopifyOrder: { $ref: "../components/schemas/ShopifyOrder.yaml" }
                                bigOrder: { $ref: "../components/schemas/BigOrder.yaml" }
                                errors:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            message: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Account or customer not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Validation error.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/shopify_orders":
    get:
        tags: [Fabricator Orders]
        operationId: getShopifyOrders
        summary: List Shopify orders (paired with Big Orders)
        description: |
            Lists Shopify orders with search, status filtering, and cursor-based pagination.
            Each result is paired with its Big Order if one exists.

            **Note:** if `SHOPIFY_FACTORY_API_ACCESS_TOKEN` is empty (dev with no Shopify
            creds), returns generated dummy orders instead of hitting Shopify.
        parameters:
            - in: query
              name: limit
              schema: { type: integer, default: 25 }
            - in: query
              name: cursor
              schema: { type: string }
            - in: query
              name: search
              schema: { type: string }
              description: Search by order name.
            - in: query
              name: status
              schema:
                  type: string
                  enum: [Open, Closed, Cancelled, Archived]
            - in: query
              name: fulfillment_status
              schema:
                  type: string
                  enum: [Fulfilled, Partial, Unfulfilled, Any]
            - in: query
              name: cache
              schema: { type: integer }
              description: If `1`, return cached orders instead of hitting Shopify.
        responses:
            "200":
                description: Paginated Shopify orders + Big Orders.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                orders:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            shopifyOrder: { $ref: "../components/schemas/ShopifyOrder.yaml" }
                                            bigOrder: { $ref: "../components/schemas/BigOrder.yaml" }
                                totalOrdersCount: { type: integer }
                                prevCursor: { type: string }
                                nextCursor: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "422":
                description: Invalid `status` / `fulfillment_status`.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/shopify_order/{shopifyOrderId}":
    parameters:
        - in: path
          name: shopifyOrderId
          required: true
          schema: { type: string }
          description: Shopify's numeric order id.
    get:
        tags: [Fabricator Orders]
        operationId: getShopifyOrder
        summary: Fetch a Shopify order
        description: Returns a single Shopify order. Proxies to the Shopify Admin API; no cache.
        responses:
            "200":
                description: Shopify order.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/ShopifyOrder.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Shopify order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank `shopifyOrderId`.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]
    delete:
        tags: [Fabricator Orders]
        operationId: deleteShopifyTestOrder
        summary: Delete a test Shopify order
        description: Deletes a Shopify order. Only works for orders with `origin = TestData`. Throws on any non-test order.
        responses:
            "200":
                description: '"OK".'
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/shopify_order_cache/{shopifyOrderId}":
    parameters:
        - in: path
          name: shopifyOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getCachedShopifyOrder
        summary: Cached copy of a Shopify order
        description: |
            Reads the cached Shopify order, skipping the live Shopify API call. Stricter
            auth than the uncached variant. Use for debugging cache vs. live shape;
            otherwise prefer `GET /admin/shop/shopify_order/:shopifyOrderId`.
        responses:
            "200":
                description: Cached Shopify order (may be stale).
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/ShopifyOrder.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Cached order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/shopify_order/{shopifyOrderId}/fulfillments":
    parameters:
        - in: path
          name: shopifyOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getShopifyOrderFulfillments
        summary: Shopify fulfillments
        description: Returns Shopify fulfillments for an order — the concrete shipments Shopify has recorded.
        responses:
            "200":
                description: Array of Shopify fulfillment objects.
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: object
                                description: Shopify fulfillment record — see Shopify's spec for the full shape.
                                properties:
                                    id: { type: integer, format: int64 }
                                    order_id: { type: integer, format: int64 }
                                    status: { type: string, description: "e.g. `success`, `cancelled`, `failure`." }
                                    tracking_company: { type: string }
                                    tracking_number: { type: string }
                                    tracking_url: { type: string, format: uri }
                                    created_at: { type: string, format: date-time }
                                    updated_at: { type: string, format: date-time }
                                    shipment_status: { type: [string, "null"] }
                                    line_items:
                                        type: array
                                        items:
                                            type: object
                                            additionalProperties: true
                                additionalProperties: true
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Fulfillments not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/shopify_order/{shopifyOrderId}/fulfillment_orders":
    parameters:
        - in: path
          name: shopifyOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getShopifyOrderFulfillmentOrders
        summary: Shopify fulfillment orders
        description: Returns Shopify fulfillment orders — the scheduling records that precede fulfillments.
        responses:
            "200":
                description: Array of Shopify fulfillment-order records.
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: object
                                description: Shopify fulfillment-order record — see Shopify's spec for the full shape.
                                properties:
                                    id: { type: integer, format: int64 }
                                    order_id: { type: integer, format: int64 }
                                    shop_id: { type: integer, format: int64 }
                                    status: { type: string, description: "e.g. `open`, `in_progress`, `closed`." }
                                    request_status: { type: string }
                                    supported_actions:
                                        type: array
                                        items: { type: string }
                                    line_items:
                                        type: array
                                        items:
                                            type: object
                                            additionalProperties: true
                                    destination:
                                        type: object
                                        additionalProperties: true
                                additionalProperties: true
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/shopify_order/{shopifyOrderId}/line_item":
    parameters:
        - in: path
          name: shopifyOrderId
          required: true
          schema: { type: string }
    post:
        tags: [Fabricator Orders]
        operationId: createShopifyOrderLineItem
        summary: Add a line item to a Shopify order
        description: |
            Adds a line item to an existing Shopify order. **Note:** the current handler
            has known issues — fields appear to be read but ignored in favor of hardcoded
            values. Verify in code before relying on this endpoint.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [shopifyProductVariantId, quantity]
                        properties:
                            shopifyProductVariantId:
                                oneOf:
                                    - type: string
                                    - type: number
                            quantity: { type: integer }
        responses:
            "200":
                description: Updated Shopify order.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/ShopifyOrder.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Order or variant not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/shopify_order/{shopifyOrderId}/line_item/{shopifyLineItemId}":
    parameters:
        - in: path
          name: shopifyOrderId
          required: true
          schema: { type: string }
        - in: path
          name: shopifyLineItemId
          required: true
          schema: { type: string }
    delete:
        tags: [Fabricator Orders]
        operationId: removeShopifyOrderLineItem
        summary: Remove a line item from a Shopify order
        description: Removes a line item from a Shopify order. Same caveat as the POST variant — handler may use hardcoded ids.
        responses:
            "200":
                description: Updated Shopify order.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/ShopifyOrder.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Order or line item not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/shopify_order/{shopifyOrderId}/risks":
    parameters:
        - in: path
          name: shopifyOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getShopifyOrderRisks
        summary: Shopify fraud-risk assessments
        description: Returns Shopify fraud-risk assessments for an order.
        responses:
            "200":
                description: Array of Shopify order-risk records.
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: object
                                description: Shopify order-risk record — see Shopify's spec for the full shape.
                                properties:
                                    id: { type: integer, format: int64 }
                                    order_id: { type: integer, format: int64 }
                                    cause_cancel: { type: boolean }
                                    display: { type: boolean }
                                    message: { type: string }
                                    recommendation:
                                        type: string
                                        description: "`accept`, `investigate`, or `cancel`."
                                    score: { type: string, description: Numeric string between 0 and 1. }
                                    source: { type: string, description: "e.g. `Shopify`, `External`." }
                                additionalProperties: true
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/webhooks/install":
    post:
        tags: [Fabricator Orders]
        operationId: installShopifyWebhooks
        summary: Install Shopify webhooks
        description: Installs the webhooks admin_api expects Shopify to call (order created, updated, paid, fulfilled, etc.).
        responses:
            "200":
                description: Install summary.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                installed:
                                    type: array
                                    items: { type: string }
                                    description: Topics installed (e.g. `orders/create`, `orders/paid`).
                                skipped:
                                    type: array
                                    items: { type: string }
                                errors:
                                    type: array
                                    items: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/webhooks/uninstall":
    post:
        tags: [Fabricator Orders]
        operationId: uninstallShopifyWebhooks
        summary: Uninstall Shopify webhooks
        description: Removes all webhooks admin_api has registered with Shopify.
        responses:
            "200":
                description: Uninstall summary.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                removed:
                                    type: array
                                    items: { type: string }
                                errors:
                                    type: array
                                    items: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/webhooks":
    get:
        tags: [Fabricator Orders]
        operationId: getShopifyWebhookResults
        summary: List registered Shopify webhooks
        description: Returns the webhooks Shopify has recorded as registered for this app.
        responses:
            "200":
                description: Array of Shopify webhook records.
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: object
                                properties:
                                    id: { type: integer, format: int64 }
                                    topic:
                                        type: string
                                        description: "e.g. `orders/create`, `orders/paid`."
                                    address: { type: string, format: uri }
                                    format: { type: string, example: "json" }
                                    api_version: { type: string }
                                    created_at: { type: string, format: date-time }
                                    updated_at: { type: string, format: date-time }
                                    fields:
                                        type: array
                                        items: { type: string }
                                    metafield_namespaces:
                                        type: array
                                        items: { type: string }
                                additionalProperties: true
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin, FabricatorAdmin]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/shopify_orders/pair":
    post:
        tags: [Fabricator Orders]
        operationId: createBeyondLensPair
        summary: Create a Beyond + lens-insert order pair
        description: |
            Creates a pair linking a Beyond-only Shopify order to a separate Lens-insert-only
            order for the same customer. Fabricator pipeline then treats the two as a
            single shipment. Search is by **order name**, not id.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [beyondShopifyOrderName, lensOnlyShopifyOrderName]
                        properties:
                            beyondShopifyOrderName: { type: string }
                            lensOnlyShopifyOrderName: { type: string }
        responses:
            "200":
                description: Created pair record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BeyondLensOrderPair.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Beyond or lens order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank names, customer mismatch, or invalid line-item composition on either side.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin, FabricatorAdmin]
        x-scopes: ["orders:write", "admin:all"]
    get:
        tags: [Fabricator Orders]
        operationId: findBeyondLensPair
        summary: Find a pair by Beyond order name
        parameters:
            - in: query
              name: beyondShopifyOrderName
              required: true
              schema: { type: string }
        responses:
            "200":
                description: Pair record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BeyondLensOrderPair.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Beyond order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank `beyondShopifyOrderName`.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin, FabricatorAdmin]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/shopify_orders/pairs":
    get:
        tags: [Fabricator Orders]
        operationId: getAllBeyondLensPairs
        summary: List all order pairs
        responses:
            "200":
                description: Array of pair records.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/BeyondLensOrderPair.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin, FabricatorAdmin]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/shopify_orders/pair/{pairId}":
    parameters:
        - in: path
          name: pairId
          required: true
          schema: { type: string }
    delete:
        tags: [Fabricator Orders]
        operationId: deleteBeyondLensPair
        summary: Remove an order pair
        description: Removes a pair record. Does not delete the underlying Shopify orders.
        responses:
            "200":
                description: '"OK".'
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Pair not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank `pairId`.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin, FabricatorAdmin]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/orders":
    get:
        tags: [Fabricator Orders]
        operationId: getBigOrders
        summary: List Big Orders
        description: Lists Big Orders with filtering and pagination.
        parameters:
            - in: query
              name: offset
              schema: { type: integer }
            - in: query
              name: limit
              schema: { type: integer }
            - in: query
              name: nextAction
              schema: { type: string }
              description: Filter by the checklist's next-action value.
            - in: query
              name: bigscreenAccountId
              schema: { type: string }
            - in: query
              name: shopifyOrderId
              schema: { type: string }
            - in: query
              name: exactShopifyProductIds
              schema: { type: string }
              description: CSV — orders that contain all of these product ids.
            - in: query
              name: exactShopifyVariantIds
              schema: { type: string }
              description: CSV — orders that contain all of these variant ids.
        responses:
            "200":
                description: Big Orders page.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [items, count, totalCount]
                            properties:
                                items:
                                    type: array
                                    items: { $ref: "../components/schemas/BigOrder.yaml" }
                                count: { type: integer }
                                totalCount: { type: integer }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "422":
                description: Query-param validation error.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/order":
    post:
        tags: [Fabricator Orders]
        operationId: createBigOrder
        summary: Create a Big Order from a Shopify order
        description: |
            Idempotent by default — if a Big Order already exists for the Shopify order,
            returns it unchanged. With `audiostrap=1`, permits creating a second Big
            Order for the same Shopify order to handle a separate audio-strap line item.
        parameters:
            - in: query
              name: audiostrap
              schema: { type: string, enum: ["1"] }
              description: When set, allow a second Big Order for an audio-strap add-on.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [shopifyOrderId]
                        properties:
                            shopifyOrderId:
                                oneOf:
                                    - type: string
                                    - type: number
                            scanRequestAction:
                                type: string
                                enum: [DuplicateMostRecentScanRequest, CreateNewScanRequest]
        responses:
            "200":
                description: Created (or existing) Big Order.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrder.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "422":
                description: Validation, fulfillability, or duplicate-audio-strap error.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/order/{bigOrderId}":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getBigOrder
        summary: Fetch a Big Order
        responses:
            "200":
                description: Big Order.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrder.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big Order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]
    put:
        tags: [Fabricator Orders]
        operationId: updateBigOrderAdmin
        summary: Run a Big Order action
        description: |
            Runs a Big Order action — the write side of the checklist state machine.
            Acquires a distributed lock on the Big Order for the action's duration.
            Response shape varies by action — typically a `ScanRequest`, `Job`,
            `ScanRequestEmailResponse`, or the updated `BigOrder`. Dispatch on `action`
            client-side to know which shape to expect. `silentEmail=true` suppresses
            customer-facing email for actions that would normally send one.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [action]
                        properties:
                            action: { type: string, description: A `BigOrderAction` enum value. }
                            priority: { type: integer }
                            ipd: { type: integer, minimum: 55, maximum: 75 }
                            scanRequestId: { type: string }
                            overrideJobId: { type: string }
                            shipmentHold: { type: boolean }
                            shippingServiceLevel: { type: string }
                            silentEmail: { type: boolean }
        responses:
            "200":
                description: |
                    Action result. Shape varies by `action`:
                    - `SendScanRequest` / scan-related actions → a `ScanRequest`.
                    - `CreateJob` → a `Job`.
                    - email-sending actions → `{ scanRequest, emailResponse }`.
                    - everything else → the updated `BigOrder`.

                    The default schema below is `BigOrder`; cast the response in your client based on the `action` you sent.
                content:
                    application/json:
                        schema:
                            oneOf:
                                - $ref: "../components/schemas/BigOrder.yaml"
                                - $ref: "../components/schemas/ScanRequest.yaml"
                                - $ref: "../components/schemas/Job.yaml"
                                - type: object
                                  description: Email-action shape.
                                  properties:
                                      scanRequest: { $ref: "../components/schemas/ScanRequest.yaml" }
                                      emailResponse:
                                          type: object
                                          additionalProperties: true
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big Order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Validation error or invalid action for current state.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:write", "admin:all"]
    delete:
        tags: [Fabricator Orders]
        operationId: deleteBigOrder
        summary: Hard-delete a Big Order
        description: Hard-deletes a Big Order. No soft-delete or recovery. Does not delete the underlying Shopify order.
        responses:
            "200":
                description: '"OK".'
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big Order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin, FabricatorAdmin]
        x-scopes: ["orders:write", "admin:all"]

"/admin/shop/order/{bigOrderId}/scan_requests":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getBigOrderScanRequests
        summary: Scan requests for a Big Order
        description: Lists scan requests associated with a Big Order's account + order combo.
        responses:
            "200":
                description: Scan requests page.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [items, count, totalCount]
                            properties:
                                items: { type: array, items: { $ref: "../components/schemas/ScanRequest.yaml" } }
                                count: { type: integer }
                                totalCount: { type: integer }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big Order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/order/{bigOrderId}/shipping_summary":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getBigOrderShippingSummary
        summary: Shipping summary for a Big Order
        description: |
            Computes the shipping summary — line-item-to-shipment-group mapping, current
            shipment per group, and available inventory slots for groups that haven't
            shipped yet. This is what Arda renders on the Big Order detail page.
        responses:
            "200":
                description: Shipping summary.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrderShippingSummary.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big Order or its Shopify order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/order/{bigOrderId}/shipments":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getBigOrderShipments
        summary: Shipments for a Big Order
        description: Lists every shipment created for a Big Order, across all shipment groups.
        responses:
            "200":
                description: Shipments page.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [items, count]
                            properties:
                                items: { type: array, items: { $ref: "../components/schemas/BigShipment.yaml" } }
                                count: { type: integer }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big Order or shipment not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/account/{bigscreenAccountId}/orders":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: getBigOrdersForAccount
        summary: Big Orders for an account
        description: Lists every Big Order belonging to the supplied Bigscreen account.
        responses:
            "200":
                description: Big Orders page.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [items, count, totalCount]
                            properties:
                                items: { type: array, items: { $ref: "../components/schemas/BigOrder.yaml" } }
                                count: { type: integer }
                                totalCount: { type: integer }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Account not found (the message is "The big order could not be found.", a known misleading text).
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/order/{bigOrderId}/checklist":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: runBigOrderChecklistOnce
        summary: Run the checklist (read-only)
        description: |
            Runs the Big Order checklist to compute the next action without mutating the
            order. Idempotent but does real work (Shopify lookups, inventory queries).
            **Note:** a 422 with `success: false` is not an API failure — it means the
            checklist ran fine but the order isn't ready to advance.
        responses:
            "200":
                description: Checklist result.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrderChecklistResult.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big Order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: "Skipped (already shipped/cancelled), missing account, or `success: false` checklist result."
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrderChecklistResult.yaml" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/order/{bigOrderId}/sync_line_items":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: syncBigOrderLineItems
        summary: Re-read line items from Shopify
        description: Re-reads line items from Shopify and persists any changes to the Big Order.
        responses:
            "200":
                description: Sync result — diff summary of what changed.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrderSyncResult.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/order/{bigOrderId}/sync":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Fabricator Orders]
        operationId: syncBigOrder
        summary: Full sync of a single Big Order
        description: |
            Pulls fresh order data from Shopify, updates line items, refreshes line-item
            types and snapshots, repairs shipment groups if needed, and updates snapshots
            for Arda-auto-added items. Uses a Redis distributed lock to prevent concurrent
            syncs for the same order. Will not sync shipped or cancelled orders.
        responses:
            "200":
                description: Change summary, optionally including the updated `BigOrder`.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrderSyncResult.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Big Order or Shopify order not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "422":
                description: Skipped (already shipped/cancelled) or blank id.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/orders/report":
    get:
        tags: [Fabricator Orders]
        operationId: runBigOrdersReport
        summary: Big Orders report
        description: |
            Runs the Big Orders report — totals plus per-state breakdown across
            every Big Order. Posts a Discord summary as a side effect; returns the
            same payload to the caller.
        responses:
            "200":
                description: Report data.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                totalBigOrders: { type: integer }
                                totalInProgress: { type: integer }
                                totalReadyToShip: { type: integer }
                                totalShipped: { type: integer }
                                bigOrdersByState:
                                    type: object
                                    additionalProperties: { type: integer }
                                    description: Keyed by `BigOrderState` enum string name (e.g. `AwaitingScanRequest`).
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Fabricator, FabricatorReadOnly]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/orders/report2":
    get:
        tags: [Fabricator Orders]
        operationId: runBigOrdersReport2
        summary: Big Orders report (v2)
        description: V2 of the Big Orders report. Different shape than v1; pick whichever matches the UI you're building.
        responses:
            "200":
                description: Report data (v2 shape).
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                generatedAt: { type: string, format: date-time }
                                totalBigOrders: { type: integer }
                                problemBigOrders:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            bigOrderId: { type: string }
                                            shopifyOrderName: { type: string }
                                            state: { type: string }
                                            stuckSinceDays: { type: integer }
                                stateBreakdown:
                                    type: object
                                    additionalProperties: { type: integer }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Fabricator, FabricatorReadOnly]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/orders/checklist":
    get:
        tags: [Fabricator Orders]
        operationId: runBigOrderChecklistAll
        summary: Run checklist over all Big Orders
        description: |
            Runs the checklist worker over every Big Order. Async in production
            (returns `"OK"` immediately); synchronous in test envs. Watch
            `/admin/workers/status` for completion.
        responses:
            "200":
                description: '"OK" — fire-and-forget in production.'
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Fabricator, FabricatorReadOnly]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/orders/data":
    get:
        tags: [Fabricator Orders]
        operationId: getBigOrdersData
        summary: Big Orders data export
        responses:
            "200":
                description: Bulk Big Orders data export.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                generatedAt: { type: string, format: date-time }
                                totalBigOrders: { type: integer }
                                bigOrders:
                                    type: array
                                    items: { $ref: "../components/schemas/BigOrder.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Fabricator, FabricatorReadOnly]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/orders/sync":
    get:
        tags: [Fabricator Orders]
        operationId: syncAllBigOrders
        summary: Async sync of all Big Orders (worker)
        description: Enqueues an async `orders_sync` worker. Fire-and-forget; observe via `/admin/workers/status`.
        responses:
            "200":
                description: '"OK".'
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin, FabricatorReadOnly]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/orders/sync2":
    get:
        tags: [Fabricator Orders]
        operationId: syncBigOrders2
        summary: Alternate Big Orders sync
        description: Alternate sync path. Also used by the Shopify webhook handler.
        responses:
            "200":
                description: Aggregate sync summary.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                ordersProcessed: { type: integer }
                                ordersChanged: { type: integer }
                                durationMs: { type: integer }
                                errors:
                                    type: array
                                    items: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin, FabricatorReadOnly]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/orders/sync3":
    get:
        tags: [Fabricator Orders]
        operationId: syncBigOrders3
        summary: Big Orders sync (v3)
        description: Third sync variant — historical separation from sync2. Prefer sync3 for new work unless you have a reason to pin to an older path.
        responses:
            "200":
                description: Aggregate sync summary (v3 shape).
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                ordersProcessed: { type: integer }
                                ordersChanged: { type: integer }
                                durationMs: { type: integer }
                                errors:
                                    type: array
                                    items: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin, FabricatorReadOnly]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/orders/sync_all_big_orders":
    get:
        tags: [Fabricator Orders]
        operationId: syncAllBigOrdersAndRepair
        summary: Resync all Big Orders, repair shipment groups
        description: |
            Resyncs all Big Orders and repairs shipment groups. Async in production,
            synchronous in test envs.
        responses:
            "200":
                description: '"OK".'
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin, FabricatorReadOnly]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/sync/{shopifyOrderId}":
    parameters:
        - in: path
          name: shopifyOrderId
          required: true
          schema: { type: string }
          description: |
              The trailing segment is **optional** in the registered route
              (`/admin/shop/sync{/:shopifyOrderId}`) — but the handler is a stub either way.
    get:
        tags: [Fabricator Orders]
        operationId: syncShopifyOrderPlaceholder
        summary: Placeholder (not implemented)
        description: |
            Placeholder for a future "sync a specific Shopify order into its Big Order"
            endpoint. Currently always returns `400 "Not implemented."` — calling this
            does nothing useful today. Use `GET /admin/shop/order/{bigOrderId}/sync`
            for per-order sync instead.
        responses:
            "400":
                description: '"Not implemented." (plain text).'
                content:
                    text/plain:
                        schema: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/products":
    get:
        tags: [Fabricator Orders]
        operationId: getShopifyProducts
        summary: List Shopify products
        description: Lists Shopify products directly from Shopify (not cached).
        parameters:
            - in: query
              name: limit
              schema: { type: integer, default: 50 }
            - in: query
              name: offset
              schema: { type: integer, default: 0 }
        responses:
            "200":
                description: Array of Shopify products.
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: object
                                description: Shopify product — see Shopify's spec for the full shape.
                                properties:
                                    id: { type: integer, format: int64 }
                                    title: { type: string }
                                    handle: { type: string }
                                    body_html: { type: string }
                                    vendor: { type: string }
                                    product_type: { type: string }
                                    status: { type: string, description: "`active`, `archived`, `draft`." }
                                    tags: { type: string }
                                    variants:
                                        type: array
                                        items:
                                            type: object
                                            additionalProperties: true
                                    images:
                                        type: array
                                        items:
                                            type: object
                                            additionalProperties: true
                                    created_at: { type: string, format: date-time }
                                    updated_at: { type: string, format: date-time }
                                    published_at: { type: string, format: date-time }
                                additionalProperties: true
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "422":
                description: Query validation error.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/products_snapshot":
    get:
        tags: [Fabricator Orders]
        operationId: getShopifyProductsSnapshot
        summary: In-memory Shopify product snapshot
        description: |
            Returns the in-memory snapshot of Shopify products (variant map). Fast — no API
            call — but potentially stale. Refreshed at process start and on certain sync events.
        responses:
            "200":
                description: |
                    `ShopifyData.ShopifyProductVariantMap` — keyed by Shopify variant id, value
                    is the variant payload plus a denormalized parent product reference.
                content:
                    application/json:
                        schema:
                            type: object
                            description: Variant id → variant record map.
                            additionalProperties:
                                type: object
                                properties:
                                    id: { type: integer, format: int64 }
                                    product_id: { type: integer, format: int64 }
                                    title: { type: string }
                                    sku: { type: string }
                                    price: { type: string }
                                    inventory_quantity: { type: integer }
                                    weight: { type: number }
                                    weight_unit: { type: string }
                                    barcode: { type: string }
                                    option1: { type: string }
                                    option2: { type: string }
                                    option3: { type: string }
                                    requires_shipping: { type: boolean }
                                additionalProperties: true
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:read", "admin:all"]

"/admin/shop/test/getBeyondPackageInventoryCode":
    post:
        tags: [Fabricator Orders]
        operationId: testGetBeyondPackageInventoryCode
        summary: Compute Beyond package inventory code
        description: |
            Computes the Beyond package inventory code for a given product-type combo.
            Thin wrapper around `ShippingAdminApi.getBeyondPackageInventoryCode`; exposed
            for QA and factory-tool debugging.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [beyondProductType, shellProductType]
                        properties:
                            beyondProductType: { type: string }
                            shellProductType: { type: string }
                            cushionProductType: { type: string }
                            hasAccessories: { type: boolean }
                            hasLenses: { type: boolean }
        responses:
            "200":
                description: Inventory-code computation result.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                inventoryCode:
                                    type: string
                                    description: Computed package inventory code.
                                packageType:
                                    type: string
                                    description: Resolved `BigShipmentPackageType`.
                                weight: { type: number }
                                dimensions:
                                    type: object
                                    properties:
                                        length: { type: number }
                                        width: { type: number }
                                        height: { type: number }
                                breakdown:
                                    type: object
                                    additionalProperties: true
                                    description: Per-product-type contribution to the final code.
            "400":
                description: '"beyondProductType and shellProductType are required".'
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Fabricator]
        x-scopes: ["orders:write", "admin:all"]
