{
  "openapi": "3.1.0",
  "info": {
    "title": "Techfleet Sync — Public API",
    "version": "1.0.0",
    "description": "Programmatic access to a merchant's device inventory, orders, and IMEI intelligence.\n\nTwo surfaces share one credential model:\n\n- **Merchant API (`/v1`)** — REST endpoints authenticated with a merchant API key (`Authorization: Bearer tfs_live_…`). This is what a merchant (or a marketplace integrating on a merchant's behalf) uses to read inventory and manage orders.\n- **UCP (`/ucp`)** — the Universal Commerce Protocol for AI agents. Accepts **either** a merchant API key **or** a buyer-link slug. With an API key you see the merchant's base catalog and pricing; with a buyer-link slug you see that buyer's negotiated margin.\n\nThe MCP server (`/mcp`) is documented separately at https://sync.techfleet.dev/mcp — it speaks JSON-RPC + SSE rather than REST and is not described by this spec. The ACP Checkout API (`/acp`, Agentic Commerce Protocol) is documented at https://sync.techfleet.dev/acp — `complete` charges the agent's Stripe shared payment token (`payment_data.instrument.credential.token`); declines return `402` with reservations released.\n\nGenerate keys from the dashboard under Settings → API Keys. Keys are scoped `read`, `write`, or `admin`.\n\n## Conventions\n\n- **Rate limits**: 1000 requests/hour per key. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; a 429 also returns `Retry-After`.\n- **Idempotency**: send an `Idempotency-Key` header (a UUID v4) on order-creating POSTs. A retry with the same key returns the original result instead of creating a duplicate (24h window).\n- **Request IDs**: every response includes `X-Request-Id`; include it in support requests. It is also echoed in error bodies as `request_id`.\n- **Pagination**: list endpoints accept `limit` + either `offset` or an opaque `cursor`, and return `has_more` + `next_cursor`. Prefer `cursor` for stable iteration over changing data.\n- **Errors**: `{ \"error\": \"<message>\", \"code\": \"<machine_code>\", \"request_id\": \"req_…\" }`.",
    "contact": { "name": "Techfleet API", "email": "api@techfleet.dev" }
  },
  "servers": [
    { "url": "https://api.techfleet.dev", "description": "Production (canonical API host)" },
    { "url": "https://sync.techfleet.dev/api", "description": "Production (alias — same routes under /api)" }
  ],
  "security": [{ "merchantApiKey": [] }],
  "tags": [
    { "name": "Inventory", "description": "Read serialized units and products (Merchant API)." },
    { "name": "Orders", "description": "List, read, and create orders (Merchant API)." },
    { "name": "Buyer Links", "description": "List buyer links (Merchant API)." },
    { "name": "IMEI Intelligence", "description": "Atlas device intelligence by IMEI." },
    { "name": "Webhooks", "description": "Subscribe to order.* / inventory.* events (HMAC-signed push)." },
    { "name": "UCP", "description": "Universal Commerce Protocol — agent-native commerce. Accepts an API key or a buyer-link slug." }
  ],
  "paths": {
    "/v1/inventory": {
      "get": {
        "tags": ["Inventory"],
        "operationId": "listInventory",
        "summary": "List serialized units",
        "description": "Returns serialized units (individual devices) for the authenticated merchant.",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "default": "available" }, "description": "Filter by unit status (e.g. available, reserved, sold)." },
          { "name": "grade", "in": "query", "schema": { "type": "string" }, "description": "Filter by cosmetic grade (A, B, C, D). Case-insensitive." },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search device name or IMEI." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "A page of units. All list endpoints share this envelope (data + count + offset/limit + has_more + next_cursor).",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "data": { "type": "array", "items": { "$ref": "#/components/schemas/Unit" } },
                "count": { "type": "integer" },
                "offset": { "type": "integer" },
                "limit": { "type": "integer" },
                "has_more": { "type": "boolean" },
                "next_cursor": { "type": "string", "nullable": true, "description": "Pass as ?cursor= to fetch the next page; null when has_more is false." }
              }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/inventory/{imei}": {
      "get": {
        "tags": ["Inventory"],
        "operationId": "getUnitByImei",
        "summary": "Get a unit by IMEI",
        "parameters": [{ "name": "imei", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "The unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unit" } } } },
          "404": { "$ref": "#/components/responses/NotFound" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/products": {
      "get": {
        "tags": ["Inventory"],
        "operationId": "listProducts",
        "summary": "List products",
        "description": "Returns the merchant's product catalog (models), each with available-unit counts.",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search product name or SKU." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "A page of products.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } },
                "count": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }
              }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/orders": {
      "get": {
        "tags": ["Orders"],
        "operationId": "listOrders",
        "summary": "List orders",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by order status." },
          { "name": "channel", "in": "query", "schema": { "type": "string" }, "description": "Filter by sales channel." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "A page of orders.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSummary" } },
                "count": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }
              }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "tags": ["Orders"],
        "operationId": "createOrder",
        "summary": "Create an order",
        "description": "Creates an order and atomically reserves serialized units (oversell-safe). Requires a key with `write` scope. Send an `Idempotency-Key` to make retries safe.",
        "security": [{ "merchantApiKey": [] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } }
        },
        "responses": {
          "201": {
            "description": "Order created.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "orderId": { "type": "string" }, "orderNumber": { "type": "string" },
                "totalAmount": { "type": "number" }, "status": { "type": "string", "example": "pending" }
              }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/orders/{orderNumber}": {
      "get": {
        "tags": ["Orders"],
        "operationId": "getOrder",
        "summary": "Get an order by number",
        "parameters": [{ "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "The order with line items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } },
          "404": { "$ref": "#/components/responses/NotFound" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/buyer-links": {
      "get": {
        "tags": ["Buyer Links"],
        "operationId": "listBuyerLinks",
        "summary": "List buyer links",
        "parameters": [
          { "name": "active", "in": "query", "schema": { "type": "string", "enum": ["true", "false"], "default": "true" }, "description": "Set to `false` to include inactive links." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "A page of buyer links.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "data": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerLink" } },
                "count": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }
              }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": ["Webhooks"],
        "operationId": "listWebhooks",
        "summary": "List webhook endpoints",
        "responses": {
          "200": {
            "description": "Registered endpoints (secrets are never returned).",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } },
                "knownEvents": { "type": "array", "items": { "type": "string" }, "example": ["order.created", "order.status_changed", "inventory.updated"] }
              }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "tags": ["Webhooks"],
        "operationId": "createWebhook",
        "summary": "Create a webhook endpoint",
        "description": "Subscribe to events. Requires `write` scope. The signing `secret` is returned ONCE — verify the `X-Techfleet-Signature: t=<ts>,v1=<hmac>` header with it. Events may be exact keys, the wildcard `*`, or a category prefix like `order.*`.",
        "security": [{ "merchantApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["url", "events"],
            "properties": {
              "url": { "type": "string", "format": "uri" },
              "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "example": ["order.created", "order.status_changed"] },
              "description": { "type": "string" }
            }
          } } }
        },
        "responses": {
          "201": {
            "description": "Created. Save the secret now.",
            "content": { "application/json": { "schema": {
              "allOf": [
                { "$ref": "#/components/schemas/WebhookEndpoint" },
                { "type": "object", "properties": { "secret": { "type": "string", "description": "Shown once." }, "warning": { "type": "string" } } }
              ]
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "tags": ["Webhooks"],
        "operationId": "deleteWebhook",
        "summary": "Deactivate a webhook endpoint",
        "security": [{ "merchantApiKey": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Deactivated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
          "404": { "$ref": "#/components/responses/NotFound" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": {
        "tags": ["Webhooks"],
        "operationId": "listWebhookDeliveries",
        "summary": "Recent delivery attempts (debugging)",
        "security": [{ "merchantApiKey": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Up to 50 recent deliveries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/imei/{imei}/intelligence": {
      "get": {
        "tags": ["IMEI Intelligence"],
        "operationId": "imeiIntelligence",
        "summary": "Look up Atlas device intelligence by IMEI",
        "description": "Returns manufacturer, carrier, lock status, blacklist, and warranty data. The free bundle (model identification) is unlimited; paid bundles debit Atlas credits and require `?force=1` (write scope) to bypass cache.",
        "parameters": [
          { "name": "imei", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "bundle", "in": "query", "schema": { "type": "string", "enum": ["free", "basic", "standard", "premium"] } },
          { "name": "force", "in": "query", "schema": { "type": "string", "enum": ["1", "true"] }, "description": "Bypass cache and re-query upstream. Requires write scope." }
        ],
        "responses": {
          "200": { "description": "Lookup result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImeiIntelligence" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/imei/lookup": {
      "post": {
        "tags": ["IMEI Intelligence"],
        "operationId": "imeiLookup",
        "summary": "Look up device intelligence (POST form)",
        "description": "Equivalent to GET /v1/imei/{imei}/intelligence. Requires write scope.",
        "security": [{ "merchantApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["imei"],
            "properties": {
              "imei": { "type": "string", "minLength": 8, "maxLength": 24 },
              "bundle": { "type": "string", "enum": ["free", "basic", "standard", "premium"] },
              "force_refresh": { "type": "boolean" }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Lookup result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImeiIntelligence" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/ucp/inventory": {
      "get": {
        "tags": ["UCP"],
        "operationId": "ucpListInventory",
        "summary": "List inventory (agent view)",
        "description": "Returns products with a single `buyerPrice` per item. Authenticate with a merchant API key (base pricing) or a buyer-link slug (margin pricing). The slug may also be supplied in the path as `/ucp/{slug}/inventory`.",
        "security": [{ "merchantApiKey": [] }, { "buyerSlug": [] }],
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "grade", "in": "query", "schema": { "type": "string", "enum": ["A", "B", "C", "D"] } },
          { "name": "min_price", "in": "query", "schema": { "type": "number" } },
          { "name": "max_price", "in": "query", "schema": { "type": "number" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
        ],
        "responses": {
          "200": {
            "description": "Agent-priced product list.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "merchantName": { "type": "string" },
                "slug": { "type": "string", "nullable": true },
                "total": { "type": "integer" },
                "items": { "type": "array", "items": { "$ref": "#/components/schemas/UcpProduct" } }
              }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/ucp/inventory/{imei}": {
      "get": {
        "tags": ["UCP"],
        "operationId": "ucpGetUnitByImei",
        "summary": "Look up a device by IMEI (agent view)",
        "security": [{ "merchantApiKey": [] }, { "buyerSlug": [] }],
        "parameters": [{ "name": "imei", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Unit found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unit" } } } },
          "404": { "$ref": "#/components/responses/NotFound" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/ucp/order": {
      "post": {
        "tags": ["UCP"],
        "operationId": "ucpPlaceOrder",
        "summary": "Place an order (agent)",
        "description": "Atomically reserves units (oversell-safe) and creates an order. Requires write scope (a buyer-link slug always has it; a read-only API key is rejected). The slug may also be supplied in the path as `/ucp/{slug}/order`. Send an `Idempotency-Key` to make retries safe.",
        "security": [{ "merchantApiKey": [] }, { "buyerSlug": [] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UcpOrderRequest" } } }
        },
        "responses": {
          "201": {
            "description": "Order created.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "orderId": { "type": "string" }, "orderNumber": { "type": "string" },
                "totalAmount": { "type": "number" }, "status": { "type": "string", "example": "pending" },
                "itemCount": { "type": "integer" }
              }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "description": "Insufficient stock for one of the requested products." }
        }
      }
    },
    "/ucp/order/{orderNumber}": {
      "get": {
        "tags": ["UCP"],
        "operationId": "ucpOrderStatus",
        "summary": "Get order status (agent)",
        "security": [{ "merchantApiKey": [] }, { "buyerSlug": [] }],
        "parameters": [{ "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Order status with line items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UcpOrderStatus" } } } },
          "404": { "$ref": "#/components/responses/NotFound" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/ucp/imei/{imei}/intelligence": {
      "get": {
        "tags": ["UCP"],
        "operationId": "ucpImeiIntelligence",
        "summary": "Atlas device intelligence by IMEI (agent)",
        "security": [{ "merchantApiKey": [] }, { "buyerSlug": [] }],
        "parameters": [
          { "name": "imei", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "bundle", "in": "query", "schema": { "type": "string", "enum": ["free", "basic", "standard", "premium"] } },
          { "name": "force", "in": "query", "schema": { "type": "string", "enum": ["1", "true"] } }
        ],
        "responses": {
          "200": { "description": "Lookup result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImeiIntelligence" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/ucp/inquiry": {
      "post": {
        "tags": ["UCP"],
        "operationId": "ucpInquiry",
        "summary": "Natural-language inventory question (agent)",
        "description": "Answers a free-text question grounded in the current inventory snapshot.",
        "security": [{ "merchantApiKey": [] }, { "buyerSlug": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["message"],
            "properties": { "message": { "type": "string", "description": "Natural-language question." } }
          } } }
        },
        "responses": {
          "200": {
            "description": "AI-generated answer.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": { "response": { "type": "string" }, "inventorySnapshot": { "type": "integer" } }
            } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": { "type": "string", "format": "uuid" },
        "description": "Retry-safe key (UUID v4 recommended). A repeat POST with the same key returns the original order instead of creating a duplicate (24h window)."
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "schema": { "type": "string" },
        "description": "Opaque pagination cursor taken from a prior response's next_cursor. When supplied, offset is ignored."
      }
    },
    "securitySchemes": {
      "merchantApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Merchant API key. Format: `tfs_live_` + 32 hex characters (41 chars total). Create one in the dashboard under Settings → API Keys. Send as `Authorization: Bearer tfs_live_…`."
      },
      "buyerSlug": {
        "type": "http",
        "scheme": "bearer",
        "description": "Buyer-link slug issued by a merchant (UCP only). Send as `Authorization: Bearer {slug}` or `?slug={slug}`. Returns catalog priced at that buyer's negotiated margin."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid credentials.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing or invalid API key. Use Authorization: Bearer tfs_live_..." } } }
      },
      "Forbidden": {
        "description": "The key is valid but lacks the required scope.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Insufficient scope. Key has 'read', requires 'write'" } } }
      },
      "NotFound": {
        "description": "Resource not found.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Human-readable message." },
          "code": { "type": "string", "description": "Stable machine-readable code (e.g. unauthorized, insufficient_scope, insufficient_stock, rate_limited, not_found).", "example": "insufficient_stock" },
          "param": { "type": "string", "description": "Offending field, when applicable." },
          "request_id": { "type": "string", "description": "Correlation id (also in the X-Request-Id header).", "example": "req_8f3k…" }
        },
        "required": ["error", "code"]
      },
      "Unit": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "imei": { "type": "string", "nullable": true },
          "serial_number": { "type": "string", "nullable": true },
          "device_name": { "type": "string", "nullable": true },
          "grade": { "type": "string", "nullable": true },
          "battery_health": { "type": "integer", "nullable": true },
          "storage": { "type": "string", "nullable": true },
          "color": { "type": "string", "nullable": true },
          "carrier_lock": { "type": "string", "nullable": true },
          "status": { "type": "string" },
          "purchase_price": { "type": "number", "nullable": true },
          "warehouse_id": { "type": "string", "nullable": true },
          "created_at": { "type": "integer", "description": "Epoch milliseconds." }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "sku": { "type": "string", "nullable": true },
          "base_price": { "type": "number" },
          "stock": { "type": "integer" },
          "condition": { "type": "string", "nullable": true },
          "available_units": { "type": "integer" }
        }
      },
      "UcpProduct": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Product id, or `sc:<listingId>` for Supply Connect network inventory." },
          "name": { "type": "string" },
          "sku": { "type": "string", "nullable": true },
          "condition": { "type": "string", "nullable": true },
          "stock": { "type": "integer" },
          "buyerPrice": { "type": "number", "description": "Price in USD for this caller (base price for an API key, margin price for a slug)." },
          "availableGrades": { "type": "string", "nullable": true, "example": "A,B,C" },
          "avgBatteryHealth": { "type": "integer", "nullable": true },
          "supplyConnect": { "type": "boolean", "description": "True when the item comes from the partner network." }
        }
      },
      "OrderSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "order_number": { "type": "string" },
          "buyer_name": { "type": "string" },
          "buyer_email": { "type": "string", "nullable": true },
          "channel": { "type": "string", "nullable": true },
          "status": { "type": "string" },
          "total_amount": { "type": "number" },
          "tracking_number": { "type": "string", "nullable": true },
          "created_at": { "type": "integer" }
        }
      },
      "OrderDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/OrderSummary" },
          {
            "type": "object",
            "properties": {
              "buyer_phone": { "type": "string", "nullable": true },
              "notes": { "type": "string", "nullable": true },
              "shippingAddress": { "type": "object", "nullable": true },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "device_id": { "type": "string", "nullable": true },
                    "unit_id": { "type": "string", "nullable": true },
                    "quantity": { "type": "integer" },
                    "unit_price": { "type": "number" },
                    "product_name": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          }
        ]
      },
      "WebhookEndpoint": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "events": { "type": "array", "items": { "type": "string" } },
          "description": { "type": "string", "nullable": true },
          "active": { "type": "boolean" },
          "failureCount": { "type": "integer" },
          "lastDeliveredAt": { "type": "integer", "nullable": true },
          "lastStatusCode": { "type": "integer", "nullable": true },
          "createdAt": { "type": "integer" }
        }
      },
      "BuyerLink": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "url": { "type": "string" },
          "buyerName": { "type": "string" },
          "marginPercent": { "type": "number" },
          "active": { "type": "boolean" },
          "reshareEnabled": { "type": "boolean" },
          "emailGated": { "type": "boolean" },
          "expiresAt": { "type": "integer", "nullable": true },
          "viewCount": { "type": "integer" },
          "reshareParentId": { "type": "string", "nullable": true },
          "createdAt": { "type": "integer" }
        }
      },
      "ImeiIntelligence": {
        "type": "object",
        "properties": {
          "cached": { "type": "boolean" },
          "cost": { "type": "number", "description": "Atlas credits debited (0 for cache hits and the free bundle)." },
          "result": { "type": "object", "description": "Provider-normalized intelligence fields." },
          "expiresAt": { "type": "integer", "nullable": true, "description": "Cache expiry, epoch milliseconds." }
        }
      },
      "OrderItemInput": {
        "type": "object",
        "required": ["productId", "unitPrice"],
        "properties": {
          "productId": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1, "default": 1 },
          "unitPrice": { "type": "number", "minimum": 0 }
        }
      },
      "ShippingAddress": {
        "type": "object",
        "properties": {
          "addressLine1": { "type": "string" },
          "addressLine2": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "postalCode": { "type": "string" },
          "country": { "type": "string" }
        }
      },
      "CreateOrderRequest": {
        "type": "object",
        "required": ["buyerName", "items"],
        "properties": {
          "buyerName": { "type": "string" },
          "buyerEmail": { "type": "string", "format": "email" },
          "buyerPhone": { "type": "string" },
          "channel": { "type": "string", "default": "api" },
          "notes": { "type": "string" },
          "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/OrderItemInput" } },
          "shippingAddress": { "$ref": "#/components/schemas/ShippingAddress" }
        }
      },
      "UcpOrderRequest": {
        "type": "object",
        "required": ["buyerName", "buyerEmail", "items"],
        "properties": {
          "buyerName": { "type": "string" },
          "buyerEmail": { "type": "string", "format": "email" },
          "buyerPhone": { "type": "string" },
          "notes": { "type": "string" },
          "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/OrderItemInput" } },
          "shippingAddress": { "$ref": "#/components/schemas/ShippingAddress" }
        }
      },
      "UcpOrderStatus": {
        "type": "object",
        "properties": {
          "orderId": { "type": "string" },
          "orderNumber": { "type": "string" },
          "status": { "type": "string" },
          "totalAmount": { "type": "number" },
          "trackingNumber": { "type": "string", "nullable": true },
          "createdAt": { "type": "string", "format": "date-time" },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "productName": { "type": "string" },
                "quantity": { "type": "integer" },
                "unitPrice": { "type": "number" }
              }
            }
          }
        }
      }
    }
  }
}