{ "swagger": "2.0", "info": { "description": "Public, company-scoped API for third-party integrations. Authenticate with either a company API key or an OAuth2 client_credentials access token — both grant the same scoped access. See docs/PARTNER_API.md for the full guide.", "title": "ShedCloud Partner API", "contact": {}, "version": "1.0" }, "basePath": "/", "paths": { "/oauth/token": { "post": { "security": [ { "BasicAuth": [] } ], "description": "Exchanges OAuth2 client credentials for a short-lived bearer access token (client_credentials grant, RFC 6749 §4.4). Send client_id/client_secret via HTTP Basic auth or as form fields.", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "partner-oauth" ], "summary": "Issue an access token", "parameters": [ { "type": "string", "description": "Must be 'client_credentials'", "name": "grant_type", "in": "formData", "required": true }, { "type": "string", "description": "OAuth client id (omit if using HTTP Basic auth)", "name": "client_id", "in": "formData" }, { "type": "string", "description": "OAuth client secret (omit if using HTTP Basic auth)", "name": "client_secret", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.TokenResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/configurator-sessions": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Mints a single-use launch URL for the Structura 3D configurator. Optionally attach a customer, reopen a quote's design (quoteId), or open an in-stock building (workOrderId or serialNumber). returnUrl must match an allowlisted origin configured in Settings \u003e Developer API. Supports the Idempotency-Key header.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-configurator-sessions" ], "summary": "Create a configurator session", "parameters": [ { "description": "Session parameters", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.ConfiguratorSessionCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.ConfiguratorSessionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/customers": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's customers with filtering, sorting, and pagination.", "produces": [ "application/json" ], "tags": [ "partner-customers" ], "summary": "List customers", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on name, email, or phone", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by email (substring)", "name": "email", "in": "query" }, { "type": "string", "description": "Filter by phone (substring)", "name": "phone", "in": "query" }, { "type": "boolean", "description": "Include customers that were merged into another record (excluded by default)", "name": "includeMerged", "in": "query" }, { "type": "string", "description": "Filter by external reference, key:value exact match", "name": "externalRef", "in": "query" }, { "type": "string", "description": "Created on/after (RFC 3339 or YYYY-MM-DD)", "name": "createdFrom", "in": "query" }, { "type": "string", "description": "Created on/before (RFC 3339 or YYYY-MM-DD)", "name": "createdTo", "in": "query" }, { "type": "string", "description": "Updated on/after (RFC 3339 or YYYY-MM-DD)", "name": "updatedFrom", "in": "query" }, { "type": "string", "description": "Updated on/before (RFC 3339 or YYYY-MM-DD)", "name": "updatedTo", "in": "query" }, { "type": "string", "default": "createdAt", "description": "Sort field: name | email | createdAt | updatedAt", "name": "sort", "in": "query" }, { "type": "string", "default": "desc", "description": "Sort direction: asc | desc", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.CustomerListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a new customer. Email is required and must be unique within the company (409 on duplicates).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-customers" ], "summary": "Create a customer", "parameters": [ { "description": "Customer to create", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.CustomerCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.CustomerItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/customers/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one customer by id. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-customers" ], "summary": "Get a customer", "parameters": [ { "type": "string", "description": "Customer id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.CustomerItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "patch": { "security": [ { "PartnerBearer": [] } ], "description": "Updates allowlisted customer fields (contact info, address, code, active). Unknown fields are rejected. Changing the email to one that belongs to another customer returns 409.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-customers" ], "summary": "Update a customer", "parameters": [ { "type": "string", "description": "Customer id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.CustomerPatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.CustomerItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/customers/{id}/merge": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Marks the customer in the path as merged into survivorId, relinks all of its leads/quotes/orders to the survivor, and emits a customer.merged event. The merged customer keeps resolving on GET (merged=true, mergedInto set) but disappears from lists (unless includeMerged=true) and rejects writes with 409. Supports Idempotency-Key.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-customers" ], "summary": "Merge a duplicate customer into a survivor", "parameters": [ { "type": "string", "description": "Duplicate (loser) customer id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Merge target", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.CustomerMergeRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.CustomerMergeResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/documents": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the file metadata (contract PDFs, previews, photos) linked to one order, quote, or work order. Download the bytes via GET /partner/v1/documents/{id}/download.", "produces": [ "application/json" ], "tags": [ "partner-documents" ], "summary": "List documents for an entity", "parameters": [ { "type": "string", "description": "order | quote | workOrder", "name": "entityType", "in": "query", "required": true }, { "type": "string", "description": "Entity id (24-char hex)", "name": "entityId", "in": "query", "required": true }, { "type": "string", "description": "Filter by stored category (e.g. Contract)", "name": "type", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.DocumentListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/documents/{id}/download": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns a presigned URL valid for 10 minutes. The URL is single-purpose — request a fresh one for each download.", "produces": [ "application/json" ], "tags": [ "partner-documents" ], "summary": "Get a document download link", "parameters": [ { "type": "string", "description": "Document id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.DocumentDownloadResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/domains": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the company's white-label storefront domains (subdomains configured on DNS integrations) with their per-location assignments: hidePrices, defaultForStore, and product/size mappings.", "produces": [ "application/json" ], "tags": [ "partner-domains" ], "summary": "List domains", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Only domains assigned to this location id, with locations narrowed to it", "name": "locationId", "in": "query" }, { "type": "boolean", "description": "true → only location entries flagged Default For Store (domains without one are dropped)", "name": "defaultForStore", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.DomainListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/events": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the company's change events after the given cursor, oldest first. Persist nextCursor and poll again to consume the feed losslessly. Events are retained for ~60 days.", "produces": [ "application/json" ], "tags": [ "partner-events" ], "summary": "Poll the change-event feed", "parameters": [ { "type": "string", "description": "Last consumed event id; omit to start from the oldest retained event", "name": "cursor", "in": "query" }, { "type": "string", "description": "Comma-separated event types to include (e.g. order.status_changed,payment.paid)", "name": "types", "in": "query" }, { "type": "integer", "default": 100, "description": "Max events per page (max 200)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.EventListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/events/{id}/redeliver": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Re-enqueues one event to every active webhook subscription whose type filter matches. Use after fixing a broken endpoint. Delivery is at-least-once — dedupe by event id.", "produces": [ "application/json" ], "tags": [ "partner-events" ], "summary": "Redeliver an event", "parameters": [ { "type": "string", "description": "Event id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/partnerapi.EventRedeliverResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/leads": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's leads with filtering, sorting, and pagination. All field names are clean, human-readable keys — internal codes never appear.", "produces": [ "application/json" ], "tags": [ "partner-leads" ], "summary": "List leads", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on customer name, order number, email, phone, or salesperson", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status (e.g. Open, Active, Sold, Lost, Retired)", "name": "status", "in": "query" }, { "type": "string", "description": "Sales location id or slug", "name": "location", "in": "query" }, { "type": "string", "description": "Filter by customer email (substring)", "name": "customerEmail", "in": "query" }, { "type": "string", "description": "Filter by customer phone (substring)", "name": "customerPhone", "in": "query" }, { "type": "string", "description": "Filter by exact lead number", "name": "orderNumber", "in": "query" }, { "type": "string", "description": "Filter by salesperson email (substring)", "name": "salesperson", "in": "query" }, { "type": "string", "description": "Filter by external reference, key:value exact match", "name": "externalRef", "in": "query" }, { "type": "string", "description": "Created on/after (RFC 3339 or YYYY-MM-DD)", "name": "createdFrom", "in": "query" }, { "type": "string", "description": "Created on/before (RFC 3339 or YYYY-MM-DD)", "name": "createdTo", "in": "query" }, { "type": "string", "description": "Updated on/after (RFC 3339 or YYYY-MM-DD)", "name": "updatedFrom", "in": "query" }, { "type": "string", "description": "Updated on/before (RFC 3339 or YYYY-MM-DD)", "name": "updatedTo", "in": "query" }, { "type": "string", "default": "createdAt", "description": "Sort field: orderNumber | customerName | status | total | createdAt | updatedAt", "name": "sort", "in": "query" }, { "type": "string", "default": "desc", "description": "Sort direction: asc | desc", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LeadListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a lead at the given sales location with the customer's contact information. When salespersonName/salespersonEmail are omitted, the location's lead-routing strategy (round-robin, availability, skill-based) auto-assigns a salesperson — the same routing in-stock quote creation uses.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-leads" ], "summary": "Create a lead", "parameters": [ { "description": "Sales location + customer contact", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.LeadCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.LeadItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/leads/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one lead by id. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-leads" ], "summary": "Get a lead", "parameters": [ { "type": "string", "description": "Lead id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LeadItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "patch": { "security": [ { "PartnerBearer": [] } ], "description": "Updates allowlisted lead fields (salesLocation, salespersonName, salespersonEmail). Unknown fields are rejected.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-leads" ], "summary": "Update a lead", "parameters": [ { "type": "string", "description": "Lead id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.LeadPatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LeadItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/leads/{id}/status": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Moves a lead between allowlisted statuses (Open ↔ Lost/Retired). Other transitions are rejected.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-leads" ], "summary": "Update a lead's status", "parameters": [ { "type": "string", "description": "Lead id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Target status", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.PartnerStatusRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LeadItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/leads/{id}/status-history": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the lead's status transitions, newest first, with the acting user and action description.", "produces": [ "application/json" ], "tags": [ "partner-leads" ], "summary": "Get status history for a lead", "parameters": [ { "type": "string", "description": "Lead id (24-char hex)", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.StatusHistoryResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/locations": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's locations (sales lots, plants, warehouses) with filtering, sorting, and pagination.", "produces": [ "application/json" ], "tags": [ "partner-locations" ], "summary": "List locations", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on name, code, or city", "name": "search", "in": "query" }, { "type": "boolean", "description": "Filter by active flag", "name": "active", "in": "query" }, { "type": "boolean", "description": "Filter by sales-lot flag", "name": "salesLot", "in": "query" }, { "type": "boolean", "description": "Filter by plant flag", "name": "plant", "in": "query" }, { "type": "string", "description": "Filter by exact region label (dealer-defined)", "name": "region", "in": "query" }, { "type": "string", "default": "createdAt", "description": "Sort field: name | code | city | createdAt | updatedAt", "name": "sort", "in": "query" }, { "type": "string", "default": "desc", "description": "Sort direction: asc | desc", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LocationListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a new location. Name is required, plus either an address or a latitude/longitude pair. The location code must be unique within the company.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-locations" ], "summary": "Create a location", "parameters": [ { "description": "Location to create", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.LocationCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.LocationItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/locations/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one location by id. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-locations" ], "summary": "Get a location", "parameters": [ { "type": "string", "description": "Location id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LocationItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "patch": { "security": [ { "PartnerBearer": [] } ], "description": "Updates allowlisted location fields. Latitude and longitude must be provided together. Unknown fields are rejected.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-locations" ], "summary": "Update a location", "parameters": [ { "type": "string", "description": "Location id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.LocationPatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LocationItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/locations/{id}/domains": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the domains the given location is assigned to, with each domain's locations narrowed to that location. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-domains" ], "summary": "List a location's domains", "parameters": [ { "type": "string", "description": "Location id (24-char hex)", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "boolean", "description": "true → only the entry flagged Default For Store", "name": "defaultForStore", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.DomainListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/lot-stock": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's ready-to-sell physical inventory (units sitting on a lot, rental returns, or immediate-sale units).", "produces": [ "application/json" ], "tags": [ "partner-inventory" ], "summary": "List on-lot inventory", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "default": "ALL", "description": "ALL | Lot Stock | Rental Return | Immediate Sale (case-insensitive; hyphens accepted, e.g. lot-stock)", "name": "purchaseType", "in": "query" }, { "type": "string", "description": "Location id or slug", "name": "location", "in": "query" }, { "type": "string", "description": "Filter by the locations' exact region label (dealer-defined)", "name": "region", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on serial number or title", "name": "search", "in": "query" }, { "type": "string", "default": "createdAt", "description": "Sort field: serialNumber | title | price | createdAt", "name": "sort", "in": "query" }, { "type": "string", "default": "desc", "description": "Sort direction: asc | desc", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LotStockResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/me": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the company, credential type, granted scopes, and rate-limit configuration for the calling credential. Requires any valid Partner API credential — no specific scope.", "produces": [ "application/json" ], "tags": [ "partner-meta" ], "summary": "Introspect the authenticated credential", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.MeResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's sales orders (records that are neither leads nor quotes) with filtering, sorting, and pagination.", "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "List sales orders", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on customer name, order number, email, phone, or salesperson", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status (e.g. Unsubmitted, Unprocessed, Processed, On hold, Closed)", "name": "status", "in": "query" }, { "type": "string", "description": "Sales location id or slug", "name": "location", "in": "query" }, { "type": "string", "description": "Filter by customer email (substring)", "name": "customerEmail", "in": "query" }, { "type": "string", "description": "Filter by customer phone (substring)", "name": "customerPhone", "in": "query" }, { "type": "string", "description": "Filter by exact order number", "name": "orderNumber", "in": "query" }, { "type": "string", "description": "Filter by salesperson email (substring)", "name": "salesperson", "in": "query" }, { "type": "string", "description": "Filter by external reference, key:value exact match", "name": "externalRef", "in": "query" }, { "type": "string", "description": "Filter by payment type: rto | cash", "name": "paymentType", "in": "query" }, { "type": "string", "description": "Filter by serial number (substring)", "name": "serialNumber", "in": "query" }, { "type": "string", "description": "Created on/after (RFC 3339 or YYYY-MM-DD)", "name": "createdFrom", "in": "query" }, { "type": "string", "description": "Created on/before (RFC 3339 or YYYY-MM-DD)", "name": "createdTo", "in": "query" }, { "type": "string", "description": "Updated on/after (RFC 3339 or YYYY-MM-DD)", "name": "updatedFrom", "in": "query" }, { "type": "string", "description": "Updated on/before (RFC 3339 or YYYY-MM-DD)", "name": "updatedTo", "in": "query" }, { "type": "string", "default": "createdAt", "description": "Sort field: orderNumber | customerName | status | total | createdAt | updatedAt", "name": "sort", "in": "query" }, { "type": "string", "default": "desc", "description": "Sort direction: asc | desc", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.OrderListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a full sales order: customer (existing id or inline auto-create), location, base product (model + optional size), optional upgrade lines, pricing header, optional configurator payload, and delivery address. Runs the same pipeline as the portal (order number, detail rows, configurator link, status log, ledger snapshot, audit, CRM). New orders start in status \"Unsubmitted\". Send an Idempotency-Key header to make retries safe.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Create a sales order", "parameters": [ { "type": "string", "description": "Unique key making the create retry-safe", "name": "Idempotency-Key", "in": "header" }, { "description": "Order payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.OrderCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.OrderItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one sales order by id. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Get a sales order", "parameters": [ { "type": "string", "description": "Sales order id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.OrderItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "patch": { "security": [ { "PartnerBearer": [] } ], "description": "Updates allowlisted sales order fields (customer contact, salesperson, salesLocation, delivery address). No pricing, serial, or work-order fields in v1. Orders with a contract out for signature reject changes with 409.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Update a sales order", "parameters": [ { "type": "string", "description": "Sales order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.SalesOrderPatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.OrderItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders/{id}/contract": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the derived signing state of the order's contract: status, version, who has signed and when, and the stored PDF document id. Signature images and customer data sheet fields are never included.", "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Get an order's contract summary", "parameters": [ { "type": "string", "description": "Order id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.ContractSummary" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders/{id}/line-items": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the order's curated line items (upgrades, added/removed options, standard features) and the configured building summary.", "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Get line items for an order", "parameters": [ { "type": "string", "description": "Order id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LineItemsResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Adds one upgrade line (product reference + quantity/price) to the order. Idempotent on lineKey: re-sending the same key returns the existing line instead of duplicating it. Header pricing is not recalculated — PATCH the order's pricing fields afterward.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Add a line item to an order", "parameters": [ { "type": "string", "description": "Order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Line item", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.LineItemCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.LineItemCreateResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders/{id}/line-items/{lineId}": { "delete": { "security": [ { "PartnerBearer": [] } ], "description": "Removes one upgrade line by its line id (from GET line-items or the add response). The base product line cannot be deleted. Header pricing is not recalculated — PATCH the order's pricing fields afterward.", "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Delete a line item from an order", "parameters": [ { "type": "string", "description": "Order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Line id", "name": "lineId", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders/{id}/payment-links": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a Stripe Checkout session for the order and returns the hosted payment URL. The company's Stripe integration must be connected and have payments enabled. When the customer pays, the webhook pipeline records the payment and emits payment.* events automatically. By default the customer also receives the payment-link email — pass \"sendEmail\": false to suppress it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-payments" ], "summary": "Create a Stripe payment link for an order", "parameters": [ { "type": "string", "description": "Order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Payment link payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.PaymentLinkCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.PaymentLinkResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders/{id}/payments": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the payment records linked to one sales order, newest first.", "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "List an order's payments", "parameters": [ { "type": "string", "description": "Order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.PaymentListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Records a manual payment (cash, check, financed, or manual) against a sales order, through the same pipeline as the portal: payment record, localized mirror, payment-ledger recording (order balance recalculation), audit. Card/ACH payments are rejected — those records are created by the Stripe webhook pipeline (use payment-links instead). Status is always \"paid\". Send an Idempotency-Key header to make retries safe.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-payments" ], "summary": "Record a manual payment on an order", "parameters": [ { "type": "string", "description": "Unique key making the create retry-safe", "name": "Idempotency-Key", "in": "header" }, { "type": "string", "description": "Order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Payment payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.PaymentCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.PaymentItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders/{id}/status": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Moves a sales order between allowlisted statuses (Unsubmitted → Unprocessed/On hold, Unprocessed ↔ On hold). \"Processed\" is blocked in v1. Submitting (→ Unprocessed) requires a serial number on the order or its linked work order.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Update a sales order's status", "parameters": [ { "type": "string", "description": "Sales order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Target status", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.PartnerStatusRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.OrderItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/orders/{id}/status-history": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the order's status transitions, newest first, with the acting user and action description.", "produces": [ "application/json" ], "tags": [ "partner-orders" ], "summary": "Get status history for an order", "parameters": [ { "type": "string", "description": "Order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.StatusHistoryResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/payments": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's payment records, newest first, with order/status/date filters.", "produces": [ "application/json" ], "tags": [ "partner-payments" ], "summary": "List payments", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Filter by sales order id (24-char hex)", "name": "orderId", "in": "query" }, { "type": "string", "description": "Filter by status (case-insensitive exact match, e.g. paid, Refunded)", "name": "status", "in": "query" }, { "type": "string", "description": "Created on/after (RFC 3339 or YYYY-MM-DD)", "name": "createdFrom", "in": "query" }, { "type": "string", "description": "Created on/before (RFC 3339 or YYYY-MM-DD)", "name": "createdTo", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.PaymentListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/payments/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one payment record by id. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-payments" ], "summary": "Get a payment", "parameters": [ { "type": "string", "description": "Payment id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.PaymentItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/products": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's finished catalog products (raw materials and kits are excluded) with gallery image URLs, filtering, sorting, and pagination. For serialized on-lot units, use GET /partner/v1/lot-stock.", "produces": [ "application/json" ], "tags": [ "partner-inventory" ], "summary": "List products", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on name, SKU, or description", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by SKU (substring)", "name": "sku", "in": "query" }, { "type": "boolean", "description": "Filter by active flag", "name": "active", "in": "query" }, { "type": "string", "description": "Created on/after (RFC 3339 or YYYY-MM-DD)", "name": "createdFrom", "in": "query" }, { "type": "string", "description": "Created on/before (RFC 3339 or YYYY-MM-DD)", "name": "createdTo", "in": "query" }, { "type": "string", "description": "Updated on/after (RFC 3339 or YYYY-MM-DD)", "name": "updatedFrom", "in": "query" }, { "type": "string", "description": "Updated on/before (RFC 3339 or YYYY-MM-DD)", "name": "updatedTo", "in": "query" }, { "type": "string", "default": "createdAt", "description": "Sort field: name | sku | price | createdAt | updatedAt", "name": "sort", "in": "query" }, { "type": "string", "default": "desc", "description": "Sort direction: asc | desc", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.ProductListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a finished catalog product. Name is required. Optionally link it under an existing product line with lineId. Pricing/dimensions for configurable models should live on size children — see POST /partner/v1/products/{id}/sizes.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-inventory" ], "summary": "Create a product", "parameters": [ { "description": "Product to create", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.ProductCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.ProductItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/products/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one finished catalog product by id with gallery image URLs. Ids belonging to another company — or to raw materials / kits — return 404.", "produces": [ "application/json" ], "tags": [ "partner-inventory" ], "summary": "Get a product", "parameters": [ { "type": "string", "description": "Product id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.ProductItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "patch": { "security": [ { "PartnerBearer": [] } ], "description": "Updates allowlisted product fields (name, description, sku, price, width, length, active). Unknown fields are rejected. Raw materials, kits, and products hidden from the Partner API return 404.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-inventory" ], "summary": "Update a product", "parameters": [ { "type": "string", "description": "Product id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.ProductPatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.ProductItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/products/{id}/sizes": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a size child under a catalog product (width, length, price) and links it with the finished-good relationship — the same structure the portal's size editor writes. Size children carry the model's real pricing and dimensions.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-inventory" ], "summary": "Add a size to a product", "parameters": [ { "type": "string", "description": "Parent product id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Size to create", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.ProductSizeCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.ProductSizeItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/quotes": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's quotes with filtering, sorting, and pagination.", "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "List quotes", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on customer name, quote number, email, phone, or salesperson", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status (e.g. Active, Sold, Lost, Retired)", "name": "status", "in": "query" }, { "type": "string", "description": "Sales location id or slug", "name": "location", "in": "query" }, { "type": "string", "description": "Filter by customer email (substring)", "name": "customerEmail", "in": "query" }, { "type": "string", "description": "Filter by customer phone (substring)", "name": "customerPhone", "in": "query" }, { "type": "string", "description": "Filter by exact quote number", "name": "orderNumber", "in": "query" }, { "type": "string", "description": "Filter by salesperson email (substring)", "name": "salesperson", "in": "query" }, { "type": "string", "description": "Filter by external reference, key:value exact match", "name": "externalRef", "in": "query" }, { "type": "boolean", "description": "true = only quotes converted to an order, false = only unconverted", "name": "converted", "in": "query" }, { "type": "string", "description": "Created on/after (RFC 3339 or YYYY-MM-DD)", "name": "createdFrom", "in": "query" }, { "type": "string", "description": "Created on/before (RFC 3339 or YYYY-MM-DD)", "name": "createdTo", "in": "query" }, { "type": "string", "description": "Updated on/after (RFC 3339 or YYYY-MM-DD)", "name": "updatedFrom", "in": "query" }, { "type": "string", "description": "Updated on/before (RFC 3339 or YYYY-MM-DD)", "name": "updatedTo", "in": "query" }, { "type": "string", "default": "createdAt", "description": "Sort field: orderNumber | customerName | status | total | createdAt | updatedAt", "name": "sort", "in": "query" }, { "type": "string", "default": "desc", "description": "Sort direction: asc | desc", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.QuoteListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a quote for an on-lot building identified by serial number or work order id. The unit's work order is linked to the quote (copying serial number, product lines, and pricing), the sales location is assigned, and lead routing auto-assigns a salesperson when the location has routing configured. Newly created customers are synced to any connected CRM. Fails with 409 when the unit already has an active quote or order, is a stock template, or is cancelled.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Create a quote from an in-stock unit", "parameters": [ { "description": "In-stock unit reference + customer", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.QuoteCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.QuoteItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/quotes/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one quote by id. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Get a quote", "parameters": [ { "type": "string", "description": "Quote id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.QuoteItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "patch": { "security": [ { "PartnerBearer": [] } ], "description": "Updates allowlisted quote fields (customer contact, salesperson, salesLocation, delivery address). No pricing fields in v1.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Update a quote", "parameters": [ { "type": "string", "description": "Quote id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.SalesOrderPatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.QuoteItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/quotes/{id}/convert": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Converts an open quote into a real sales order: allocates the next order number, clones the quote's product lines and configurator onto the new order, marks the quote Sold with a back-reference, and re-links the quote's work order to the order. The new order starts in the Unsubmitted status. Fails with 409 when the quote is already Sold/Cancelled/Deleted or an active order already exists for it. Requires the orders write scope.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Convert a quote to a sales order", "parameters": [ { "type": "string", "description": "Quote id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Optional salesperson overrides", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/partnerapi.QuoteConvertRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.OrderItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/quotes/{id}/line-items": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the quote's curated line items (upgrades, added/removed options, standard features) and the configured building summary.", "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Get line items for a quote", "parameters": [ { "type": "string", "description": "Quote id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.LineItemsResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Adds one upgrade line (product reference + quantity/price) to the quote. Idempotent on lineKey: re-sending the same key returns the existing line instead of duplicating it. Header pricing is not recalculated — PATCH the quote's pricing fields afterward.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Add a line item to a quote", "parameters": [ { "type": "string", "description": "Quote id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Line item", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.LineItemCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.LineItemCreateResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/quotes/{id}/line-items/{lineId}": { "delete": { "security": [ { "PartnerBearer": [] } ], "description": "Removes one upgrade line by its line id (from GET line-items or the add response). The base product line cannot be deleted. Header pricing is not recalculated — PATCH the quote's pricing fields afterward.", "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Delete a line item from a quote", "parameters": [ { "type": "string", "description": "Quote id (24-char hex)", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Line id", "name": "lineId", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/quotes/{id}/status": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Moves a quote between allowlisted statuses (Open → Active/Lost/Retired, Active → Lost/Retired, Lost → Active, Retired → Active). Other transitions are rejected.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Update a quote's status", "parameters": [ { "type": "string", "description": "Quote id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Target status", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.PartnerStatusRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.QuoteItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/quotes/{id}/status-history": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the quote's status transitions, newest first, with the acting user and action description.", "produces": [ "application/json" ], "tags": [ "partner-quotes" ], "summary": "Get status history for a quote", "parameters": [ { "type": "string", "description": "Quote id (24-char hex)", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.StatusHistoryResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/roles": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the company's assignable RBAC roles, for discovering valid roleId values for user create/update.", "produces": [ "application/json" ], "tags": [ "partner-users" ], "summary": "List roles", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.RolesResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/stock-templates": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the company's stock templates — buildable catalog designs (not physical inventory; see /lot-stock for on-lot units). Each entry carries images, pricing, public tags, and a structuraUrl deep link to the interactive 3D configurator view.", "produces": [ "application/json" ], "tags": [ "partner-inventory" ], "summary": "List stock templates", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 60)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive match on work-order number, template name, or product name", "name": "search", "in": "query" }, { "type": "string", "description": "Comma-separated public tags; templates must carry all of them", "name": "tags", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.StockTemplateListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/stock-templates/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one stock template by its work-order id. Ids belonging to another company (or non-template work orders) return 404.", "produces": [ "application/json" ], "tags": [ "partner-inventory" ], "summary": "Get a stock template", "parameters": [ { "type": "string", "description": "Stock template work-order id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.StockTemplateItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/users": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's users/salespeople with their location assignments and lead-routing pool membership.", "produces": [ "application/json" ], "tags": [ "partner-users" ], "summary": "List users", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on name or email", "name": "search", "in": "query" }, { "type": "boolean", "description": "Filter by active state", "name": "active", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.UserListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a company user (salesperson) through the portal's own pipeline: profile, RBAC role, location assignments, and the invitation email (default on). When the email belongs to an existing ShedCloud account, that account is linked to the company instead of duplicated. The user's Cognito login is created at their first sign-in via the invite — not by this call.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-users" ], "summary": "Create a user", "parameters": [ { "description": "User to create", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.UserCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.UserItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/users/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one company user by id. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-users" ], "summary": "Get a user", "parameters": [ { "type": "string", "description": "User id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.UserItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "patch": { "security": [ { "PartnerBearer": [] } ], "description": "Updates a company user: profile fields, RBAC role (roleId), location assignments (locationIds replaces; allLocations grants unrestricted access), and active (per-company enable/disable — the owner is protected). Empty/omitted fields are left untouched.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-users" ], "summary": "Update a user", "parameters": [ { "type": "string", "description": "User id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.UserPatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.UserItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/webhook-deliveries": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the delivery attempt log, newest first, optionally narrowed to one event or subscription. Rows are retained ~30 days.", "produces": [ "application/json" ], "tags": [ "partner-events" ], "summary": "List webhook delivery attempts", "parameters": [ { "type": "string", "description": "Filter by event id", "name": "eventId", "in": "query" }, { "type": "string", "description": "Filter by subscription id", "name": "subscriptionId", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.WebhookDeliveryListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/work-orders": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the authenticated company's work orders (owned and shared) with filtering, sorting, and pagination.", "produces": [ "application/json" ], "tags": [ "partner-work-orders" ], "summary": "List work orders", "parameters": [ { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Case-insensitive substring match on serial number, title, customer name, or work order number", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status (e.g. Open build, Build in process, Finished good, Delivered)", "name": "status", "in": "query" }, { "type": "string", "description": "Building location id or slug", "name": "location", "in": "query" }, { "type": "string", "description": "Filter by serial number (substring)", "name": "serialNumber", "in": "query" }, { "type": "integer", "description": "Filter by linked sales order number", "name": "orderNumber", "in": "query" }, { "type": "string", "description": "Filter by linked sales order id (24-char hex)", "name": "linkedOrderId", "in": "query" }, { "type": "string", "description": "Filter by external reference, key:value exact match", "name": "externalRef", "in": "query" }, { "type": "string", "description": "Created on/after (RFC 3339 or YYYY-MM-DD)", "name": "createdFrom", "in": "query" }, { "type": "string", "description": "Created on/before (RFC 3339 or YYYY-MM-DD)", "name": "createdTo", "in": "query" }, { "type": "string", "description": "Updated on/after (RFC 3339 or YYYY-MM-DD)", "name": "updatedFrom", "in": "query" }, { "type": "string", "description": "Updated on/before (RFC 3339 or YYYY-MM-DD)", "name": "updatedTo", "in": "query" }, { "type": "string", "default": "createdAt", "description": "Sort field: workOrderNumber | serialNumber | status | createdAt | updatedAt", "name": "sort", "in": "query" }, { "type": "string", "default": "desc", "description": "Sort direction: asc | desc", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.WorkOrderListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "post": { "security": [ { "PartnerBearer": [] } ], "description": "Creates a manufacturing work order the same way the portal's building wizard does: status starts in \"Customer Care\", the work order number is allocated automatically, and the friendly type enums map to the internal build-type flags. An optional sizeId attaches a product size (creating the manufacturing BOM unless purchaseType is existing-physical-inventory). Serial numbers are enforced unique per company. Send an Idempotency-Key header to make retries safe.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-work-orders" ], "summary": "Create a work order", "parameters": [ { "type": "string", "description": "Unique key making the create retry-safe", "name": "Idempotency-Key", "in": "header" }, { "description": "Work order payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.WorkOrderCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/partnerapi.WorkOrderItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/work-orders/{id}": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns one work order by id. Ids belonging to another company return 404.", "produces": [ "application/json" ], "tags": [ "partner-work-orders" ], "summary": "Get a work order", "parameters": [ { "type": "string", "description": "Work order id (24-char hex)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.WorkOrderItem" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } }, "patch": { "security": [ { "PartnerBearer": [] } ], "description": "Updates allowlisted work order fields (title, description, buildingLocation, promisedDate). No serial number changes in v1.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-work-orders" ], "summary": "Update a work order", "parameters": [ { "type": "string", "description": "Work order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.WorkOrderPatchRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.WorkOrderItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/work-orders/{id}/status": { "post": { "security": [ { "PartnerBearer": [] } ], "description": "Moves a work order along the production flow: Open build → Build in process → Finished good → Delivered. Other transitions (including \"Requested materials\", which transfers inventory) are rejected.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "partner-work-orders" ], "summary": "Update a work order's status", "parameters": [ { "type": "string", "description": "Work order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "description": "Target status", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/partnerapi.PartnerStatusRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.WorkOrderItem" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } }, "/partner/v1/work-orders/{id}/status-history": { "get": { "security": [ { "PartnerBearer": [] } ], "description": "Returns the work order's status transitions, newest first, with the acting user and action description.", "produces": [ "application/json" ], "tags": [ "partner-status-history" ], "summary": "Get status history for a work order", "parameters": [ { "type": "string", "description": "Work order id (24-char hex)", "name": "id", "in": "path", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 50, "description": "Page size (max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/partnerapi.StatusHistoryResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/partnerapi.ErrorResponse" } } } } } }, "definitions": { "partnerapi.BuildingConfiguration": { "type": "object", "properties": { "model": { "type": "string" }, "roofColor": { "type": "string" }, "roofMaterial": { "type": "string" }, "siding": { "type": "string" }, "sidingColor": { "type": "string" }, "trimColor": { "type": "string" } } }, "partnerapi.ConfiguratorSessionCreateRequest": { "type": "object", "properties": { "customerId": { "description": "CustomerID optionally attaches an existing customer (create one first\nvia POST /partner/v1/customers). Ids from another company 404.", "type": "string" }, "locationId": { "type": "string" }, "quoteId": { "description": "QuoteID reopens an existing quote's saved design.", "type": "string" }, "returnUrl": { "description": "ReturnURL must match the company's allowlisted origins\n(Settings \u003e Developer API). Passed through to Structura so the shopper\ncan be sent back to the partner's site after saving.", "type": "string" }, "serialNumber": { "type": "string" }, "ttlSeconds": { "type": "integer" }, "workOrderId": { "description": "WorkOrderID / SerialNumber launch an in-stock building's design.", "type": "string" } } }, "partnerapi.ConfiguratorSessionResponse": { "type": "object", "properties": { "customerId": { "type": "string" }, "expiresAt": { "type": "string" }, "launchUrl": { "description": "LaunchURL is the single-use link to hand to the shopper. Opening it\nconsumes the token and redirects into the configurator.", "type": "string" }, "quoteId": { "type": "string" }, "sessionId": { "type": "string" } } }, "partnerapi.ContractSummary": { "type": "object", "properties": { "contractNumber": { "type": "string" }, "contractVersion": { "description": "short code allocated per signature request", "type": "string" }, "customerSigned": { "type": "boolean" }, "customerSignedAt": { "type": "string" }, "orderId": { "type": "string" }, "salespersonSigned": { "type": "boolean" }, "salespersonSignedAt": { "type": "string" }, "signedPdfDocumentId": { "description": "SignedPdfDocumentId references the stored contract PDF, usable against\nGET /partner/v1/documents/{id}/download.", "type": "string" }, "status": { "description": "Status: draft | out_for_signature | partially_signed | completed", "type": "string" } } }, "partnerapi.CustomerCreateRequest": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "code": { "type": "string" }, "contactName": { "type": "string" }, "contactPerson": { "type": "string" }, "email": { "type": "string" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string" }, "phone": { "type": "string" }, "state": { "type": "string" }, "zipCode": { "type": "string" } } }, "partnerapi.CustomerItem": { "type": "object", "properties": { "active": { "type": "boolean" }, "address": { "type": "string" }, "city": { "type": "string" }, "code": { "type": "string" }, "contactName": { "type": "string" }, "contactPerson": { "type": "string" }, "createdAt": { "type": "string" }, "email": { "type": "string" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "id": { "type": "string" }, "merged": { "description": "Merge lineage: a merged duplicate keeps resolving by id but carries\nmerged=true and points at the surviving record.", "type": "boolean" }, "mergedAt": { "type": "string" }, "mergedInto": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "state": { "type": "string" }, "updatedAt": { "type": "string" }, "version": { "type": "integer" }, "zipCode": { "type": "string" } } }, "partnerapi.CustomerListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.CustomerItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.CustomerMergeRequest": { "type": "object", "properties": { "survivorId": { "description": "SurvivorID is the customer that absorbs the duplicate in the path.", "type": "string" } } }, "partnerapi.CustomerMergeResponse": { "type": "object", "properties": { "mergedCustomerId": { "description": "MergedCustomerId is the loser's id — it now resolves with merged=true\nand mergedInto pointing at the survivor.", "type": "string" }, "relinkedSalesEntities": { "description": "RelinkedSalesEntities counts the leads/quotes/orders moved to the\nsurvivor.", "type": "integer" }, "survivor": { "$ref": "#/definitions/partnerapi.CustomerItem" } } }, "partnerapi.CustomerPatchRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "address": { "type": "string" }, "city": { "type": "string" }, "code": { "type": "string" }, "contactName": { "type": "string" }, "contactPerson": { "type": "string" }, "email": { "type": "string" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string" }, "phone": { "type": "string" }, "state": { "type": "string" }, "zipCode": { "type": "string" } } }, "partnerapi.DocumentDownloadResponse": { "type": "object", "properties": { "downloadUrl": { "type": "string" }, "expiresAt": { "type": "string" }, "fileName": { "type": "string" } } }, "partnerapi.DocumentItem": { "type": "object", "properties": { "createdAt": { "type": "string" }, "fileName": { "type": "string" }, "id": { "type": "string" }, "mimeType": { "type": "string" }, "name": { "type": "string" }, "sizeBytes": { "type": "integer" }, "type": { "description": "stored category, e.g. Contract", "type": "string" } } }, "partnerapi.DocumentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.DocumentItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.DomainItem": { "type": "object", "properties": { "apexDomain": { "type": "string" }, "integrationId": { "description": "IntegrationID is the DNS integration record the subdomain belongs to.", "type": "string" }, "locations": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.DomainLocation" } }, "subdomain": { "type": "string" }, "verified": { "description": "Verified reports whether the subdomain's DNS records have been\nverified (per-subdomain check, falling back to the integration flag).", "type": "boolean" } } }, "partnerapi.DomainListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.DomainItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.DomainLocation": { "type": "object", "properties": { "code": { "type": "string" }, "defaultForStore": { "description": "DefaultForStore marks this domain as the location's default storefront\ndomain. A location has at most one default domain across all domains.", "type": "boolean" }, "hidePrices": { "description": "HidePrices hides pricing for this location on this domain's storefront.", "type": "boolean" }, "locationId": { "type": "string" }, "name": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.DomainProduct" } } } }, "partnerapi.DomainProduct": { "type": "object", "properties": { "excludedUpgrades": { "description": "ExcludedUpgrades are upgrade ids hidden for this product on this domain.", "type": "array", "items": { "type": "string" } }, "productId": { "type": "string" }, "sizes": { "description": "Sizes are the size ids enabled for this product on this domain.", "type": "array", "items": { "type": "string" } } } }, "partnerapi.ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "partnerapi.EventItem": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "id": { "type": "string" }, "occurredAt": { "type": "string" }, "resourceId": { "type": "string" }, "resourceType": { "type": "string" }, "resourceUrl": { "type": "string" }, "resourceVersion": { "type": "integer" }, "type": { "type": "string" } } }, "partnerapi.EventListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.EventItem" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } } }, "partnerapi.EventRedeliverResponse": { "type": "object", "properties": { "enqueued": { "type": "integer" }, "eventId": { "type": "string" } } }, "partnerapi.LeadCreateCustomer": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "partnerapi.LeadCreateRequest": { "type": "object", "properties": { "customer": { "$ref": "#/definitions/partnerapi.LeadCreateCustomer" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "locationId": { "type": "string" }, "salespersonEmail": { "type": "string" }, "salespersonName": { "type": "string" } } }, "partnerapi.LeadItem": { "type": "object", "properties": { "createdAt": { "type": "string" }, "customer": { "$ref": "#/definitions/partnerapi.PartnerCustomer" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "id": { "type": "string" }, "location": { "$ref": "#/definitions/partnerapi.PartnerLocation" }, "orderNumber": { "type": "integer" }, "salesperson": { "$ref": "#/definitions/partnerapi.PartnerSalesperson" }, "status": { "type": "string" }, "statusChangedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "version": { "type": "integer" } } }, "partnerapi.LeadListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.LeadItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.LeadPatchRequest": { "type": "object", "properties": { "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "salesLocation": { "type": "string" }, "salespersonEmail": { "type": "string" }, "salespersonName": { "type": "string" } } }, "partnerapi.LineItem": { "type": "object", "properties": { "amount": { "type": "number" }, "category": { "type": "string" }, "colorName": { "type": "string" }, "id": { "type": "string" }, "isStandardFeature": { "type": "boolean" }, "name": { "type": "string" }, "productId": { "type": "string" }, "quantity": { "type": "number" }, "side": { "type": "string" }, "status": { "description": "included | added | removed", "type": "string" } } }, "partnerapi.LineItemCreateRequest": { "type": "object", "properties": { "lineKey": { "description": "LineKey makes the add idempotent: re-sending the same key returns the\nexisting line (200) instead of duplicating it. Generated when omitted.", "type": "string" }, "price": { "type": "number" }, "productId": { "type": "string" }, "quantity": { "description": "default 1", "type": "number" } } }, "partnerapi.LineItemCreateResponse": { "type": "object", "properties": { "created": { "description": "Created is false when the lineKey matched an existing line.", "type": "boolean" }, "lineId": { "type": "string" }, "price": { "type": "number" }, "productId": { "type": "string" }, "quantity": { "type": "number" } } }, "partnerapi.LineItemTotals": { "type": "object", "properties": { "added": { "type": "integer" }, "included": { "type": "integer" }, "removed": { "type": "integer" } } }, "partnerapi.LineItemsResponse": { "type": "object", "properties": { "configuration": { "$ref": "#/definitions/partnerapi.BuildingConfiguration" }, "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.LineItem" } }, "totals": { "$ref": "#/definitions/partnerapi.LineItemTotals" } } }, "partnerapi.LocationCreateRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "address": { "type": "string" }, "city": { "type": "string" }, "code": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPerson": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": "string" }, "phone": { "type": "string" }, "plant": { "type": "boolean" }, "salesLot": { "type": "boolean" }, "slug": { "type": "string" }, "state": { "type": "string" }, "zipCode": { "type": "string" } } }, "partnerapi.LocationItem": { "type": "object", "properties": { "active": { "type": "boolean" }, "address": { "type": "string" }, "city": { "type": "string" }, "code": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPerson": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": "string" }, "phone": { "type": "string" }, "plant": { "type": "boolean" }, "region": { "description": "Region is a dealer-defined grouping label (e.g. \"Southeast\"). Quotes\nand orders derive their region through their sales location.", "type": "string" }, "salesLot": { "type": "boolean" }, "slug": { "type": "string" }, "state": { "type": "string" }, "storeHours": { "description": "StoreHours is the weekly open/close schedule keyed by day\n(\"mon\"..\"sun\"). Omitted when the location has no schedule configured.", "type": "object", "additionalProperties": { "$ref": "#/definitions/partnerapi.StoreHoursDay" } }, "timezone": { "description": "Timezone is the company-level IANA timezone (locations don't carry\ntheir own yet). Store hours are interpreted in this zone.", "type": "string" }, "updatedAt": { "type": "string" }, "zipCode": { "type": "string" } } }, "partnerapi.LocationListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.LocationItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.LocationPatchRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "address": { "type": "string" }, "city": { "type": "string" }, "code": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPerson": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": "string" }, "phone": { "type": "string" }, "plant": { "type": "boolean" }, "salesLot": { "type": "boolean" }, "slug": { "type": "string" }, "state": { "type": "string" }, "zipCode": { "type": "string" } } }, "partnerapi.LotStockAttributes": { "type": "object", "properties": { "roofColor": { "type": "string" }, "roofMaterial": { "type": "string" }, "siding": { "type": "string" }, "sidingColor": { "type": "string" }, "trimColor": { "type": "string" } } }, "partnerapi.LotStockItem": { "type": "object", "properties": { "attributes": { "description": "Attributes is the building's exterior configuration (siding, colors,\nroof) — the same values the work-order detail page shows. Omitted when\nthe unit has no configurator.", "allOf": [ { "$ref": "#/definitions/partnerapi.LotStockAttributes" } ] }, "basePrice": { "type": "number" }, "id": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "locationSlug": { "type": "string" }, "price": { "type": "number" }, "purchaseType": { "type": "string" }, "serialNumber": { "type": "string" }, "sold": { "type": "boolean" }, "title": { "type": "string" }, "workOrderId": { "type": "string" } } }, "partnerapi.LotStockResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.LotStockItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.MeRateLimit": { "type": "object", "properties": { "burst": { "type": "integer" }, "requestsPerSecond": { "type": "integer" } } }, "partnerapi.MeResponse": { "type": "object", "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "credentialType": { "description": "CredentialType is \"api_key\" or \"oauth_client\".", "type": "string" }, "rateLimit": { "$ref": "#/definitions/partnerapi.MeRateLimit" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "partnerapi.OrderCreateLineItem": { "type": "object", "properties": { "lineKey": { "description": "LineKey is an optional stable per-line identifier; generated when\nomitted. Shows up as the line id on GET line-items and is the handle\nfor DELETE line-items.", "type": "string" }, "price": { "type": "number" }, "productId": { "type": "string" }, "quantity": { "description": "default 1", "type": "number" } } }, "partnerapi.OrderCreateRequest": { "type": "object" }, "partnerapi.OrderItem": { "type": "object", "properties": { "createdAt": { "type": "string" }, "customer": { "$ref": "#/definitions/partnerapi.PartnerCustomer" }, "deliveredAt": { "type": "string" }, "deposits": { "$ref": "#/definitions/partnerapi.PartnerDeposits" }, "expectedDeliveryDate": { "type": "string" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "id": { "type": "string" }, "location": { "$ref": "#/definitions/partnerapi.PartnerLocation" }, "orderNumber": { "type": "integer" }, "pricing": { "$ref": "#/definitions/partnerapi.PartnerPricing" }, "rto": { "$ref": "#/definitions/partnerapi.PartnerRTO" }, "salesperson": { "$ref": "#/definitions/partnerapi.PartnerSalesperson" }, "serialNumber": { "type": "string" }, "sourceQuoteId": { "type": "string" }, "sourceQuoteNumber": { "type": "integer" }, "status": { "type": "string" }, "statusChangedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "version": { "type": "integer" }, "workOrderId": { "type": "string" } } }, "partnerapi.OrderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.OrderItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.PartnerCustomer": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "partnerapi.PartnerDelivery": { "type": "object", "properties": { "deliveredAt": { "type": "string" }, "driverName": { "type": "string" }, "runNumber": { "type": "integer" }, "runStatus": { "description": "Open | Scheduled | En Route | Delivered", "type": "string" }, "scheduledDate": { "description": "per-stop delivery date on the run assignment", "type": "string" } } }, "partnerapi.PartnerDeposits": { "type": "object", "properties": { "balance": { "type": "number" }, "downPayment": { "type": "number" }, "securityDeposit": { "type": "number" }, "totalDueToday": { "type": "number" }, "totalPaid": { "type": "number" } } }, "partnerapi.PartnerLocation": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "partnerapi.PartnerPricing": { "type": "object", "properties": { "changeOrderFee": { "type": "number" }, "monthlyPayment": { "type": "number" }, "paymentType": { "description": "rto | cash", "type": "string" }, "subtotal": { "type": "number" }, "total": { "type": "number" } } }, "partnerapi.PartnerRTO": { "type": "object", "properties": { "balance": { "type": "number" }, "damageWaiver": { "type": "number" }, "downPayment": { "type": "number" }, "monthlyPayment": { "type": "number" }, "providerName": { "type": "string" }, "rent": { "type": "number" }, "securityDeposit": { "type": "number" }, "termMonths": { "type": "integer" }, "totalDueToday": { "type": "number" } } }, "partnerapi.PartnerSalesperson": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } } }, "partnerapi.PartnerStatusRequest": { "type": "object", "properties": { "actionDescription": { "type": "string" }, "status": { "type": "string" } } }, "partnerapi.PaymentCreateRequest": { "type": "object", "properties": { "amount": { "type": "number" }, "bankName": { "description": "BankName applies to method \"financed\" only.", "type": "string" }, "checkNumber": { "description": "CheckNumber applies to method \"check\" only.", "type": "string" }, "description": { "description": "Description shows on the payment record (defaults to \"\u003cMethod\u003e payment\").", "type": "string" }, "method": { "description": "Method is one of: cash, check, financed, manual.", "type": "string" } } }, "partnerapi.PaymentItem": { "type": "object", "properties": { "amount": { "type": "number" }, "createdAt": { "type": "string" }, "customerId": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "method": { "description": "card | ach | cash | check | financed | manual", "type": "string" }, "orderId": { "type": "string" }, "providerReference": { "description": "ProviderReference is the Stripe checkout-session or payment-intent id\nfor card/ACH payments; empty for manual records.", "type": "string" }, "refundedAmount": { "type": "number" }, "refundedAt": { "type": "string" }, "status": { "description": "Open | pending | processing | paid | payment failed | Refunded | Canceled", "type": "string" } } }, "partnerapi.PaymentLinkCreateRequest": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "description": "Currency defaults to \"usd\".", "type": "string" }, "email": { "description": "Email overrides the order's customer email as the link recipient.", "type": "string" }, "name": { "description": "Name labels the Stripe Checkout line item (defaults to \"Order #\u003cn\u003e\").", "type": "string" }, "sendEmail": { "description": "SendEmail controls the customer payment-link email (default true).", "type": "boolean" } } }, "partnerapi.PaymentLinkResponse": { "type": "object", "properties": { "emailSent": { "description": "EmailSent reports whether the payment-link email was queued.", "type": "boolean" }, "expiresAt": { "type": "string" }, "sessionId": { "type": "string" }, "url": { "type": "string" } } }, "partnerapi.PaymentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.PaymentItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.ProductCreateRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "description": { "type": "string" }, "length": { "type": "number" }, "lineId": { "description": "LineID links the new product under an existing product line (parent\nproduct) via the finished-good relationship.", "type": "string" }, "name": { "type": "string" }, "price": { "type": "number" }, "sku": { "type": "string" }, "width": { "type": "number" } } }, "partnerapi.ProductItem": { "type": "object", "properties": { "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "images": { "description": "Images are ready-to-use public URLs from the product's gallery,\nfalling back to the legacy image slots on the product record.", "type": "array", "items": { "type": "string" } }, "length": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number" }, "sku": { "type": "string" }, "updatedAt": { "type": "string" }, "width": { "type": "number" } } }, "partnerapi.ProductListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.ProductItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.ProductPatchRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "description": { "type": "string" }, "length": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number" }, "sku": { "type": "string" }, "width": { "type": "number" } } }, "partnerapi.ProductSizeCreateRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "length": { "type": "number" }, "name": { "description": "Name defaults to \"\u003cwidth\u003ex\u003clength\u003e\" when omitted.", "type": "string" }, "price": { "type": "number" }, "sku": { "type": "string" }, "width": { "type": "number" } } }, "partnerapi.ProductSizeItem": { "type": "object", "properties": { "active": { "type": "boolean" }, "id": { "type": "string" }, "length": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number" }, "productId": { "type": "string" }, "sku": { "type": "string" }, "width": { "type": "number" } } }, "partnerapi.QuoteConvertRequest": { "type": "object", "properties": { "salespersonEmail": { "type": "string" }, "salespersonName": { "description": "Optional salesperson overrides; fall back to whatever the quote has.", "type": "string" } } }, "partnerapi.QuoteCreateCustomer": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "partnerapi.QuoteCreateDeliveryAddress": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "state": { "type": "string" }, "zipCode": { "type": "string" } } }, "partnerapi.QuoteCreateRequest": { "type": "object", "properties": { "customer": { "$ref": "#/definitions/partnerapi.QuoteCreateCustomer" }, "deliveryAddress": { "$ref": "#/definitions/partnerapi.QuoteCreateDeliveryAddress" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "locationId": { "type": "string" }, "note": { "type": "string" }, "price": { "type": "number" }, "purchaseType": { "type": "string" }, "serialNumber": { "type": "string" }, "workOrderId": { "type": "string" } } }, "partnerapi.QuoteItem": { "type": "object", "properties": { "converted": { "type": "boolean" }, "convertedOrderId": { "type": "string" }, "convertedOrderNumber": { "type": "integer" }, "createdAt": { "type": "string" }, "customer": { "$ref": "#/definitions/partnerapi.PartnerCustomer" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "id": { "type": "string" }, "location": { "$ref": "#/definitions/partnerapi.PartnerLocation" }, "orderNumber": { "type": "integer" }, "pricing": { "$ref": "#/definitions/partnerapi.PartnerPricing" }, "rto": { "$ref": "#/definitions/partnerapi.PartnerRTO" }, "salesperson": { "$ref": "#/definitions/partnerapi.PartnerSalesperson" }, "serialNumber": { "type": "string" }, "status": { "type": "string" }, "statusChangedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "validUntil": { "description": "ValidUntil: when this date passes while the quote is still Open/Active,\na quote.expired event is emitted (daily sweep). Settable via PATCH.", "type": "string" }, "version": { "type": "integer" }, "workOrderId": { "type": "string" } } }, "partnerapi.QuoteListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.QuoteItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.RoleItem": { "type": "object", "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "isSystem": { "type": "boolean" }, "key": { "type": "string" }, "name": { "type": "string" } } }, "partnerapi.RolesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.RoleItem" } } } }, "partnerapi.SalesOrderPatchRequest": { "type": "object", "properties": { "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "deliveryAddress": { "type": "string" }, "deliveryCity": { "type": "string" }, "deliveryState": { "type": "string" }, "deliveryZipCode": { "type": "string" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "salesLocation": { "type": "string" }, "salespersonEmail": { "type": "string" }, "salespersonName": { "type": "string" } } }, "partnerapi.StatusChangeActor": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } } }, "partnerapi.StatusChangeItem": { "type": "object", "properties": { "actor": { "$ref": "#/definitions/partnerapi.StatusChangeActor" }, "changedAt": { "type": "string" }, "description": { "type": "string" }, "previousStatus": { "type": "string" }, "status": { "type": "string" } } }, "partnerapi.StatusHistoryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.StatusChangeItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.StockTemplateItem": { "type": "object", "properties": { "basePrice": { "description": "Prices mirror the public gallery: base price, upgrades total, and the\ntotal of removed standard features.", "type": "number" }, "configuratorId": { "description": "ConfiguratorID is the template's 3D configuration; StructuraURL\ndeep-links the interactive 3D view of it.", "type": "string" }, "description": { "type": "string" }, "descriptionHtml": { "type": "string" }, "id": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "productId": { "type": "string" }, "productName": { "type": "string" }, "removedPrice": { "type": "number" }, "sizeId": { "type": "string" }, "structuraUrl": { "type": "string" }, "tags": { "description": "Tags are the template's public tags (internal tags are never exposed).", "type": "array", "items": { "type": "string" } }, "templateName": { "type": "string" }, "upgradesPrice": { "type": "number" }, "workOrderNumber": { "type": "string" } } }, "partnerapi.StockTemplateListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.StockTemplateItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.StoreHoursDay": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "partnerapi.TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" }, "token_type": { "type": "string" } } }, "partnerapi.UserCreateRequest": { "type": "object", "properties": { "allLocations": { "type": "boolean" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "invite": { "description": "Invite controls the invitation email (default true).", "type": "boolean" }, "lastName": { "type": "string" }, "locationIds": { "description": "LocationIDs restricts the user to specific locations; AllLocations\ngrants the unrestricted assignment instead. Mutually exclusive.", "type": "array", "items": { "type": "string" } }, "phone": { "type": "string" }, "roleId": { "description": "RoleID references a company RBAC role — discover ids via GET /partner/v1/roles.", "type": "string" } } }, "partnerapi.UserItem": { "type": "object", "properties": { "active": { "type": "boolean" }, "allLocations": { "type": "boolean" }, "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "inLeadRoutingPool": { "type": "boolean" }, "locationIds": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "partnerapi.UserListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.UserItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.UserPatchRequest": { "type": "object", "properties": { "active": { "description": "Active enables/disables the user's membership in this company. The\ncompany owner cannot be disabled.", "type": "boolean" }, "allLocations": { "type": "boolean" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "locationIds": { "description": "LocationIDs, when present, REPLACES the user's location assignments.", "type": "array", "items": { "type": "string" } }, "phone": { "type": "string" }, "roleId": { "type": "string" } } }, "partnerapi.WebhookDeliveryItem": { "type": "object", "properties": { "attempt": { "type": "integer" }, "deliveredAt": { "type": "string" }, "durationMs": { "type": "integer" }, "error": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "id": { "type": "string" }, "ok": { "type": "boolean" }, "statusCode": { "type": "integer" }, "subscriptionId": { "type": "string" }, "url": { "type": "string" } } }, "partnerapi.WebhookDeliveryListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.WebhookDeliveryItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.WorkOrderCreateRequest": { "type": "object", "properties": { "deliveryType": { "description": "delivery-from-factory | built-on-site | delivered-from-dealer | delivered-from-lot-stock", "type": "string" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "locationId": { "description": "required: building location id or slug", "type": "string" }, "promisedDate": { "type": "string" }, "purchaseType": { "description": "new-build | existing-physical-inventory | general | stock", "type": "string" }, "serialNumber": { "description": "optional; uniqueness enforced (409)", "type": "string" }, "sizeId": { "description": "optional product size to attach", "type": "string" }, "title": { "type": "string" }, "workOrderType": { "description": "made-to-order | lot-stock | rental-return | immediate-sale | template", "type": "string" } } }, "partnerapi.WorkOrderItem": { "type": "object", "properties": { "basePrice": { "type": "number" }, "createdAt": { "type": "string" }, "delivery": { "description": "detail endpoint only", "allOf": [ { "$ref": "#/definitions/partnerapi.PartnerDelivery" } ] }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "id": { "type": "string" }, "location": { "$ref": "#/definitions/partnerapi.PartnerLocation" }, "orderId": { "description": "linked sales order", "type": "string" }, "orderNumber": { "description": "linked sales order number", "type": "integer" }, "promisedDate": { "type": "string" }, "serialNumber": { "type": "string" }, "status": { "type": "string" }, "statusChangedAt": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": "string" }, "version": { "type": "integer" }, "workOrderNumber": { "type": "integer" } } }, "partnerapi.WorkOrderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/partnerapi.WorkOrderItem" } }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "partnerapi.WorkOrderPatchRequest": { "type": "object", "properties": { "buildingLocation": { "type": "string" }, "description": { "type": "string" }, "externalReferences": { "type": "object", "additionalProperties": { "type": "string" } }, "promisedDate": { "type": "string" }, "title": { "type": "string" } } } }, "securityDefinitions": { "BasicAuth": { "type": "basic" }, "PartnerBearer": { "description": "API key or OAuth access token, e.g. \"Bearer sc_live_...\" or \"Bearer sc_at_...\".", "type": "apiKey", "name": "Authorization", "in": "header" } } }