{ "openapi": "3.1.0", "info": { "title": "DabDash Tenant API", "version": "0.0.0", "description": "REST facade over the DabDash tenant MCP tools. Every operation here dispatches into the exact same handler the tenant MCP server (/mcp) calls — the two surfaces cannot drift apart. Served from each tenant's own subdomain or mapped custom domain, never from the platform domain." }, "servers": [ { "url": "https://{tenantDomain}", "description": "Your store's subdomain (e.g. {your-store-slug}.dabdash.com) or mapped custom domain.", "variables": { "tenantDomain": { "default": "{your-store-slug}.dabdash.com", "description": "Your store's subdomain or custom domain — never the platform domain." } } } ], "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ], "components": { "securitySchemes": { "tenantApiKey": { "type": "http", "scheme": "bearer", "description": "A tenant MCP token (dmcp_...) minted from the vendor dashboard at /admin/settings/mcp." }, "tenantOAuth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://dabdash.com/mcp/tenant/{slug}/oauth/authorize", "tokenUrl": "https://dabdash.com/mcp/tenant/{slug}/oauth/token", "scopes": [] } } } }, "schemas": { "AnalyticsQueryRequest": { "properties": { "report": { "description": "The report to run", "enum": [ "revenue_by_tenant", "orders_by_status", "top_products", "revenue_over_time", "customer_stats" ], "type": "string" }, "date_from": { "description": "Start date for the report period (YYYY-MM-DD, default: 30 days ago)", "type": [ "string", "null" ] }, "date_to": { "description": "End date for the report period (YYYY-MM-DD, default: today)", "type": [ "string", "null" ] } }, "type": "object", "required": [ "report" ] }, "AnalyticsQueryResponse": { "properties": { "report": { "type": "string" }, "period": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "tenant": { "type": "string" }, "results": { "anyOf": [ { "items": { "properties": { "tenant_id": { "type": "integer" }, "status": { "type": "string" }, "date": { "type": "string" }, "product": { "type": "string" }, "orders": { "type": "integer" }, "count": { "type": "integer" }, "units_sold": { "type": "integer" }, "revenue": { "type": "string" }, "total": { "type": "string" } }, "type": "object" }, "type": "array" }, { "properties": { "new_customers": { "type": "integer" }, "total_customers": { "type": "integer" } }, "type": "object" } ] } }, "type": "object" }, "BundleListRequest": { "properties": { "include_variation_ids": { "description": "Include the list of attached product variation IDs for each bundle. Defaults to false.", "type": [ "boolean", "null" ] }, "only_active": { "description": "Return only is_active bundles. Defaults to false (all bundles).", "type": [ "boolean", "null" ] } }, "type": "object" }, "BundleListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "summary": { "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "zero_discount": { "type": "integer" } }, "type": "object" }, "zero_discount_bundles": { "items": { "type": "string" }, "type": "array" }, "bundles": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "quantity": { "type": "integer" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" }, "discount_display": { "type": "string" }, "is_active": { "type": "boolean" }, "is_example": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "variation_count": { "type": "integer" }, "variation_ids": { "items": { "type": "integer" }, "type": [ "array", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "BundleUpsertRequest": { "properties": { "bundle_id": { "description": "ID of an existing bundle to update. Omit to create a new bundle.", "type": [ "integer", "null" ] }, "name": { "description": "Bundle name shown to vendors and customers (e.g. \"Any 4 for $77\"). Required when creating.", "type": [ "string", "null" ] }, "quantity": { "description": "Trigger threshold — number of cart units that activates the deal. Min 2. Required when creating.", "type": [ "integer", "null" ] }, "discount_type": { "description": "\"percent\", \"fixed\" (per-unit dollars), or \"fixed_total\" (dollars for the whole set). Required when creating.", "type": [ "string", "null" ] }, "discount_value": { "description": "Percent 0–100 for \"percent\"; dollars for \"fixed\" and \"fixed_total\". Required when creating.", "type": [ "number", "null" ] }, "is_active": { "description": "Whether the bundle is live. Defaults to true on create; left unchanged on update unless passed.", "type": [ "boolean", "null" ] }, "starts_at": { "description": "Optional start datetime (tenant timezone, stored as UTC). Pass null to clear.", "type": [ "string", "null" ] }, "ends_at": { "description": "Optional end datetime (tenant timezone, stored as UTC). Must be on/after starts_at. Pass null to clear.", "type": [ "string", "null" ] }, "variation_ids": { "description": "Product variation IDs to apply the bundle to. Omit to leave membership unchanged.", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "variation_mode": { "description": "How to apply variation_ids: \"replace\" (default), \"add\", or \"detach\".", "type": [ "string", "null" ] } }, "type": "object" }, "BundleUpsertResponse": { "properties": { "action": { "type": "string" }, "bundle_id": { "type": "integer" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" }, "discount_value_unit": { "type": "string" }, "is_active": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "variation_count": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" }, "CampaignApplyTemplateRequest": { "properties": { "campaign_id": { "description": "ID of the DRAFT campaign to apply the template to.", "type": "integer" }, "template_id": { "description": "System template id (e.g. \"summer-new-arrivals\"). Omit with use_month_default=true to apply this month's calendar default.", "type": [ "string", "null" ] }, "use_month_default": { "description": "When true and template_id is omitted, applies the month_calendar default for month (or the current month in the tenant timezone).", "type": [ "boolean", "null" ] }, "month": { "description": "Calendar month 1-12 for month_calendar lookup when use_month_default is true. Defaults to the current month.", "type": [ "integer", "null" ] } }, "type": "object", "required": [ "campaign_id" ] }, "CampaignApplyTemplateResponse": { "properties": { "error": { "type": [ "string", "null" ] }, "available_templates": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "type": "object" }, "type": [ "array", "null" ] }, "action": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "integer", "null" ] }, "template_id": { "type": [ "string", "null" ] }, "use_month_default": { "type": [ "boolean", "null" ] }, "month": { "type": [ "integer", "null" ] }, "theme": { "type": [ "string", "null" ] }, "html_body_length": { "type": [ "integer", "null" ] }, "has_unsubscribe_token": { "type": [ "boolean", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "CampaignAudienceInspectRequest": { "properties": { "contact_list_ids": { "description": "Contact list IDs to scope the split. Omit or pass [] to use all subscribed contacts + customers.", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "include_customers": { "description": "Include store customers in the audience. Defaults to true.", "type": [ "boolean", "null" ] }, "channel": { "description": "\"email\" or \"sms\". Defaults to email.", "type": [ "string", "null" ] } }, "type": "object" }, "CampaignAudienceInspectResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "channel": { "type": "string" }, "include_customers": { "type": "boolean" }, "warm": { "type": "integer" }, "cold": { "type": "integer" }, "guidance": { "type": "string" } }, "type": "object" }, "CampaignControlRequest": { "properties": { "campaign_id": { "description": "ID of the campaign to pause or resume.", "type": "integer" }, "action": { "description": "\"pause\" or \"resume\".", "type": "string" }, "dry_run": { "description": "If true (default), report without writing. Pass false to apply.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "campaign_id", "action" ] }, "CampaignControlResponse": { "properties": { "action": { "type": "string" }, "dry_run": { "type": "boolean" }, "tenant_slug": { "type": "string" }, "campaign_id": { "type": "integer" }, "campaign_name": { "type": "string" }, "previous_status": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "CampaignFlyerStylePackRequest": { "properties": { "action": { "description": "\"show\" (default behaviour), \"set\", or \"clear\".", "type": "string" }, "label": { "description": "set: a short name for the pack, e.g. \"Past in-house flyers\".", "type": [ "string", "null" ] }, "prompt_lines": { "description": "set: the art direction, one short line each. Replaces what is saved.", "type": [ "array", "null" ] }, "media_ids": { "description": "set: media library ids to use as style references. They move into the style-reference folder.", "type": [ "array", "null" ] }, "clear_images": { "description": "clear: also take the images out of the style-reference folder. They stay in the library.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "action" ] }, "CampaignFlyerStylePackResponse": { "properties": { "action": { "type": "string" }, "tenant_slug": { "type": "string" }, "enabled": { "type": "boolean" }, "label": { "type": "string" }, "prompt_lines": { "type": "array" }, "images": { "type": "array" }, "images_used_per_flyer": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" }, "CampaignGenerateFlyerRequest": { "properties": { "theme": { "description": "What the flyer is for, in plain words. E.g. \"September restock — cosy autumn mood, warm light\".", "type": "string" }, "product_ids": { "description": "Product IDs to feature. Their photos anchor the artwork. Omit to auto-pick the newest featured products that have images.", "type": [ "array", "null" ] }, "campaign_id": { "description": "DRAFT campaign to place the artwork into. Omit to only add it to the media library.", "type": [ "integer", "null" ] }, "slot_index": { "description": "1-based image slot to fill. Defaults to 1, the hero slot.", "type": [ "integer", "null" ] }, "aspect_ratio": { "description": "Shape of the artwork: \"4:3\" (default, email banner), \"1:1\", \"16:9\", \"3:4\". Anything else falls back to the default.", "type": [ "string", "null" ] }, "alt_text": { "description": "Alt text for the placed image. Defaults to the theme.", "type": [ "string", "null" ] } }, "type": "object", "required": [ "theme" ] }, "CampaignGenerateFlyerResponse": { "properties": { "action": { "type": "string" }, "media_id": { "type": "integer" }, "image_url": { "type": "string" }, "campaign_id": { "type": "integer" }, "placed": { "type": "boolean" }, "filled_placeholder": { "type": "boolean" }, "remaining_slots": { "type": "integer" }, "featured_products": { "type": "array" }, "message": { "type": "string" } }, "type": "object" }, "CampaignGetRequest": { "properties": { "campaign_id": { "description": "ID of the campaign to read.", "type": "integer" } }, "type": "object", "required": [ "campaign_id" ] }, "CampaignGetResponse": { "properties": { "campaign_id": { "type": "integer" }, "name": { "type": "string" }, "channel": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "fallback_first_name": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "status": { "type": "string" }, "audience_includes_customers": { "type": "boolean" }, "html_body": { "type": [ "string", "null" ] }, "html_body_length": { "type": [ "integer", "null" ] }, "plain_body": { "type": [ "string", "null" ] }, "sms_body": { "type": [ "string", "null" ] }, "sms_body_length": { "type": [ "integer", "null" ] }, "message": { "type": "string" } }, "type": "object" }, "CampaignRecipientsRequeueRequest": { "properties": { "campaign_id": { "description": "ID of the campaign to unstick.", "type": "integer" }, "include_failed": { "description": "Reset failed recipients to pending. Default true.", "type": [ "boolean", "null" ] }, "reset_stale_sending": { "description": "Reset stuck status=sending recipients to pending. Default true.", "type": [ "boolean", "null" ] }, "retry_sending_log_errors": { "description": "Retry recipients listed in the campaign sending error log (retryable types only). Default false.", "type": [ "boolean", "null" ] }, "dispatch_limit": { "description": "Max immediate send jobs when retry_sending_log_errors=true (default 200, max 500).", "type": [ "integer", "null" ] }, "dry_run": { "description": "If true (default), report counts without writing. Pass false to apply.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "campaign_id" ] }, "CampaignRecipientsRequeueResponse": { "properties": { "action": { "type": "string" }, "dry_run": { "type": "boolean" }, "tenant_slug": { "type": "string" }, "campaign_id": { "type": "integer" }, "campaign_name": { "type": "string" }, "previous_status": { "type": "string" }, "status": { "type": "string" }, "pending_before": { "type": "integer" }, "failed_before": { "type": "integer" }, "sending_before": { "type": "integer" }, "failed_requeued": { "type": "integer" }, "sending_reset": { "type": "integer" }, "pending_after": { "type": "integer" }, "failed_after": { "type": "integer" }, "sending_log_error_rows": { "type": "integer" }, "sending_log_recipients_matched": { "type": "integer" }, "sending_log_recipients_reset": { "type": "integer" }, "sending_log_jobs_dispatched": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" }, "CampaignSendTestRequest": { "properties": { "campaign_id": { "description": "ID of the campaign to send a test copy of.", "type": "integer" }, "to_email": { "description": "Email address for an email campaign test copy.", "type": [ "string", "null" ] }, "to_phone": { "description": "Phone number for a text campaign test copy (E.164 or local format).", "type": [ "string", "null" ] } }, "type": "object", "required": [ "campaign_id" ] }, "CampaignSendTestResponse": { "properties": { "action": { "type": "string" }, "channel": { "type": "string" }, "campaign_id": { "type": "integer" }, "sent_to": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "CampaignSetImageRequest": { "properties": { "campaign_id": { "description": "ID of the DRAFT campaign to place the image into.", "type": "integer" }, "media_id": { "description": "ID of a public image in the tenant's media library to insert.", "type": "integer" }, "slot_index": { "description": "1-based placeholder to fill when the body has more than one. Defaults to the first.", "type": [ "integer", "null" ] }, "alt_text": { "description": "Override alt text. Defaults to the media asset's own alt text, then the campaign name.", "type": [ "string", "null" ] } }, "type": "object", "required": [ "campaign_id", "media_id" ] }, "CampaignSetImageResponse": { "properties": { "action": { "type": "string" }, "campaign_id": { "type": "integer" }, "media_id": { "type": "integer" }, "image_url": { "type": "string" }, "filled_placeholder": { "type": "boolean" }, "appended": { "type": "boolean" }, "image_in_body": { "type": "boolean" }, "message": { "type": "string" } }, "type": "object" }, "CampaignSpamScoreRequest": { "properties": { "campaign_id": { "description": "Load content from this campaign. Omit to score inline subject/html_body or sms_body.", "type": [ "integer", "null" ] }, "channel": { "description": "\"email\" or \"sms\". Required when scoring inline content without campaign_id.", "type": [ "string", "null" ] }, "subject": { "description": "Email subject (inline mode).", "type": [ "string", "null" ] }, "html_body": { "description": "Email HTML body (inline mode).", "type": [ "string", "null" ] }, "sms_body": { "description": "SMS body (inline mode).", "type": [ "string", "null" ] }, "for_send": { "description": "If true, fold the send-time deep check into the same 0–100 score (email only). Default false (live rules).", "type": [ "boolean", "null" ] } }, "type": "object" }, "CampaignSpamScoreResponse": { "properties": { "score": { "type": "integer" }, "band": { "type": "string" }, "channel": { "type": "string" }, "summary": { "type": "string" }, "version": { "type": "string" }, "findings": { "items": { "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "penalty": { "type": "integer" }, "message": { "type": "string" }, "hint": { "type": "string" }, "evidence": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "can_send": { "type": "boolean" }, "min_send_score": { "type": "integer" }, "deep_check_applied": { "type": "boolean" }, "campaign_id": { "type": [ "integer", "null" ] }, "message": { "type": "string" } }, "type": "object" }, "CampaignUpsertRequest": { "properties": { "campaign_id": { "description": "ID of an existing campaign to edit. Omit to create a new draft.", "type": [ "integer", "null" ] }, "name": { "description": "Internal campaign name (max 120 chars). Required when creating.", "type": [ "string", "null" ] }, "channel": { "description": "\"email\" (default) or \"sms\" (text blast). Only set on create.", "type": [ "string", "null" ] }, "subject": { "description": "Email subject line shown to recipients (max 200 chars). Required when creating an email campaign.", "type": [ "string", "null" ] }, "fallback_first_name": { "description": "Stand-in when {{first_name}} is blank (max 80). Empty string clears. Omit on update to keep.", "type": [ "string", "null" ] }, "html_body": { "description": "Full email HTML. Sanitized on save. Use {{unsubscribe_url}}, {{first_name}}, {{last_name}} tokens.", "type": [ "string", "null" ] }, "sms_body": { "description": "Text message body for SMS campaigns (max 1600 chars). Required when creating a text campaign.", "type": [ "string", "null" ] }, "plain_body": { "description": "Optional plain-text alternative. Auto-derived from the HTML at send time if omitted.", "type": [ "string", "null" ] }, "mode": { "description": "\"smtp\" (default) or \"webhook\". Left unchanged on update unless passed.", "type": [ "string", "null" ] }, "audience_includes_customers": { "description": "Whether to include the tenant's customers in the audience. Defaults to true on create.", "type": [ "boolean", "null" ] } }, "type": "object" }, "CampaignUpsertResponse": { "properties": { "action": { "type": "string" }, "campaign_id": { "type": "integer" }, "name": { "type": "string" }, "channel": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "fallback_first_name": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "status": { "type": "string" }, "audience_includes_customers": { "type": "boolean" }, "message": { "type": "string" }, "sms_body_length": { "type": [ "integer", "null" ] }, "html_body_length": { "type": [ "integer", "null" ] }, "has_unsubscribe_token": { "type": [ "boolean", "null" ] }, "spam_score": { "type": [ "integer", "null" ] }, "spam_band": { "type": [ "string", "null" ] }, "spam_summary": { "type": [ "string", "null" ] }, "spam_can_send": { "type": [ "boolean", "null" ] }, "spam_min_send_score": { "type": [ "integer", "null" ] }, "spam_findings": { "items": { "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "penalty": { "type": "integer" }, "message": { "type": "string" }, "hint": { "type": "string" }, "evidence": { "type": [ "string", "null" ] } }, "type": "object" }, "type": [ "array", "null" ] } }, "type": "object" }, "CatalogCollapseRequest": { "properties": { "base_name": { "description": "The group to merge, exactly as returned by catalog_flattening_audit (e.g. \"GLITTER BOMB | TOP SHELF FLOWER\").", "type": "string" }, "dry_run": { "description": "Defaults to TRUE — shows the plan without changing anything. Pass false to actually merge.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "base_name" ] }, "CatalogCollapseResponse": { "properties": { "dry_run": { "type": "boolean" }, "base_name": { "type": "string" }, "survivor_product_id": { "type": [ "integer", "null" ] }, "survivor_slug": { "type": "string" }, "products_removed": { "type": "integer" }, "total_grams": { "type": "number" }, "cost_per_gram_cents": { "type": [ "integer", "null" ] }, "tiers": { "items": { "properties": { "label": { "type": "string" }, "weight_grams": { "type": "number" }, "price_cents": { "type": "integer" } }, "type": "object" }, "type": "array" }, "absorbed": { "items": { "properties": { "product_id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "notes": { "items": { "type": "string" }, "type": "array" }, "tenant_slug": { "type": "string" }, "next_step": { "type": "string" } }, "type": "object" }, "CatalogFlatteningAuditRequest": { "type": "object", "properties": [] }, "CatalogFlatteningAuditResponse": { "properties": { "tenant_slug": { "type": "string" }, "summary": { "properties": { "flattened_products": { "type": "integer" }, "collapsible_families": { "type": "integer" }, "blocked_families": { "type": "integer" }, "products_removed_if_merged": { "type": "integer" } }, "type": "object" }, "families": { "items": { "properties": { "base_name": { "type": "string" }, "collapsible": { "type": "boolean" }, "blocker": { "type": [ "string", "null" ] }, "members": { "items": { "properties": { "product_id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "weight_grams": { "type": "number" }, "price_cents": { "type": "integer" }, "cost_cents": { "type": [ "integer", "null" ] }, "stock_units": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "CategoryManageRequest": { "properties": { "action": { "description": "\"list\" (default), \"create\", \"update\", or \"delete\".", "type": [ "string", "null" ] }, "category_id": { "description": "ID of an existing category. Required for update and delete.", "type": [ "integer", "null" ] }, "name": { "description": "Category name shown to customers. Required when creating.", "type": [ "string", "null" ] }, "slug": { "description": "URL slug, unique per tenant. Auto-generated from name when omitted on create.", "type": [ "string", "null" ] }, "description": { "description": "Optional category description.", "type": [ "string", "null" ] }, "parent_id": { "description": "Parent category id, or null for a top-level category.", "type": [ "integer", "null" ] }, "sort_order": { "description": "Display order (lower sorts first).", "type": [ "integer", "null" ] }, "is_active": { "description": "Whether the category is visible on the storefront.", "type": [ "boolean", "null" ] }, "is_featured": { "description": "Whether the category appears in the homepage featured grid.", "type": [ "boolean", "null" ] }, "media_id": { "description": "Media library asset id to set as image_path (the branded, customer-facing image).", "type": [ "integer", "null" ] }, "base_media_id": { "description": "Media library asset id to set as base_image_path (the unbranded source canvas).", "type": [ "integer", "null" ] }, "confirm": { "description": "Required (true) for action=delete.", "type": [ "boolean", "null" ] } }, "type": "object" }, "CategoryManageResponse": { "properties": { "action": { "type": "string" }, "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "total": { "type": [ "integer", "null" ] }, "categories": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_id": { "type": [ "integer", "null" ] }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_featured": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] }, "base_image_path": { "type": [ "string", "null" ] }, "product_count": { "type": "integer" } }, "type": "object" }, "type": [ "array", "null" ] }, "category": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_id": { "type": [ "integer", "null" ] }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_featured": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] }, "base_image_path": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "ContactCleanupRequest": { "properties": { "statuses": { "description": "Which validation statuses to purge. Defaults to [\"invalid\"]. Only \"invalid\" and \"risky\" are allowed; \"unknown\" is refused because those contacts are simply not graded yet.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "list_id": { "description": "Limit the purge to one contact list. Omit to sweep every list in the store.", "type": [ "integer", "null" ] }, "dry_run": { "description": "Defaults to TRUE — reports what would be deleted without deleting. Pass false to actually delete.", "type": [ "boolean", "null" ] } }, "type": "object" }, "CouponListRequest": { "properties": { "only_active": { "description": "Return only is_active coupons. Defaults to false (all coupons).", "type": [ "boolean", "null" ] } }, "type": "object" }, "CouponListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "summary": { "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "exhausted": { "type": "integer" } }, "type": "object" }, "coupons": { "items": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "number" }, "value_unit": { "type": "string" }, "min_order_cents": { "type": "integer" }, "max_uses": { "type": [ "integer", "null" ] }, "used_count": { "type": "integer" }, "is_exhausted": { "type": "boolean" }, "max_uses_per_customer": { "type": "integer" }, "limit_match_by": { "type": "string" }, "applies_to": { "type": "string" }, "is_active": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "CouponUpsertRequest": { "properties": { "coupon_id": { "description": "ID of an existing coupon to update. Omit to create a new coupon.", "type": [ "integer", "null" ] }, "code": { "description": "Coupon code customers enter at checkout (case-insensitive, stored uppercase). Required when creating.", "type": [ "string", "null" ] }, "type": { "description": "\"percentage\", \"fixed\", or \"free_delivery\". Required when creating.", "type": [ "string", "null" ] }, "value": { "description": "Percent 0-100 for \"percentage\"; dollars for \"fixed\"; ignored for \"free_delivery\". Required when creating (pass 0 for free_delivery).", "type": [ "number", "null" ] }, "min_order": { "description": "Minimum order subtotal in dollars required to use the coupon. Omit or 0 for no minimum.", "type": [ "number", "null" ] }, "freebie_id": { "description": "ID of a Freebie (from freebie_list) to link, making this a code-triggered freebie. Pass null to unlink.", "type": [ "integer", "null" ] }, "max_uses": { "description": "Total redemption cap across all customers. Omit/null for unlimited.", "type": [ "integer", "null" ] }, "max_uses_per_customer": { "description": "Redemption cap per customer, matched via limit_match_by. Defaults to 1.", "type": [ "integer", "null" ] }, "limit_match_by": { "description": "\"email\", \"phone\", or \"both\" — how max_uses_per_customer is enforced. \"phone\"/\"both\" require the tenant's phone-at-checkout setting to be on.", "type": [ "string", "null" ] }, "applies_to": { "description": "\"all\", \"products\", or \"categories\". See tool description for applies_to_ids.", "type": [ "string", "null" ] }, "applies_to_ids": { "description": "Product ids (applies_to=\"products\") or category ids (applies_to=\"categories\") this coupon is scoped to. All must belong to this tenant. Pass [] to clear.", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "requires_subscribed_customer": { "description": "Newsletter-subscriber-exclusive code: when true, only a registered customer who has NOT opted out of marketing email (email_opt_out=false) can redeem it. Gates to store customers only — never platform leads. Guests are always rejected. Defaults to false.", "type": [ "boolean", "null" ] }, "subscription_ladder_id": { "description": "ID of an existing SubscriptionDiscountLadder to link. Pass null to unlink. See tool description.", "type": [ "integer", "null" ] }, "ladder_start_percent": { "description": "Mounting ladder: percent off for orders before start_order_index. 0-100. See tool description.", "type": [ "integer", "null" ] }, "ladder_step_percent": { "description": "Mounting ladder: percent the discount climbs each order once past start_order_index. 0-100. See tool description.", "type": [ "integer", "null" ] }, "ladder_cap_percent": { "description": "Mounting ladder: ceiling percent the discount pegs at once reached. 0-100. See tool description.", "type": [ "integer", "null" ] }, "ladder_start_order_index": { "description": "Mounting ladder: 1-based order number the climb begins at. See tool description.", "type": [ "integer", "null" ] }, "is_active": { "description": "Whether the coupon is live. Defaults to true on create; left unchanged on update unless passed.", "type": [ "boolean", "null" ] }, "starts_at": { "description": "Optional start date (tenant timezone, stored as UTC start-of-day). Pass null to clear.", "type": [ "string", "null" ] }, "expires_at": { "description": "Optional expiry date (tenant timezone, stored as UTC end-of-day). Must be on/after starts_at. Pass null to clear.", "type": [ "string", "null" ] } }, "type": "object" }, "CouponUpsertResponse": { "properties": { "action": { "type": "string" }, "coupon_id": { "type": "integer" }, "code": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "number" }, "value_unit": { "type": "string" }, "min_order_cents": { "type": "integer" }, "freebie_id": { "type": [ "integer", "null" ] }, "subscription_ladder_id": { "type": [ "integer", "null" ] }, "applies_to": { "type": "string" }, "applies_to_ids": { "items": { "type": "integer" }, "type": [ "array", "null" ] }, "requires_subscribed_customer": { "type": "boolean" }, "is_active": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "message": { "type": "string" } }, "type": "object" }, "CustomerAddressesRequest": { "properties": { "customer_id": { "description": "Exact customer id (optional)", "type": [ "integer", "null" ] }, "email": { "description": "Exact customer email (optional)", "type": [ "string", "null" ] }, "phone": { "description": "Customer phone number (optional)", "type": [ "string", "null" ] } }, "type": "object" }, "CustomerAddressesResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "customer": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "default_address_id": { "type": [ "integer", "null" ] } }, "type": "object" }, "addresses": { "items": { "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "address": { "type": "string" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "saved_zone": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "detected_zone": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "zone_matches_saved_zone": { "type": [ "boolean", "null" ] }, "is_default": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "CustomerListRequest": { "properties": { "updated_since": { "description": "ISO-8601 timestamp — only return customers updated at or after this time (optional)", "type": [ "string", "null" ] }, "limit": { "description": "Rows per page (default 25, max 100)", "type": [ "integer", "null" ] }, "cursor": { "description": "Opaque cursor from a previous response's next_cursor — omit to start from the first page", "type": [ "string", "null" ] } }, "type": "object" }, "CustomerListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "customers": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "loyalty_points": { "type": "integer" }, "email_verified_at": { "type": [ "string", "null" ] }, "last_login_at": { "type": [ "string", "null" ] }, "id_verified_at": { "type": [ "string", "null" ] }, "medical_record_verified_at": { "type": [ "string", "null" ] }, "phone_verified_at": { "type": [ "string", "null" ] }, "phone_validation_status": { "type": "string" }, "no_loyalty": { "type": "boolean" }, "no_coupons": { "type": "boolean" }, "deletion_requested_at": { "type": [ "string", "null" ] }, "email_opt_out": { "type": "boolean" }, "sms_marketing_opt_out": { "type": "boolean" }, "sms_notifications_muted": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "type": "object" }, "CustomerLookupRequest": { "properties": { "customer_id": { "description": "Exact customer id (optional)", "type": [ "integer", "null" ] }, "email": { "description": "Exact customer email (optional)", "type": [ "string", "null" ] }, "phone": { "description": "Customer phone number, digits or formatted (optional)", "type": [ "string", "null" ] }, "name": { "description": "Partial customer name (optional)", "type": [ "string", "null" ] }, "limit": { "description": "Number of matches to return (default 10, max 25)", "type": [ "integer", "null" ] } }, "type": "object" }, "CustomerLookupResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "matched_customers": { "type": "integer" }, "customers": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "loyalty_points": { "type": "integer" }, "email_verified_at": { "type": [ "string", "null" ] }, "last_login_at": { "type": [ "string", "null" ] }, "default_address_id": { "type": [ "integer", "null" ] }, "id_verified_at": { "type": [ "string", "null" ] }, "medical_record_verified_at": { "type": [ "string", "null" ] }, "phone_verified_at": { "type": [ "string", "null" ] }, "phone_validation_status": { "type": "string" }, "no_loyalty": { "type": "boolean" }, "no_coupons": { "type": "boolean" }, "deletion_requested_at": { "type": [ "string", "null" ] }, "email_opt_out": { "type": "boolean" }, "sms_marketing_opt_out": { "type": "boolean" }, "sms_notifications_muted": { "type": "boolean" }, "addresses_count": { "type": "integer" }, "orders_count": { "type": "integer" }, "conversation_count": { "type": "integer" }, "addresses": { "items": { "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "address": { "type": "string" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "zone_id": { "type": [ "integer", "null" ] }, "zone_name": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "recent_orders": { "items": { "properties": { "id": { "type": "integer" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "total": { "type": "integer" }, "total_display": { "type": "string" }, "coupon_code": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "CustomerUpdateRequest": { "properties": { "customer_id": { "description": "The customer to update", "type": "integer" }, "name": { "description": "New display name", "type": [ "string", "null" ] }, "email": { "description": "New email address (must be unique within the tenant)", "type": [ "string", "null" ] }, "phone": { "description": "New phone number, digits or formatted", "type": [ "string", "null" ] }, "email_opt_out": { "description": "Set true to suppress marketing email. Cannot be set to false — un-suppression happens in DabDash only.", "type": [ "boolean", "null" ] }, "sms_marketing_opt_out": { "description": "Set true to suppress marketing texts. Cannot be set to false.", "type": [ "boolean", "null" ] }, "sms_notifications_muted": { "description": "Set true to mute transactional/order SMS notifications. Cannot be set to false.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "customer_id" ] }, "CustomerUpdateResponse": { "properties": { "customer": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email_opt_out": { "type": "boolean" }, "sms_marketing_opt_out": { "type": "boolean" }, "sms_notifications_muted": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ] } }, "type": "object" }, "updated_fields": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "FreebieListRequest": { "properties": { "only_active": { "description": "Return only is_active freebies. Defaults to false (all freebies).", "type": [ "boolean", "null" ] } }, "type": "object" }, "FreebieListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "summary": { "properties": { "total": { "type": "integer" }, "active": { "type": "integer" } }, "type": "object" }, "freebies": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "spend_threshold_cents": { "type": "integer" }, "product_id": { "type": "integer" }, "product_name": { "type": [ "string", "null" ] }, "is_merch_product": { "type": "boolean" }, "variation_id": { "type": [ "integer", "null" ] }, "variation_name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "is_stackable": { "type": "boolean" }, "is_active": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "FreebieUpsertRequest": { "properties": { "freebie_id": { "description": "ID of an existing freebie to update. Omit to create a new freebie.", "type": [ "integer", "null" ] }, "name": { "description": "Freebie name shown to vendors (e.g. \"Spend $50 Get Papers\"). Required when creating.", "type": [ "string", "null" ] }, "product_id": { "description": "The product given away. Must belong to this tenant. Required when creating.", "type": [ "integer", "null" ] }, "variation_id": { "description": "Optional specific variation of product_id to give away. Must belong to this tenant. Pass null to clear.", "type": [ "integer", "null" ] }, "spend_threshold": { "description": "Minimum cart spend in dollars that triggers this freebie. Required when creating.", "type": [ "number", "null" ] }, "quantity": { "description": "How many units of the product/variation are given away once triggered. Required when creating.", "type": [ "integer", "null" ] }, "is_stackable": { "description": "Whether this rule can combine with other freebie rules on the same order. Defaults to false.", "type": [ "boolean", "null" ] }, "is_active": { "description": "Whether the freebie is live. Defaults to true on create; left unchanged on update unless passed.", "type": [ "boolean", "null" ] }, "starts_at": { "description": "Optional start date (tenant timezone, stored as UTC). Pass null to clear.", "type": [ "string", "null" ] }, "ends_at": { "description": "Optional end date (tenant timezone, stored as UTC). Must be on/after starts_at. Pass null to clear.", "type": [ "string", "null" ] }, "category_ids": { "description": "Category IDs to scope this freebie to. Must belong to this tenant; foreign ids are ignored. Omit to leave unchanged; pass an empty array to clear all.", "items": { "type": "integer" }, "type": [ "array", "null" ] } }, "type": "object" }, "FreebieUpsertResponse": { "properties": { "action": { "type": "string" }, "freebie_id": { "type": "integer" }, "name": { "type": "string" }, "product_id": { "type": "integer" }, "variation_id": { "type": [ "integer", "null" ] }, "spend_threshold_cents": { "type": "integer" }, "quantity": { "type": "integer" }, "is_stackable": { "type": "boolean" }, "is_active": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "category_count": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" }, "GoogleAnalyticsRequest": { "properties": { "report": { "description": "The report type to run", "enum": [ "overview", "top_pages", "traffic_sources", "top_events", "daily_trend" ], "type": "string" }, "days": { "description": "Number of days to look back (default 30, max 365)", "type": [ "integer", "null" ] } }, "type": "object", "required": [ "report" ] }, "GoogleAnalyticsResponse": { "properties": { "scope": { "type": "string" }, "property": { "type": [ "string", "null" ] }, "property_id": { "type": [ "string", "null" ] }, "report": { "type": "string" }, "days": { "type": "integer" }, "results": { "anyOf": [ { "properties": { "sessions": { "type": [ "integer", "null" ] }, "avg_session_duration": { "type": [ "string", "null" ] }, "avg_session_duration_seconds": { "type": [ "number", "null" ] }, "pageviews": { "type": [ "integer", "null" ] }, "bounce_rate": { "type": [ "number", "null" ] }, "users": { "type": [ "integer", "null" ] } }, "type": "object" }, { "items": { "properties": { "path": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "medium": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] }, "pageviews": { "type": [ "integer", "null" ] }, "sessions": { "type": [ "integer", "null" ] }, "users": { "type": [ "integer", "null" ] }, "count": { "type": [ "integer", "null" ] }, "bounce_rate": { "type": [ "number", "null" ] }, "avg_session_duration": { "type": [ "number", "null" ] }, "mobile_pct": { "type": [ "number", "null" ] }, "desktop_pct": { "type": [ "number", "null" ] } }, "type": "object" }, "type": "array" } ] } }, "type": "object" }, "InventoryAuditLookupRequest": { "properties": { "product_ids": { "description": "List of product IDs to look up.", "type": "array" }, "cutoff_iso": { "description": "ISO8601 timestamp. The last quantity_after strictly BEFORE this moment is returned for each variation. Example: \"2026-05-03T00:00:00Z\".", "type": "string" } }, "type": "object", "required": [ "product_ids", "cutoff_iso" ] }, "InventoryAuditLookupResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "cutoff": { "type": "string" }, "not_found_product_ids": { "items": { "type": "integer" }, "type": "array" }, "products": { "items": { "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "product_slug": { "type": "string" }, "current_state": { "properties": { "tracking_type": { "type": "string" }, "inventory_mode": { "type": [ "string", "null" ] }, "pricing_structure_id": { "type": [ "integer", "null" ] }, "product_stock_quantity": { "type": "number" }, "variations": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "stock_quantity": { "type": "number" }, "price_cents": { "type": "integer" }, "weight_value": { "type": [ "number", "null" ] }, "sort_order": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "audit_history": { "items": { "properties": { "variation_id": { "type": [ "integer", "null" ] }, "last_quantity_after_before_cutoff": { "type": [ "number", "null" ] }, "last_action": { "type": [ "string", "null" ] }, "last_notes": { "type": [ "string", "null" ] }, "last_reference_type": { "type": [ "string", "null" ] }, "last_logged_at": { "type": "string" }, "variation_currently_exists": { "type": "boolean" }, "variation_current_name": { "type": [ "string", "null" ] }, "variation_current_stock": { "type": [ "number", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "InventoryStatusRequest": { "properties": { "alert_only": { "description": "If true, return only low-stock and out-of-stock items (default false)", "type": [ "boolean", "null" ] } }, "type": "object" }, "InventoryStatusResponse": { "properties": { "summary": { "properties": { "total_products": { "type": "integer" }, "in_stock": { "type": "integer" }, "low_stock_alerts": { "type": "integer" }, "out_of_stock": { "type": "integer" } }, "type": "object" }, "low_stock_alerts": { "items": { "properties": { "tenant": { "type": "string" }, "product": { "type": "string" }, "quantity": { "type": "number" }, "threshold": { "type": "number" } }, "type": "object" }, "type": "array" }, "out_of_stock": { "items": { "properties": { "tenant": { "type": "string" }, "product": { "type": "string" } }, "type": "object" }, "type": "array" }, "in_stock_items": { "items": { "properties": { "tenant": { "type": "string" }, "product": { "type": "string" }, "quantity": { "type": "number" } }, "type": "object" }, "type": [ "array", "null" ] } }, "type": "object" }, "MailboxInspectRequest": { "properties": { "platform": { "description": "Inspect a platform-owned mailbox (tenant_id IS NULL). When true, tenant_slug is ignored and email_account_id is required.", "type": "boolean" }, "email_account_id": { "description": "Specific EmailAccount id (required for platform=true; optional for tenant_slug — defaults to the tenant's single mailbox).", "type": "integer" } }, "type": "object" }, "MailboxInspectResponse": { "properties": { "account": { "properties": { "id": { "type": "integer" }, "tenant_id": { "type": [ "integer", "null" ] }, "tenant_slug": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" }, "encryption": { "type": "string" }, "folder": { "type": "string" }, "is_active": { "type": "boolean" }, "leave_on_server": { "type": "boolean" } }, "type": "object" }, "sync_state": { "properties": { "last_synced_uid": { "type": [ "integer", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] }, "minutes_since_last_sync": { "type": [ "integer", "null" ] }, "last_sync_error": { "type": [ "string", "null" ] }, "last_sync_error_at": { "type": [ "string", "null" ] }, "minutes_since_last_error": { "type": [ "integer", "null" ] } }, "type": "object" }, "ingestion": { "properties": { "inbound_count": { "type": "integer" }, "outbound_count": { "type": "integer" }, "total_count": { "type": "integer" }, "last_inbound_fetched_at": { "type": [ "string", "null" ] }, "last_inbound_minutes_ago": { "type": [ "integer", "null" ] } }, "type": "object" }, "verdict": { "properties": { "state": { "type": "string" }, "explanation": { "type": "string" }, "suggested_action": { "type": [ "string", "null" ] } }, "type": "object" }, "recent_messages": { "items": { "properties": { "id": { "type": "integer" }, "direction": { "type": "string" }, "from_domain": { "type": [ "string", "null" ] }, "subject_length": { "type": "integer" }, "fetched_at": { "type": [ "string", "null" ] }, "has_attachments": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "MediaComposeRequest": { "properties": { "category_id": { "description": "Storefront swag mode: composite the platform branding onto this category via SwagImagesService instead of the manual layout below. At most one of category_id or widget_id.", "type": [ "integer", "null" ] }, "widget_id": { "description": "Storefront swag mode: composite the platform branding onto this widget via SwagImagesService instead of the manual layout below. At most one of category_id or widget_id.", "type": [ "integer", "null" ] }, "base_media_id": { "description": "ID of a library image to use as the background. Provide exactly one of base_media_id or base_url.", "type": [ "integer", "null" ] }, "base_url": { "description": "Public http(s) URL of the background image. Provide exactly one of base_media_id or base_url.", "type": [ "string", "null" ] }, "logo_media_id": { "description": "ID of a library image to place on top, unaltered. At most one of logo_media_id or logo_url.", "type": [ "integer", "null" ] }, "logo_url": { "description": "Public http(s) URL of the logo to place on top, unaltered.", "type": [ "string", "null" ] }, "headline": { "description": "Large text under the logo (max 120 chars). Wrapped to at most 2 lines.", "type": [ "string", "null" ] }, "subtitle": { "description": "Smaller text under the headline (max 200 chars). Wrapped to at most 3 lines.", "type": [ "string", "null" ] }, "font": { "description": "Typeface: anton, bebas, oswald, playfair, sans, serif. Defaults to \"sans\".", "type": [ "string", "null" ] }, "logo_position": { "description": "Vertical placement of the whole block: \"top\", \"center\" (default) or \"bottom\".", "type": [ "string", "null" ] }, "logo_width_pct": { "description": "Logo width as a fraction of the base width, 0.05-0.90. Defaults to 0.30.", "type": [ "number", "null" ] }, "text_color": { "description": "Headline colour as #RRGGBB. Defaults to #FFFFFF.", "type": [ "string", "null" ] }, "subtitle_color": { "description": "Subtitle colour as #RRGGBB. Defaults to text_color.", "type": [ "string", "null" ] }, "headline_size_pct": { "description": "Headline size as a fraction of base width, 0.01-0.25. Defaults to 0.07.", "type": [ "number", "null" ] }, "subtitle_size_pct": { "description": "Subtitle size as a fraction of base width, 0.01-0.15. Defaults to 0.035.", "type": [ "number", "null" ] }, "scrim": { "description": "Darkening behind the logo/text for legibility: \"none\", \"soft\" (default) or \"strong\".", "type": [ "string", "null" ] }, "text_shadow": { "description": "Draw a soft shadow under the text. Defaults to true.", "type": [ "boolean", "null" ] }, "filename": { "description": "Filename to record for the new asset (e.g. \"natal-day-hero.png\").", "type": [ "string", "null" ] }, "alt_text": { "description": "Alt text for accessibility and captions (max 500 chars).", "type": [ "string", "null" ] }, "folder": { "description": "Library folder to group the asset under (max 100 chars).", "type": [ "string", "null" ] } }, "type": "object" }, "MediaComposeResponse": { "properties": { "action": { "type": "string" }, "media_id": { "type": [ "integer", "null" ] }, "url": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "original_filename": { "type": [ "string", "null" ] }, "alt_text": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ] }, "visibility": { "type": [ "string", "null" ] }, "composed_layers": { "type": [ "string", "null" ] }, "wrapped": { "type": [ "boolean", "null" ] }, "category_id": { "type": [ "integer", "null" ] }, "widget_id": { "type": [ "integer", "null" ] }, "image_path": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "message": { "type": "string" } }, "type": "object" }, "MediaListRequest": { "properties": { "visibility": { "description": "\"public\" (default), \"private\", or \"all\".", "type": [ "string", "null" ] }, "folder": { "description": "Only return assets in this exact library folder.", "type": [ "string", "null" ] }, "search": { "description": "Filter by a substring of the original filename.", "type": [ "string", "null" ] } }, "type": "object" }, "MediaListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "visibility": { "type": "string" }, "total": { "type": "integer" }, "returned": { "type": "integer" }, "truncated": { "type": "boolean" }, "assets": { "items": { "properties": { "media_id": { "type": "integer" }, "url": { "type": "string" }, "original_filename": { "type": [ "string", "null" ] }, "mime_type": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "orientation": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ] }, "alt_text": { "type": [ "string", "null" ] }, "size_bytes": { "type": "integer" }, "visibility": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "MediaUploadRequest": { "properties": { "source_url": { "description": "Public http(s) URL to fetch the image from. Provide exactly one source.", "type": [ "string", "null" ] }, "source_path": { "description": "Local file path to read the image from. Provide exactly one source.", "type": [ "string", "null" ] }, "source_base64": { "description": "Base64-encoded image bytes (data: prefix optional). Provide exactly one source.", "type": [ "string", "null" ] }, "filename": { "description": "Original filename to record (e.g. \"summer-flyer.png\"). Defaults to a derived name.", "type": [ "string", "null" ] }, "alt_text": { "description": "Alt text for accessibility and captions (max 500 chars).", "type": [ "string", "null" ] }, "folder": { "description": "Optional library folder to group the asset under (max 100 chars).", "type": [ "string", "null" ] } }, "type": "object" }, "MediaUploadResponse": { "properties": { "action": { "type": "string" }, "media_id": { "type": "integer" }, "url": { "type": "string" }, "mime_type": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "size_bytes": { "type": "integer" }, "original_filename": { "type": [ "string", "null" ] }, "alt_text": { "type": [ "string", "null" ] }, "folder": { "type": [ "string", "null" ] }, "visibility": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "MetrcDiagnosticsRequest": { "type": "object", "properties": [] }, "MetrcDiagnosticsResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "integration": { "anyOf": [ { "properties": { "status": { "type": "string" } }, "type": "object" }, { "properties": { "status": { "type": "string" }, "mode": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "license_number": { "type": "string" }, "connected_at": { "type": [ "string", "null" ] }, "last_error_at": { "type": [ "string", "null" ] }, "last_error_message": { "type": [ "string", "null" ] } }, "type": "object" } ] }, "sync_states": { "items": { "properties": { "resource": { "type": "string" }, "last_run_at": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "audit_log_counts_by_http_status": { "type": "object" }, "report_counts_by_status": { "type": "object" }, "last_reconciliation_run": { "properties": { "run_at": { "type": "string" }, "matched_count": { "type": "integer" }, "drifted_count": { "type": "integer" }, "note": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "type": "object" }, "OrderDashboardRequest": { "properties": { "order_number": { "description": "Exact order number (optional)", "type": [ "string", "null" ] }, "customer_email": { "description": "Exact customer email (optional)", "type": [ "string", "null" ] }, "customer_phone": { "description": "Customer phone number, digits or formatted (optional)", "type": [ "string", "null" ] }, "status": { "description": "Filter by order status: pending, confirmed, preparing, out_for_delivery, delivered, cancelled", "enum": [ "pending", "confirmed", "preparing", "out_for_delivery", "delivered", "cancelled" ], "type": [ "string", "null" ] }, "payment_status": { "description": "Filter by payment status: pending, paid, failed, refunded", "enum": [ "pending", "paid", "failed", "refunded" ], "type": [ "string", "null" ] }, "date_from": { "description": "Start date filter (YYYY-MM-DD format)", "type": [ "string", "null" ] }, "date_to": { "description": "End date filter (YYYY-MM-DD format)", "type": [ "string", "null" ] }, "min_total": { "description": "Minimum order total in cents", "type": [ "integer", "null" ] }, "limit": { "description": "Number of orders to return (default 25, max 100)", "type": [ "integer", "null" ] } }, "type": "object" }, "OrderDashboardResponse": { "properties": { "summary": { "properties": { "matched_orders": { "type": "integer" }, "total_revenue_cents": { "type": "integer" }, "total_revenue": { "type": "string" } }, "type": "object" }, "orders": { "items": { "properties": { "id": { "type": "integer" }, "order_number": { "type": "string" }, "tenant": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "subtotal": { "type": "string" }, "total": { "type": "string" }, "customer_email": { "type": [ "string", "null" ] }, "customer_phone": { "type": [ "string", "null" ] }, "coupon_code": { "type": [ "string", "null" ] }, "coupon_discount": { "type": "string" }, "mix_match_discount": { "type": "string" }, "loyalty_discount": { "type": "string" }, "is_asap": { "type": "boolean" }, "scheduled_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PricingStructureAssignRequest": { "properties": { "structure_id": { "description": "ID of the shared BUNDLE structure to assign. Must NOT be a hidden (inline) structure.", "type": "integer" }, "product_slugs": { "description": "List of product slugs to assign to this structure. Provide product_slugs or product_ids (or both).", "type": [ "array", "null" ] }, "product_ids": { "description": "List of product IDs to assign to this structure. Provide product_slugs or product_ids (or both).", "type": [ "array", "null" ] } }, "type": "object", "required": [ "structure_id" ] }, "PricingStructureAssignResponse": { "properties": { "structure_id": { "type": "integer" }, "structure_name": { "type": "string" }, "tracking_type": { "type": "string" }, "summary": { "properties": { "assigned": { "type": "integer" }, "skipped": { "type": "integer" }, "refused": { "type": "integer" }, "not_found": { "type": "integer" } }, "type": "object" }, "results": { "items": { "properties": { "identifier": { "type": [ "integer", "string" ] }, "product_id": { "type": [ "integer", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "orphaned_structure_deleted": { "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PricingStructureDeleteRequest": { "properties": { "structure_ids": { "description": "List of structure IDs to delete. Bundle structures are always accepted; inline structures are only accepted when product_count=0.", "type": "array" }, "force": { "description": "If true, deletes even if products are still assigned (they will be orphaned — use only after migrating products). Requires orphan_products_acknowledged=true alongside.", "type": [ "boolean", "null" ] }, "orphan_products_acknowledged": { "description": "Explicit acknowledgment that force=true will orphan products. Required when force=true and any structure has product_count > 0. Defaults to false.", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "structure_ids" ] }, "PricingStructureDeleteResponse": { "properties": { "summary": { "properties": { "deleted": { "type": "integer" }, "refused": { "type": "integer" }, "not_found": { "type": "integer" } }, "type": "object" }, "results": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "product_count": { "type": [ "integer", "null" ] }, "product_count_at_deletion": { "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PricingStructureListRequest": { "properties": { "kind": { "description": "Filter by kind: \"inline\" for hidden 1:1 structures, \"bundle\" for shared structures, or omit for all.", "type": [ "string", "null" ] }, "include_tiers": { "description": "Include tier details for each structure. Defaults to false.", "type": [ "boolean", "null" ] }, "include_product_ids": { "description": "Include the list of product IDs assigned to each structure. Defaults to false.", "type": [ "boolean", "null" ] } }, "type": "object" }, "PricingStructureListResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "summary": { "properties": { "total": { "type": "integer" }, "bundle_count": { "type": "integer" }, "inline_count": { "type": "integer" } }, "type": "object" }, "structures": { "items": { "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "tracking_type": { "type": "string" }, "family": { "type": "string" }, "is_default": { "type": "boolean" }, "product_count": { "type": "integer" }, "product_ids": { "items": { "type": "integer" }, "type": [ "array", "null" ] }, "tiers": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "weight_grams": { "type": "number" }, "price_cents": { "type": "integer" }, "price_display": { "type": "string" }, "compare_at_price_cents": { "type": [ "integer", "null" ] }, "compare_at_price_display": { "type": [ "string", "null" ] }, "cost_price_cents": { "type": [ "integer", "null" ] }, "mix_match_tags": { "type": [ "array", "null" ] }, "sort_order": { "type": "integer" } }, "type": "object" }, "type": [ "array", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PricingStructureRestoreRequest": { "properties": { "product_id": { "description": "The product whose pricing structure and variations will be rebuilt.", "type": "integer" }, "tracking_type": { "description": "Tracking type for the new inline structure: simple, unit, weight, matrix, matrix_unit.", "type": "string" }, "inventory_mode": { "description": "Inventory mode override: \"product\" or \"variation\". If omitted, defaults are applied per tracking_type rules (weight→product, matrix→variation).", "type": [ "string", "null" ] }, "product_stock_quantity": { "description": "When inventory_mode=product, the value to set on products.stock_quantity. Ignored otherwise.", "type": [ "number", "null" ] }, "tiers": { "description": "Array of tiers. Each: {name (string, required), price (dollars, required), compare_at_price (dollars, nullable), cost_price (dollars, nullable), weight_grams (number, required for weight/matrix), mix_match_tags (array, nullable), stock_quantity (number, required), restore_variation_id (int, optional — re-uses an existing variation row).}", "type": "array" }, "delete_unreferenced": { "description": "If true, hard-deletes variations not referenced in tiers. Default false (deactivates them).", "type": [ "boolean", "null" ] } }, "type": "object", "required": [ "product_id", "tracking_type", "tiers" ] }, "PricingStructureRestoreResponse": { "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "new_structure_id": { "type": "integer" }, "tracking_type": { "type": "string" }, "inventory_mode": { "type": "string" }, "tiers": { "items": { "properties": { "tier_name": { "type": "string" }, "variation_id": { "type": "integer" }, "action": { "type": "string" }, "stock_quantity": { "type": "number" } }, "type": "object" }, "type": "array" }, "unreferenced_variations": { "items": { "properties": { "variation_id": { "type": "integer" }, "name": { "type": "string" }, "stock_quantity": { "type": "number" } }, "type": "object" }, "type": "array" }, "unreferenced_action": { "type": "string" } }, "type": "object" }, "PricingStructureUpsertRequest": { "properties": { "structure_id": { "description": "ID of an existing BUNDLE structure to update. Must NOT be a hidden (inline) structure. Omit to create a new bundle or to edit inline via product_slug/product_id.", "type": [ "integer", "null" ] }, "product_slug": { "description": "Product slug for inline (1:1) mode. Identifies which product's hidden structure to edit. Mutually exclusive with structure_id.", "type": [ "string", "null" ] }, "product_id": { "description": "Product id for inline (1:1) mode. Alternative to product_slug. Mutually exclusive with structure_id.", "type": [ "integer", "null" ] }, "name": { "description": "Structure name. Required when creating a bundle. Ignored for inline structures (name is derived from the product name).", "type": [ "string", "null" ] }, "tracking_type": { "description": "Pricing type: simple, weight, unit, matrix, or matrix_unit. Required when creating. For updates, changing tracking_type re-syncs all linked products.", "type": [ "string", "null" ] }, "tiers": { "description": "Replacement tier list. Each tier: {name (string, required), weight_grams (number, required for weight/matrix), price (dollars, required), compare_at_price (dollars, nullable), cost_price (dollars, nullable), mix_match_tags (array of strings, nullable)}.", "type": [ "array", "null" ] } }, "type": "object" }, "PricingStructureUpsertResponse": { "properties": { "mode": { "type": "string" }, "structure_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "tracking_type": { "type": [ "string", "null" ] }, "tier_count": { "type": [ "integer", "null" ] }, "products_resynced": { "type": [ "integer", "null" ] }, "warning": { "type": [ "string", "null" ] }, "product_id": { "type": [ "integer", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "ProductFeatureManageRequest": { "properties": { "action": { "description": "\"list\" (default) or \"set\".", "type": [ "string", "null" ] }, "product_ids": { "description": "Product ids to update. Required for action=set.", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "featured": { "description": "Value to set is_featured to for product_ids. Required for action=set.", "type": [ "boolean", "null" ] } }, "type": "object" }, "ProductFeatureManageResponse": { "properties": { "action": { "type": "string" }, "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "total": { "type": [ "integer", "null" ] }, "products": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "is_featured": { "type": "boolean" }, "stock_status": { "type": "string" } }, "type": "object" }, "type": [ "array", "null" ] }, "updated": { "items": { "type": "integer" }, "type": [ "array", "null" ] }, "not_found": { "items": { "type": "integer" }, "type": [ "array", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "ProductImageAssignRequest": { "properties": { "product_id": { "description": "Product id to update.", "type": [ "integer", "null" ] }, "media_id": { "description": "Tenant media library asset id for featured_image.", "type": [ "integer", "null" ] }, "gallery_media_ids": { "description": "Tenant media library asset ids that replace gallery_images (empty array clears).", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "clear_featured": { "description": "When true, clear featured_image. Mutually exclusive with media_id.", "type": [ "boolean", "null" ] }, "dry_run": { "description": "Preview without writing. Defaults true.", "type": [ "boolean", "null" ] }, "overwrite": { "description": "Replace an existing featured_image. Defaults false.", "type": [ "boolean", "null" ] } }, "type": "object" }, "ProductImageAssignResponse": { "properties": { "action": { "type": "string" }, "dry_run": { "type": "boolean" }, "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "product": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "featured_image": { "type": [ "string", "null" ] }, "featured_image_url": { "type": [ "string", "null" ] }, "gallery_images": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "changes": { "properties": { "featured_image": { "type": [ "string", "null" ] }, "gallery_images": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": [ "object", "null" ] } }, "type": "object" }, "ProductImageStrainAssignRequest": { "properties": { "assignments": { "description": "Explicit product_id/strain_id pairs to assign. Mutually exclusive with auto_match.", "items": { "properties": { "product_id": { "type": "integer" }, "strain_id": { "type": "integer" } }, "type": "object" }, "type": [ "array", "null" ] }, "auto_match": { "description": "When true, find and assign matches automatically instead of using assignments.", "type": [ "boolean", "null" ] }, "search": { "description": "auto_match only: filter candidate products by name.", "type": [ "string", "null" ] }, "limit": { "description": "auto_match only: max products to consider. Default 25, max 100.", "type": [ "integer", "null" ] }, "dry_run": { "description": "Preview without writing. Defaults true.", "type": [ "boolean", "null" ] }, "overwrite": { "description": "Replace an existing featured_image. Defaults false.", "type": [ "boolean", "null" ] } }, "type": "object" }, "ProductImageStrainAssignResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "dry_run": { "type": "boolean" }, "summary": { "properties": { "assigned": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "type": "object" }, "results": { "items": { "properties": { "product_id": { "type": "integer" }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "ProductImageStrainMatchRequest": { "properties": { "product_ids": { "description": "Limit the search to these product ids. Omit to scan all products missing a featured image.", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "search": { "description": "Filter candidate products by name (case-insensitive contains).", "type": [ "string", "null" ] }, "limit": { "description": "Max products to propose matches for. Default 25, max 100.", "type": [ "integer", "null" ] } }, "type": "object" }, "ProductImageStrainMatchResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "total": { "type": "integer" }, "proposals": { "items": { "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "current_featured_image": { "type": [ "string", "null" ] }, "proposed_strain_id": { "type": [ "integer", "null" ] }, "proposed_strain_name": { "type": [ "string", "null" ] }, "proposed_image_url": { "type": [ "string", "null" ] }, "match_method": { "type": "string" }, "confidence": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "ProductInspectRequest": { "properties": { "product_id": { "description": "Exact product id (optional if name_query or sku supplied)", "type": [ "integer", "null" ] }, "name_query": { "description": "Partial product name match (optional if product_id or sku supplied)", "type": [ "string", "null" ] }, "sku": { "description": "Exact SKU of a variation belonging to the product (optional if product_id or name_query supplied). SKUs are unique per tenant.", "type": [ "string", "null" ] } }, "type": "object" }, "ProductInspectResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "mix_match_settings": { "properties": { "default_quantity": { "type": "integer" }, "default_discount_type": { "type": "string" }, "default_discount_value": { "type": "number" }, "rules": { "type": "array" } }, "type": "object" }, "products": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "tracking_type": { "type": "string" }, "inventory_mode": { "type": [ "string", "null" ] }, "stock_quantity": { "type": "number" }, "stock_status": { "type": "string" }, "pricing_structure": { "type": [ "string", "null" ] }, "variations": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "price_cents": { "type": "integer" }, "price_display": { "type": "string" }, "compare_at_price_cents": { "type": [ "integer", "null" ] }, "compare_at_price_display": { "type": [ "string", "null" ] }, "on_sale": { "type": "boolean" }, "mix_match_tags": { "type": [ "array", "null" ] }, "weight_value": { "type": [ "number", "null" ] }, "stock_quantity": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "ProductManageRequest": { "properties": { "action": { "description": "\"create\" (default).", "type": [ "string", "null" ] }, "name": { "description": "Product name shown to customers. Required for create.", "type": [ "string", "null" ] }, "price": { "description": "Unit price in dollars (e.g. 24.99). Omit to leave $0 until edited.", "type": [ "number", "null" ] }, "sku": { "description": "SKU for the default variation.", "type": [ "string", "null" ] }, "stock_quantity": { "description": "On-hand unit count. Omit to leave unset.", "type": [ "number", "null" ] }, "category_ids": { "description": "Storefront category ids to attach.", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "description": { "description": "Product description. Strain enrich fills this when omitted.", "type": [ "string", "null" ] }, "strain_id": { "description": "Platform strain id from strain_lookup. Copies strain data onto the product.", "type": [ "integer", "null" ] }, "skip_strain_enrich": { "description": "If true, do not auto-match or apply a strain from the product name.", "type": [ "boolean", "null" ] } }, "type": "object" }, "ProductManageResponse": { "properties": { "action": { "type": "string" }, "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "product": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "strain_id": { "type": [ "integer", "null" ] }, "featured_image": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "strain_applied": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "confidence": { "type": "string" } }, "type": [ "object", "null" ] }, "strain_matches": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "confidence": { "type": "string" } }, "type": "object" }, "type": [ "array", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "ProductProfitabilityRequest": { "properties": { "date_from": { "description": "Start date YYYY-MM-DD (default: 90 days ago in tenant TZ).", "type": [ "string", "null" ] }, "date_to": { "description": "End date YYYY-MM-DD (default: today in tenant TZ).", "type": [ "string", "null" ] }, "sort": { "description": "\"margin\" (default), \"revenue\", or \"units\".", "type": [ "string", "null" ] }, "limit": { "description": "Max products to return (default 20, max 50).", "type": [ "integer", "null" ] }, "min_margin_percent": { "description": "Threshold for promo_headroom_ok (default 25).", "type": [ "number", "null" ] }, "only_in_stock": { "description": "When true, drop out-of-stock catalog products (default false).", "type": [ "boolean", "null" ] }, "require_cost": { "description": "When true (default), only lines with cost_price > 0 are ranked.", "type": [ "boolean", "null" ] } }, "type": "object" }, "ProductProfitabilityResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "period": { "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "summary": { "properties": { "products_ranked": { "type": "integer" }, "products_with_cost": { "type": "integer" }, "promo_headroom_count": { "type": "integer" }, "min_margin_percent": { "type": "number" } }, "type": "object" }, "products": { "items": { "properties": { "product_id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "units_sold": { "type": "integer" }, "revenue_cents": { "type": "integer" }, "cogs_cents": { "type": "integer" }, "margin_cents": { "type": "integer" }, "margin_percent": { "type": "number" }, "stock_status": { "type": [ "string", "null" ] }, "is_featured": { "type": [ "boolean", "null" ] }, "promo_headroom_ok": { "type": "boolean" }, "has_cost_data": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "ProductUnitPriceSearchRequest": { "properties": { "unit": { "description": "Unit to price per: \"g\", \"oz\" (default, 28g), or \"lb\" (448g)", "type": [ "string", "null" ] }, "name_query": { "description": "Optional partial product name filter", "type": [ "string", "null" ] }, "min_price": { "description": "Minimum price per unit in dollars (optional)", "type": [ "number", "null" ] }, "max_price": { "description": "Maximum price per unit in dollars (optional)", "type": [ "number", "null" ] }, "sort": { "description": "\"asc\" (cheapest first, default) or \"desc\" (most expensive first)", "type": [ "string", "null" ] }, "only_in_stock": { "description": "When true (default), exclude out-of-stock variations", "type": [ "boolean", "null" ] }, "limit": { "description": "Max results to return (default 25, max 100)", "type": [ "integer", "null" ] } }, "type": "object" }, "ProductUnitPriceSearchResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "unit": { "type": "string" }, "unit_grams": { "type": "number" }, "summary": { "properties": { "variations_ranked": { "type": "integer" }, "products_considered": { "type": "integer" } }, "type": "object" }, "results": { "items": { "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "product_slug": { "type": "string" }, "pricing_type": { "type": "string" }, "variation_id": { "type": "integer" }, "variation_name": { "type": "string" }, "weight_value_grams": { "type": "number" }, "price_cents": { "type": "integer" }, "price_display": { "type": "string" }, "price_per_unit_cents": { "type": "number" }, "price_per_unit_display": { "type": "string" }, "stock_quantity": { "type": "number" }, "in_stock": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "ProductUpdateBySkuRequest": { "properties": { "sku": { "description": "Exact SKU of the product's variation. SKUs are unique per tenant.", "type": "string" }, "stock_quantity": { "description": "New absolute stock quantity (unit count, not grams). Omit to leave stock unchanged.", "type": [ "number", "null" ] }, "price": { "description": "New price in dollars (e.g. 24.99). Omit to leave price unchanged.", "type": [ "number", "null" ] } }, "type": "object", "required": [ "sku" ] }, "ProductUpdateBySkuResponse": { "properties": { "product_id": { "type": "integer" }, "variation_id": { "type": "integer" }, "sku": { "type": "string" }, "stock_quantity": { "type": [ "number", "null" ] }, "price_cents": { "type": [ "integer", "null" ] }, "updated_fields": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "PromotionAuditRequest": { "properties": { "order_number": { "description": "Optional order number to compare against configured promotions", "type": [ "string", "null" ] }, "include_inactive": { "description": "Include inactive or expired promotions too (optional)", "type": [ "boolean", "null" ] } }, "type": "object" }, "PromotionAuditResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "order": { "properties": { "id": { "type": "integer" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "subtotal": { "type": "integer" }, "delivery_fee": { "type": "integer" }, "service_fee": { "type": "integer" }, "discount_amount": { "type": "integer" }, "coupon_code": { "type": [ "string", "null" ] }, "coupon_type": { "type": [ "string", "null" ] }, "coupon_discount": { "type": "integer" }, "mix_match_discount": { "type": "integer" }, "loyalty_points_redeemed": { "type": "integer" }, "loyalty_discount": { "type": "integer" }, "total": { "type": "integer" }, "zone": { "type": [ "string", "null" ] }, "items": { "items": { "properties": { "product": { "type": [ "string", "null" ] }, "variation": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "integer" }, "line_total": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": [ "object", "null" ] }, "storewide_sale": { "properties": { "active": { "type": "boolean" }, "type": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "type": "object" }, "loyalty": { "properties": { "enabled": { "type": "boolean" }, "points_per_dollar": { "type": [ "number", "null" ] }, "redeem_points_per_dollar": { "type": [ "number", "null" ] } }, "type": "object" }, "bundles": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" }, "discount_display": { "type": "string" }, "is_active": { "type": "boolean" }, "variation_count": { "type": "integer" } }, "type": "object" }, "type": "array" }, "mix_match": { "properties": { "note": { "type": "string" }, "rules": { "items": { "properties": { "tag": { "type": "string" }, "quantity": { "type": "integer" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" } }, "type": "object" }, "type": "array" }, "tagged_variations": { "items": { "properties": { "variation_id": { "type": "integer" }, "product": { "type": [ "string", "null" ] }, "variation": { "type": "string" }, "price": { "type": "integer" }, "tags": { "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "coupons": { "items": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "number" }, "min_order": { "type": "integer" }, "max_uses": { "type": [ "integer", "null" ] }, "used_count": { "type": "integer" }, "max_uses_per_customer": { "type": "integer" }, "applies_to": { "type": "string" }, "applies_to_ids": { "type": [ "array", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "freebies": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "spend_threshold": { "type": "integer" }, "quantity": { "type": "integer" }, "is_stackable": { "type": "boolean" }, "is_active": { "type": "boolean" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "variation": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PurchaseOrderDraftCreateRequest": { "properties": { "supplier_id": { "description": "Supplier id from supplier_upsert.", "type": "integer" }, "notes": { "description": "Optional notes stored on the draft (invoice number, delivery date, etc.).", "type": [ "string", "null" ] } }, "type": "object" }, "PurchaseOrderDraftCreateResponse": { "properties": { "purchase_order": { "properties": { "id": { "type": "integer" }, "po_number": { "type": "string" }, "status": { "type": "string" }, "supplier_id": { "type": "integer" }, "edit_path": { "type": "string" } }, "type": "object" } }, "type": "object" }, "PurchaseOrderLineAddRequest": { "properties": { "purchase_order_id": { "description": "Draft purchase order id from purchase_order_draft_create.", "type": "integer" }, "product_id": { "description": "Catalog product id to order.", "type": "integer" }, "variation_id": { "description": "Size/variation id when the product uses variation inventory.", "type": [ "integer", "null" ] }, "qty": { "description": "Quantity to order (grams or units, matching the product).", "type": "number" }, "unit_cost": { "description": "Unit cost in dollars. Omit to use the last cost for this supplier.", "type": [ "number", "null" ] }, "match_confidence": { "description": "How confident the catalog match is, from 0 to 1. Pass when importing from OCR.", "type": [ "number", "null" ] } }, "type": "object" }, "PurchaseOrderLineAddResponse": { "properties": { "line": { "properties": { "id": { "type": "integer" }, "purchase_order_id": { "type": "integer" }, "product_id": { "type": "integer" }, "variation_id": { "type": [ "integer", "null" ] }, "product_name": { "type": "string" }, "variation_name": { "type": [ "string", "null" ] }, "qty_ordered": { "type": "number" }, "unit_cost_cents": { "type": "integer" }, "match_confidence": { "type": [ "number", "null" ] } }, "type": "object" } }, "type": "object" }, "PushNotificationDiagnosticsRequest": { "properties": { "hours": { "description": "Lookback window for notification history in hours (default 72, max 720)", "type": [ "integer", "null" ] }, "limit": { "description": "Max recent notifications to return (default 50, max 200)", "type": [ "integer", "null" ] } }, "type": "object" }, "PushNotificationDiagnosticsResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "is_active": { "type": "boolean" } }, "type": "object" }, "vendor_user": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "firebase_config": { "properties": { "configured": { "type": "boolean" }, "credentials_source": { "type": "string" }, "project_id": { "type": [ "string", "null" ] }, "status": { "type": "string" } }, "type": "object" }, "token_health": { "anyOf": [ { "properties": { "has_token": { "type": "boolean" }, "is_fresh": { "type": "boolean" }, "token_preview": { "type": [ "string", "null" ] }, "token_updated_at": { "type": [ "string", "null" ] }, "token_age_days": { "type": [ "integer", "null" ] }, "freshness_threshold_days": { "type": "integer" }, "status": { "type": "string" }, "status_detail": { "type": "string" } }, "type": "object" } ] }, "notification_settings": { "properties": { "notify_new_order_push": { "type": "boolean" }, "notify_new_order_email": { "type": "boolean" }, "notify_low_stock": { "type": "boolean" }, "notify_restock_request": { "type": "boolean" }, "note": { "type": "string" } }, "type": "object" }, "recent_notifications": { "properties": { "lookback_hours": { "type": "integer" }, "total": { "type": "integer" }, "push_sent_count": { "type": "integer" }, "email_sent_count": { "type": "integer" }, "neither_sent_count": { "type": "integer" }, "push_rate_pct": { "type": [ "number", "null" ] }, "by_type": { "type": "object" }, "entries": { "items": { "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "push_sent": { "type": "boolean" }, "email_sent": { "type": "boolean" }, "is_read": { "type": "boolean" }, "read_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "diagnosis": { "properties": { "overall_status": { "type": "string" }, "blockers": { "items": { "type": "string" }, "type": "array" }, "warnings": { "items": { "type": "string" }, "type": "array" }, "summary": { "type": "string" } }, "type": "object" } }, "type": "object" }, "SearchConsoleRequest": { "properties": { "report": { "description": "The report type to run", "enum": [ "overview", "top_queries", "top_pages", "daily_trend" ], "type": "string" }, "days": { "description": "Number of days to look back (default 30, max 365)", "type": [ "integer", "null" ] } }, "type": "object", "required": [ "report" ] }, "SearchConsoleResponse": { "properties": { "scope": { "type": "string" }, "site_url": { "type": [ "string", "null" ] }, "report": { "type": "string" }, "days": { "type": "integer" }, "results": { "anyOf": [ { "properties": { "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" } }, "type": "object" }, { "items": { "properties": { "query": { "type": "string" }, "page": { "type": "string" }, "date": { "type": "string" }, "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" } }, "type": "object" }, "type": "array" } ] } }, "type": "object" }, "StoreInfoRequest": { "type": "object", "properties": [] }, "StoreInfoResponse": { "properties": { "store": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "country": { "type": "string" }, "on_trial": { "type": "boolean" }, "has_active_subscription": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "StrainLookupRequest": { "properties": { "query": { "description": "Strain name to search (e.g. \"Blue Dream\").", "type": "string" } }, "type": "object", "required": [ "query" ] }, "StrainLookupResponse": { "properties": { "query": { "type": "string" }, "total": { "type": "integer" }, "strains": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "thc_percentage": { "type": [ "number", "null" ] }, "cbd_percentage": { "type": [ "number", "null" ] }, "indica_percentage": { "type": [ "number", "null" ] }, "sativa_percentage": { "type": [ "number", "null" ] }, "short_description": { "type": [ "string", "null" ] }, "has_hosted_image": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "SupplierUpsertRequest": { "properties": { "supplier_id": { "description": "Existing supplier id to update. Omit to create (or match by name).", "type": [ "integer", "null" ] }, "name": { "description": "Supplier name. Required when creating.", "type": [ "string", "null" ] }, "email": { "description": "Supplier email for sending purchase orders.", "type": [ "string", "null" ] }, "phone": { "description": "Supplier phone.", "type": [ "string", "null" ] }, "license_number": { "description": "License or account number if you store one.", "type": [ "string", "null" ] }, "notes": { "description": "Internal notes about this supplier.", "type": [ "string", "null" ] }, "lead_time_days": { "description": "Typical lead time in days (0–365). Defaults to 0 on create.", "type": [ "integer", "null" ] }, "is_active": { "description": "Whether this supplier can be used on new purchase orders. Defaults to true on create.", "type": [ "boolean", "null" ] } }, "type": "object" }, "SupplierUpsertResponse": { "properties": { "created": { "type": "boolean" }, "supplier": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "license_number": { "type": [ "string", "null" ] }, "lead_time_days": { "type": "integer" }, "is_active": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "TenantBrandingManageRequest": { "properties": { "action": { "description": "\"show\" (default) or \"set\".", "type": [ "string", "null" ] }, "media_id": { "description": "Library asset to use as the store logo. Required to change the logo.", "type": [ "integer", "null" ] }, "hero_media_id": { "description": "Library asset to use as the homepage hero (settings.hero_image_path).", "type": [ "integer", "null" ] }, "clear_hero": { "description": "When true, remove the homepage hero. Mutually exclusive with hero_media_id.", "type": [ "boolean", "null" ] }, "source_url": { "description": "Public http(s) URL of a BIMI SVG. Provide exactly one BIMI source.", "type": [ "string", "null" ] }, "source_path": { "description": "Local file path of a BIMI SVG. Provide exactly one BIMI source.", "type": [ "string", "null" ] }, "source_base64": { "description": "Base64-encoded BIMI SVG bytes. Provide exactly one BIMI source.", "type": [ "string", "null" ] }, "dry_run": { "description": "If true (the default for set), report only and write nothing.", "type": [ "boolean", "null" ] } }, "type": "object" }, "TenantBrandingManageResponse": { "properties": { "action": { "type": "string" }, "dry_run": { "type": [ "boolean", "null" ] }, "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "storefront_url": { "type": "string" } }, "type": "object" }, "logo_path": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "hero_image_path": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "bimi_logo_path": { "type": [ "string", "null" ] }, "bimi_url": { "type": [ "string", "null" ] }, "bimi_txt": { "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "type": [ "object", "null" ] }, "cloudflare_connected": { "type": "boolean" }, "dns_updated": { "type": [ "boolean", "null" ] }, "would_set_logo": { "type": [ "boolean", "null" ] }, "would_set_hero": { "type": [ "boolean", "null" ] }, "would_clear_hero": { "type": [ "boolean", "null" ] }, "would_set_bimi": { "type": [ "boolean", "null" ] }, "message": { "type": "string" } }, "type": "object" }, "WidgetManageRequest": { "properties": { "action": { "description": "\"list\" (default), \"create\", \"update\", or \"delete\".", "type": [ "string", "null" ] }, "widget_id": { "description": "ID of an existing widget. Required for update and delete.", "type": [ "integer", "null" ] }, "title": { "description": "Widget headline. Required when creating.", "type": [ "string", "null" ] }, "subtitle": { "description": "Widget sub-label shown under the headline.", "type": [ "string", "null" ] }, "cta_text": { "description": "Call-to-action button text (e.g. \"Shop Now\").", "type": [ "string", "null" ] }, "link_type": { "description": "\"product\", \"category\", \"mix_match\", or \"featured\". See LINK_TYPE in the tool description.", "type": [ "string", "null" ] }, "product_id": { "description": "Target product id when link_type=product.", "type": [ "integer", "null" ] }, "category_id": { "description": "Target category id when link_type=category.", "type": [ "integer", "null" ] }, "mix_match_tag": { "description": "Target mix & match tag when link_type=mix_match.", "type": [ "string", "null" ] }, "sort_order": { "description": "Display order (lower sorts first).", "type": [ "integer", "null" ] }, "is_active": { "description": "Whether the widget is visible on the storefront.", "type": [ "boolean", "null" ] }, "media_id": { "description": "Media library asset id to set as image_path (the branded, customer-facing image).", "type": [ "integer", "null" ] }, "base_media_id": { "description": "Media library asset id to set as base_image_path (the unbranded source canvas).", "type": [ "integer", "null" ] }, "confirm": { "description": "Required (true) for action=delete.", "type": [ "boolean", "null" ] } }, "type": "object" }, "WidgetManageResponse": { "properties": { "action": { "type": "string" }, "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "total": { "type": [ "integer", "null" ] }, "widgets": { "items": { "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "subtitle": { "type": [ "string", "null" ] }, "cta_text": { "type": [ "string", "null" ] }, "link_type": { "type": [ "string", "null" ] }, "destination_url": { "type": [ "string", "null" ] }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] }, "base_image_path": { "type": [ "string", "null" ] } }, "type": "object" }, "type": [ "array", "null" ] }, "widget": { "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "subtitle": { "type": [ "string", "null" ] }, "cta_text": { "type": [ "string", "null" ] }, "link_type": { "type": [ "string", "null" ] }, "destination_url": { "type": [ "string", "null" ] }, "sort_order": { "type": "integer" }, "is_active": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] }, "base_image_path": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "ZoneDiagnosticsRequest": { "properties": { "customer_address_id": { "description": "Saved customer address id to inspect (optional)", "type": [ "integer", "null" ] }, "order_number": { "description": "Order number whose delivery address should be checked (optional)", "type": [ "string", "null" ] }, "zone_id": { "description": "Specific zone to compare against (optional)", "type": [ "integer", "null" ] }, "latitude": { "description": "Manual latitude to test (optional)", "type": [ "number", "null" ] }, "longitude": { "description": "Manual longitude to test (optional)", "type": [ "number", "null" ] } }, "type": "object" }, "ZoneDiagnosticsResponse": { "properties": { "tenant": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "source": { "anyOf": [ { "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "address": { "type": "string" } }, "type": "object" }, { "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "order_number": { "type": "string" }, "delivery_address": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "address_coordinates": { "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "type": "object" }, "saved_zone": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "inside": { "type": [ "boolean", "null" ] } }, "type": [ "object", "null" ] }, "detected_zone": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "priority": { "type": "integer" } }, "type": [ "object", "null" ] }, "zones": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "priority": { "type": "integer" }, "delivery_fee": { "type": "integer" }, "service_fee": { "type": "integer" }, "min_order": { "type": "integer" }, "color": { "type": "string" }, "inside": { "type": "boolean" }, "polygon_points": { "type": "integer" }, "polygon": { "type": [ "array", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "paths": { "/api/v1/tools/analytics_query": { "post": { "operationId": "analytics_query", "summary": "Run read-only analytics queries against the production database. Available reports: revenue_by_tenant, orders_by_status, top_products, revenue_over_time, customer_stats. Revenue dating uses RevenueAttribution (pass tenant_slug for delivered-mode tenants).", "tags": [ "analytics", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsQueryRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/AnalyticsQueryResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/bundle_list": { "post": { "operationId": "bundle_list", "summary": "List a tenant's bundle deals (\"mix & match\" — e.g. \"buy 4 for $77\") with id, name, trigger\nquantity, discount type/value, active state, schedule window, and attached variation count.\nBundles are the live cart engine (MixMatchService): a bundle fires when a cart holds at least\n`quantity` units across its attached variations. Always call this before bundle_upsert to get\nthe bundle id and confirm the current discount configuration.\n\nIMPORTANT: this reads the `bundles` table — the source of truth the storefront cart uses. It is\nNOT the legacy `mix_match_rules` tenant setting that promotion_audit / product_inspect surface;\nthose are stale display-only data. Trust this tool for what actually applies at checkout.\n\ndiscount_type:\n percent → discount_value is a percentage 0–100, applied per unit.\n fixed → discount_value is dollars off PER UNIT.\n fixed_total → discount_value is the dollar TOTAL for the whole set (\"$77 for 4\").", "tags": [ "promotions", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/BundleListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/bundle_upsert": { "post": { "operationId": "bundle_upsert", "summary": "Create or update a bundle deal (mix & match) on behalf of a tenant. Bundles are the live cart\nengine: a bundle fires when a cart holds at least `quantity` units across its attached variations.\n\nUPDATE MODE (bundle_id provided):\n Edits the bundle. Only the fields you pass are changed; omitted fields are left as-is.\n\nCREATE MODE (no bundle_id):\n Creates a new bundle. name, quantity, discount_type, and discount_value are required.\n\nDISCOUNT VALUE UNITS — read carefully, this is the common mistake:\n discount_type = \"percent\" → discount_value is a percentage 0–100 (e.g. 20 = 20% off each unit).\n discount_type = \"fixed\" → discount_value is DOLLARS off PER UNIT (e.g. 5 = $5 off each).\n discount_type = \"fixed_total\" → discount_value is the DOLLARS TOTAL for the whole set\n (e.g. quantity=4, discount_value=77 → \"any 4 for $77\").\n For fixed and fixed_total, pass dollars (e.g. 77 or 77.00) — the tool stores cents internally.\n For percent, pass the percentage (e.g. 20), NOT a fraction.\n\nVARIATIONS:\n variation_ids + variation_mode control which product variations the bundle applies to.\n mode \"replace\" (default) sets membership to exactly variation_ids; \"add\" attaches them to the\n existing set; \"detach\" removes them. Variations not owned by the tenant are ignored.\n Omit variation_ids entirely to leave membership untouched.\n\nSCHEDULE:\n starts_at / ends_at are interpreted in the tenant's timezone and stored as UTC. Pass null/omit\n for an always-on bundle.\n\nAlways call bundle_list first to get the bundle_id and confirm the current configuration.", "tags": [ "promotions", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/BundleUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_apply_template": { "post": { "operationId": "campaign_apply_template", "summary": "Apply a built-in system email template to a DRAFT campaign, replacing its html_body with the\nrendered, tenant-branded design. This mirrors the \"Choose template\" action in the vendor admin.\n\nThe template is rendered with the tenant's own branding (theme colour, logo, name, address, phone),\nthen sanitized and written to the campaign's html_body. The {{unsubscribe_url}} token is preserved.\nThe design ships with placeholder copy ([Product name], $00, \"Your headline here\", etc.) — after\napplying, use campaign_upsert to set the real html_body with this tenant's products, prices, and\noffers, or hand off to the vendor to fill in.\n\nOnly DRAFT campaigns can have a template applied. To discover valid template_id values, omit\ntemplate_id (or pass an unknown one) and the tool returns the list of available templates.\n\nTypical flow: campaign_upsert (create draft) → campaign_apply_template (lay down the design) →\ncampaign_upsert (replace html_body with real data) → campaign_send_test (preview).", "tags": [ "marketing", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignApplyTemplateRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignApplyTemplateResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_audience_inspect": { "post": { "operationId": "campaign_audience_inspect", "summary": "Split the tenant's campaign audience into warm (≥1 past order) vs cold (no order history)\nrecipients. Use this before drafting a newsletter or SMS in the Create Promotion flow:\nwarm audiences can get exclusive codes and commercial copy; cold audiences need\npersonalized, spam-safe language — never hard-sell or aggressive exclusive deals.\n\nReturns counts only — it does not create or send a campaign.", "tags": [ "marketing", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignAudienceInspectRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignAudienceInspectResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_control": { "post": { "operationId": "campaign_control", "summary": "Pause or resume a vendor email/SMS campaign.\n\npause: sets status=paused with paused_reason=manual. Works from sending\nor recovering. Pending recipients stay pending; the dispatcher skips this\ncampaign so sibling sending campaigns can use the shared throttle.\n\nresume: from paused → sending (clears pause fields). From recovering →\nsending and requeues transport-failed recipients (same as auto-resume\nafter a healthy webhook health check).\n\ndry_run defaults TRUE. Always confirm tenant_slug and campaign_id first.", "tags": [ "marketing", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignControlRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignControlResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_flyer_style_pack": { "post": { "operationId": "campaign_flyer_style_pack", "summary": "Teach campaign_generate_flyer what this shop's flyers look like, using their OWN past work.\n\nA style pack is two things, both stored on the shop itself:\n - Images: one or more past flyers or mood boards, held in the shop's media library.\n - Art direction: short lines describing the look to carry forward (\"seasonal scenes, deal-dense\n grids, deep green and gold, calm lower third\").\n\nWhen a pack is saved, every flyer generation attaches it ahead of the product photos and asks the\nmodel to match the MOOD and COMPOSITION — never to copy text, logos or prices out of it.\n\nACTIONS:\n - show — what is saved right now: the direction lines and the images on file.\n - set — save direction lines and/or point the pack at media library images.\n prompt_lines replaces the saved direction. media_ids MOVES those library assets into\n the style-reference folder (they stay ordinary library assets, reusable elsewhere).\n - clear — remove the direction lines, and with clear_images=true also take the images back out\n of the style-reference folder. Nothing is deleted from the library.\n\nHOW TO GET AN IMAGE IN: upload the flyer through the shop's media library (or send it to Dabby in\nchat, which files it there), then pass its media_id here. The pack lives entirely in the database,\nso it survives every deploy and can be changed at any time without one.", "tags": [ "marketing", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignFlyerStylePackRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignFlyerStylePackResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_generate_flyer": { "post": { "operationId": "campaign_generate_flyer", "summary": "Generate BESPOKE flyer artwork for a campaign from the shop's own product photos, then drop it\nstraight into the campaign design. This is the intended way to make a marketing email look like\na designed flyer instead of a text layout — reach for it before writing copy, because the rest of\nthe email is built to sit under the artwork.\n\nWHAT IT PRODUCES:\n A layered, dimensional flyer illustration in the shop's brand colours, composed around the real\n packaging from the product photos you name. It renders NO text — the email supplies every word\n as real text so it stays readable, translatable, and safe with images disabled.\n\nREQUIREMENTS:\n The shop must have its own AI key connected (Settings → Dab AI). Generation is billed to that\n key, not to the platform, so a shop without one gets a clear message instead of a flyer. Use\n the highest-quality model available on the key; that is the default and it is the point.\n A shop that has saved a style pack (campaign_flyer_style_pack) automatically gets its own past\n flyers attached as references, so the artwork matches the creative it already sends.\n\nHOW TO USE IT:\n - theme — what the flyer is for, in plain words (\"September restock, cosy autumn mood\").\n - product_ids — the products to feature. Omit and it picks the shop's newest featured products\n that actually have photos.\n - campaign_id — a DRAFT campaign to place the artwork into. Omit to just add it to the media\n library and place it later with campaign_set_image.\n - slot_index — which image slot to fill (1-based). Defaults to the first, which is the hero.\n\nTypical flow: campaign_upsert (create) → campaign_apply_template (design) →\ncampaign_generate_flyer (hero artwork) → campaign_upsert (real copy) → campaign_send_test.\n\nThe result always lands in the media library, so it can be reused on the storefront or in a later\nsend without generating twice.", "tags": [ "marketing", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignGenerateFlyerRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignGenerateFlyerResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_get": { "post": { "operationId": "campaign_get", "summary": "Read a campaign back, including the message body you are about to edit.\n\nEvery other campaign tool reports html_body_length — a character count — so\nwithout this you would be rewriting a document you have never seen. Call this\nfirst whenever you are asked to change, finish, or comment on existing copy.\n\nEmail campaigns return html_body; text campaigns return sms_body. A rendered\nsystem template runs 10-32KB, so read once and edit from what you read rather\nthan re-fetching between changes.", "tags": [ "marketing", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignGetRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignGetResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_recipients_requeue": { "post": { "operationId": "campaign_recipients_requeue", "summary": "Unstick a vendor email/SMS campaign that auto-paused or stalled mid-send.\n\nResets failed recipients (and optionally stale \"sending\" rows) back to pending,\nclears webhook_consecutive_failures / paused_reason / last_error, and sets the\ncampaign status to sending so the dispatcher continues. Already-sent recipients\nare never touched.\n\nPass retry_sending_log_errors=true to retry every recipient that appears in the\ncampaign sending log with a retryable error (502/timeout/SMTP soft fail, etc.).\nThose jobs dispatch immediately (up to dispatch_limit) so they are not stuck\nbehind a large pending queue. The log rows stay — they are diagnostic history.\n\nUse when a webhook campaign froze after consecutive endpoint errors (or soft\nSMTP failures that were misclassified before the soft-fail fix) and pending\n+ failed recipients remain.\n\ndry_run defaults to TRUE — first call reports counts only. Pass dry_run=false\nto apply. Always confirm tenant_slug with tenant_list and campaign_id with the vendor.", "tags": [ "marketing", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRecipientsRequeueRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignRecipientsRequeueResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_send_test": { "post": { "operationId": "campaign_send_test", "summary": "Send a single test copy of a campaign so the design and copy can be reviewed before the real send.\n\nEmail campaigns go out through the tenant's own SMTP settings — exactly the path a real send uses.\nPass to_email. Requires complete SMTP settings.\n\nText (SMS) campaigns go out through the tenant's connected Twilio account. Pass to_phone instead of\nto_email. Requires Twilio to be connected.\n\nThis is a preview only: it does NOT start the campaign, does NOT touch the audience, and does NOT\nrecord any send/open/click stats. Personalization tokens render with sample values; unsubscribe links\npoint at harmless test URLs.\n\nWorks on a campaign in any status (a draft preview is the common case). Always confirm the\ncampaign_id with the vendor first.", "tags": [ "marketing", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSendTestRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignSendTestResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_set_image": { "post": { "operationId": "campaign_set_image", "summary": "Drop an image from the tenant's media library into a DRAFT campaign — no link copying, no manual\nHTML. Give it a campaign_id and a media_id (from the tenant's own library) and it fills an image\nplaceholder in the campaign body with that image, using the library image's own public URL and\nalt text. The URL is on the tenant's public disk, so it passes the campaign HTML sanitizer\nuntouched and renders in email clients.\n\nWHICH SLOT IT FILLS:\n System templates render image placeholders labelled \"Add image\". By default this tool fills the\n FIRST remaining placeholder. Pass slot_index (1-based) to target a specific placeholder when a\n template has more than one. If the body has no placeholder left, the image is appended at the end.\n\nREQUIREMENTS:\n - The campaign must be a DRAFT and belong to the tenant.\n - The media asset must belong to the tenant and be public (private assets have no shareable URL).\n\nTypical flow: campaign_upsert (create) → campaign_apply_template (design with placeholders) →\ncampaign_set_image (fill each placeholder) → campaign_upsert (real copy) → campaign_send_test.", "tags": [ "marketing", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSetImageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignSetImageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_spam_score": { "post": { "operationId": "campaign_spam_score", "summary": "Score vendor campaign copy for inbox risk (email HTML or SMS).\n\nOne score only: 0–100 (0 = spam, 100 = primary-inbox friendly). Live scoring uses\nfirst-party rules. Pass for_send=true to run the same deep filter check used on\nsend/schedule and fold it into that single number (never a second score).\n\nVendors cannot send or schedule below the platform minimum (default 80). Aim for\n80+ before handoff; 85+ is excellent.\n\nPass campaign_id (loads draft content) OR inline channel + content fields.", "tags": [ "marketing", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSpamScoreRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignSpamScoreResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/campaign_upsert": { "post": { "operationId": "campaign_upsert", "summary": "Create or edit a vendor email campaign on behalf of a tenant. This is the vendor → their-customers\ncampaign universe (NOT the platform drip-to-leads system). Completed campaigns cannot be edited.\n\nCREATE MODE (no campaign_id):\n Creates a new draft. For email campaigns, `name` and `subject` are required; `html_body` is optional\n on create — omit it to start blank and apply a system template afterwards with campaign_apply_template.\n For text (SMS) campaigns, set channel to \"sms\" and pass `sms_body` (name required). Twilio must be\n connected on the tenant.\n\nUPDATE MODE (campaign_id provided):\n Edits an existing campaign. Only the fields you pass are changed; omitted fields are left as-is.\n Drafts accept all fields. Sending or paused campaigns accept content fields only — for email that is\n name, subject, html_body, plain_body, fallback_first_name; for text that is name, sms_body,\n and fallback_first_name. Sending campaigns keep\n running and unreached recipients get the latest version. Scheduled, cancelled, and failed campaigns\n must be edited from the vendor admin.\n\nHTML BODY (email only):\n Pass the full email HTML in `html_body`. It is sanitized exactly like the vendor admin editor:\n a full document ( / ) keeps its table-based structure; a fragment is run\n through the stricter inline allowlist. Use the literal token {{unsubscribe_url}} where the\n unsubscribe link should appear — it is replaced per-recipient at send time and a List-Unsubscribe\n header is added automatically. Personalization tokens {{first_name}} and {{last_name}} are also\n replaced at send time. When {{first_name}} is blank, fallback_first_name is used (default \"there\"\n when unset). Pass fallback_first_name as \"\" to clear an override.\n\nSMS BODY (text only):\n Pass the message in `sms_body` (max 1600 chars). Tokens {{first_name}} and {{last_name}} are\n replaced at send time (same first-name fallback as email). Text campaigns only target opted-in shop customers.\n\nAUDIENCE / MODE (email only):\n mode is \"smtp\" (default) or \"webhook\". audience_includes_customers (default true) targets the\n tenant's own customers. This tool does not send anything — use campaign_send_test to preview,\n then the vendor sends from the admin.\n\nAlways confirm the tenant_slug with tenant_list first. To populate a draft from a built-in design,\ncreate it here, then call campaign_apply_template.", "tags": [ "marketing", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/catalog_collapse": { "post": { "operationId": "catalog_collapse", "summary": "Merges a group of size-split products into ONE product with size options.\n\nTurns \"Blue Dream - 3.5G\", \"Blue Dream - 7G\", \"Blue Dream - 28G\" (three separate products,\neach with one \"Default\" option) into a single \"Blue Dream\" product that sells by weight with\n3.5g / 7g / 28g options. Stock is added together into one shared pool, and each old price\nbecomes the price of its size.\n\nRun catalog_flattening_audit first to see the groups and their exact base_name.\n\nSAFETY:\n- dry_run defaults to TRUE. Nothing changes until you pass dry_run=false. The dry run returns\n the exact sizes, prices, stock, and which products would be removed.\n- Past orders are never affected — they keep the product name and price the customer saw.\n- Refused when two products in the group claim the same size, or when any product belongs to\n another store.\n- This removes the duplicate products. It cannot be undone from here.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogCollapseRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CatalogCollapseResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/catalog_flattening_audit": { "post": { "operationId": "catalog_flattening_audit", "summary": "Read-only. Finds products whose sizes were split into separate products instead of tiers.\n\nThis happens when a catalog is imported from a store that put the size in the product NAME\n(\"Blue Dream - 3.5G\", \"Blue Dream - 7G\") instead of a size option column. The importer has no\nsize column to read, so each size becomes its own product with a single \"Default\" option, and\nthe store ends up with a long flat menu that cannot use weight pricing or mix & match deals.\n\nReturns each group of products that belong together (\"family\"), the sizes and prices found,\nand whether the group can be safely merged. A group is NOT mergeable when two of its products\nclaim the same size — that must be resolved by hand first.\n\nNothing is changed. Use catalog_collapse to merge a group.", "tags": [ "catalog", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogFlatteningAuditRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CatalogFlatteningAuditResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/category_manage": { "post": { "operationId": "category_manage", "summary": "List, create, update, or delete a tenant's storefront categories.\n\nACTIONS:\n list (default): return every category with id, name, slug, parent, sort_order,\n is_active, is_featured, and image_url. Always call this first to find a\n category_id before update/delete, and to check for slug collisions before create.\n create: requires name (slug is auto-generated from name if omitted).\n update: requires category_id. Only the fields you pass are changed.\n delete: requires category_id and confirm=true. Refuses if the category still has\n products or children attached (detach or reassign them first).\n\nIMAGES: pass media_id (from media_list / media_upload) to set image_path (the final,\ncustomer-facing image) or base_image_path (the unbranded source canvas SwagImagesService\ncomposites branding onto). Omit both to leave images untouched.\n\nAlways call action=list first to confirm category_id / slug before update or delete.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryManageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CategoryManageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/contact_cleanup": { "post": { "operationId": "contact_cleanup", "summary": "Removes contacts that failed email validation from an imported list.\n\nTypical use: a CSV import brought in thousands of addresses, the validator graded them,\nand the list is now full of dead addresses that will bounce and hurt sending reputation.\n\nSAFETY:\n- dry_run defaults to TRUE. Nothing is deleted until you pass dry_run=false. The dry run\n returns exactly how many contacts match and a sample of them.\n- Only statuses \"invalid\" and \"risky\" can be purged. \"unknown\" means the validator has not\n graded that contact YET — those are never deleted, and asking for them is refused.\n- Scoped to one contact list when list_id is given, otherwise the whole store.\n- Contacts are deleted, not unsubscribed. This cannot be undone from here.", "tags": [ "customers", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCleanupRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": [] } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/coupon_list": { "post": { "operationId": "coupon_list", "summary": "List a tenant's discount coupons with code, type, value, usage limits, redemption count,\nactive state, and schedule window. Coupons are customer-entered codes applied at checkout\n(distinct from bundles, which fire automatically on cart contents — use bundle_list for those).\n\ntype:\n percentage → value is a percentage 0-100 off the order subtotal.\n fixed → value is dollars off the order subtotal.\n free_delivery → waives the delivery fee only; value is unused for this type.\n\nAlways call this before making coupon-related decisions to see current codes, usage caps,\nand whether a coupon has already been exhausted (used_count vs max_uses).", "tags": [ "promotions", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CouponListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/coupon_upsert": { "post": { "operationId": "coupon_upsert", "summary": "Create or update a discount coupon on behalf of a tenant. Coupons are customer-entered codes\napplied at checkout (distinct from bundles, which fire automatically on cart contents — use\nbundle_upsert for those).\n\nUPDATE MODE (coupon_id provided):\n Edits the coupon. Only the fields you pass are changed; omitted fields are left as-is.\n\nCREATE MODE (no coupon_id):\n Creates a new coupon. code, type, and value are required.\n\nVALUE UNITS:\n type = \"percentage\" → value is a percentage 0-100 off the order subtotal.\n type = \"fixed\" → value is DOLLARS off the order subtotal (e.g. 10 = $10 off).\n type = \"free_delivery\" → value is ignored (pass 0); this type only waives the delivery fee.\n\nmin_order is a dollar minimum order subtotal required to use the coupon (pass dollars, e.g. 25\nfor a $25 minimum — the tool stores cents internally). Omit or pass 0 for no minimum.\n\nfreebie_id links this coupon to an existing Freebie (see freebie_list/freebie_upsert), turning it\ninto a \"code-triggered freebie\": a customer who applies the code while below min_order has the\ncode parked (kept attached, not rejected) and sees cart progress toward unlocking it, instead of\nthe code being discarded. Pass null to unlink. The freebie must belong to the same tenant.\n\nlimit_match_by (\"email\"|\"phone\"|\"both\") controls how max_uses_per_customer is enforced. Using\n\"phone\" or \"both\" REQUIRES the tenant's \"Require phone at checkout\" setting to be on — otherwise\nthe update is rejected, since customers without a phone on file could otherwise reuse the coupon\npast its per-customer limit.\n\nSCHEDULE:\n starts_at / expires_at are interpreted in the tenant's timezone and stored as UTC. Pass\n null/omit for an always-on coupon.\n\nPRODUCT/CATEGORY SCOPING:\n applies_to=\"products\" or \"categories\" restricts the discount to matching cart lines only —\n checkout math is fully scope-aware (a scoped coupon never discounts the whole cart). Pass\n applies_to_ids as an array of product ids (when applies_to=\"products\") or category ids (when\n applies_to=\"categories\") — all ids must belong to this tenant. Passing applies_to=\"products\"/\n \"categories\" with an empty or omitted applies_to_ids behaves the same as \"all\" (no scope\n configured yet). Switching back to applies_to=\"all\" does not automatically clear a\n previously-set applies_to_ids — pass applies_to_ids=[] explicitly to clear it.\n\nSUBSCRIPTION MOUNTING DISCOUNT LADDERS (subscribe-and-save retention):\n A coupon can carry a \"mounting ladder\" so its discount climbs with each successive order a\n customer's delivery subscription generates, pegging at a ceiling — e.g. order 1 = 0% off,\n then +5% every order up to a 20% cap. This only affects orders generated for a subscription\n linked to this coupon (DeliverySubscription.coupon_id) — it has no effect on ordinary\n one-off checkout use of the code, which still uses type/value as normal.\n\n subscription_ladder_id: link to an existing ladder (from another coupon) by id, or pass null\n to unlink. Must belong to the same tenant.\n\n ladder_start_percent / ladder_step_percent / ladder_cap_percent / ladder_start_order_index:\n pass any of these to CREATE a new ladder inline (on coupon create) or EDIT the tiers of the\n ladder already linked to this coupon (on update) — do not combine with subscription_ladder_id\n in the same call. All four are whole-number percentages (0-100) except start_order_index,\n which is the 1-based order number the climb begins at (orders before it stay at\n ladder_start_percent). Omitted ladder_* fields default to 0% start / 5% step / 20% cap /\n order 1 on create; on update, only the fields you pass are changed.\n\nAlways call coupon_list first to get the coupon_id and confirm the current configuration.", "tags": [ "promotions", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CouponUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/customer_addresses": { "post": { "operationId": "customer_addresses", "summary": "Return a customer's saved addresses, coordinates, saved zones, and zone mismatch diagnostics.", "tags": [ "customers", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressesRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CustomerAddressesResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/customer_list": { "post": { "operationId": "customer_list", "summary": "Page through all customers for a tenant, optionally filtered to those updated since a given time. Built for bulk sync — use customer_lookup instead for a single targeted search.", "tags": [ "customers", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CustomerListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/customer_lookup": { "post": { "operationId": "customer_lookup", "summary": "Find customers by id, email, phone, or name and return their recent addresses, orders, and support context.", "tags": [ "customers", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLookupRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CustomerLookupResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/customer_update": { "post": { "operationId": "customer_update", "summary": "Update a customer's contact fields (name, email, phone) and/or suppress marketing consent (email_opt_out, sms_marketing_opt_out, sms_notifications_muted — one-way, cannot un-suppress). Verification, loyalty, and other DabDash-owned fields cannot be set here.", "tags": [ "customers", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/CustomerUpdateResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/freebie_list": { "post": { "operationId": "freebie_list", "summary": "List a tenant's freebie rules (\"spend $X, get a free item\") with id, name, spend threshold,\nthe product/variation given away, quantity, stackable flag, active state, and schedule window.\nFreebies are evaluated on every cart change by FreebieService: a rule fires once its\nspend_threshold is met, adding `quantity` of the configured product/variation to the cart.\n\nIMPORTANT: this reads the `freebies` table — the source of truth the storefront cart uses. It\nis NOT the legacy freebie summary promotion_audit surfaces alongside coupons/bundles; that view\nis stale display-only data built for a different purpose. Trust this tool for what actually\napplies at checkout.\n\nis_merch_product: true when the freebie's product is tagged \"merch\" (Product.tags contains\n\"merch\") — a branded giveaway item (hats, apparel) rather than sellable cannabis inventory.\nPrefer merch-tagged products over high-COGS flower when recommending a NEW freebie: giving away\npromo materials protects margin the same way a discount code doesn't.\n\nis_stackable:\n true → this rule can fire alongside OTHER DIFFERENT freebie rules on the same order (each\n rule still only fires once, at its configured quantity, regardless of how far above\n its own threshold the cart is).\n false → this rule cannot combine with other freebie rules; if multiple non-stackable rules\n qualify, FreebieService applies its own precedence to pick one.\n This flag does NOT multiply a single rule's quantity by how many multiples of the threshold\n the cart reaches — a $50-threshold rule at $150 spent still gives quantity 1, not 3.", "tags": [ "promotions", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreebieListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/FreebieListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/freebie_upsert": { "post": { "operationId": "freebie_upsert", "summary": "Create or update a freebie rule (\"spend $X, get a free item\") on behalf of a tenant. Freebies\nare evaluated on every cart change: a rule fires once its spend_threshold is met, adding\n`quantity` of the configured product/variation to the cart (distinct from bundles, which fire\non cart CONTENTS/quantity — use bundle_upsert for those).\n\nUPDATE MODE (freebie_id provided):\n Edits the freebie. Only the fields you pass are changed; omitted fields are left as-is,\n EXCEPT category_ids, which — like bundle_upsert's variation_ids — fully replaces the category\n set whenever passed (pass an empty array to clear all categories).\n\nCREATE MODE (no freebie_id):\n Creates a new freebie. name, product_id, spend_threshold, and quantity are required.\n\nproduct_id and variation_id (if given) MUST belong to the same tenant — foreign ids are\nrejected, not silently ignored (unlike bundle_upsert's variation_ids, since a freebie needs\nexactly one product to give away, not a set).\n\nspend_threshold is entered in DOLLARS (e.g. 50 for a $50 minimum spend) — the tool stores cents\ninternally.\n\nis_stackable:\n true → this rule can fire alongside OTHER DIFFERENT freebie rules on the same order.\n false → this rule cannot combine with other freebie rules.\n Does NOT multiply this rule's own quantity by how many multiples of spend_threshold the cart\n reaches — a $50-threshold rule at $150 spent still gives quantity 1, not 3.\n\nSCHEDULE:\n starts_at / ends_at are interpreted in the tenant's timezone and stored as UTC. Pass\n null/omit for an always-on freebie.\n\nAlways call freebie_list first to get the freebie_id and confirm the current configuration.", "tags": [ "promotions", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreebieUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/FreebieUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/google_analytics": { "post": { "operationId": "google_analytics", "summary": "Query Google Analytics (GA4) data for the platform (dabdash.com) or a specific tenant with a connected GA integration. Returns traffic overview, top pages, traffic sources, top events, and daily trend.", "tags": [ "analytics", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAnalyticsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/GoogleAnalyticsResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/inventory_audit_lookup": { "post": { "operationId": "inventory_audit_lookup", "summary": "Look up the historical inventory state of a list of products from the inventory_audit_logs table.\n\nFor each product, returns every variation_id ever logged in the audit trail (including variations\nthat have since been deleted), the variation's last known stock_quantity strictly BEFORE the given\ncutoff timestamp, and that variation's most recent action+notes for context.\n\nUse this tool to recover pre-incident stock values when variations have been overwritten or\ndeleted by a destructive operation (e.g. an erroneous pricing structure assignment that wiped\nunit/simple variations and replaced them with weight tiers).\n\nOutput is grouped per product. Each product also includes its CURRENT variations and their stock\nfor comparison so you can see the delta.", "tags": [ "catalog", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryAuditLookupRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/InventoryAuditLookupResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/inventory_status": { "post": { "operationId": "inventory_status", "summary": "Get inventory status across all tenants or a specific tenant. Shows low stock alerts and out-of-stock products.", "tags": [ "catalog", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryStatusRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/InventoryStatusResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/mailbox_inspect": { "post": { "operationId": "mailbox_inspect", "summary": "Inspect a tenant inbound mailbox: sync watermark, last error, recent ingestion counts (inbound/outbound), and a healthy/bootstrap/stalled/quiet verdict. Pass a tenant_slug, or pass platform=true for a platform-owned mailbox (tenant_id IS NULL).", "tags": [ "customers", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxInspectRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MailboxInspectResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/media_compose": { "post": { "operationId": "media_compose", "summary": "Build a finished campaign/storefront creative ON THE SERVER: take a base picture, drop the\nvendor's logo on top, add a headline and subtitle, and save the RESULT straight into the\ntenant's media library. Returns a media_id + public URL ready to place with campaign_set_image,\ncategory_manage, widget_manage, tenant_branding_manage, product_image_assign, or\ntenant_blog_upsert.\n\nPROVIDE THE BASE (exactly one):\n - base_media_id — preferred for tenant-owned photos already in the library (media_list /\n media_upload). Keeps the source visible in Admin → Media.\n - base_url — public https URL for external/generated artwork. Only the composed\n OUTPUT is saved as a library row; the raw URL bytes are not separately ingested. Prefer\n media_upload → base_media_id when the photo should remain in the media library (#184).\n\nPROVIDE THE LOGO (optional, at most one):\n - logo_media_id / logo_url — same two options as the base (prefer logo_media_id for the\n tenant logo so it stays linked in Media).\n THE LOGO IS NEVER ALTERED. It is scaled to fit (aspect ratio locked) and placed as-is —\n its colours, strokes and transparency are left exactly as supplied. For legibility on busy\n artwork use the `scrim` option, which darkens the area BEHIND the logo and text.\n\nLAYOUT: logo on top, headline under it, subtitle under that — the block is centred\nhorizontally and positioned with logo_position (top / center / bottom). Sizes are given as a\nfraction of the base image width so they scale with any canvas. Long text is word-wrapped\nautomatically; the response's `wrapped` flag tells you when that happened so you can shorten it.\n\nCONSTRAINTS: sources max 5 MB, JPEG/PNG/WebP/GIF, max 8000x8000. The finished image goes\nthrough the same pipeline as media_upload — re-encoded to WebP, resized to fit, de-duplicated\nby content — so identical inputs return the existing media_id instead of a duplicate.\n\nTypical flow: media_upload (or media_list) → media_compose → place with media_id.\n\nSTOREFRONT SWAG MODE (category_id or widget_id): instead of the manual layout above,\npass category_id or widget_id to run the platform's own storefront branding pipeline\n(SwagImagesService) against that exact category or widget — the same compositor used by\nthe dev seeder and vendor admin: tenant logo eyebrow, Bebas Neue headline (shrunk to fit\nlong names automatically), brand-colour accent rule, and a sub-label (the tenant's live\ndomain for categories, the widget's own subtitle for widgets). Pass base_media_id or\nbase_url to set/replace the row's base_image_path first; omit both to recompose from\nwhatever base_image_path is already saved. Saves directly to image_path on that category\nor widget — this is an internal/admin tool, not exposed to vendors.", "tags": [ "media", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaComposeRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MediaComposeResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/media_list": { "post": { "operationId": "media_list", "summary": "List the images in a tenant's media library — id, public URL, dimensions, filename, folder, and alt\ntext. Use this to find the media_id of an image to place into a campaign with campaign_set_image,\ninstead of guessing. Returns newest first.\n\nFilter with `folder` (exact match) or `search` (filename substring). `visibility` defaults to\n\"public\" (the emailable assets); pass \"all\" or \"private\" to widen. Confirm the tenant_slug with\ntenant_list first.", "tags": [ "media", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MediaListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/media_upload": { "post": { "operationId": "media_upload", "summary": "Upload an image into a tenant's media library (the same library the vendor admin uses). The image\nis ingested through the platform's shared media pipeline — re-encoded to WebP, resized to fit, EXIF-\noriented, content-addressed for dedup — and a media_assets row is created. It ALWAYS lands in the\nlibrary, and the tool returns the new media_id and public URL.\n\nPLACE the media_id with the matching tool (never hotlink the URL as a product/blog/hero path):\n - campaign_set_image — email campaign HTML\n - category_manage / widget_manage — storefront images (media_id / base_media_id)\n - tenant_branding_manage — store logo (media_id) or homepage hero (hero_media_id)\n - product_image_assign — product featured / gallery\n - tenant_blog_upsert — vendor blog featured image\n - media_compose — base_media_id / logo_media_id for composed creatives\n\nPROVIDE THE IMAGE ONE OF THREE WAYS (exactly one):\n - source_url — fetch the image from a public http(s) URL (preferred for remote agents).\n - source_path — read a local file path on the server/agent host (often broken on prod FS).\n - source_base64 — raw base64 of the image bytes (no data: prefix needed; a data: prefix is stripped).\n\nCONSTRAINTS: max 5 MB; JPEG, PNG, WebP, or GIF. Identical bytes already in the library are de-duped\n(you get the existing media_id back). Uploads default to public visibility so the image is emailable.\n\nOptional alt_text and folder help organise and caption the asset. Confirm the tenant_slug with\ntenant_list first. To see what's already in the library, use media_list.", "tags": [ "media", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MediaUploadResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/metrc_diagnostics": { "post": { "operationId": "metrc_diagnostics", "summary": "Returns a JSON summary of Metrc compliance status for a tenant: integration mode, sync states, audit log counts by HTTP status, and pending/failed report counts. Pass a tenant_slug to inspect a specific tenant.", "tags": [ "integrations", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetrcDiagnosticsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/MetrcDiagnosticsResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/order_dashboard": { "post": { "operationId": "order_dashboard", "summary": "Query orders across all tenants. Filter by status, order number, customer clues, date range, amount, or tenant. Returns order list with pricing context.", "tags": [ "orders", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDashboardRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/OrderDashboardResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_assign": { "post": { "operationId": "pricing_structure_assign", "summary": "Assign a shared bundle pricing structure to one or more products. Re-syncs variations for each\nreassigned product. Automatically deletes orphaned inline (hidden) structures when replacing them.\n\nSAFETY RULES enforced by this tool:\n- The target structure_id must be a BUNDLE (is_hidden=false). Inline structures cannot be assigned\n to products this way — that would violate the 1:1 contract.\n- If a product's current structure is inline (hidden) and this product is its only consumer\n (product_count == 1), the old inline structure is deleted automatically.\n- If a product's current structure is inline but product_count > 1, assignment is refused for that\n product with an explanation — this is a data anomaly that needs manual resolution.\n- Each product result includes a status: assigned | skipped (already on this structure) | refused.\n\nUse pricing_structure_list to get valid structure IDs before calling this tool.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureAssignRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureAssignResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_delete": { "post": { "operationId": "pricing_structure_delete", "summary": "Delete one or more pricing structures by ID.\n\nSAFETY RULES enforced by this tool:\n- BUNDLE structures (is_hidden=false): always deletable unless products are still assigned.\n Pass force=true to delete even when products are assigned (use only after migrating them).\n- INLINE structures (is_hidden=true): only deletable when product_count=0 (orphaned).\n Inline structures with products attached cannot be deleted — use pricing_structure_assign\n to move the product to a bundle first, which auto-cleans the inline structure.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureDeleteRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureDeleteResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_list": { "post": { "operationId": "pricing_structure_list", "summary": "List all pricing structures for a tenant with their kind (inline|bundle), product count, tracking type,\nand tier summary. Always call this before pricing_structure_upsert or pricing_structure_assign to get\nstructure IDs and confirm which structures are bundles vs inline (1:1 product) structures.\n\nkind=inline → hidden 1:1 structure tied to exactly one product (is_hidden=true)\nkind=bundle → shared structure visible on /admin/pricing, used by 0 or more products (is_hidden=false)", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureListRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureListResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_restore": { "post": { "operationId": "pricing_structure_restore", "summary": "Surgical restore tool. Rebuilds a single product's pricing structure and variations EXACTLY to a\nspecified state. Bypasses the standard syncVariationsForProduct routine — you control every field.\n\nUse this AFTER inventory_audit_lookup has revealed the pre-incident state of variations whose\nnames/prices/stock were destroyed by an erroneous bundle reassignment.\n\nBehaviour:\n- Creates a NEW inline (hidden, 1:1) pricing structure with the given tracking_type, tier\n definitions, and a name like \"Product: (Hidden)\". Old structure linkage is\n replaced. The previous structure is NOT deleted by this tool.\n- For each tier in the spec, finds-or-creates a variation. Matching is by `restore_variation_id`\n if provided, else by name. If found, the variation is updated in place (preserving its id and\n its audit-log history). If not found, a new variation is created.\n- Stock_quantity is set EXACTLY to the value specified — this is the whole point of the tool.\n- Sets product.tracking_type, product.inventory_mode, product.base_unit per the new structure.\n- Variations on the product not referenced by any tier in the spec are DEACTIVATED (is_active=false)\n so they stop being shown but their audit history is retained. Pass `delete_unreferenced=true` to\n hard-delete them instead.\n\nSAFETY:\n- Wrap each call in its own transaction.\n- Will refuse if the new tracking_type is incompatible with stored cost data.\n- Inline-only by design — bundles are not recreated by this tool. Use pricing_structure_assign\n to put the product on a bundle if that's what you want.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureRestoreRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureRestoreResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/pricing_structure_upsert": { "post": { "operationId": "pricing_structure_upsert", "summary": "Create or edit a pricing structure's tiers, name, and tracking type. Operates in three modes:\n\nBUNDLE MODE (structure_id provided, structure is not hidden):\n Edit a shared bundle structure visible on /admin/pricing. Tiers are replaced and ALL products\n linked to the bundle are re-synced. Returns how many products were affected as a warning.\n\nINLINE MODE (product_slug or product_id provided, no structure_id):\n Edit the hidden 1:1 pricing structure for a single product. Tiers are replaced and variations\n are re-synced for that product only. Refuses if the product currently uses a bundle structure —\n use pricing_structure_assign to detach from the bundle first.\n\nCREATE BUNDLE MODE (no structure_id, no product_slug/product_id):\n Create a new shared bundle structure. Does not link it to any products.\n\nSAFETY RULES enforced by this tool:\n- Never accepts structure_id pointing to a hidden (inline) structure — always go via product_slug/product_id.\n- Tiers for weight/matrix types must have weight_grams > 0.\n- Tiers for simple type: only the first tier is used; name and weight_grams are normalised.\n- Prices are accepted as dollar amounts (e.g. 12.99) and converted to cents internally.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingStructureUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PricingStructureUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_feature_manage": { "post": { "operationId": "product_feature_manage", "summary": "List or set which products are featured on a tenant's storefront home page\n(the \"Featured Products\" section, HomeController — up to 8 shown, ordered by\nthe tenant's default product sort).\n\nACTIONS:\n list (default): return every is_featured=true product with id, slug, name,\n stock_status. Always call this first to see the current set before\n changing it.\n set: pass product_ids (array) and featured (bool) to set is_featured on\n those products. Unlisted products are left untouched — this is an\n additive/subtractive edit, not a replace-the-whole-set operation.\n\nProducts must be resolved to ids first (product_inspect or this tool's list\naction). Featuring an out-of-stock product is allowed but usually undesirable\n— check stock_status in the list output before featuring.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFeatureManageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductFeatureManageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_image_assign": { "post": { "operationId": "product_image_assign", "summary": "Set a product's featured image and/or gallery from the tenant media library.\nPass media_id (from media_list / media_upload) for featured_image, and/or\ngallery_media_ids to replace gallery_images. Does not upload bytes and does\nnot create media_assets rows — ingest first with media_upload. Assets must be\npublic (private library items have no storefront URL).\n\ndry_run (default true) previews without writing. overwrite (default false)\nrefuses to replace an existing featured_image unless true. clear_featured\nclears featured_image without setting a new one.\n\nDistinct from product_image_strain_assign, which writes a shared platform\nstrain CDN URL and never creates a tenant library row (GitHub #72 / #184).", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductImageAssignRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductImageAssignResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_image_strain_assign": { "post": { "operationId": "product_image_strain_assign", "summary": "Apply a hosted platform strain photo to a product's featured_image.\nWrites a URL string to the product row only — never uploads/copies bytes,\nnever creates a tenant media_assets row (this is the shared strain\nlibrary, not tenant media).\n\nTwo modes (exactly one required):\n assignments: explicit [{product_id, strain_id}, ...] pairs you already\n decided on (e.g. from product_image_strain_match's proposals).\n auto_match: true — re-runs product_image_strain_match's own matching\n internally against products missing a featured image (optionally\n scoped by search/limit) and applies every exact/partial match found.\n\ndry_run (default true) previews without writing — always call once with\ndry_run=true and review the results before dry_run=false.\n\noverwrite (default false) — a product that already has a featured_image\nis skipped, never replaced, unless overwrite=true. Idempotent: if a\nproduct's featured_image already equals the target strain's hosted URL,\nit is reported skipped/already_set regardless of overwrite (nothing to\ndo, not an error).\n\nRefuses to assign a strain whose image is not hosted on the platform\n(skipped/strain_image_not_hosted) — never writes a dead or third-party\nhotlinked URL as a product's featured image.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductImageStrainAssignRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductImageStrainAssignResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_image_strain_match": { "post": { "operationId": "product_image_strain_match", "summary": "Find products on a tenant's storefront that have no featured image, and\npropose a hosted platform strain photo for each by matching product name\nagainst the strain library. Read-only — never writes to a product; pass\nthe results to product_image_strain_assign to actually apply them.\n\nOnly proposes strains whose photo is already hosted on the platform\n(cdn.strains.dabdash.com/strains/... — see StrainImageService::isHostedUrl). A name match\nagainst an unhosted/dead-remote strain is reported as match_method=none\nrather than proposing a broken or third-party hotlinked image.\n\nMatch order per product: 1) the product's own strain_id FK, if set\n(match_method=strain_id_fk, confidence=exact) 2) case-insensitive exact\nname match (confidence=exact) 3) prefix/contains name match, shortest\nstrain name wins ties (confidence=partial) 4) no match\n(match_method=none, confidence=none).", "tags": [ "catalog", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductImageStrainMatchRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductImageStrainMatchResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_inspect": { "post": { "operationId": "product_inspect", "summary": "Inspect a specific product including every variation's price, compare_at_price, mix_match_tags, stock, and the tenant's mix & match rule settings. Use this to audit pricing, sale state, and bundle configuration for support tickets.", "tags": [ "catalog", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInspectRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductInspectResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_manage": { "post": { "operationId": "product_manage", "summary": "Create a simple product for a tenant (v1: one price, unit tracking — the same\ndefault as a blank create-product page). Call strain_lookup first when the\nname looks like a strain, then pass strain_id so description, type, THC/CBD,\nindica/sativa, effects, flavors, rating, and the hosted strain photo fill in\nexactly like the vendor create page.\n\nIf strain_id is omitted, this tool name-matches the platform strain library\nitself: an exact name match is applied automatically; close matches are\nreturned as strain_matches so you can offer them. Pass skip_strain_enrich=true\nto skip that.\n\nACTIONS:\n create: requires name. Optional price (dollars), sku, stock_quantity,\n category_ids, description, strain_id.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductManageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductManageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_profitability": { "post": { "operationId": "product_profitability", "summary": "Rank a tenant's products by real net margin using order-line COGS\n(order_items.cost_price), not price-tier approximations. Use this before\nrecommending sales, coupons, freebies, or subscription mounting ladders —\nonly promote SKUs with enough margin headroom.\n\nRevenue dating follows RevenueAttribution (placed vs delivered) for the\ntenant. Freebie gift lines are excluded from COGS so giveaways do not\ndistort product margins. Results include current catalog stock_status and\na promo_headroom_ok flag (margin_percent >= min_margin_percent).\n\nSort: margin (default), revenue, or units. Pass a wide date_from for\ntenants with older imported history.", "tags": [ "analytics", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductProfitabilityRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductProfitabilityResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_unit_price_search": { "post": { "operationId": "product_unit_price_search", "summary": "Search and rank a tenant's catalog by computed per-unit price (e.g. price\nper gram or price per ounce), across every weight-family product (types\n\"weight\" and \"matrix\") — something product_inspect cannot do because it\nonly looks up one product at a time by id/name/sku.\n\nFor each active, in-stock variation with a weight_value, computes\nprice_per_gram = price_cents / weight_value, then scales it to the\nrequested unit (default \"oz\" = 28g, matching the storefront's weight-tier\nconvention). Use this to answer \"what's the cheapest/most expensive\nproduct per ounce\", \"find products under $X/g\", or to rank the catalog by\nunit economics for pricing audits and promo targeting.\n\nOnly weight-family products (weight, matrix) have a meaningful per-gram\nprice — unit-family products (simple, unit, matrix_unit) are excluded\nsince their variations are priced per item, not per weight.", "tags": [ "catalog", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUnitPriceSearchRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductUnitPriceSearchResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/product_update_by_sku": { "post": { "operationId": "product_update_by_sku", "summary": "Update a simple product's stock quantity and/or price by SKU — the inventory-sync path for an external POS. v1 scope: SIMPLE products only (single implicit unit, no weight/variant tiers). Every other pricing type (weight, unit, matrix, matrix_unit) is rejected with a clear message; those need per-tier/per-variant targeting that a flat SKU+quantity+price payload cannot express safely. Always call product_inspect with sku first to confirm which product/type you are targeting.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdateBySkuRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProductUpdateBySkuResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/promotion_audit": { "post": { "operationId": "promotion_audit", "summary": "Inspect coupons, freebies, mix and match rules, loyalty settings, and storewide sale state for overcharge or missed-discount support tickets.", "tags": [ "promotions", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionAuditRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PromotionAuditResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/purchase_order_draft_create": { "post": { "operationId": "purchase_order_draft_create", "summary": "Create a draft purchase order for a supplier. Does not receive stock.\nAfter creating, add lines with purchase_order_line_add, then tell the\nvendor to review the draft in admin (never auto-receive).", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOrderDraftCreateRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PurchaseOrderDraftCreateResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/purchase_order_line_add": { "post": { "operationId": "purchase_order_line_add", "summary": "Add a product line to a draft purchase order. Pass product_id (and\nvariation_id when the product tracks stock by size). qty is the ordered\nquantity. unit_cost is dollars per unit; omit to use last cost.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOrderLineAddRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PurchaseOrderLineAddResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/push_notification_diagnostics": { "post": { "operationId": "push_notification_diagnostics", "summary": "Diagnose push notification (FCM) delivery for a vendor. Surfaces token health, notification settings, recent send history with push/email flags, and a plain-language diagnosis of why pushes are or are not being delivered.", "tags": [ "integrations", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushNotificationDiagnosticsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/PushNotificationDiagnosticsResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/search_console": { "post": { "operationId": "search_console", "summary": "Query Google Search Console data for the platform (dabdash.com) or a specific tenant with a connected GSC integration. Returns search overview, top queries, top pages, and daily trend.", "tags": [ "analytics", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchConsoleRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/SearchConsoleResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/store_info": { "post": { "operationId": "store_info", "summary": "Identify the connected store — name, slug, timezone, currency, country, and subscription status. Use to validate an API token during setup.", "tags": [ "store", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreInfoRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/StoreInfoResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/strain_lookup": { "post": { "operationId": "strain_lookup", "summary": "Search the platform strain database — the same catalog vendors search on the\ncreate-product page. Returns name, type, cannabinoids, effects, flavors, and\nwhether a hosted photo exists. Use this BEFORE creating a product whose name\nlooks like a strain, then pass strain_id to product_manage so the product is\nfilled from that row. Not tenant-owned media; photos stay on the shared\nstrain CDN.", "tags": [ "catalog", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrainLookupRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/StrainLookupResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/supplier_upsert": { "post": { "operationId": "supplier_upsert", "summary": "Create or update a product supplier for purchase orders.\n\nUPDATE MODE (supplier_id): only the fields you pass are changed.\nCREATE MODE (no supplier_id): name is required. If a supplier with the\nsame name already exists for this vendor, that row is updated instead.\n\nAlways resolve the supplier_id before purchase_order_draft_create.", "tags": [ "catalog", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierUpsertRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/SupplierUpsertResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/tenant_branding_manage": { "post": { "operationId": "tenant_branding_manage", "summary": "Show or update a tenant's store logo, homepage hero image, and BIMI email\nlogo, then upsert the Cloudflare `default._bimi` TXT record when the zone\nis connected.\n\nACTIONS:\n show (default): current logo_path, storefront logo URL (custom domain when\n set), hero_image_path/URL, BIMI path/URL, the TXT value to publish,\n and whether Cloudflare is connected.\n set: pass media_id (from media_list / media_upload) to point logo_path at a\n library asset. Pass hero_media_id for settings.hero_image_path, or\n clear_hero=true to remove the hero. Pass exactly one of source_base64 /\n source_path / source_url for an SVG to store the BIMI logo at\n tenants/{id}/bimi-logo.svg (media_upload cannot take SVG). dry_run\n defaults true — the first call reports what would happen.\n\nLogo URLs and BIMI `l=` values always use the tenant storefront host\n(custom domain or {slug}.dabdash.com), never the platform APP_URL.", "tags": [ "integrations", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantBrandingManageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/TenantBrandingManageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/widget_manage": { "post": { "operationId": "widget_manage", "summary": "List, create, update, or delete a tenant's homepage marketing widgets (the hero slider cards\nlinking to a product, category, featured products, or a mix & match tag).\n\nACTIONS:\n list (default): return every widget with id, title, subtitle, link_type, target, sort_order,\n is_active, and image_url. Always call this first to find a widget_id.\n create: requires title. link_type + its matching id/tag is optional but recommended so the\n widget's CTA actually goes somewhere (see LINK_TYPE below). Defaults to \"featured\"\n (no target) when omitted.\n update: requires widget_id. Only the fields you pass are changed.\n delete: requires widget_id and confirm=true.\n\nLINK_TYPE — pairs with exactly one target field:\n \"product\" → product_id\n \"category\" → category_id\n \"mix_match\" → mix_match_tag\n \"featured\" → no target needed (links to the featured-products listing)\n\nIMAGES: pass media_id (from media_list / media_upload) to set image_path (the final,\ncustomer-facing image) or base_image_path (the unbranded source canvas SwagImagesService\ncomposites the headline/logo overlay onto). Omit both to leave images untouched.\n\nAlways call action=list first to confirm widget_id before update or delete.", "tags": [ "promotions", "write" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetManageRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/WidgetManageResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } }, "/api/v1/tools/zone_diagnostics": { "post": { "operationId": "zone_diagnostics", "summary": "Inspect zone polygons against customer or order coordinates to explain why an address is inside or outside delivery coverage.", "tags": [ "zones", "read" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneDiagnosticsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string" }, "data": { "$ref": "#/components/schemas/ZoneDiagnosticsResponse" } } } } } }, "401": { "description": "Missing or invalid tenant credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "The tenant has no active trial, subscription, or grace period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A read-scoped key was used to call a write tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown tool name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Request validation failed, or the tool reported a business error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object" } }, "required": [ "error", "message" ] } } } } }, "security": [ { "tenantApiKey": [] }, { "tenantOAuth": [] } ] } } } }