{ "openapi": "3.0.0", "paths": { "/": { "get": { "operationId": "AppController_getHello", "parameters": [], "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "App" ] } }, "/health": { "get": { "operationId": "AppController_health", "parameters": [], "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "App" ] } }, "/provider/offers": { "post": { "description": "Create a new service offering as a provider. The offer will be associated with your team.", "operationId": "ProviderOffersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOfferDto" } } } }, "responses": { "201": { "description": "Offer successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Provider role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "An offer with the same SKU already exists (SKUs are unique)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Create a new offer", "tags": [ "provider-offers" ] }, "get": { "description": "Retrieve all offers created by your provider team.", "operationId": "ProviderOffersController_findAll", "parameters": [], "responses": { "200": { "description": "List of offers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResponse" } } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List all your offers", "tags": [ "provider-offers" ] } }, "/provider/offers/{id}": { "get": { "description": "Retrieve details of a specific offer you created.", "operationId": "ProviderOffersController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Offer not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get a specific offer", "tags": [ "provider-offers" ] }, "patch": { "description": "Update an existing offer. You can only update your own offers.", "operationId": "ProviderOffersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOfferDto" } } } }, "responses": { "200": { "description": "Offer successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Offer not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "An offer with the same SKU already exists (SKUs are unique)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Update an offer", "tags": [ "provider-offers" ] }, "delete": { "description": "Permanently delete an offer. You can only delete your own offers.", "operationId": "ProviderOffersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offer successfully deleted" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Offer not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Delete an offer", "tags": [ "provider-offers" ] } }, "/provider/offers/{id}/publish": { "post": { "description": "Validate an offer against the publish-readiness rules and, if it passes, set its status to active. Returns 400 with structured validationErrors when the offer is not ready to publish.", "operationId": "ProviderOffersController_publish", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offer published (status: active)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferResponse" } } } }, "400": { "description": "Offer failed publish validation. Unlike a DTO validation failure, this body carries one entry per unmet publish rule in `validationErrors`, plus the same rules grouped by editor section in `sections`.", "content": { "application/json": { "schema": { "title": "Publish Validation Error", "type": "object", "required": [ "error", "message", "validationErrors" ], "properties": { "error": { "type": "string", "example": "Validation failed" }, "message": { "type": "string", "example": "Please fix 2 validation issues before publishing." }, "validationErrors": { "type": "array", "description": "One entry per unmet publish rule.", "items": { "type": "object", "required": [ "section", "field", "message" ], "properties": { "section": { "type": "string", "description": "Editor section the field belongs to, e.g. \"pricing\".", "example": "pricing" }, "field": { "type": "string", "description": "Dot-delimited path to the offending field.", "example": "monthlyPrice" }, "message": { "type": "string", "example": "Monthly price is required" } } } }, "sections": { "type": "object", "description": "The same errors keyed by section, for rendering inline in a form.", "additionalProperties": true } } } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Offer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Publish an offer", "tags": [ "provider-offers" ] } }, "/provider/offers/{id}/duplicate": { "post": { "description": "Create a new draft offer pre-filled from an existing one. The copy gets a \"(Copy)\" name, resets to draft status, omits the unique SKU, and strips known sample pricing entries.", "operationId": "ProviderOffersController_duplicate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Duplicated offer (new draft)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Offer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Duplicate an offer", "tags": [ "provider-offers" ] } }, "/provider/offers/bulk-upload/template": { "get": { "description": "Download a CSV template file with headers and an example row. Use this template to bulk upload offers.", "operationId": "ProviderOffersController_downloadTemplate", "parameters": [], "responses": { "200": { "description": "CSV template file", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Download CSV template for bulk offer upload", "tags": [ "provider-offers" ] } }, "/provider/offers/bulk-upload": { "post": { "description": "Upload a CSV file to create multiple offers at once. Download the template first using GET /bulk-upload/template. The CSV supports linking offers to markets using the \"marketNames\" column (comma-separated market names). Markets must already exist before uploading - create them first via the markets API.", "operationId": "ProviderOffersController_bulkUpload", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file with offer data (use the template from GET /bulk-upload/template)" } } } } } }, "responses": { "201": { "description": "Bulk upload completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUploadResultDto" } } } }, "400": { "description": "Invalid CSV file or validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Bulk upload offers from CSV", "tags": [ "provider-offers" ] } }, "/provider/offers/bulk-upload/validate": { "post": { "description": "Upload a CSV file to validate its structure and data without actually creating offers. This is useful for checking your CSV before performing the actual bulk upload.", "operationId": "ProviderOffersController_validateCsv", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file to validate" } } } } } }, "responses": { "200": { "description": "Validation results", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "rowCount": { "type": "number" } } } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Validate CSV file without creating offers", "tags": [ "provider-offers" ] } }, "/provider/offers/bulk-update": { "post": { "description": "Upload a CSV file to update multiple existing offers at once, using the same template as bulk upload (GET /bulk-upload/template). Each row is matched to an existing offer by its \"sku\" column (scoped to your team), so \"sku\" is required on every row. Blank cells leave the existing value unchanged — only non-blank columns are applied — which means this endpoint cannot clear a field back to empty. Rows whose SKU does not match one of your offers are reported as errors and never created.", "operationId": "ProviderOffersController_bulkUpdate", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file with offer data (use the template from GET /bulk-upload/template)" } } } } } }, "responses": { "201": { "description": "Bulk update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateResultDto" } } } }, "400": { "description": "Invalid CSV file or validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Bulk update offers from CSV", "tags": [ "provider-offers" ] } }, "/provider/offers/bulk-update/validate": { "post": { "description": "Upload a CSV file to validate it against the bulk-update rules without writing anything. Checks that every row has a \"sku\" matching one of your offers and that any non-blank enum, numeric, and market values are valid.", "operationId": "ProviderOffersController_validateUpdateCsv", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file to validate" } } } } } }, "responses": { "200": { "description": "Validation results", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "rowCount": { "type": "number" } } } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Validate a bulk-update CSV without updating offers", "tags": [ "provider-offers" ] } }, "/provider/orders": { "get": { "description": "Retrieve all order items for your offers that need fulfillment. Each item represents a single offer ordered by a reseller.", "operationId": "ProviderOrdersController_findAll", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "Filter by order item status", "schema": { "enum": [ "pending", "submitted_to_provider", "accepted", "rejected", "scheduled", "in_progress", "completed", "active", "cancelled", "failed" ], "type": "string" } } ], "responses": { "200": { "description": "List of order items" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List order items to fulfill", "tags": [ "provider-orders" ] } }, "/provider/orders/{itemId}": { "get": { "description": "Retrieve detailed information about a specific order item for fulfillment.", "operationId": "ProviderOrdersController_findOne", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order item details" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order item not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get order item details", "tags": [ "provider-orders" ] } }, "/provider/orders/{itemId}/status": { "patch": { "description": "Update the fulfillment status of an order item (e.g., accept, reject, schedule, complete). Use this to manage the order workflow from acceptance to completion.", "operationId": "ProviderOrdersController_updateStatus", "parameters": [ { "name": "itemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemStatusDto" } } } }, "responses": { "200": { "description": "Order item status successfully updated" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order item not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Update order item status", "tags": [ "provider-orders" ] } }, "/provider/markets": { "post": { "operationId": "ProviderMarketsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMarketDto" } } } }, "responses": { "201": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Create a market", "tags": [ "provider-markets" ] }, "get": { "operationId": "ProviderMarketsController_findAll", "parameters": [], "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List all markets for your team", "tags": [ "provider-markets" ] } }, "/provider/markets/{id}": { "get": { "operationId": "ProviderMarketsController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get a market by id", "tags": [ "provider-markets" ] }, "patch": { "operationId": "ProviderMarketsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMarketDto" } } } }, "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Update a market", "tags": [ "provider-markets" ] }, "delete": { "operationId": "ProviderMarketsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Delete a market", "tags": [ "provider-markets" ] } }, "/provider/markets/{id}/areas": { "post": { "description": "Areas compose a market. Supply the `type` field and the matching fields: postalCodes (postal), admin* fields (admin), geometry (polygon), h3Cells (h3), or sourceRef (serviceability — must name an active serviceability integration source owned by your team). Use operation=exclude to carve a hole out of the market.", "operationId": "ProviderMarketsController_addArea", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertMarketAreaDto" } } } }, "responses": { "201": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Add a geographic area to a market", "tags": [ "provider-markets" ] } }, "/provider/markets/{id}/areas/{areaId}": { "delete": { "operationId": "ProviderMarketsController_removeArea", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "areaId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Remove an area from a market", "tags": [ "provider-markets" ] } }, "/provider/customers": { "get": { "description": "Customers are people who have placed an order for one of your offers. This list does not include reseller-side leads.", "operationId": "ProviderCustomersController_findAll", "parameters": [], "responses": { "200": { "description": "List of customers" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List customers", "tags": [ "provider-customers" ] } }, "/provider/customers/{customerId}": { "get": { "description": "Detail view of a customer including the order items they have placed for your offers.", "operationId": "ProviderCustomersController_findOne", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer detail" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get customer detail", "tags": [ "provider-customers" ] } }, "/provider/webhooks": { "post": { "description": "Register an HTTPS endpoint to receive signed order-event deliveries. The response includes the signing secret — it is shown only this once.", "operationId": "ProviderWebhooksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookDto" } } } }, "responses": { "201": { "description": "The webhook, including its signing secret" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Register a webhook", "tags": [ "provider-webhooks" ] }, "get": { "description": "Secrets are masked — the full value is only ever returned at creation.", "operationId": "ProviderWebhooksController_findAll", "parameters": [], "responses": { "200": { "description": "Your webhooks, newest first" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List your registered webhooks", "tags": [ "provider-webhooks" ] } }, "/provider/webhooks/{id}": { "get": { "operationId": "ProviderWebhooksController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The webhook, without its signing secret" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get a webhook by id", "tags": [ "provider-webhooks" ] }, "patch": { "operationId": "ProviderWebhooksController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookDto" } } } }, "responses": { "200": { "description": "The updated webhook" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Update a webhook (url, subscribed events, or active state)", "tags": [ "provider-webhooks" ] }, "delete": { "operationId": "ProviderWebhooksController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Delete a webhook", "tags": [ "provider-webhooks" ] } }, "/provider/webhooks/{id}/deliveries": { "get": { "operationId": "ProviderWebhooksController_listDeliveries", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent delivery attempts, newest first" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List recent delivery attempts for a webhook", "tags": [ "provider-webhooks" ] } }, "/provider/brands": { "post": { "description": "Brands are the visual identity offers display under instead of your team name. Each team manages its own brands; names are matched case-insensitively within the team.", "operationId": "ProviderBrandsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrandDto" } } } }, "responses": { "201": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name already used by your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Create a brand", "tags": [ "provider-brands" ] }, "get": { "operationId": "ProviderBrandsController_findAll", "parameters": [], "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List all brands for your team", "tags": [ "provider-brands" ] } }, "/provider/brands/{id}": { "get": { "operationId": "ProviderBrandsController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get a brand by id", "tags": [ "provider-brands" ] }, "patch": { "description": "Renaming or re-logoing a brand changes it for every offer displaying it. Sending an empty imageUrl clears the logo.", "operationId": "ProviderBrandsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrandDto" } } } }, "responses": { "200": { "description": "The updated brand" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name already used by your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Update a brand", "tags": [ "provider-brands" ] }, "delete": { "description": "Only brands no offer references can be deleted.", "operationId": "ProviderBrandsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand deleted" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Brand is in use by offers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Delete an unused brand", "tags": [ "provider-brands" ] } }, "/team/api-keys": { "get": { "description": "Lists the authenticated team's API keys (values are obfuscated).", "operationId": "TeamApiKeysController_list", "parameters": [], "responses": { "200": { "description": "API keys for the team" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "team-api-key": [] } ], "summary": "List API keys", "tags": [ "team api keys" ] }, "post": { "description": "Creates a new API key for the authenticated team. The full key value is returned only in this response.", "operationId": "TeamApiKeysController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamApiKeyDto" } } } }, "responses": { "201": { "description": "The created API key" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "team-api-key": [] } ], "summary": "Create an API key", "tags": [ "team api keys" ] } }, "/team/api-keys/{id}": { "delete": { "description": "Permanently deletes one of the team's API keys. Requests using it will immediately fail authentication.", "operationId": "TeamApiKeysController_revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "API key id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The key was deleted" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Key not found for this team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "team-api-key": [] } ], "summary": "Revoke an API key", "tags": [ "team api keys" ] } }, "/team/members": { "get": { "description": "Lists the team's active members and pending invitations.", "operationId": "TeamMembersController_list", "parameters": [], "responses": { "200": { "description": "Members and pending invitations" }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "team-api-key": [] } ], "summary": "List team members", "tags": [ "team members" ] } }, "/team/members/invitations": { "post": { "description": "Sends an email invitation to join the team. The invitee becomes an active member once they accept.", "operationId": "TeamMembersController_invite", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteTeamMemberDto" } } } }, "responses": { "201": { "description": "The created invitation" }, "400": { "description": "Invalid email, or the address is already a member/invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "team-api-key": [] } ], "summary": "Invite a team member", "tags": [ "team members" ] } }, "/team/members/invitations/{id}": { "delete": { "description": "Revokes one of the team's pending invitations.", "operationId": "TeamMembersController_revokeInvitation", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Invitation id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The invitation was revoked" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Invitation not found for this team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "team-api-key": [] } ], "summary": "Revoke an invitation", "tags": [ "team members" ] } }, "/team/members/{membershipId}": { "delete": { "description": "Removes a member from the team. They immediately lose access to team resources.", "operationId": "TeamMembersController_removeMember", "parameters": [ { "name": "membershipId", "required": true, "in": "path", "description": "Organization membership id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The member was removed" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Member not found for this team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "team-api-key": [] } ], "summary": "Remove a team member", "tags": [ "team members" ] } }, "/reseller/catalog": { "get": { "description": "Browse all service offers available to your reseller team. Visibility is based on provider settings (all resellers, preferred resellers, or selected resellers). Supports filtering by category, price range, ZIP code, and search terms. Results are sorted by relevance!", "operationId": "ResellerCatalogController_findAll", "parameters": [ { "name": "category", "required": false, "in": "query", "description": "Filter by service category", "schema": { "example": "internet", "type": "string", "enum": [ "internet", "electricity", "other" ] } }, { "name": "minPrice", "required": false, "in": "query", "description": "Minimum monthly price", "schema": { "example": 0, "type": "number" } }, { "name": "maxPrice", "required": false, "in": "query", "description": "Maximum monthly price", "schema": { "example": 100, "type": "number" } }, { "name": "zipCode", "required": false, "in": "query", "description": "ZIP code to check availability", "schema": { "example": "94102", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search term (searches name, description, marketing headline)", "schema": { "example": "fiber internet", "type": "string" } } ], "responses": { "200": { "description": "List of available offers" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Browse available offers", "tags": [ "reseller-catalog" ] } }, "/reseller/catalog/{id}": { "get": { "description": "Retrieve detailed information about a specific offer in the catalog. You can only view offers that are available to your reseller team.", "operationId": "ResellerCatalogController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offer details" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Offer not found or not available to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get offer details", "tags": [ "reseller-catalog" ] } }, "/reseller/availability": { "post": { "description": "Given a service address, returns every offer your reseller team can sell at that location. Coverage is evaluated against each offer’s availability rules — postal codes and active market areas (including state-wide and city-level coverage) — and provider visibility settings (all resellers, preferred resellers, or selected resellers). This is the same availability logic used by shareable checkout links, exposed as a dedicated address-driven endpoint. Results are returned both as a flat list and grouped by category for checkout UIs.", "operationId": "ResellerAvailabilityController_findAvailable", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckAvailabilityDto" } } } }, "responses": { "200": { "description": "Offers available at the given address" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Find available offers for an address", "tags": [ "reseller-availability" ] } }, "/reseller/orders": { "post": { "description": "Create a new order for one or more service offers. Each offer will be sent to its respective provider for fulfillment. You can only order offers that are available to your reseller team.", "operationId": "ResellerOrdersController_create", "parameters": [ { "name": "idempotency-key", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Client-generated key for this checkout attempt. A repeat request with the same key (e.g. a network retry or double-click) returns the original order instead of creating a duplicate.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderDto" } } } }, "responses": { "201": { "description": "Order successfully created" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "One or more offers are not available to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Place a new order", "tags": [ "reseller-orders" ] }, "get": { "description": "Retrieve all orders placed by your reseller team. Includes order items and their fulfillment status.", "operationId": "ResellerOrdersController_findAll", "parameters": [], "responses": { "200": { "description": "List of orders" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List your orders", "tags": [ "reseller-orders" ] } }, "/reseller/orders/{id}": { "get": { "description": "Retrieve detailed information about a specific order, including all items and their fulfillment status.", "operationId": "ResellerOrdersController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order details" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get order details", "tags": [ "reseller-orders" ] } }, "/reseller/orders/{id}/cancel": { "patch": { "description": "Cancel a pending or submitted order. Orders can only be cancelled if they have not been accepted by providers.", "operationId": "ResellerOrdersController_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order successfully cancelled" }, "400": { "description": "Order cannot be cancelled in its current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Cancel an order", "tags": [ "reseller-orders" ] } }, "/reseller/links": { "post": { "description": "Generate a shareable link for tenants to order services at a specific address. The link can be shared via email or SMS. Tenants can use the link to browse available offers and place orders without needing to create an account.", "operationId": "ResellerLinksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLinkDto" } } } }, "responses": { "201": { "description": "Link successfully created" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Create a shareable link", "tags": [ "reseller-links" ] }, "get": { "description": "Retrieve all shareable links created by your reseller team. Includes view and order counts for analytics.", "operationId": "ResellerLinksController_findAll", "parameters": [], "responses": { "200": { "description": "List of links" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List all shareable links", "tags": [ "reseller-links" ] } }, "/reseller/links/{id}": { "get": { "description": "Retrieve detailed information about a specific link, including recent orders placed via the link.", "operationId": "ResellerLinksController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Link details" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Link not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get link details", "tags": [ "reseller-links" ] }, "patch": { "description": "Update link properties such as property name, move-in date, or status. Set status to \"inactive\" to disable a link without deleting it.", "operationId": "ResellerLinksController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLinkDto" } } } }, "responses": { "200": { "description": "Link successfully updated" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Link not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Update a link", "tags": [ "reseller-links" ] }, "delete": { "description": "Permanently delete a shareable link. Orders placed via this link will be preserved.", "operationId": "ResellerLinksController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Link successfully deleted" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Link not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Delete a link", "tags": [ "reseller-links" ] } }, "/reseller/customers": { "get": { "description": "Returns this reseller team's customers (people who have placed an order) and leads (people added manually, by API import, or by event). Filter via the kind query param.", "operationId": "ResellerCustomersController_findAll", "parameters": [ { "name": "kind", "required": false, "in": "query", "schema": { "enum": [ "lead", "customer" ], "type": "string" } } ], "responses": { "200": { "description": "List of customers" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List customers and leads", "tags": [ "reseller-customers" ] }, "post": { "description": "Create a new lead or customer record. Resellers use this to track contacts from off-platform sources before they place an order.", "operationId": "ResellerCustomersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerDto" } } } }, "responses": { "201": { "description": "Customer created" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A record for this person already exists in your list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Add a customer or lead manually", "tags": [ "reseller-customers" ] } }, "/reseller/customers/{customerId}": { "get": { "operationId": "ResellerCustomersController_findOne", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer detail" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get customer detail (with this reseller's orders)", "tags": [ "reseller-customers" ] }, "patch": { "description": "Update reseller-private fields. To update the underlying contact info (name, email, address) the contact themselves must place a new order, since those fields are shared across all teams that know this person.", "operationId": "ResellerCustomersController_update", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerDto" } } } }, "responses": { "200": { "description": "Customer updated" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Update customer notes / tags / status / kind", "tags": [ "reseller-customers" ] }, "delete": { "description": "Removes the link between this reseller and the customer. The shared Customer record itself is preserved so other teams' views are unaffected.", "operationId": "ResellerCustomersController_remove", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer removed" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Remove customer from this reseller's list", "tags": [ "reseller-customers" ] } }, "/reseller/webhooks": { "post": { "description": "Register an HTTPS endpoint to receive signed order-event deliveries for orders your team placed. The response includes the signing secret — it is shown only this once.", "operationId": "ResellerWebhooksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookDto" } } } }, "responses": { "201": { "description": "The webhook, including its signing secret" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Register a webhook", "tags": [ "reseller-webhooks" ] }, "get": { "description": "Secrets are masked — the full value is only ever returned at creation.", "operationId": "ResellerWebhooksController_findAll", "parameters": [], "responses": { "200": { "description": "Your webhooks, newest first" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List your registered webhooks", "tags": [ "reseller-webhooks" ] } }, "/reseller/webhooks/{id}": { "get": { "operationId": "ResellerWebhooksController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The webhook, without its signing secret" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get a webhook by id", "tags": [ "reseller-webhooks" ] }, "patch": { "operationId": "ResellerWebhooksController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookDto" } } } }, "responses": { "200": { "description": "The updated webhook" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Update a webhook (url, subscribed events, or active state)", "tags": [ "reseller-webhooks" ] }, "delete": { "operationId": "ResellerWebhooksController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "Delete a webhook", "tags": [ "reseller-webhooks" ] } }, "/reseller/webhooks/{id}/deliveries": { "get": { "description": "The 50 most recent attempts, newest first. Every attempt is logged whether it succeeded or failed — start here when a delivery appears to be missing.", "operationId": "ResellerWebhooksController_listDeliveries", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent delivery attempts, newest first" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found or does not belong to your team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "api-key": [] } ], "summary": "List recent delivery attempts for a webhook", "tags": [ "reseller-webhooks" ] } }, "/public/links/{slug}": { "get": { "description": "Retrieve public information about a shareable link, including the service address and property name. This endpoint does not require authentication.", "operationId": "PublicLinksController_findBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "The unique link identifier (from the URL)", "schema": { "example": "abc123", "type": "string" } } ], "responses": { "200": { "description": "Link details" }, "400": { "description": "Link is no longer active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get link details", "tags": [ "public" ] } }, "/public/links/{slug}/offers": { "get": { "description": "Retrieve all service offers available for the address associated with this link. Offers are grouped by category (internet, electricity, other). This endpoint does not require authentication.", "operationId": "PublicLinksController_getOffers", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "The unique link identifier (from the URL)", "schema": { "example": "abc123", "type": "string" } } ], "responses": { "200": { "description": "Available offers grouped by category" }, "400": { "description": "Link is no longer active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get available offers for a link", "tags": [ "public" ] } }, "/public/links/{slug}/orders": { "post": { "description": "Create a new order for the selected service offers. The order will be associated with the reseller who created the link. This endpoint does not require authentication.", "operationId": "PublicLinksController_createOrder", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "The unique link identifier (from the URL)", "schema": { "example": "abc123", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicOrderDto" } } } }, "responses": { "201": { "description": "Order successfully created" }, "400": { "description": "Invalid order data or link is inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Submit an order via a shareable link", "tags": [ "public" ] } }, "/public/shop/offers": { "get": { "description": "Returns active, consumer-enabled offers, optionally filtered by ZIP/city/state (coverage-checked through the offer's markets) and category. Unauthenticated — backs the public /shop storefront.", "operationId": "PublicShopController_listOffers", "parameters": [ { "name": "zip", "required": false, "in": "query", "description": "ZIP code to browse", "schema": { "example": "78701", "type": "string" } }, { "name": "city", "required": false, "in": "query", "schema": { "example": "Austin", "type": "string" } }, { "name": "state", "required": false, "in": "query", "schema": { "example": "TX", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "internet", "type": "string", "enum": [ "internet", "electricity", "other" ] } } ], "responses": { "200": { "description": "Matching consumer offers" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Browse consumer-enabled offers", "tags": [ "public" ] } }, "/public/shop/offers/{publicSlug}": { "get": { "description": "Full pricing/compliance detail for one consumer-enabled offer. Pass `zip` to re-check coverage for that ZIP. Unauthenticated.", "operationId": "PublicShopController_getOffer", "parameters": [ { "name": "publicSlug", "required": true, "in": "path", "schema": { "example": "fiber-500-by-acme", "type": "string" } }, { "name": "zip", "required": false, "in": "query", "description": "ZIP the shopper is browsing from — when present, the response includes an `available` flag re-checking coverage for this specific ZIP.", "schema": { "example": "78701", "type": "string" } } ], "responses": { "200": { "description": "Offer detail" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Offer not found or not consumer-enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Get a consumer offer by its public slug", "tags": [ "public" ] } }, "/public/shop/serviceability": { "post": { "description": "Given a full street address, returns per-offer serviceability + exact price for offers whose markets reference an external serviceability source. Layered on top of ZIP coverage (not a gate) — offers without a source are simply absent from the result map. Unauthenticated.", "operationId": "PublicShopController_checkServiceability", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopServiceabilityDto" } } } }, "responses": { "200": { "description": "Per-offer serviceability detail keyed by offer id" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Check address-level serviceability for on-screen offers", "tags": [ "public" ] } }, "/public/shop/orders": { "post": { "description": "Creates an order through the canonical transactional path (idempotent, snapshotted, outbox-emitting), attributed to the house reseller team. Re-checks coverage against the submitted address; unauthenticated.", "operationId": "PublicShopController_createOrder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShopOrderDto" } } } }, "responses": { "201": { "description": "Order created (or the original, on idempotent replay)" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "One or more offers are no longer available at this address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Shop checkout is not configured (house reseller team unset)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Place a checkout-mode shop order", "tags": [ "public" ] } }, "/public/shop/clicks": { "post": { "description": "Logs a click for a consumer offer — a lead_gen click returns a redirectUrl (the provider URL with Offergrid attribution merged on); a checkout-mode click is fire-and-forget funnel logging with no redirect. Unauthenticated, lightly rate-limited per IP.", "operationId": "PublicShopController_createClick", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShopClickDto" } } } }, "responses": { "201": { "description": "Click recorded" }, "401": { "description": "Missing, malformed, or revoked `x-api-key` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Valid API key, but your team's role does not grant access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Offer not found or not consumer-enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server error. Safe to retry idempotent requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Record an outbound shop click", "tags": [ "public" ] } } }, "info": { "title": "OfferGrid API", "description": "Complete B2B marketplace API connecting service providers with reseller partners. Streamlines distribution and sale of essential services like internet and electricity.\n\n## API Organization\n\nThe API is organized by context (provider vs reseller) to make it clear which operations are available to each role:\n\n**Provider Endpoints** (`/provider/*`)\n- Create and manage your service offerings\n- View and fulfill orders from resellers\n- Manage reseller relationships\n\n**Reseller Endpoints** (`/reseller/*`)\n- Browse available service offerings (catalog)\n- Place orders on behalf of customers\n- Track order status and fulfillment\n\n**Hybrid Teams** can access both provider and reseller endpoints with the same API key.", "version": "1.0", "contact": {} }, "tags": [ { "name": "provider-offers", "description": "Provider: Manage your service offerings" }, { "name": "provider-orders", "description": "Provider: Fulfill orders from resellers" }, { "name": "reseller-catalog", "description": "Reseller: Browse available service offerings" }, { "name": "reseller-availability", "description": "Reseller: Find offers available at a service address" }, { "name": "reseller-orders", "description": "Reseller: Place and manage orders" }, { "name": "reseller-customers", "description": "Reseller: Manage customers and leads" }, { "name": "reseller-links", "description": "Reseller: Manage shareable customer links" }, { "name": "reseller-webhooks", "description": "Reseller: Receive order events for the orders you placed" }, { "name": "links", "description": "Partner links management" } ], "servers": [ { "url": "https://api.offergrid.io", "description": "Production" } ], "components": { "securitySchemes": { "api-key": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Team API key for authentication. Your team role (provider/reseller/hybrid) determines which endpoints you can access." } }, "schemas": { "CreateOfferDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Public-facing name of the offer", "example": "High-Speed Internet 1000 Mbps" }, "internalName": { "type": "string", "description": "Internal name for tracking (not shown to customers)", "example": "HSI-1000-Q4-2024" }, "category": { "type": "string", "description": "Service category", "enum": [ "internet", "electricity", "other" ], "example": "internet" }, "status": { "type": "string", "description": "Current status of the offer", "enum": [ "draft", "active", "inactive", "archived" ], "example": "draft", "default": "draft" }, "sku": { "type": "string", "description": "Stock Keeping Unit (SKU) - must be unique", "example": "INT-1000-001" }, "externalId": { "type": "string", "description": "External system identifier", "example": "ext-12345" }, "externalProductKey": { "type": "string", "description": "Identifier of this offer's product in the provider's serviceability source. When the source returns several products for an address, this selects the one whose price/plan is shown for this offer; offers sharing a market can therefore each surface their own address-level pricing. Leave unset to use the source's default (payload-level) projection.", "example": "FIBER-500" }, "metadata": { "type": "object", "description": "Custom metadata as JSON object", "example": { "tags": [ "fiber", "residential" ], "priority": 1 } }, "description": { "type": "string", "description": "Detailed description of the offer", "example": "Blazing fast fiber internet with unlimited data" }, "internalDescription": { "type": "string", "description": "Internal notes and description", "example": "Q4 promotional offer for new markets" }, "marketingHeadline": { "type": "string", "description": "Marketing headline", "example": "Get Lightning-Fast Internet Today!" }, "marketingDescription": { "type": "string", "description": "Marketing description", "example": "Experience the future of connectivity with our fiber-optic network" }, "keyFeatures": { "description": "Array of key features", "example": [ "1000 Mbps download", "Unlimited data", "No contract" ], "type": "array", "items": { "type": "string" } }, "imageUrl": { "type": "string", "description": "URL to offer image", "example": "https://cdn.example.com/offers/internet-1000.jpg" }, "overview": { "type": "string", "description": "Detailed overview of the offer", "example": "This package includes installation, router, and 24/7 support" }, "brandId": { "type": "string", "description": "Id of one of your team brands (see /provider/brands) to display the offer under. Takes precedence over brandName. Send null on update to clear the brand and fall back to the provider team identity.", "example": "a3f1c9c2-7f42-4b6e-9a8e-2f0d5c6b1e77" }, "brandName": { "type": "string", "description": "Brand display name. When set, buyer-facing surfaces show this brand's name/logo instead of the owning provider team — used to load offers under another company's identity. If your team has no brand with this name it is created; matching is case/space-insensitive within your team. Falls back to the provider team name when omitted. Ignored when brandId is set.", "example": "Direct Energy" }, "brandImageUrl": { "type": "string", "description": "Brand logo URL. Only used to set the image when the brand is first created (or when an existing brand has no image); it never overwrites an existing brand logo.", "example": "https://logo.clearbit.com/directenergy.com" }, "submissionUrl": { "type": "string", "description": "URL for order submission", "example": "https://provider.example.com/api/orders" }, "submissionConfig": { "type": "object", "description": "Submission configuration including form fields", "example": { "formFields": [ { "name": "address", "type": "text", "required": true }, { "name": "phone", "type": "tel", "required": true } ], "metadata": [] } }, "electricity": { "allOf": [ { "$ref": "#/components/schemas/ElectricityContractWrite" } ], "description": "Structured electricity contract — the only way to set an electricity offer’s pricing, term, plan and disclosures. Folded into storage server-side. Grouped as rate / term / plan / disclosures." }, "internet": { "allOf": [ { "$ref": "#/components/schemas/InternetContractWrite" } ], "description": "Structured internet contract — the only way to set an internet offer’s speed, data allowance, term and disclosures. Folded into storage server-side. Grouped as speed / data / term / disclosures." }, "pricingType": { "type": "string", "description": "Pricing type", "enum": [ "fixed", "variable", "tiered", "custom" ], "example": "fixed" }, "monthlyPrice": { "type": "number", "description": "Monthly recurring price", "example": 59.99, "minimum": 0 }, "marketNames": { "description": "Scope the offer to one or more existing markets by NAME. Each name must match an existing market on your team (create markets separately via the markets API). Mirrors the CSV bulk-upload `marketNames` column so a JSON integration and the CSV path use the same identifier. Use `marketIds` if you already have market IDs. Cannot be combined with `marketIds`.", "example": [ "Texas — Oncor", "Texas — CenterPoint" ], "type": "array", "items": { "type": "string" } }, "marketIds": { "description": "Scope the offer to one or more existing markets by ID. Each id must belong to a market on your team. Prefer `marketNames` when you have the market name (matches the CSV column and is easier to author). Cannot be combined with `marketNames`.", "example": [ "b1c8d1e2-..." ], "type": "array", "items": { "type": "string" } }, "consumerEnabled": { "type": "boolean", "description": "Publish this offer to the public /shop consumer storefront. Defaults to false — nothing appears in the shop without explicit opt-in. Independent of reseller (B2B) access.", "example": true }, "consumerMode": { "type": "string", "description": "How a consumer-enabled offer converts on the shop. `checkout`: the shopper completes the order inside Offergrid. `lead_gen`: the CTA logs a click and redirects to your own `leadGenUrl` with attribution params; Offergrid creates no order. Required (enforced at publish) when consumerEnabled is true. Send null to clear.", "enum": [ "lead_gen", "checkout" ], "example": "lead_gen" }, "leadGenUrl": { "type": "string", "description": "Partner signup URL template for `lead_gen` offers — where the shop CTA sends the shopper. Must be an https:// URL and may embed {{variable}} placeholders in query-parameter values, rendered from collected customer data at handoff. Supported variables: first_name, last_name, full_name, email, phone, street, unit, city, state, zip, esiid, start_date, action (move/switch), tdsp_duns, click_id, offer_external_id. The full template (https, allowlisted variables, placeholders only in query values) is validated when the offer is published. Send null to clear.", "example": "https://partner.example.com/signup?ref=offergrid&fname={{first_name}}&zip={{zip}}" } }, "required": [ "name" ], "title": "Create Offer Request" }, "UpdateOfferDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Public-facing name of the offer", "example": "High-Speed Internet 1000 Mbps" }, "internalName": { "type": "string", "description": "Internal name for tracking (not shown to customers)", "example": "HSI-1000-Q4-2024" }, "category": { "type": "string", "description": "Service category", "enum": [ "internet", "electricity", "other" ], "example": "internet" }, "status": { "type": "string", "description": "Current status of the offer", "enum": [ "draft", "active", "inactive", "archived" ], "example": "draft", "default": "draft" }, "sku": { "type": "string", "description": "Stock Keeping Unit (SKU) - must be unique", "example": "INT-1000-001" }, "externalId": { "type": "string", "description": "External system identifier", "example": "ext-12345" }, "externalProductKey": { "type": "string", "description": "Identifier of this offer's product in the provider's serviceability source. When the source returns several products for an address, this selects the one whose price/plan is shown for this offer; offers sharing a market can therefore each surface their own address-level pricing. Leave unset to use the source's default (payload-level) projection.", "example": "FIBER-500" }, "metadata": { "type": "object", "description": "Custom metadata as JSON object", "example": { "tags": [ "fiber", "residential" ], "priority": 1 } }, "description": { "type": "string", "description": "Detailed description of the offer", "example": "Blazing fast fiber internet with unlimited data" }, "internalDescription": { "type": "string", "description": "Internal notes and description", "example": "Q4 promotional offer for new markets" }, "marketingHeadline": { "type": "string", "description": "Marketing headline", "example": "Get Lightning-Fast Internet Today!" }, "marketingDescription": { "type": "string", "description": "Marketing description", "example": "Experience the future of connectivity with our fiber-optic network" }, "keyFeatures": { "description": "Array of key features", "example": [ "1000 Mbps download", "Unlimited data", "No contract" ], "type": "array", "items": { "type": "string" } }, "imageUrl": { "type": "string", "description": "URL to offer image", "example": "https://cdn.example.com/offers/internet-1000.jpg" }, "overview": { "type": "string", "description": "Detailed overview of the offer", "example": "This package includes installation, router, and 24/7 support" }, "brandId": { "type": "string", "description": "Id of one of your team brands (see /provider/brands) to display the offer under. Takes precedence over brandName. Send null on update to clear the brand and fall back to the provider team identity.", "example": "a3f1c9c2-7f42-4b6e-9a8e-2f0d5c6b1e77" }, "brandName": { "type": "string", "description": "Brand display name. When set, buyer-facing surfaces show this brand's name/logo instead of the owning provider team — used to load offers under another company's identity. If your team has no brand with this name it is created; matching is case/space-insensitive within your team. Falls back to the provider team name when omitted. Ignored when brandId is set.", "example": "Direct Energy" }, "brandImageUrl": { "type": "string", "description": "Brand logo URL. Only used to set the image when the brand is first created (or when an existing brand has no image); it never overwrites an existing brand logo.", "example": "https://logo.clearbit.com/directenergy.com" }, "submissionUrl": { "type": "string", "description": "URL for order submission", "example": "https://provider.example.com/api/orders" }, "submissionConfig": { "type": "object", "description": "Submission configuration including form fields", "example": { "formFields": [ { "name": "address", "type": "text", "required": true }, { "name": "phone", "type": "tel", "required": true } ], "metadata": [] } }, "electricity": { "allOf": [ { "$ref": "#/components/schemas/ElectricityContractWrite" } ], "description": "Structured electricity contract — the only way to set an electricity offer’s pricing, term, plan and disclosures. Folded into storage server-side. Grouped as rate / term / plan / disclosures." }, "internet": { "allOf": [ { "$ref": "#/components/schemas/InternetContractWrite" } ], "description": "Structured internet contract — the only way to set an internet offer’s speed, data allowance, term and disclosures. Folded into storage server-side. Grouped as speed / data / term / disclosures." }, "pricingType": { "type": "string", "description": "Pricing type", "enum": [ "fixed", "variable", "tiered", "custom" ], "example": "fixed" }, "monthlyPrice": { "type": "number", "description": "Monthly recurring price", "example": 59.99, "minimum": 0 }, "marketNames": { "description": "Scope the offer to one or more existing markets by NAME. Each name must match an existing market on your team (create markets separately via the markets API). Mirrors the CSV bulk-upload `marketNames` column so a JSON integration and the CSV path use the same identifier. Use `marketIds` if you already have market IDs. Cannot be combined with `marketIds`.", "example": [ "Texas — Oncor", "Texas — CenterPoint" ], "type": "array", "items": { "type": "string" } }, "marketIds": { "description": "Scope the offer to one or more existing markets by ID. Each id must belong to a market on your team. Prefer `marketNames` when you have the market name (matches the CSV column and is easier to author). Cannot be combined with `marketNames`.", "example": [ "b1c8d1e2-..." ], "type": "array", "items": { "type": "string" } }, "consumerEnabled": { "type": "boolean", "description": "Publish this offer to the public /shop consumer storefront. Defaults to false — nothing appears in the shop without explicit opt-in. Independent of reseller (B2B) access.", "example": true }, "consumerMode": { "type": "string", "description": "How a consumer-enabled offer converts on the shop. `checkout`: the shopper completes the order inside Offergrid. `lead_gen`: the CTA logs a click and redirects to your own `leadGenUrl` with attribution params; Offergrid creates no order. Required (enforced at publish) when consumerEnabled is true. Send null to clear.", "enum": [ "lead_gen", "checkout" ], "example": "lead_gen" }, "leadGenUrl": { "type": "string", "description": "Partner signup URL template for `lead_gen` offers — where the shop CTA sends the shopper. Must be an https:// URL and may embed {{variable}} placeholders in query-parameter values, rendered from collected customer data at handoff. Supported variables: first_name, last_name, full_name, email, phone, street, unit, city, state, zip, esiid, start_date, action (move/switch), tdsp_duns, click_id, offer_external_id. The full template (https, allowlisted variables, placeholders only in query values) is validated when the offer is published. Send null to clear.", "example": "https://partner.example.com/signup?ref=offergrid&fname={{first_name}}&zip={{zip}}" } }, "title": "Update Offer Request" }, "BulkUploadResultDto": { "type": "object", "properties": { "totalRows": { "type": "number", "description": "Total rows processed" }, "successCount": { "type": "number", "description": "Number of successfully created offers" }, "errorCount": { "type": "number", "description": "Number of failed offers" }, "createdOfferIds": { "description": "Created offer IDs", "type": "array", "items": { "type": "string" } }, "errors": { "description": "Detailed errors for failed rows", "type": "array", "items": { "type": "object" } }, "warnings": { "description": "Warnings for all rows", "type": "array", "items": { "type": "object" } } }, "required": [ "totalRows", "successCount", "errorCount", "createdOfferIds", "errors" ], "title": "Bulk Upload Result" }, "BulkUpdateResultDto": { "type": "object", "properties": { "totalRows": { "type": "number", "description": "Total rows processed" }, "successCount": { "type": "number", "description": "Number of successfully updated offers" }, "errorCount": { "type": "number", "description": "Number of failed rows" }, "updatedOfferIds": { "description": "Updated offer IDs", "type": "array", "items": { "type": "string" } }, "errors": { "description": "Detailed errors for failed rows", "type": "array", "items": { "type": "object" } }, "warnings": { "description": "Warnings for all rows", "type": "array", "items": { "type": "object" } } }, "required": [ "totalRows", "successCount", "errorCount", "updatedOfferIds", "errors" ], "title": "Bulk Update Result" }, "UpdateItemStatusDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "submitted_to_provider", "accepted", "rejected", "scheduled", "in_progress", "completed", "active", "cancelled", "failed" ], "description": "New status for the order item", "example": "accepted" }, "providerNotes": { "type": "string", "description": "Notes from provider about this status update", "example": "Installation scheduled for next Tuesday" }, "scheduledFor": { "type": "string", "description": "Scheduled date/time for installation or activation (ISO 8601)", "example": "2025-01-15T10:00:00Z" }, "metadata": { "type": "object", "description": "Additional metadata for this status update", "example": { "trackingNumber": "ABC123", "estimatedCompletion": "2025-01-20" } } }, "required": [ "status" ], "title": "Update Item Status Request" }, "CreateMarketDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Provider-facing market name. Unique per provider team.", "example": "Austin Metro" }, "description": { "type": "string", "description": "Optional description of the market.", "example": "Fiber footprint across Travis and Williamson counties." }, "status": { "type": "string", "description": "Lifecycle status.", "enum": [ "draft", "active", "paused", "archived" ], "default": "draft" }, "tags": { "description": "Free-form tags for grouping markets.", "example": [ "fiber", "priority" ], "type": "array", "items": { "type": "string" } } }, "required": [ "name" ], "title": "Create Market" }, "UpdateMarketDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Provider-facing market name. Unique per provider team.", "example": "Austin Metro" }, "description": { "type": "string", "description": "Optional description of the market.", "example": "Fiber footprint across Travis and Williamson counties." }, "status": { "type": "string", "description": "Lifecycle status.", "enum": [ "draft", "active", "paused", "archived" ], "default": "draft" }, "tags": { "description": "Free-form tags for grouping markets.", "example": [ "fiber", "priority" ], "type": "array", "items": { "type": "string" } } }, "title": "Update Market" }, "UpsertMarketAreaDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "postal", "admin", "polygon", "h3", "utility_territory", "serviceability" ] }, "operation": { "type": "string", "enum": [ "include", "exclude" ], "default": "include" }, "label": { "type": "string", "description": "Optional display label (e.g. \"Travis County\", \"78704 cluster\")." }, "postalCodes": { "example": [ "78701", "78702" ], "type": "array", "items": { "type": "string" } }, "postalCountry": { "type": "string", "example": "US" }, "adminLevel": { "type": "string", "enum": [ "state", "county", "city", "census_place" ] }, "adminCountry": { "type": "string", "example": "US" }, "adminState": { "type": "string", "example": "TX" }, "adminCounty": { "type": "string", "example": "Travis" }, "adminCity": { "type": "string", "example": "Austin" }, "adminGeoid": { "type": "string", "description": "Census GEOID for stable matching." }, "geometry": { "type": "object", "description": "GeoJSON Polygon or MultiPolygon." }, "h3Cells": { "type": "array", "items": { "type": "string" } }, "h3Resolution": { "type": "number", "example": 8 }, "utilityCodes": { "description": "TDSP/TDU DUNS codes, e.g. Oncor \"1039940674000\".", "example": [ "1039940674000" ], "type": "array", "items": { "type": "string" } }, "utilityCountry": { "type": "string", "example": "US" }, "sourceType": { "type": "string", "enum": [ "fabric_upload", "external_api" ] }, "sourceRef": { "type": "string", "description": "The IntegrationSource key this area resolves through. Required for serviceability areas, where it must name an active serviceability source owned by your team." }, "gating": { "type": "boolean", "description": "Serviceability areas only. true = the market covers an address only when this source answers on-net; false (default) = the source enriches offer detail but never hides the offer. An unanswerable lookup never gates.", "default": false } }, "required": [ "type" ], "title": "Upsert Market Area" }, "CreateWebhookDto": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS endpoint that will receive signed order-event deliveries", "example": "https://your-system.example.com/offergrid-callback" }, "events": { "type": "array", "description": "Event types this webhook subscribes to", "example": [ "order.item.created", "order.item.status_changed" ], "items": { "type": "string", "enum": [ "order.created", "order.item.created", "order.item.status_changed", "order.cancelled" ] } } }, "required": [ "url", "events" ], "title": "Create Webhook" }, "UpdateWebhookDto": { "type": "object", "properties": { "url": { "type": "string", "example": "https://your-system.example.com/offergrid-callback" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.created", "order.item.created", "order.item.status_changed", "order.cancelled" ] } }, "isActive": { "type": "boolean", "description": "Pause/resume deliveries without deleting the webhook" } }, "title": "Update Webhook" }, "CreateBrandDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name buyers see on offers using this brand. Matched case-insensitively within your team — creating a name your team already uses returns a conflict.", "example": "Direct Energy" }, "imageUrl": { "type": "string", "description": "Logo image URL shown on buyer-facing offer cards. Must serve an actual image; cards fall back to name initials when it fails to load.", "example": "https://cdn.example.com/logos/direct-energy.png" } }, "required": [ "name" ], "title": "Create Brand" }, "UpdateBrandDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name buyers see on offers using this brand. Matched case-insensitively within your team — creating a name your team already uses returns a conflict.", "example": "Direct Energy" }, "imageUrl": { "type": "string", "description": "Logo image URL shown on buyer-facing offer cards. Send an empty string to clear the logo (cards fall back to name initials).", "example": "https://cdn.example.com/logos/direct-energy.png" } }, "title": "Update Brand" }, "CreateTeamApiKeyDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Descriptive name for the API key" } }, "required": [ "name" ], "title": "Create Team Api Key" }, "InviteTeamMemberDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the person to invite" } }, "required": [ "email" ], "title": "Invite Team Member" }, "AddressDto": { "type": "object", "properties": { "street": { "type": "string", "example": "123 Main Street" }, "unit": { "type": "string", "example": "Unit 205" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "zipCode": { "type": "string", "example": "78701" }, "country": { "type": "string", "example": "US", "default": "US" } }, "required": [ "street", "city", "state", "zipCode", "country" ], "title": "Address" }, "CheckAvailabilityDto": { "type": "object", "properties": { "address": { "description": "Service address to check availability for", "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "category": { "type": "string", "enum": [ "internet", "electricity", "other" ], "description": "Only return offers in this service category", "example": "internet" }, "minPrice": { "type": "number", "description": "Minimum monthly price", "example": 0 }, "maxPrice": { "type": "number", "description": "Maximum monthly price", "example": 100 } }, "required": [ "address" ], "title": "Find Available Offers Request" }, "OrderItemDto": { "type": "object", "properties": { "offerId": { "type": "string", "description": "ID of the offer to order", "example": "123e4567-e89b-12d3-a456-426614174000" }, "metadata": { "type": "object", "description": "Per-item metadata stored on the resulting OrderItem. For electricity offers, carry enrollment details here so the provider can fulfill the enrollment.", "example": { "enrollment": { "enrollmentType": "switch", "esid": "10443720000000000", "requestedStartDate": "2026-07-15" } } } }, "required": [ "offerId" ], "title": "Order Item" }, "ServiceAddressDto": { "type": "object", "properties": { "street": { "type": "string", "example": "123 Main St" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "zipCode": { "type": "string", "example": "94102" }, "country": { "type": "string", "example": "US" } }, "required": [ "street", "city", "state", "zipCode", "country" ], "title": "Service Address" }, "CustomerInfoDto": { "type": "object", "properties": { "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "fullName": { "type": "string", "example": "John Doe", "description": "Legacy single-field name — prefer firstName + lastName. Required only when both are absent; split on the last space when used." }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+1-555-123-4567" } }, "required": [ "email", "phone" ], "title": "Customer Information" }, "CreateOrderDto": { "type": "object", "properties": { "items": { "description": "Array of items to order (offers)", "example": [ { "offerId": "123e4567-e89b-12d3-a456-426614174000" } ], "type": "array", "items": { "$ref": "#/components/schemas/OrderItemDto" } }, "serviceAddress": { "description": "Service address for installation", "allOf": [ { "$ref": "#/components/schemas/ServiceAddressDto" } ] }, "customerInfo": { "description": "Customer information", "allOf": [ { "$ref": "#/components/schemas/CustomerInfoDto" } ] }, "notes": { "type": "string", "description": "Additional notes for the order", "example": "Customer prefers morning installations" }, "metadata": { "type": "object", "description": "Additional metadata for the order", "example": { "referralSource": "property-listing", "unitNumber": "4B" } } }, "required": [ "items", "serviceAddress", "customerInfo" ], "title": "Create Order Request" }, "CreateLinkDto": { "type": "object", "properties": { "address": { "description": "Service address for the tenant", "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "propertyName": { "type": "string", "description": "Property name or description", "example": "Sunset Apartments Unit 205" }, "moveInDate": { "type": "string", "description": "Expected move-in date (ISO 8601)", "example": "2025-02-01" } }, "required": [ "address" ], "title": "Create Link Request" }, "UpdateLinkDto": { "type": "object", "properties": { "propertyName": { "type": "string", "description": "Property name or description", "example": "Sunset Apartments Unit 205" }, "moveInDate": { "type": "string", "description": "Expected move-in date (ISO 8601)", "example": "2025-02-01" }, "status": { "type": "string", "description": "Link status", "enum": [ "active", "inactive" ], "example": "active" } }, "title": "Update Link Request" }, "CreateCustomerDto": { "type": "object", "properties": { "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "fullName": { "type": "string", "example": "Jane Doe", "description": "Legacy single-field name — prefer firstName + lastName. Required only when both are absent; split on the last space when used." }, "email": { "type": "string", "example": "jane@example.com" }, "phone": { "type": "string", "example": "+1-555-123-4567" }, "addressLine1": { "type": "string", "example": "123 Main St" }, "addressLine2": { "type": "string", "example": "Apt 4B" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "postalCode": { "type": "string", "example": "94102" }, "country": { "type": "string", "example": "US" }, "kind": { "type": "string", "description": "Whether to track as a lead (pre-order) or as a customer.", "enum": [ "lead", "customer" ], "default": "lead" }, "source": { "type": "string", "description": "Where this contact came from.", "enum": [ "order", "link", "api_import", "manual", "event", "shop", "reseller" ], "default": "manual" }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "description": "Open-ended attributes (source URL, external IDs, etc.)", "example": { "sourceUrl": "https://example.com/listing/42" } } }, "title": "Create Customer" }, "UpdateCustomerDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lead", "customer" ] }, "status": { "type": "string", "enum": [ "active", "churned", "unsubscribed" ] }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "title": "Update Customer" }, "SelectedOfferDto": { "type": "object", "properties": { "offerId": { "type": "string", "description": "Offer ID to order", "example": "uuid-of-offer" } }, "required": [ "offerId" ], "title": "Selected Offer" }, "CreatePublicOrderDto": { "type": "object", "properties": { "customerInfo": { "description": "Customer contact information", "allOf": [ { "$ref": "#/components/schemas/CustomerInfoDto" } ] }, "items": { "description": "List of offers to order (one per category)", "type": "array", "items": { "$ref": "#/components/schemas/SelectedOfferDto" } }, "moveInDate": { "type": "string", "description": "Move-in date (ISO 8601)", "example": "2025-02-01" }, "notes": { "type": "string", "description": "Additional notes from the customer", "example": "Please contact me in the morning" }, "idempotencyKey": { "type": "string", "description": "Client-generated key for this checkout attempt. A repeat submission with the same key (e.g. a network retry or double-click on Submit) returns the original order instead of creating a duplicate.", "example": "a1b2c3d4-checkout-attempt" } }, "required": [ "customerInfo", "items" ], "title": "Create Public Order Request" }, "ShopServiceabilityDto": { "type": "object", "properties": { "street": { "type": "string", "example": "123 Main St" }, "unit": { "type": "string", "example": "Unit 4B" }, "zip": { "type": "string", "example": "78701" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "country": { "type": "string", "example": "US", "default": "US" }, "category": { "type": "string", "enum": [ "internet", "electricity", "other" ], "example": "internet" }, "offerIds": { "description": "Restrict the check to these offer ids (the cards on screen).", "type": "array", "items": { "type": "string" } } }, "required": [ "street", "zip" ], "title": "Shop Serviceability" }, "ShopOrderItemDto": { "type": "object", "properties": { "offerId": { "type": "string", "description": "ID of the consumer-enabled offer to order" }, "metadata": { "type": "object", "description": "Per-item metadata stored on the resulting OrderItem — for electricity offers, carry enrollment details here (mirrors the reseller checkout wizard).", "example": { "enrollment": { "enrollmentType": "switch", "esid": "10443720000000000", "requestedStartDate": "2026-07-15" } } } }, "required": [ "offerId" ], "title": "Shop Order Item" }, "ShopServiceAddressDto": { "type": "object", "properties": { "street": { "type": "string", "example": "123 Main St" }, "unit": { "type": "string", "example": "Unit 4B" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "zipCode": { "type": "string", "example": "78701" }, "country": { "type": "string", "example": "US", "default": "US" } }, "required": [ "street", "city", "state", "zipCode" ], "title": "Shop Service Address" }, "ShopCustomerInfoDto": { "type": "object", "properties": { "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "fullName": { "type": "string", "example": "Jane Doe", "description": "Legacy single-field name — prefer firstName + lastName. Required only when both are absent; split on the last space when used." }, "email": { "type": "string", "example": "jane@example.com" }, "phone": { "type": "string", "example": "555-123-4567" } }, "required": [ "email", "phone" ], "title": "Shop Customer Info" }, "CreateShopOrderDto": { "type": "object", "properties": { "items": { "description": "Offers to order — checkout-mode offers only, one per category", "type": "array", "items": { "$ref": "#/components/schemas/ShopOrderItemDto" } }, "serviceAddress": { "description": "Service address for installation", "allOf": [ { "$ref": "#/components/schemas/ShopServiceAddressDto" } ] }, "customerInfo": { "description": "Shopper contact information", "allOf": [ { "$ref": "#/components/schemas/ShopCustomerInfoDto" } ] }, "notes": { "type": "string", "description": "Additional notes from the shopper" }, "idempotencyKey": { "type": "string", "description": "Client-generated key for this checkout attempt. A repeat submission with the same key (network retry, double-click on Submit) returns the original order instead of creating a duplicate.", "example": "a1b2c3d4-checkout-attempt" }, "sessionId": { "type": "string", "description": "Anonymous client-generated session id, so the checkout-mode click this order completes can be tied to the same funnel as its lead_gen counterpart.", "example": "a1b2c3d4-shopper-session" } }, "required": [ "items", "serviceAddress", "customerInfo" ], "title": "Create Shop Order" }, "ShopClickContactDto": { "type": "object", "properties": { "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "fullName": { "type": "string", "example": "Jane Doe", "description": "Legacy single-field name — prefer firstName + lastName. Required only when both are absent; split on the last space when used." }, "email": { "type": "string", "example": "jane@example.com" }, "phone": { "type": "string", "example": "555-123-4567" } }, "required": [ "email" ], "title": "Shop Click Contact" }, "ShopClickServiceAddressDto": { "type": "object", "properties": { "street": { "type": "string", "example": "123 Main Street" }, "unit": { "type": "string", "example": "Apt 4B" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "zipCode": { "type": "string", "example": "78701" } }, "required": [ "street" ], "title": "Shop Click Service Address" }, "ShopClickEnrollmentDto": { "type": "object", "properties": { "enrollmentType": { "type": "string", "example": "move_in", "description": "switch (existing meter stays on) or move_in (new occupancy)" }, "esid": { "type": "string", "example": "10443720005941666" }, "requestedStartDate": { "type": "string", "example": "2026-09-01" } }, "title": "Shop Click Enrollment" }, "CreateShopClickDto": { "type": "object", "properties": { "offerId": { "type": "string", "description": "The offer this click is for" }, "zip": { "type": "string", "example": "78701" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "sessionId": { "type": "string", "description": "Anonymous client-generated UUID grouping clicks within one shopper session", "example": "a1b2c3d4-shopper-session" }, "referrer": { "type": "string", "example": "https://www.google.com/" }, "utm": { "type": "object", "example": { "utm_source": "google", "utm_campaign": "internet-austin" } }, "contact": { "description": "Optional contact capture before a lead_gen redirect — always skippable. When present, creates a provider lead (Customer + TeamCustomer).", "allOf": [ { "$ref": "#/components/schemas/ShopClickContactDto" } ] }, "serviceAddress": { "description": "Full service address, when the handoff was reached through the checkout wizard. Its city/state/zipCode fill in for any top-level zip/city/state left unset.", "allOf": [ { "$ref": "#/components/schemas/ShopClickServiceAddressDto" } ] }, "enrollment": { "description": "Optional electricity enrollment details collected before a lead_gen handoff — used to fill the offer's URL template (ESIID, start date, move vs switch) so the partner prefills its signup flow.", "allOf": [ { "$ref": "#/components/schemas/ShopClickEnrollmentDto" } ] } }, "required": [ "offerId", "sessionId" ], "title": "Create Shop Click" }, "ElectricityCharge": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "perKwh" ] }, "centsPerKwh": { "type": "number", "minimum": 0 }, "owner": { "type": "string", "enum": [ "provider", "utility" ] }, "label": { "type": "string", "minLength": 1 }, "minUsageKwh": { "type": "number", "minimum": 0 }, "maxUsageKwh": { "type": "number", "minimum": 0 } }, "required": [ "type", "centsPerKwh", "owner", "label" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "fixed" ] }, "amountDollars": { "type": "number", "minimum": 0 }, "owner": { "type": "string", "enum": [ "provider", "utility" ] }, "label": { "type": "string", "minLength": 1 }, "minUsageKwh": { "type": "number", "minimum": 0 }, "maxUsageKwh": { "type": "number", "minimum": 0 } }, "required": [ "type", "amountDollars", "owner", "label" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "credit" ] }, "amountDollars": { "type": "number", "minimum": 0 }, "owner": { "type": "string", "enum": [ "provider", "utility" ] }, "label": { "type": "string", "minLength": 1 }, "minUsageKwh": { "type": "number", "minimum": 0 }, "maxUsageKwh": { "type": "number", "minimum": 0 } }, "required": [ "type", "amountDollars", "owner", "label" ], "additionalProperties": false } ], "title": "Electricity Charge", "description": "A single provider (REP) or utility delivery (TDU) charge line. perKwh lines bill per kWh in an optional usage band; fixed/credit lines apply a flat dollar amount (credits entered positive, subtracted)." }, "ElectricityContractWrite": { "type": "object", "properties": { "rate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "fixed", "variable", "indexed" ] }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/ElectricityCharge" } }, "avgPriceAt1000Kwh": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "term": { "type": "object", "properties": { "length": { "type": "string", "enum": [ "no_contract", "month_to_month", "months_12", "months_24", "months_36" ] }, "earlyTerminationFee": { "nullable": true, "type": "number", "minimum": 0 }, "earlyTerminationFeeNotes": { "nullable": true, "type": "string" } }, "additionalProperties": false }, "plan": { "type": "object", "properties": { "renewablePercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "freeNightsWeekends": { "type": "boolean" }, "noDeposit": { "type": "boolean" } }, "additionalProperties": false }, "disclosures": { "type": "object", "properties": { "electricityFactsLabel": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] }, "versionId": { "type": "string" }, "avgPrice500kwh": { "type": "number", "minimum": 0 }, "avgPrice1000kwh": { "type": "number", "minimum": 0 }, "avgPrice2000kwh": { "type": "number", "minimum": 0 }, "renewablePercent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "puctCertNumber": { "type": "string" }, "puctCertifiedName": { "type": "string" }, "termsOfServiceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] }, "yourRightsUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] } }, "additionalProperties": false } }, "additionalProperties": false, "title": "Electricity Contract (write)", "description": "The electricity offer payload accepted on create/update. When present it is authoritative for pricing/term/plan/disclosures and is folded into storage server-side. Grouped as rate / term / plan / disclosures." }, "ElectricityContract": { "type": "object", "properties": { "rate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "fixed", "variable", "indexed" ] }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/ElectricityCharge" } }, "avgPriceAt1000Kwh": { "type": "number", "minimum": 0 }, "estimatedMonthlyAt1000Kwh": { "nullable": true, "type": "number", "minimum": 0, "readOnly": true } }, "additionalProperties": false }, "term": { "type": "object", "properties": { "length": { "type": "string", "enum": [ "no_contract", "month_to_month", "months_12", "months_24", "months_36" ] }, "earlyTerminationFee": { "nullable": true, "type": "number", "minimum": 0 }, "earlyTerminationFeeNotes": { "nullable": true, "type": "string" } }, "additionalProperties": false }, "plan": { "type": "object", "properties": { "renewablePercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "freeNightsWeekends": { "type": "boolean" }, "noDeposit": { "type": "boolean" } }, "additionalProperties": false }, "disclosures": { "type": "object", "properties": { "electricityFactsLabel": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] }, "versionId": { "type": "string" }, "avgPrice500kwh": { "type": "number", "minimum": 0 }, "avgPrice1000kwh": { "type": "number", "minimum": 0 }, "avgPrice2000kwh": { "type": "number", "minimum": 0 }, "renewablePercent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "puctCertNumber": { "type": "string" }, "puctCertifiedName": { "type": "string" }, "termsOfServiceUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] }, "yourRightsUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] } }, "additionalProperties": false } }, "additionalProperties": false, "title": "Electricity Contract", "description": "The electricity offer payload returned on read. Same shape as the write contract plus the derived, read-only `rate.estimatedMonthlyAt1000Kwh` headline." }, "InternetContractWrite": { "type": "object", "properties": { "speed": { "type": "object", "properties": { "minBandwidthMbps": { "type": "number", "minimum": 0 }, "maxBandwidthMbps": { "type": "number", "minimum": 0 }, "connectionType": { "type": "string", "enum": [ "fiber", "cable", "dsl", "satellite", "fixed_wireless", "5g_home" ] } }, "additionalProperties": false }, "data": { "type": "object", "properties": { "capGb": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "term": { "type": "object", "properties": { "length": { "type": "string", "enum": [ "no_contract", "month_to_month", "months_12", "months_24", "months_36" ] }, "earlyTerminationFee": { "nullable": true, "type": "number", "minimum": 0 }, "earlyTerminationFeeNotes": { "nullable": true, "type": "string" } }, "additionalProperties": false }, "disclosures": { "type": "object", "properties": { "broadbandLabel": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] }, "typicalDownload": { "type": "number", "minimum": 0 }, "typicalUpload": { "type": "number", "minimum": 0 }, "typicalLatency": { "type": "number", "minimum": 0 }, "dataCapGb": { "nullable": true, "type": "number", "minimum": 0 } }, "additionalProperties": false }, "networkManagementUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] } }, "additionalProperties": false } }, "additionalProperties": false, "title": "Internet Contract (write)", "description": "The internet offer payload accepted on create/update. When present it is authoritative for speed/data/term/disclosures and is folded into storage server-side. Grouped as speed / data / term / disclosures." }, "InternetContract": { "type": "object", "properties": { "speed": { "type": "object", "properties": { "minBandwidthMbps": { "type": "number", "minimum": 0 }, "maxBandwidthMbps": { "type": "number", "minimum": 0 }, "connectionType": { "type": "string", "enum": [ "fiber", "cable", "dsl", "satellite", "fixed_wireless", "5g_home" ] } }, "additionalProperties": false }, "data": { "type": "object", "properties": { "capGb": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "term": { "type": "object", "properties": { "length": { "type": "string", "enum": [ "no_contract", "month_to_month", "months_12", "months_24", "months_36" ] }, "earlyTerminationFee": { "nullable": true, "type": "number", "minimum": 0 }, "earlyTerminationFeeNotes": { "nullable": true, "type": "string" } }, "additionalProperties": false }, "disclosures": { "type": "object", "properties": { "broadbandLabel": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] }, "typicalDownload": { "type": "number", "minimum": 0 }, "typicalUpload": { "type": "number", "minimum": 0 }, "typicalLatency": { "type": "number", "minimum": 0 }, "dataCapGb": { "nullable": true, "type": "number", "minimum": 0 } }, "additionalProperties": false }, "networkManagementUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [ "" ] } ] } }, "additionalProperties": false } }, "additionalProperties": false, "title": "Internet Contract", "description": "The internet offer payload returned on read — the grouped speed / data / term / disclosures view of an internet offer." }, "OfferResponse": { "type": "object", "title": "Offer", "description": "An offer. Always includes a top-level `serviceType` discriminator (\"electricity\", \"internet\", …); electricity offers additionally include a grouped `electricity` object and internet offers a grouped `internet` object. The underlying offer fields (name, status, markets, marketing, pricing, …) are also present.", "additionalProperties": true, "properties": { "serviceType": { "type": "string", "nullable": true, "description": "Flat service-type discriminator derived from category. Check this instead of `category` directly.", "example": "internet" }, "electricity": { "allOf": [ { "$ref": "#/components/schemas/ElectricityContract" } ], "description": "Present only on electricity offers." }, "internet": { "allOf": [ { "$ref": "#/components/schemas/InternetContract" } ], "description": "Present only on internet offers." } } }, "ErrorResponse": { "type": "object", "title": "Error", "description": "Standard error envelope returned by every 4xx and 5xx response.", "required": [ "statusCode", "message" ], "properties": { "statusCode": { "type": "integer", "description": "HTTP status code, repeated in the body.", "example": 404 }, "message": { "type": "string", "description": "Human-readable explanation of what went wrong.", "example": "Offer not found" }, "error": { "type": "string", "description": "Short, stable name for the status code.", "example": "Not Found" } } }, "ValidationErrorResponse": { "type": "object", "title": "Validation Error", "description": "Returned when request-body validation fails. `message` is an array with one entry per failed constraint.", "required": [ "statusCode", "message" ], "properties": { "statusCode": { "type": "integer", "example": 400 }, "message": { "type": "array", "items": { "type": "string" }, "description": "One human-readable message per failed constraint.", "example": [ "name should not be empty", "category must be one of the following values: internet, electricity" ] }, "error": { "type": "string", "example": "Bad Request" } } } } } }