{ "components": { "schemas": { "CartVariantMutationRequest": { "additionalProperties": false, "properties": { "market_id": { "type": "string" }, "offer_id": { "type": "string" }, "product_variant_id": { "minLength": 1, "type": "string" }, "quantity": { "default": 1, "minimum": 1, "type": "integer" }, "selected_term_months": { "minimum": 1, "type": "integer" }, "selected_upfront_payment_amount_minor": { "minimum": 0, "type": "integer" } }, "required": [ "product_variant_id" ], "type": "object" }, "CartVariantSelection": { "additionalProperties": false, "properties": { "offer_id": { "minLength": 1, "type": "string" }, "product_variant_id": { "minLength": 1, "type": "string" } }, "required": [ "product_variant_id" ], "type": "object" }, "CheckoutAvailablePricingPreview": { "additionalProperties": true, "description": "Server-resolved advertised price for eligible automatic promotions; excludes unentered codes.", "properties": { "base_recurring_amount_minor": { "format": "int64", "type": "integer" }, "currency": { "type": "string" }, "free_periods": { "items": { "$ref": "#/components/schemas/CheckoutFreePeriod" }, "type": "array" }, "lowest_recurring_amount_minor": { "format": "int64", "type": "integer" }, "recurring_phases": { "items": { "$ref": "#/components/schemas/CheckoutRecurringPhase" }, "type": "array" }, "status": { "enum": [ "preview" ], "type": "string" } }, "required": [ "status", "base_recurring_amount_minor", "lowest_recurring_amount_minor", "currency", "recurring_phases", "free_periods" ], "type": "object" }, "CheckoutCart": { "properties": { "billing_address_snapshot": { "additionalProperties": true, "type": "object" }, "cart_id": { "format": "uuid", "type": "string" }, "catalog_owner_tenant_id": { "format": "uuid", "nullable": true, "type": "string" }, "commission_plan_id": { "format": "uuid", "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "customer_acceptance_snapshot": { "additionalProperties": true, "type": "object" }, "customer_document_snapshot": { "additionalProperties": true, "type": "object" }, "customer_price_snapshot": { "additionalProperties": true, "type": "object" }, "customer_snapshot": { "additionalProperties": true, "type": "object" }, "discounts_snapshot": { "additionalProperties": true, "type": "object" }, "eligibility_snapshot": { "additionalProperties": true, "type": "object" }, "google_place_id": { "nullable": true, "type": "string" }, "ip_address": { "nullable": true, "type": "string" }, "line_items": { "items": { "additionalProperties": true, "properties": { "bundle_id": { "description": "Bundle component identity for every attached child, including removable children.", "type": "string" }, "can_remove": { "description": "Whether the buyer may independently remove this line; inclusion does not imply a lock.", "type": "boolean" }, "locked_reason": { "description": "required_bundle_component only for required children.", "type": "string" }, "offers": { "items": { "additionalProperties": true, "properties": { "technical_attributes": { "$ref": "#/components/schemas/CheckoutTechnicalAttributes" } }, "type": "object" }, "type": "array" }, "required_by_variant_id": { "description": "Parent variant owning a required bundle lock; absent for removable children.", "type": "string" }, "technical_attributes": { "$ref": "#/components/schemas/CheckoutTechnicalAttributes" } }, "type": "object" }, "type": "array" }, "market_id": { "format": "uuid", "nullable": true, "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "pricebook_id": { "format": "uuid", "nullable": true, "type": "string" }, "pricing_selections": { "items": { "$ref": "#/components/schemas/PricingSelection" }, "type": "array" }, "pricing_snapshot": { "$ref": "#/components/schemas/CheckoutPricingSnapshot" }, "publication_id": { "format": "uuid", "nullable": true, "type": "string" }, "selling_tenant_id": { "format": "uuid", "nullable": true, "type": "string" }, "service_address_snapshot": { "additionalProperties": true, "type": "object" }, "status": { "type": "string" }, "storefront_key": { "type": "string" }, "submitted_at": { "format": "date-time", "nullable": true, "type": "string" }, "submitted_order_id": { "format": "uuid", "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "type": "integer" } }, "type": "object" }, "CheckoutFeature": { "properties": { "description": { "type": "string" }, "icon": { "description": "Opaque frontend icon key. Unknown keys are valid and must not be interpreted as markup or URLs.", "type": "string" }, "icon_url": { "type": "string" } }, "required": [ "description" ], "type": "object" }, "CheckoutFreePeriod": { "description": "Explicit free benefit on one recurring charge. Independent of a zero price produced by value discounts.", "properties": { "application_policy": { "enum": [ "overlap", "extend_free_periods" ], "type": "string" }, "benefit_id": { "type": "string" }, "billing_interval": { "type": "string" }, "discount_code_id": { "type": "string" }, "duration_billing_cycles": { "minimum": 1, "type": "integer" }, "label": { "type": "string" }, "line_item_index": { "minimum": 0, "type": "integer" }, "offer_id": { "type": "string" }, "promotion_id": { "type": "string" }, "start_billing_cycle": { "description": "Zero-based cycle in this charge's billing cadence.", "minimum": 0, "type": "integer" }, "variant_id": { "type": "string" } }, "required": [ "promotion_id", "benefit_id", "label", "line_item_index", "variant_id", "billing_interval", "application_policy", "start_billing_cycle", "duration_billing_cycles" ], "type": "object" }, "CheckoutPricingSnapshot": { "additionalProperties": true, "properties": { "free_periods": { "items": { "$ref": "#/components/schemas/CheckoutFreePeriod" }, "type": "array" }, "recurring_phases": { "items": { "$ref": "#/components/schemas/CheckoutRecurringPhase" }, "type": "array" } }, "type": "object" }, "CheckoutRecurringPhase": { "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "billing_interval": { "type": "string" }, "discount_ids": { "items": { "type": "string" }, "type": "array" }, "duration_billing_cycles": { "description": "Omitted for the ongoing phase.", "minimum": 1, "type": "integer" }, "labels": { "items": { "type": "string" }, "type": "array" } }, "required": [ "amount_minor", "billing_interval", "discount_ids", "labels" ], "type": "object" }, "CheckoutStorefrontOffer": { "additionalProperties": true, "properties": { "available_pricing_preview": { "$ref": "#/components/schemas/CheckoutAvailablePricingPreview" }, "offer_id": { "type": "string" } }, "required": [ "offer_id" ], "type": "object" }, "CheckoutStorefrontProduct": { "additionalProperties": true, "properties": { "name": { "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "variants": { "items": { "$ref": "#/components/schemas/CheckoutStorefrontVariant" }, "type": "array" } }, "required": [ "product_id", "name", "variants" ], "type": "object" }, "CheckoutStorefrontProductList": { "additionalProperties": true, "properties": { "products": { "items": { "$ref": "#/components/schemas/CheckoutStorefrontProduct" }, "type": "array" } }, "required": [ "products" ], "type": "object" }, "CheckoutStorefrontVariant": { "additionalProperties": true, "description": "Signup variant including existing pricing and eligibility fields, ordered technical specifications, and selling-point features.", "properties": { "features": { "items": { "$ref": "#/components/schemas/CheckoutFeature" }, "type": "array" }, "offers": { "items": { "$ref": "#/components/schemas/CheckoutStorefrontOffer" }, "type": "array" }, "specifications": { "items": { "$ref": "#/components/schemas/VariantSpecification" }, "maxItems": 100, "type": "array" }, "variant_id": { "format": "uuid", "type": "string" } }, "required": [ "variant_id", "specifications", "features" ], "type": "object" }, "CheckoutTechnicalAttributes": { "additionalProperties": false, "properties": { "broadband_consumer_label": { "additionalProperties": true, "description": "Complete published Broadband Facts resolved for this offer and selected pricebook. Monthly USD price, required provider and installation fees, contract duration and FCC plan identifier come from canonical commerce data. Authored placeholder or incomplete drafts are omitted. Consumers must use the displayed offer's label; a variant's default label cannot describe a different offer. See docs/754-services-commerce-catalog-product-domain.md.", "type": "object" } }, "type": "object" }, "CompleteOrderConfirmationRequest": { "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" }, "CreateCartRequest": { "additionalProperties": false, "properties": { "google_place_id": { "minLength": 1, "type": "string" }, "lease_context": { "properties": { "selected_term_months": { "minimum": 1, "type": "integer" } }, "type": "object" }, "market_id": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "service_address": { "additionalProperties": true, "type": "object" } }, "required": [ "google_place_id" ], "type": "object" }, "CreateLeadRequest": { "additionalProperties": false, "properties": { "address": { "maxLength": 1000, "minLength": 1, "type": "string" }, "availability_request_id": { "format": "uuid", "type": "string" }, "company": { "maxLength": 200, "type": "string" }, "contact_consent": { "enum": [ true ], "type": "boolean" }, "eligibility_status": { "maxLength": 80, "minLength": 1, "type": "string" }, "email": { "format": "email", "maxLength": 254, "type": "string" }, "google_place_id": { "maxLength": 500, "minLength": 1, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "phone": { "maxLength": 40, "type": "string" }, "storefront_key": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "name", "email", "contact_consent", "google_place_id", "address", "eligibility_status", "availability_request_id", "storefront_key" ], "type": "object" }, "DiscountCodeMutationRequest": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "discount_code_id": { "type": "string" } }, "type": "object" }, "EligibilityEvaluation": { "additionalProperties": false, "properties": { "available_product_ids": { "items": { "type": "string" }, "type": "array" }, "blocked_products": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "direct_checkout_allowed": { "type": "boolean" }, "eligibility_summary": { "additionalProperties": true, "type": "object" }, "market": { "additionalProperties": true, "nullable": true, "type": "object" }, "market_id": { "nullable": true, "type": "string" }, "request_id": { "type": "string" }, "sellable_products": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "status": { "type": "string" } }, "required": [ "request_id", "status", "available_product_ids", "sellable_products", "blocked_products", "eligibility_summary", "direct_checkout_allowed" ], "type": "object" }, "EligibilityEvaluationRequest": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "google_place_id": { "type": "string" }, "latitude": { "format": "double", "type": "number" }, "longitude": { "format": "double", "type": "number" }, "market_id": { "type": "string" }, "storefront_key": { "type": "string" } }, "type": "object" }, "ErrorResponse": { "properties": { "error": { "type": "string" } }, "required": [ "error" ], "type": "object" }, "GatewayProblem": { "additionalProperties": false, "properties": { "detail": { "type": "string" }, "instance": { "format": "uri-reference", "type": "string" }, "request_id": { "type": "string" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "type": "string" }, "type": { "format": "uri-reference", "type": "string" } }, "required": [ "type", "title", "status" ], "type": "object" }, "LeadReceipt": { "additionalProperties": false, "properties": { "lead_id": { "format": "uuid", "type": "string" } }, "required": [ "lead_id" ], "type": "object" }, "Order": { "properties": { "assigned_agent_user_id": { "nullable": true, "type": "string" }, "billing_address_snapshot": { "additionalProperties": true, "type": "object" }, "catalog_owner_tenant_id": { "format": "uuid", "type": "string" }, "commission_plan_id": { "format": "uuid", "nullable": true, "type": "string" }, "commission_snapshot": { "additionalProperties": true, "type": "object" }, "confirmed_at": { "format": "date-time", "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "customer_snapshot": { "additionalProperties": true, "type": "object" }, "discounts_snapshot": { "additionalProperties": true, "type": "object" }, "eligibility_snapshot": { "additionalProperties": true, "type": "object" }, "lifecycle_phase": { "type": "string" }, "line_items_snapshot": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "metadata": { "additionalProperties": true, "type": "object" }, "order_id": { "format": "uuid", "type": "string" }, "pricebook_id": { "format": "uuid", "nullable": true, "type": "string" }, "pricing_revision": { "format": "int64", "nullable": true, "type": "integer" }, "pricing_selections": { "items": { "$ref": "#/components/schemas/PricingSelection" }, "type": "array" }, "pricing_snapshot": { "additionalProperties": true, "type": "object" }, "publication_id": { "format": "uuid", "nullable": true, "type": "string" }, "selling_tenant_id": { "format": "uuid", "type": "string" }, "service_address_snapshot": { "additionalProperties": true, "type": "object" }, "source_legacy_order_id": { "nullable": true, "type": "string" }, "source_quote_id": { "format": "uuid", "nullable": true, "type": "string" }, "source_system": { "type": "string" }, "status": { "type": "string" }, "store_id": { "format": "uuid", "nullable": true, "type": "string" }, "submitted_at": { "format": "date-time", "nullable": true, "type": "string" }, "submitted_by_email": { "format": "email", "nullable": true, "type": "string" }, "submitted_by_user_id": { "nullable": true, "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "order_id", "tenant_id", "catalog_owner_tenant_id", "selling_tenant_id", "status", "lifecycle_phase", "customer_snapshot", "service_address_snapshot", "billing_address_snapshot", "line_items_snapshot", "pricing_snapshot", "pricing_selections", "discounts_snapshot", "eligibility_snapshot", "commission_snapshot", "source_system", "metadata", "version", "created_at", "updated_at" ], "type": "object" }, "OrderConfirmation": { "properties": { "completed_at": { "format": "date-time", "nullable": true, "type": "string" }, "confirmation_id": { "format": "uuid", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "created_by_user_id": { "nullable": true, "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "last_sent_at": { "format": "date-time", "nullable": true, "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "order_id": { "format": "uuid", "type": "string" }, "send_count": { "type": "integer" }, "status": { "type": "string" }, "superseded_at": { "format": "date-time", "nullable": true, "type": "string" }, "superseded_from_status": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "confirmation_id", "order_id", "status", "send_count", "expires_at", "metadata", "created_at", "updated_at" ], "type": "object" }, "OrderConfirmationCompletion": { "properties": { "confirmation": { "$ref": "#/components/schemas/OrderConfirmation" }, "order": { "$ref": "#/components/schemas/Order" }, "redirect_url": { "format": "uri", "nullable": true, "type": "string" } }, "required": [ "order", "confirmation" ], "type": "object" }, "OrderConfirmationMutationRequest": { "properties": { "actor_user_id": { "nullable": true, "type": "string" }, "comment": { "nullable": true, "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" } }, "type": "object" }, "OrderStatusRequest": { "properties": { "actor_user_id": { "nullable": true, "type": "string" }, "comment": { "nullable": true, "type": "string" }, "lifecycle_phase": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "status": { "type": "string" } }, "type": "object" }, "PaginatedOrdersResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Order" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "items", "total_count", "limit", "offset" ], "type": "object" }, "PricingSelection": { "properties": { "description": { "type": "string" }, "disclosure": { "type": "string" }, "eligible": { "type": "boolean" }, "enrollment_status": { "type": "string" }, "ineligible_reason": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "options": { "items": { "$ref": "#/components/schemas/PricingSelectionOption" }, "type": "array" }, "pricing_effect": { "$ref": "#/components/schemas/PricingSelectionEffect" }, "required": { "type": "boolean" }, "selected_value": { "nullable": true, "type": "boolean" }, "selection_type": { "enum": [ "boolean" ], "type": "string" } }, "required": [ "key", "label", "selection_type", "required", "eligible", "selected_value", "options", "pricing_effect", "disclosure" ], "type": "object" }, "PricingSelectionEffect": { "properties": { "currency": { "type": "string" }, "discount_id": { "type": "string" }, "discount_length": { "type": "integer" }, "label": { "type": "string" }, "one_time_delta": { "format": "int64", "nullable": true, "type": "integer" }, "recurring_delta": { "format": "int64", "nullable": true, "type": "integer" }, "status": { "enum": [ "preview", "applied", "unavailable" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "PricingSelectionOption": { "properties": { "label": { "type": "string" }, "value": { "type": "boolean" } }, "required": [ "value", "label" ], "type": "object" }, "PublicCheckoutOrder": { "additionalProperties": true, "description": "Customer-facing checkout order with the persisted canonical pricing schedule.", "properties": { "cart_id": { "format": "uuid", "type": "string" }, "friendly_order_id": { "type": "string" }, "order_id": { "format": "uuid", "type": "string" }, "pricing_snapshot": { "$ref": "#/components/schemas/CheckoutPricingSnapshot" } }, "required": [ "order_id", "friendly_order_id", "cart_id", "pricing_snapshot" ], "type": "object" }, "PutPricingSelectionRequest": { "additionalProperties": false, "properties": { "expected_version": { "format": "int64", "minimum": 1, "type": "integer" }, "value": { "type": "boolean" } }, "required": [ "value" ], "type": "object" }, "ReplaceCartVariantSelectionRequest": { "additionalProperties": false, "properties": { "expected_version": { "format": "int64", "minimum": 1, "type": "integer" }, "lease_context": { "additionalProperties": false, "properties": { "selected_term_months": { "minimum": 1, "type": "integer" } }, "required": [ "selected_term_months" ], "type": "object" }, "lease_selection": { "additionalProperties": false, "properties": { "selected_upfront_payment_amount_minor": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "selected_upfront_payment_amount_minor" ], "type": "object" }, "market_id": { "type": "string" }, "offer_id": { "minLength": 1, "type": "string" }, "product_variant_id": { "minLength": 1, "type": "string" }, "quantity": { "minimum": 1, "type": "integer" }, "replaced_selections": { "items": { "$ref": "#/components/schemas/CartVariantSelection" }, "type": "array" }, "selected_term_months": { "minimum": 1, "type": "integer" }, "selected_upfront_payment_amount_minor": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "product_variant_id", "expected_version" ], "type": "object" }, "StaleCheckoutCartResponse": { "properties": { "code": { "enum": [ "checkout_cart_stale" ], "type": "string" }, "error": { "type": "string" } }, "required": [ "error", "code" ], "type": "object" }, "StorefrontRuntimeContext": { "additionalProperties": false, "properties": { "catalog_key": { "type": "string" }, "catalog_owner_tenant_id": { "format": "uuid", "type": "string" }, "channel_id": { "type": "string" }, "eligibility_mode": { "type": "string" }, "experience_key": { "type": "string" }, "publication_id": { "format": "uuid", "type": "string" }, "route_profile": { "type": "string" }, "segment": { "type": "string" }, "storefront_key": { "type": "string" } }, "required": [ "experience_key", "storefront_key", "catalog_owner_tenant_id", "publication_id", "channel_id" ], "type": "object" }, "UpdateOrderRequest": { "additionalProperties": false, "properties": { "actor_user_id": { "nullable": true, "type": "string" }, "assigned_agent_user_id": { "nullable": true, "type": "string" }, "billing_address_snapshot": { "additionalProperties": true, "type": "object" }, "customer_snapshot": { "additionalProperties": true, "type": "object" }, "eligibility_snapshot": { "additionalProperties": true, "type": "object" }, "metadata": { "additionalProperties": true, "type": "object" }, "service_address_snapshot": { "additionalProperties": true, "type": "object" } }, "type": "object" }, "VariantRecommendations": { "additionalProperties": false, "properties": { "context": { "additionalProperties": true, "type": "object" }, "recommendations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "variant_id": { "type": "string" } }, "required": [ "context", "variant_id", "recommendations" ], "type": "object" }, "VariantSpecification": { "description": "Plain-text technical reference detail. Array order is display order; names must be unique within a group (case-insensitive).", "properties": { "group": { "maxLength": 80, "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "value": { "maxLength": 2000, "minLength": 1, "type": "string" } }, "required": [ "name", "value" ], "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "description": "Tenant-scoped integration key. Store it only in a server-side secret store. The equivalent Authorization: ApiKey \u003ckey\u003e form is also accepted; never send both forms.", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "externalDocs": { "description": "Integration guides and lifecycle policy", "url": "https://docs.connectplane.com/docs/api" }, "info": { "contact": { "name": "ConnectPlane API Support", "url": "https://docs.connectplane.com/docs/api" }, "description": "Stable API Gateway contract for approved ConnectPlane integrations. API v1 compatibility is independent of service, SDK, ConnectPlane, and platform release versions.", "title": "ConnectPlane API", "version": "1.0.0" }, "openapi": "3.0.3", "paths": { "/api/v1/commerce/carts": { "get": { "description": "Resume a checkout cart by its cart_id using the current storefront configuration.", "operationId": "getCart", "parameters": [ { "in": "query", "name": "cart_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Current checkout cart" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "The request is invalid" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Cart not found" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaleCheckoutCartResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Saved storefront context is obsolete; restart checkout with a new cart" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Temporary failure; retain the saved cart for retry" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Resume a checkout cart by its cart_id using the current storefront configuration", "tags": [ "Carts" ], "x-stability": "stable" }, "post": { "description": "Create a checkout cart for an approved storefront and service address.", "operationId": "createCart", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCartRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Create checkout cart result" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid request or domain input" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Authentication unavailable or required" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Referenced record unavailable" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Current domain state or version conflict" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Checkout cart stale" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Pricing selection ineligible" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing storage or internal request failure" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Required authority or confirmation dependency unavailable" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a checkout cart for an approved storefront and service address", "tags": [ "Carts" ], "x-stability": "stable" } }, "/api/v1/commerce/carts/{cartId}/discount-codes": { "delete": { "description": "Remove a discount code from a checkout cart and return the repriced cart.", "operationId": "removeCartDiscountCode", "parameters": [ { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "cartId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountCodeMutationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Current successful handler response" }, "400": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing input or path validation failed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Other responses from the unchanged registered middleware, handler and dependency error paths; no error-format migration or live qualification is claimed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a discount code from a checkout cart and return the repriced cart", "tags": [ "Carts" ], "x-stability": "stable" }, "post": { "description": "Apply a discount code to a checkout cart and return the repriced cart.", "operationId": "applyCartDiscountCode", "parameters": [ { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "cartId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountCodeMutationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Current successful handler response" }, "400": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing input or path validation failed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Other responses from the unchanged registered middleware, handler and dependency error paths; no error-format migration or live qualification is claimed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Apply a discount code to a checkout cart and return the repriced cart", "tags": [ "Carts" ], "x-stability": "stable" } }, "/api/v1/commerce/carts/{cartId}/pricing-selections/{selectionKey}": { "put": { "description": "Set a conditional pricing selection and return the fully repriced cart.", "operationId": "setCartPricingSelection", "parameters": [ { "in": "path", "name": "cartId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "selectionKey", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutPricingSelectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Fully repriced cart" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid selection value" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Cart or pricing selection not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Cart version conflict or submitted cart" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaleCheckoutCartResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Saved storefront context is obsolete; restart checkout with a new cart" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Pricing selection is not eligible for the current cart" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Set a conditional pricing selection and return the fully repriced cart", "tags": [ "Carts" ], "x-stability": "stable" } }, "/api/v1/commerce/carts/{cartId}/variant-selection": { "put": { "description": "Atomically replace the selected cart variants and return the reconciled cart.", "operationId": "replaceCartVariantSelection", "parameters": [ { "in": "path", "name": "cartId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceCartVariantSelectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Fully reconciled and repriced cart" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid target or replaced selection" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Cart or target variant not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Cart version conflict or submitted cart" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaleCheckoutCartResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Saved storefront context is obsolete; restart checkout with a new cart" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Atomically replace the selected cart variants and return the reconciled cart", "tags": [ "Carts" ], "x-stability": "stable" } }, "/api/v1/commerce/carts/{cartId}/variants": { "post": { "description": "Add a product variant to a checkout cart.", "operationId": "addCartVariant", "parameters": [ { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "cartId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartVariantMutationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Current successful handler response" }, "400": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing input or path validation failed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Other responses from the unchanged registered middleware, handler and dependency error paths; no error-format migration or live qualification is claimed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Add a product variant to a checkout cart", "tags": [ "Carts" ], "x-stability": "stable" }, "put": { "description": "Set a product variant quantity or offer selection on a checkout cart.", "operationId": "setCartVariant", "parameters": [ { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "cartId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartVariantMutationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Current successful handler response" }, "400": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing input or path validation failed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Other responses from the unchanged registered middleware, handler and dependency error paths; no error-format migration or live qualification is claimed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Set a product variant quantity or offer selection on a checkout cart", "tags": [ "Carts" ], "x-stability": "stable" } }, "/api/v1/commerce/carts/{cartId}/variants/{variantId}": { "delete": { "description": "Remove a product variant from a checkout cart.", "operationId": "removeCartVariant", "parameters": [ { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "cartId", "required": true, "schema": { "type": "string" } }, { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "variantId", "required": true, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "offer_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCart" } } }, "description": "Current successful handler response" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "The request is invalid" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Other responses from the unchanged registered middleware, handler and dependency error paths; no error-format migration or live qualification is claimed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a product variant from a checkout cart", "tags": [ "Carts" ], "x-stability": "stable" } }, "/api/v1/commerce/checkout/storefronts/{storefrontKey}/products": { "get": { "description": "List the published products, variants and ordered specifications available for checkout.", "operationId": "listCheckoutProducts", "parameters": [ { "in": "path", "name": "storefrontKey", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "publication_id", "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "market_id", "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "cart_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStorefrontProductList" } } }, "description": "Published signup products with ordered specifications on each variant." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid query or checkout context" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Storefront catalog not found" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List the published products, variants and ordered specifications available for checkout", "tags": [ "Catalog" ], "x-stability": "stable" } }, "/api/v1/commerce/checkout/submit": { "post": { "description": "Submit a checkout cart and create an order from its canonical price and discount schedule.", "operationId": "submitCheckout", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "cart_id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "cart_id", "first_name", "last_name", "email" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutOrder" } } }, "description": "Submitted order including recurring phases and future free-period benefits" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid checkout input" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing authorization" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Cart not found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Cart is closed or empty" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Submit a checkout cart and create an order from its canonical price and discount schedule", "tags": [ "Checkout" ], "x-stability": "stable" } }, "/api/v1/commerce/eligibility/evaluate-catalog": { "post": { "description": "Evaluate serviceability and product eligibility for an approved storefront context.", "operationId": "evaluateCatalogEligibility", "parameters": [ { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "address", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "agent_user_id", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "business", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "cart_id", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "catalog_key", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "catalog_owner_tenant_id", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "channel_id", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "eligibility_mode", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "eligibility_signals", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "lat", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "latitude", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "lng", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "longitude", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "market_id", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "place_id", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "publication_id", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "route_profile", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "segment", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "selected_term_months", "required": false, "schema": { "type": "integer" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "selling_tenant_id", "required": false, "schema": { "type": "string" } }, { "description": "Existing handler query parameter; validation and defaults are unchanged.", "in": "query", "name": "storefront_audience", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EligibilityEvaluationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EligibilityEvaluation" } } }, "description": "Current successful handler response" }, "400": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing input or path validation failed" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "405": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing method guard rejected the request" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Other responses from the unchanged registered middleware, handler and dependency error paths; no error-format migration or live qualification is claimed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Evaluate serviceability and product eligibility for an approved storefront context", "tags": [ "Catalog" ], "x-stability": "stable" } }, "/api/v1/commerce/order-confirmations/complete": { "post": { "description": "Complete an order confirmation using its single-use token.", "operationId": "completeOrderConfirmation", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteOrderConfirmationRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CompleteOrderConfirmationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderConfirmationCompletion" } } }, "description": "Completed order confirmation" }, "303": { "description": "Browser confirmation completed; redirect to the tenant URL with order_id", "headers": { "Location": { "schema": { "format": "uri", "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid or expired token" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Confirmation signing unavailable" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Complete an order confirmation using its single-use token", "tags": [ "Orders" ], "x-stability": "stable" } }, "/api/v1/commerce/orders": { "get": { "description": "List orders visible to the API-key tenant using bounded pagination.", "operationId": "listOrders", "parameters": [ { "in": "query", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 1000, "minimum": 0, "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrdersResponse" } } }, "description": "Orders" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List orders visible to the API-key tenant using bounded pagination", "tags": [ "Orders" ], "x-stability": "stable" } }, "/api/v1/commerce/orders/{orderId}": { "get": { "description": "Get one order visible to the API-key tenant.", "operationId": "getOrder", "parameters": [ { "in": "path", "name": "orderId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Order" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "The request is invalid" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Order not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one order visible to the API-key tenant", "tags": [ "Orders" ], "x-stability": "stable" }, "patch": { "description": "Update the supported customer or fulfillment fields on an order.", "operationId": "updateOrder", "parameters": [ { "description": "Selected seller tenant; exactly one seller or owner selector is required.", "example": "11111111-1111-4111-8111-111111111111", "in": "query", "name": "tenant_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Selected catalog owner tenant; mutually exclusive with tenant_id.", "in": "query", "name": "catalog_owner_tenant_id", "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "orderId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Updated order" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing, invalid or expired human authentication or original-session evidence.", "headers": { "WWW-Authenticate": { "description": "Bearer challenge emitted for authentication failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Permission, scope, actor attribution or principal kind is not authorized." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Order not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Attempted replacement of immutable commercial terms; create an explicit amendment instead" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "503": { "content": { "application/problem+json": { "schema": { "properties": { "detail": { "type": "string" }, "instance": { "format": "uri-reference", "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "title", "status" ], "type": "object" } } }, "description": "Required authentication or authorization trust is unavailable." }, "504": { "content": { "application/problem+json": { "schema": { "properties": { "detail": { "type": "string" }, "instance": { "format": "uri-reference", "type": "string" }, "status": { "type": "integer" }, "title": { "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "title", "status" ], "type": "object" } } }, "description": "Authorization or its bounded request deadline expired." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Update the supported customer or fulfillment fields on an order", "tags": [ "Orders" ], "x-stability": "stable" } }, "/api/v1/commerce/orders/{orderId}/confirmations/resend": { "post": { "description": "Issue and send a new order confirmation for an order.", "operationId": "resendOrderConfirmation", "parameters": [ { "in": "path", "name": "orderId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderConfirmationMutationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderConfirmation" } } }, "description": "Order confirmation" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "The request is invalid" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Order not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Confirmation cannot be resent" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Confirmation signing unavailable" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Issue and send a new order confirmation for an order", "tags": [ "Orders" ], "x-stability": "stable" } }, "/api/v1/commerce/orders/{orderId}/status": { "post": { "description": "Apply an allowed order status transition.", "operationId": "transitionOrderStatus", "parameters": [ { "in": "path", "name": "orderId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Updated order" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Order not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Invalid order transition" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Internal error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Apply an allowed order status transition", "tags": [ "Orders" ], "x-stability": "stable" } }, "/api/v1/commerce/runtime/storefront-experiences/{experienceKey}": { "get": { "description": "Resolve the current storefront, catalog, publication and eligibility context for an experience key.", "operationId": "getStorefrontExperience", "parameters": [ { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "experienceKey", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontRuntimeContext" } } }, "description": "Current successful handler response" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "The request is invalid" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing resource or route not found" }, "409": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing storefront runtime input or state conflict" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing storefront runtime repository resolution failure" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Other responses from the unchanged registered middleware, handler and dependency error paths; no error-format migration or live qualification is claimed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Resolve the current storefront, catalog, publication and eligibility context for an experience key", "tags": [ "Catalog" ], "x-stability": "stable" } }, "/api/v1/commerce/storefronts/{storefrontKey}/variants/{variantId}/recommendations": { "get": { "description": "List recommendations for a variant within a resolved storefront context.", "operationId": "listVariantRecommendations", "parameters": [ { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "storefrontKey", "required": true, "schema": { "type": "string" } }, { "description": "Existing dispatcher resource identifier; current parsing and validation are retained.", "in": "path", "name": "variantId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantRecommendations" } } }, "description": "Current successful handler response" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "The request is invalid" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "404": { "content": { "application/json": { "schema": {} }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Existing resource or route not found" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Other responses from the unchanged registered middleware, handler and dependency error paths; no error-format migration or live qualification is claimed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List recommendations for a variant within a resolved storefront context", "tags": [ "Catalog" ], "x-stability": "stable" } }, "/api/v1/sales/leads": { "post": { "description": "Create an immutable consented lead for the API-key tenant from a completed eligibility evaluation. Reuse the same Idempotency-Key UUID when retrying the same submission.", "operationId": "createLead", "parameters": [ { "description": "A caller-generated UUID that identifies this submission. Reuse it only when retrying the same lead.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "example": "9583e7fe-dc85-4b11-85f5-6332db91af63", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "address": "100 Market Street, Example, NY 10001", "availability_request_id": "479831ef-235d-472d-8d84-f31906285274", "company": "Example Networks", "contact_consent": true, "eligibility_status": "unavailable", "email": "alex@example.com", "google_place_id": "ChIJ-example", "name": "Alex Rivera", "phone": "+1-555-0100", "storefront_key": "connectplane" }, "schema": { "$ref": "#/components/schemas/CreateLeadRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "lead_id": "bf9203fe-123b-4fe6-91c5-f0cc7a196715" }, "schema": { "$ref": "#/components/schemas/LeadReceipt" } } }, "description": "Lead accepted, or the original receipt returned for an identical retry" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "The request is invalid" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "API key is not authorized for this operation" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "Idempotency-Key was already used with different lead data" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/GatewayProblem" } } }, "description": "An upstream dependency failed" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create an availability or sales lead", "tags": [ "Leads" ], "x-stability": "stable" } } }, "security": [ { "ApiKeyAuth": [] } ], "servers": [ { "description": "Production", "url": "https://api.connectplane.com" }, { "description": "Staging", "url": "https://api.staging.connectplane.com" } ], "tags": [ { "description": "Storefront context, eligibility, products and recommendations.", "name": "Catalog" }, { "description": "Checkout cart lifecycle and selections.", "name": "Carts" }, { "description": "Order submission.", "name": "Checkout" }, { "description": "Order lookup, updates, status and confirmation.", "name": "Orders" }, { "description": "Availability and sales lead intake.", "name": "Leads" } ] }