{
  "openapi": "3.1.0",
  "info": {
    "title": "Buceye Commerce API",
    "version": "0.1.0",
    "description": "Machine-readable APIs for WholesaleFromUSA and HomeServiceBooking. Development authentication only; SMS OTP is not implemented."
  },
  "servers": [
    {
      "url": "https://wholesalefromusa.com"
    },
    {
      "url": "https://homeservicebooking.com"
    }
  ],
  "security": [
    {
      "BearerDev": []
    }
  ],
  "tags": [
    {
      "name": "Wholesale"
    },
    {
      "name": "HomeServiceBooking"
    },
    {
      "name": "Platform"
    }
  ],
  "paths": {
    "/healthz": {
      "get": {
        "security": [],
        "tags": [
          "Platform"
        ],
        "summary": "Check service health",
        "responses": {
          "200": {
            "description": "Healthy service",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/api": {
      "get": {
        "security": [],
        "tags": [
          "Platform"
        ],
        "summary": "List platform capabilities",
        "responses": {
          "200": {
            "description": "Capability index"
          }
        }
      }
    },
    "/api/v1/wholesale/products": {
      "get": {
        "security": [],
        "tags": [
          "Wholesale"
        ],
        "summary": "Search products",
        "parameters": [
          {
            "$ref": "#/components/parameters/Query"
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Product results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductSearchResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Create product",
        "requestBody": {
          "$ref": "#/components/requestBodies/ProductBody"
        },
        "responses": {
          "201": {
            "description": "Product created"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/wholesale/products/{id}": {
      "get": {
        "security": [],
        "tags": [
          "Wholesale"
        ],
        "summary": "Retrieve product",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Product"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Update product (owner organization only, or dev token)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "sku": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "brand": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Product image URL"
                  },
                  "specifications": {
                    "type": "object"
                  },
                  "availability": {
                    "type": "object"
                  }
                },
                "description": "Only supplied fields are updated. Vendors may only edit products in their own organization."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Product updated"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          },
          "403": {
            "description": "Not your organization's product"
          },
          "404": {
            "description": "Product not found"
          }
        },
        "security": [
          {
            "BearerDev": []
          }
        ]
      }
    },
    "/api/v1/wholesale/products/{id}/offers": {
      "get": {
        "security": [],
        "tags": [
          "Wholesale"
        ],
        "summary": "Retrieve product offers",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Offers"
          }
        }
      }
    },
    "/api/v1/wholesale/offers/{id}": {
      "get": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Get offer with computed buyer prices",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Offer"
          },
          "404": {
            "description": "Not found"
          }
        }
      },
      "patch": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Update offer net/tiers/benchmark/status (owner only; prices recomputed)",
        "security": [
          {
            "BearerDev": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "manufacturer_net": {
                    "type": "number",
                    "description": "Amount the manufacturer keeps. Buyer prices are computed server-side; never send them."
                  },
                  "benchmark": {
                    "type": "object",
                    "properties": {
                      "price": {
                        "type": "number"
                      },
                      "source": {
                        "type": "string"
                      },
                      "observed_at": {
                        "type": "string"
                      }
                    },
                    "description": "Competitor benchmark price. Listing is rejected when net cannot beat it."
                  },
                  "tiers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "min_qty": {
                          "type": "integer"
                        },
                        "net": {
                          "type": "number"
                        }
                      }
                    }
                  },
                  "fulfillment": {
                    "type": "string",
                    "enum": [
                      "supplier_direct",
                      "platform"
                    ],
                    "default": "supplier_direct"
                  },
                  "external_url": {
                    "type": "string",
                    "description": "Supplier checkout URL for supplier_direct fulfillment"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "live",
                      "paused"
                    ],
                    "default": "live"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          },
          "403": {
            "description": "Not your offer"
          },
          "404": {
            "description": "Not found"
          }
        }
      },
      "delete": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Delist offer (owner only)",
        "security": [
          {
            "BearerDev": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          },
          "403": {
            "description": "Not your offer"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/v1/wholesale/suppliers": {
      "get": {
        "security": [],
        "tags": [
          "Wholesale"
        ],
        "summary": "Search suppliers",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Supplier results"
          }
        }
      },
      "post": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Create supplier profile",
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "201": {
            "description": "Supplier created"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/wholesale/suppliers/{id}": {
      "get": {
        "security": [],
        "tags": [
          "Wholesale"
        ],
        "summary": "Retrieve supplier",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Supplier"
          }
        }
      },
      "patch": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Update supplier profile",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "200": {
            "description": "Updated supplier"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/wholesale/listings": {
      "post": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Create supplier listing",
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "201": {
            "description": "Listing created"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/wholesale/listings/{id}": {
      "patch": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Update supplier listing",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "200": {
            "description": "Updated listing"
          }
        }
      }
    },
    "/api/v1/wholesale/listings/{id}/inventory": {
      "patch": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Update listing inventory",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/InventoryBody"
        },
        "responses": {
          "200": {
            "description": "Updated inventory"
          }
        }
      }
    },
    "/api/v1/wholesale/pricing-rules": {
      "post": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Create pricing rule",
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "201": {
            "description": "Pricing rule created"
          }
        }
      }
    },
    "/api/v1/wholesale/buyers/profile": {
      "post": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Create or update buyer profile",
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "200": {
            "description": "Buyer profile"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/wholesale/orders": {
      "post": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Create order from instant offer",
        "description": "Requires an active instant offer and a positive quantity. Use Idempotency-Key.",
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "201": {
            "description": "Order created in pending_confirmation"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/wholesale/orders/{id}": {
      "get": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Retrieve order",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Order and allowed states"
          }
        }
      }
    },
    "/api/v1/wholesale/orders/{id}/status": {
      "patch": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Update order fulfillment status",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/StatusBody"
        },
        "responses": {
          "200": {
            "description": "Updated order"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/home-services/services": {
      "get": {
        "security": [],
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "List service categories",
        "responses": {
          "200": {
            "description": "Service categories"
          }
        }
      }
    },
    "/api/v1/home-services/services/{slug}": {
      "get": {
        "security": [],
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Retrieve service category",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service category"
          }
        }
      }
    },
    "/api/v1/home-services/providers": {
      "get": {
        "security": [],
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Search providers",
        "parameters": [
          {
            "name": "service",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Provider results"
          }
        }
      },
      "post": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Create provider profile",
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "201": {
            "description": "Provider created"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/home-services/providers/{id}": {
      "get": {
        "security": [],
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Retrieve provider",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Provider and capabilities"
          }
        }
      },
      "patch": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Update provider profile",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "200": {
            "description": "Updated provider"
          }
        }
      }
    },
    "/api/v1/home-services/providers/{id}/availability": {
      "get": {
        "security": [],
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Check provider availability",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Availability"
          }
        }
      }
    },
    "/api/v1/home-services/requests": {
      "post": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Create service request",
        "description": "Requires service_slug and zip. Use Idempotency-Key.",
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "201": {
            "description": "Request created"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/home-services/requests/{id}": {
      "get": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Retrieve service request",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Request and allowed states"
          }
        }
      }
    },
    "/api/v1/home-services/requests/{id}/quotes": {
      "post": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Submit provider quote",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "201": {
            "description": "Quote created"
          }
        }
      }
    },
    "/api/v1/home-services/quotes/{id}": {
      "get": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Retrieve provider quote",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Quote"
          }
        }
      }
    },
    "/api/v1/home-services/quotes/{id}/accept": {
      "post": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Accept provider quote",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "200": {
            "description": "Accepted quote"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/home-services/bookings": {
      "post": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Create booking",
        "description": "Requires provider instant_booking capability. Use Idempotency-Key.",
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonBody"
        },
        "responses": {
          "201": {
            "description": "Booking created"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/home-services/bookings/{id}": {
      "get": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Retrieve booking",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Booking and allowed states"
          }
        }
      }
    },
    "/api/v1/home-services/requests/{id}/status": {
      "patch": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Update service request status",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/StatusBody"
        },
        "responses": {
          "200": {
            "description": "Updated request"
          }
        }
      }
    },
    "/api/v1/home-services/bookings/{id}/status": {
      "patch": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Update booking status",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/StatusBody"
        },
        "responses": {
          "200": {
            "description": "Updated booking"
          }
        }
      }
    },
    "/api/v1/home-services/jobs/{id}": {
      "get": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Retrieve job status",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Job status and allowed states"
          }
        }
      }
    },
    "/api/v1/home-services/jobs/{id}/status": {
      "patch": {
        "tags": [
          "HomeServiceBooking"
        ],
        "summary": "Accept or update job status",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/StatusBody"
        },
        "responses": {
          "200": {
            "description": "Updated job"
          }
        }
      }
    },
    "/api/v1/auth/vendor/register": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Register vendor",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Account email"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Vendor register successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object"
                    },
                    "organization": {
                      "type": "object",
                      "nullable": true
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/auth/vendor/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Login vendor",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Account email"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vendor login successful; returns a sess_ bearer token valid 7 days",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object"
                    },
                    "organization": {
                      "type": "object",
                      "nullable": true
                    },
                    "token": {
                      "type": "string",
                      "description": "Bearer session token (sess_...), send as Authorization: Bearer <token>"
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/auth/customer/register": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Register customer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone",
                  "password"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "description": "Account phone"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Customer register successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object"
                    },
                    "organization": {
                      "type": "object",
                      "nullable": true
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/auth/customer/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Login customer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone",
                  "password"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "description": "Account phone"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Customer login successful; returns a sess_ bearer token valid 7 days",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object"
                    },
                    "organization": {
                      "type": "object",
                      "nullable": true
                    },
                    "token": {
                      "type": "string",
                      "description": "Bearer session token (sess_...), send as Authorization: Bearer <token>"
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          }
        }
      }
    },
    "/api/v1/wholesale/offers": {
      "get": {
        "tags": [
          "Wholesale"
        ],
        "summary": "List offers with computed buyer prices",
        "parameters": [
          {
            "name": "product_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "supplier_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Offers with price_regular / price_patriot computed server-side"
          }
        }
      },
      "post": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Create offer (vendor session token; manufacturer sets net only)",
        "security": [
          {
            "BearerDev": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "product_id": {
                    "type": "string"
                  },
                  "manufacturer_net": {
                    "type": "number",
                    "description": "Amount the manufacturer keeps. Buyer prices are computed server-side; never send them."
                  },
                  "benchmark": {
                    "type": "object",
                    "properties": {
                      "price": {
                        "type": "number"
                      },
                      "source": {
                        "type": "string"
                      },
                      "observed_at": {
                        "type": "string"
                      }
                    },
                    "description": "Competitor benchmark price. Listing is rejected when net cannot beat it."
                  },
                  "tiers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "min_qty": {
                          "type": "integer"
                        },
                        "net": {
                          "type": "number"
                        }
                      }
                    }
                  },
                  "fulfillment": {
                    "type": "string",
                    "enum": [
                      "supplier_direct",
                      "platform"
                    ],
                    "default": "supplier_direct"
                  },
                  "external_url": {
                    "type": "string",
                    "description": "Supplier checkout URL for supplier_direct fulfillment"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "live",
                      "paused"
                    ],
                    "default": "live"
                  }
                },
                "required": [
                  "product_id",
                  "manufacturer_net"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Offer created with computed prices"
          },
          "400": {
            "description": "Missing/invalid fields (single 400 listing all missing)"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          },
          "403": {
            "description": "Not your organization's product"
          },
          "422": {
            "description": "Offer cannot beat the benchmark price"
          }
        }
      }
    },
    "/api/v1/wholesale/pricing-config": {
      "patch": {
        "tags": [
          "Wholesale"
        ],
        "summary": "Update pricing engine config (admin/dev only). margin_enabled=false means buyers pay exactly net (free to start).",
        "security": [
          {
            "BearerDev": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "margin_enabled": {
                    "type": "boolean"
                  },
                  "gap_share": {
                    "type": "number"
                  },
                  "floor_pct": {
                    "type": "number"
                  },
                  "ceiling_pct": {
                    "type": "number"
                  },
                  "patriot_cap_pct": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Config updated"
          },
          "401": {
            "$ref": "#/components/responses/Auth"
          },
          "403": {
            "description": "Admin only"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerDev": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token: a session token from /auth/vendor/login or /auth/customer/login (begins with sess_, valid 7 days), or a temporary development token beginning with dev_."
      }
    },
    "parameters": {
      "Id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "Query": {
        "name": "query",
        "in": "query",
        "schema": {
          "type": "string"
        }
      },
      "Category": {
        "name": "category",
        "in": "query",
        "schema": {
          "type": "string"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      }
    },
    "requestBodies": {
      "JsonBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true
            },
            "example": {
              "name": "Example record"
            }
          }
        }
      },
      "ProductBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "title",
                "sku"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "sku": {
                  "type": "string"
                },
                "category": {
                  "type": "string"
                },
                "brand": {
                  "type": "string"
                },
                "specifications": {
                  "type": "object"
                },
                "availability": {
                  "type": "object"
                },
                "description": {
                  "type": "string"
                },
                "image_url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Product image URL"
                }
              }
            },
            "example": {
              "title": "16-ounce reusable water bottle",
              "sku": "WFU-BOTTLE-16OZ",
              "category": "drinkware"
            }
          }
        }
      },
      "InventoryBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "quantity"
              ],
              "properties": {
                "quantity": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "example": {
              "quantity": 1000
            }
          }
        }
      },
      "StatusBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "status"
              ],
              "properties": {
                "status": {
                  "type": "string"
                }
              }
            },
            "example": {
              "status": "confirmed"
            }
          }
        }
      }
    },
    "responses": {
      "Auth": {
        "description": "Authentication required",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Error": {
        "description": "Structured validation or state error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "required": [
          "status",
          "service",
          "version"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          },
          "service": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "field": {
                "type": "string"
              },
              "resource_id": {
                "type": "string"
              },
              "allowed_values": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "title",
          "sku",
          "specifications",
          "availability"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "brand": {
            "type": "string"
          },
          "specifications": {
            "type": "object"
          },
          "availability": {
            "type": "object"
          }
        }
      },
      "ProductSearchResponse": {
        "type": "object",
        "required": [
          "products",
          "count"
        ],
        "properties": {
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "count": {
            "type": "integer"
          },
          "next_actions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}