{"openapi":"3.1.0","info":{"title":"Tiny Shops Tool API","version":"1.0.0"},"servers":[{"url":"/"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/v1/get_analytics":{"post":{"operationId":"get_analytics","summary":"Return revenue, order and status counts, unique visitors, and top products for a 7, 30, or 90 day period.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","enum":["7d","30d","90d"],"default":"7d"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_billing_status":{"post":{"operationId":"get_billing_status","summary":"Get the authenticated tenant's current subscription, plan, billing window, derived feature flags, usage-based pricing breakdown (base+overage), contacts snapshot, and migration status. Read-only.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_invoices":{"post":{"operationId":"list_invoices","summary":"List the authenticated tenant's subscription payment history (invoices). Paginated; ordered newest first. Read-only.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_brands":{"post":{"operationId":"list_brands","summary":"List brands for the authenticated tenant. Paginated; tenant-scoped via the kernel Prisma extension.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_brand":{"post":{"operationId":"get_brand","summary":"Fetch a single brand by id for the authenticated tenant. Throws if not found within the tenant.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/create_brand":{"post":{"operationId":"create_brand","summary":"Create a brand for the authenticated tenant. Requires `write` scope. Writes an audit row.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9-]+$"},"description":{"type":"string","maxLength":2000},"logoUrl":{"type":"string","format":"uri"},"websiteUrl":{"type":"string","format":"uri"},"isActive":{"type":"boolean"}},"required":["name","slug"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_brand":{"post":{"operationId":"update_brand","summary":"Update a brand by id for the authenticated tenant. Requires `write` scope. Writes an audit row.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9-]+$"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"logoUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"websiteUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"isActive":{"type":"boolean"}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/delete_brand":{"post":{"operationId":"delete_brand","summary":"Delete a brand by id. Requires `admin` scope and `confirm: true`. Destructive — products lose their brand link (FK SetNull). Writes an audit row.","x-requiredScope":"admin","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"confirm":{"type":"boolean","const":true}},"required":["id","confirm"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_categories":{"post":{"operationId":"list_categories","summary":"List categories for the authenticated tenant. Optional `parentId` filter (pass null for roots). Paginated; tenant-scoped.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1},"parentId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Filter by parent id. Pass null to list only root categories; omit for all."}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_category":{"post":{"operationId":"get_category","summary":"Fetch a single category by id for the authenticated tenant. Throws if not found within the tenant.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/create_category":{"post":{"operationId":"create_category","summary":"Create a category for the authenticated tenant. Requires `write` scope. parentId (optional) must belong to the same tenant. Writes an audit row.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9-]+$"},"description":{"type":"string","maxLength":2000},"imageUrl":{"type":"string","format":"uri"},"parentId":{"type":"string","minLength":1},"sortOrder":{"type":"integer"},"isActive":{"type":"boolean"}},"required":["name","slug"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_category":{"post":{"operationId":"update_category","summary":"Update a category by id. Requires `write` scope. parentId (if set) must belong to the same tenant and cannot equal the category id. Writes an audit row.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9-]+$"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"parentId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"sortOrder":{"type":"integer"},"isActive":{"type":"boolean"}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/delete_category":{"post":{"operationId":"delete_category","summary":"Delete a category by id. Requires `admin` scope and `confirm: true`. Destructive — child categories are detached (FK SetNull) and products lose their category link. Writes an audit row.","x-requiredScope":"admin","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"confirm":{"type":"boolean","const":true}},"required":["id","confirm"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_checkout":{"post":{"operationId":"get_checkout","summary":"Return the current checkout configuration (mode, fields, main filters) from `App.config`.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_checkout":{"post":{"operationId":"update_checkout","summary":"Update checkout configuration. Composite: pass any subset of `mode`, `fields`, `filters`. Each array fully replaces the existing array; other config fields are preserved. Inline-managed PaymentProvider rows are NOT synced — use the dashboard for Razorpay/Midtrans inline credentials.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["manual","native_payments","crypto"]},"fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","email","phone","select","checkbox","textarea","date","label","warning","info","bonus_toggle","promocode_input","payment_button"]},"required":{"type":"boolean"},"defaultVisible":{"type":"boolean"},"placeholder":{"type":"string"},"options":{"type":"string"},"content":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","properties":{"dependsOn":{"type":"string"},"operator":{"type":"string","enum":["equals","not_equals","contains","not_contains","is_empty","is_not_empty"]},"value":{"type":"string"},"action":{"type":"string","enum":["show","hide","require","optional","increase_price","decrease_price"]},"priceAdjustment":{"type":"object","properties":{"operator":{"type":"string","enum":["add","subtract"]},"value":{"type":"number"}},"required":["operator","value"],"additionalProperties":false}},"required":["dependsOn","operator","action"],"additionalProperties":false}},"telegramDataKey":{"type":"string","enum":["username","phone"]}},"required":["id","label","type","required","defaultVisible"],"additionalProperties":false}},"filters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["category","brand","sub_category"]},"label":{"type":"string"},"enabled":{"type":"boolean"},"order":{"type":"number"},"visibilityMode":{"type":"string","enum":["always","when_parent_has_value"]}},"required":["id","label","enabled","order","visibilityMode"],"additionalProperties":false}}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_contests":{"post":{"operationId":"list_contests","summary":"List contests for the authenticated tenant. Optional `status` filter (DRAFT|ACTIVE|ENDED|CANCELLED). Paginated; tenant-scoped.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1},"status":{"type":"string","enum":["DRAFT","ACTIVE","ENDED","CANCELLED"]}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_contest":{"post":{"operationId":"get_contest","summary":"Fetch a single contest by id for the authenticated tenant. Throws if not found within the tenant.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/create_contest":{"post":{"operationId":"create_contest","summary":"Create a contest for the authenticated tenant. Requires `write` scope. startDate must be before endDate. Status defaults to DRAFT. Writes an audit row. (Announce/winners are deliberately not exposed — use the dashboard.)","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9-]+$"},"buttonText":{"type":"string","maxLength":100},"startDate":{"type":"string","format":"date-time"},"endDate":{"$ref":"#/properties/startDate"},"maxParticipants":{"type":"integer","exclusiveMinimum":0},"prizeDescription":{"type":"string","maxLength":2000},"promoCode":{"type":"string","maxLength":100},"rules":{"type":"string","maxLength":5000},"bonusReward":{"type":"integer","minimum":0},"status":{"type":"string","enum":["DRAFT","ACTIVE","ENDED","CANCELLED"]}},"required":["title","slug","startDate","endDate"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_contest":{"post":{"operationId":"update_contest","summary":"Update a contest by id. Requires `write` scope. Supports status transitions and field edits; resulting startDate must remain before endDate. Writes an audit row.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":300},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9-]+$"},"buttonText":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"startDate":{"type":"string","format":"date-time"},"endDate":{"$ref":"#/properties/startDate"},"maxParticipants":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"prizeDescription":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"promoCode":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"rules":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"bonusReward":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"status":{"type":"string","enum":["DRAFT","ACTIVE","ENDED","CANCELLED"]}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/delete_contest":{"post":{"operationId":"delete_contest","summary":"Delete a contest by id. Requires `admin` scope and `confirm: true`. Destructive — cascades to participants. Writes an audit row.","x-requiredScope":"admin","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"confirm":{"type":"boolean","const":true}},"required":["id","confirm"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_customers":{"post":{"operationId":"list_customers","summary":"List customers (Telegram users) for the authenticated tenant. Optional `search` matches first/last/username (case-insensitive). Paginated by user id cursor.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1},"search":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_customer":{"post":{"operationId":"get_customer","summary":"Fetch a single customer by Telegram user id (stringified BigInt). Throws not_found if not in this tenant.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_customer":{"post":{"operationId":"update_customer","summary":"Update mutable customer profile fields (username, firstName, lastName, isBotBlocked, isBanned). `isBanned: true` locks the shopper out of the storefront, checkout, the store bot and broadcasts. At least one field is required. Audited.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"username":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"firstName":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}]},"isBotBlocked":{"type":"boolean"},"isBanned":{"type":"boolean"}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/adjust_bonus":{"post":{"operationId":"adjust_bonus","summary":"Atomically adjust a customer's bonus balance by `delta` (positive credits, negative debits). Returns the new balance. Audited with the delta and reason.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","minLength":1},"delta":{"type":"number"},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["customerId","delta"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/send_campaign":{"post":{"operationId":"send_campaign","summary":"Broadcast a Telegram message to tenant customers.\n\nTwo-phase: call without `confirm` to PREVIEW (returns recipientCount + ETA, no send).\nCall again with `confirm: true` to actually send. Sends are synchronous and\nfan out per-recipient via the tenant bot; cap is 500 recipients per call\nto fit within MCP client tool timeouts — split larger audiences across calls.\n\nRequires the tenant plan to include the messages feature (`hasMessages: true`).\n`audience.segment` is reserved for future use and currently rejected.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"text":{"type":"string","minLength":1},"imageUrl":{"type":"string","format":"uri"},"buttonText":{"type":"string","minLength":1},"buttonUrl":{"type":"string","format":"uri"},"audience":{"anyOf":[{"type":"object","properties":{"all":{"type":"boolean","const":true}},"required":["all"],"additionalProperties":false},{"type":"object","properties":{"customerIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["customerIds"],"additionalProperties":false},{"type":"object","properties":{"segment":{"type":"string","minLength":1}},"required":["segment"],"additionalProperties":false}]},"confirm":{"type":"boolean"}},"required":["name","text","audience"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_monetization":{"post":{"operationId":"get_monetization","summary":"Return the current bonus / referral / cashback config blocks from `App.config`.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_monetization":{"post":{"operationId":"update_monetization","summary":"Update monetization. Composite: pass any subset of `bonus`, `referral`, `cashback` (each is a full config block that fully replaces the existing block).","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"bonus":{"type":"object","properties":{"maxPercentage":{"type":"number","minimum":0,"maximum":100},"mutualExclusivityWithPromocode":{"type":"boolean"}},"required":["maxPercentage","mutualExclusivityWithPromocode"],"additionalProperties":false},"referral":{"type":"object","properties":{"referralJoinBonus":{"type":"number","minimum":0},"referrerOrderBonus":{"type":"number","minimum":0},"referrerBonusFrequency":{"type":"string","enum":["once","every_order"]}},"required":["referralJoinBonus","referrerOrderBonus","referrerBonusFrequency"],"additionalProperties":false},"cashback":{"type":"object","properties":{"enabled":{"type":"boolean"},"levels":{"type":"array","items":{"type":"object","properties":{"minOrders":{"type":"number","minimum":0},"maxOrders":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"cashbackPercentage":{"type":"number","minimum":0,"maximum":100},"levelName":{"type":"string"}},"required":["minOrders","maxOrders","cashbackPercentage","levelName"],"additionalProperties":false}},"categoryRates":{"type":"array","items":{"type":"object","properties":{"categoryKey":{"type":"string","minLength":1,"maxLength":200},"cashbackPercentage":{"type":"number","minimum":0,"maximum":100}},"required":["categoryKey","cashbackPercentage"],"additionalProperties":false},"maxItems":200},"promotions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"label":{"type":"string","maxLength":120},"startsAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"endsAt":{"anyOf":[{"$ref":"#/properties/cashback/properties/promotions/items/properties/startsAt"},{"type":"null"}]},"mode":{"type":"string","enum":["add","override"]},"cashbackPercentage":{"type":"number","minimum":0,"maximum":100},"maxCashbackPerOrder":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"default":null},"enabled":{"type":"boolean","default":true}},"required":["id","label","startsAt","endsAt","mode","cashbackPercentage"],"additionalProperties":false},"maxItems":100},"maxCashbackPerOrder":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"description":{"type":"string"},"cashbackTrigger":{"type":"string","enum":["on_order_place","on_payment","on_status"]},"cashbackTriggerStatus":{"type":"string","enum":["PENDING","PROCESSING","SHIPPED","DELIVERED","CANCELLED"]}},"required":["enabled","levels","categoryRates","promotions","maxCashbackPerOrder","cashbackTrigger"],"additionalProperties":false}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_orders":{"post":{"operationId":"list_orders","summary":"List orders for the authenticated tenant. Optional `status` filter; paginated by id cursor.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1},"status":{"type":"string","enum":["PENDING","PROCESSING","SHIPPED","DELIVERED","CANCELLED"]}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_order":{"post":{"operationId":"get_order","summary":"Read one order by id: status, paymentMethod, total in minor units, currency, the shopper Telegram user id, shipping address, checkout answers, line items, and tracking. Same shape as the `data` of the order webhook.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"integer","exclusiveMinimum":0}},"required":["orderId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/ship_order":{"post":{"operationId":"ship_order","summary":"Mark an order SHIPPED and save tracking. At least one of `trackingUrl`, `carrier`, `trackingNumber` is required. The shopper is NOT messaged unless `notify: true`; then they get the store's shipped message, with a track button only when `trackingUrl` is set. Emits the `order.updated` webhook.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"integer","exclusiveMinimum":0},"trackingUrl":{"type":"string","maxLength":2048},"carrier":{"type":"string","maxLength":100},"trackingNumber":{"type":"string","maxLength":100},"notify":{"type":"boolean"}},"required":["orderId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/set_order_status":{"post":{"operationId":"set_order_status","summary":"Update an order status (PENDING, PROCESSING, SHIPPED, DELIVERED, CANCELLED). \"Mark paid\" for a manual-payment order is PROCESSING. Wraps the kernel `setOrderStatus`, so cashback-on-status configured for the tenant is awarded identically to a dashboard-driven change, and the `order.updated` webhook fires.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"integer","exclusiveMinimum":0},"status":{"type":"string","enum":["PENDING","PROCESSING","SHIPPED","DELIVERED","CANCELLED"]}},"required":["orderId","status"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/add_order_note":{"post":{"operationId":"add_order_note","summary":"Attach a free-form internal note to an order. The note is admin-only and never exposed to customers.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"integer","exclusiveMinimum":0},"note":{"type":"string","minLength":1,"maxLength":2000}},"required":["orderId","note"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/refund_order":{"post":{"operationId":"refund_order","summary":"Record a refund for an order. Marks the order CANCELLED and audits the requested amount/reason. NOTE: does not yet call payment-provider refund APIs (see refundOrderHandler JSDoc).","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"integer","exclusiveMinimum":0},"amount":{"type":"integer","exclusiveMinimum":0},"reason":{"type":"string","maxLength":500}},"required":["orderId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/delete_order":{"post":{"operationId":"delete_order","summary":"Permanently delete an order and its dependent rows. Requires admin scope and `confirm: true`. DESTRUCTIVE.","x-requiredScope":"admin","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"integer","exclusiveMinimum":0},"confirm":{"type":"boolean","const":true}},"required":["orderId","confirm"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_payment_providers":{"post":{"operationId":"list_payment_providers","summary":"List payment providers configured for the current tenant.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_payment_provider":{"post":{"operationId":"get_payment_provider","summary":"Fetch a single PaymentProvider row by id (tenant-scoped).","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/create_payment_provider":{"post":{"operationId":"create_payment_provider","summary":"Create a PaymentProvider. Use providerName=\"Telegram Stars\" (currency XTR, no token), \"Stripe\" (token), \"Razorpay\" (token + metadata.keyId), \"Midtrans\" (metadata.merchantId/clientKey/serverKey), \"TON\" (metadata.walletAddress), \"NOWPayments\" (metadata.apiKey/ipnSecret), or a custom provider name.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"providerName":{"type":"string","minLength":1},"providerToken":{"type":"string"},"isTestMode":{"type":"boolean"},"isActive":{"type":"boolean"},"supportedCurrencies":{"type":"array","items":{"type":"string"},"minItems":1},"metadata":{"type":"object","additionalProperties":{}}},"required":["providerName","providerToken","isTestMode","isActive","supportedCurrencies"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_payment_provider":{"post":{"operationId":"update_payment_provider","summary":"Update a PaymentProvider. Pass `id` plus any subset of providerToken/isTestMode/isActive/supportedCurrencies/metadata. Rows tagged metadata.source===\"inline\" are managed by the payment_button checkout field — edit via update_checkout instead.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"providerToken":{"type":"string"},"isTestMode":{"type":"boolean"},"isActive":{"type":"boolean"},"supportedCurrencies":{"type":"array","items":{"type":"string"},"minItems":1},"metadata":{"type":"object","additionalProperties":{}}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/delete_payment_provider":{"post":{"operationId":"delete_payment_provider","summary":"Delete a PaymentProvider by id. Refuses rows managed by an inline payment_button checkout field — clear the field via update_checkout instead.","x-requiredScope":"admin","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_invoice_field_config":{"post":{"operationId":"get_invoice_field_config","summary":"Return the InvoiceFieldConfig (which buyer fields native Telegram payments collect, plus tip configuration). Returns defaults when no row exists yet.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_invoice_field_config":{"post":{"operationId":"update_invoice_field_config","summary":"Update the InvoiceFieldConfig. Composite: pass any subset of needName/needPhoneNumber/needEmail/needShippingAddress/isFlexible/maxTipAmount/suggestedTipAmounts. Other fields preserved.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"needName":{"type":"boolean"},"needPhoneNumber":{"type":"boolean"},"needEmail":{"type":"boolean"},"needShippingAddress":{"type":"boolean"},"isFlexible":{"type":"boolean"},"maxTipAmount":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":2000000000},{"type":"null"}]},"suggestedTipAmounts":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":2000000000}}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_products":{"post":{"operationId":"list_products","summary":"List products for the authenticated tenant. Paginated; results are tenant-scoped via the kernel Prisma extension.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_product":{"post":{"operationId":"get_product","summary":"Fetch a single product by id for the authenticated tenant. Throws if not found within the tenant.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/create_product":{"post":{"operationId":"create_product","summary":"Create a product (and optional variants) for the authenticated tenant. Requires `write` scope.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"description":{"type":"string"},"images":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1},"brand":{"type":"string"},"category":{"type":"string"},"subCategory":{"type":"string"},"price":{"type":"number","exclusiveMinimum":0},"salePrice":{"type":"number","exclusiveMinimum":0},"tags":{"type":"string"},"itemAmount":{"type":"integer","minimum":0},"shippingTime":{"type":"string"},"season":{"type":"string"},"brandId":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"categoryId":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"variants":{"type":"array","items":{"type":"object","properties":{"optionTitle":{"type":"string","minLength":1},"values":{"type":"array","items":{"type":"object","properties":{"variantValue":{"type":"string","minLength":1},"price":{"type":"number","minimum":0},"salePrice":{"anyOf":[{"anyOf":[{"not":{}},{"type":"number","minimum":0}]},{"type":"null"}]},"itemAmount":{"anyOf":[{"anyOf":[{"not":{}},{"type":"integer","minimum":0}]},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":0}},"required":["variantValue","price"],"additionalProperties":false},"minItems":1}},"required":["optionTitle","values"],"additionalProperties":false}}},"required":["productId","title","description","images","price"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_product":{"post":{"operationId":"update_product","summary":"Partial update of a product by internal id. Requires `write` scope. `productId` is immutable and cannot be changed.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"description":{"type":"string"},"images":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1},"brand":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"category":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"subCategory":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"price":{"type":"number","exclusiveMinimum":0},"salePrice":{"anyOf":[{"anyOf":[{"not":{}},{"type":"number","exclusiveMinimum":0}]},{"type":"null"}]},"tags":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"itemAmount":{"anyOf":[{"anyOf":[{"not":{}},{"type":"integer","minimum":0}]},{"type":"null"}]},"shippingTime":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"season":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"brandId":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"categoryId":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string"}]},{"type":"null"}]},"isHidden":{"type":"boolean"}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/delete_product":{"post":{"operationId":"delete_product","summary":"Permanently delete a product (and its variants by cascade) for the authenticated tenant. Requires `admin` scope and `confirm: true`.","x-requiredScope":"admin","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"confirm":{"type":"boolean","const":true}},"required":["id","confirm"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_stock":{"post":{"operationId":"update_stock","summary":"Adjust product or variant stock. Pass exactly one of `delta` (relative) or `absolute` (set to). Requires `write` scope.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","minLength":1},"variantId":{"type":"string","minLength":1},"delta":{"type":"integer"},"absolute":{"type":"integer","minimum":0}},"required":["productId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_variants":{"post":{"operationId":"list_variants","summary":"List variants for a product. Tenant-scoped, paginated by id cursor.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","minLength":1},"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1}},"required":["productId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_variant":{"post":{"operationId":"update_variant","summary":"Partial update of a product variant by id. Requires `write` scope.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"optionTitle":{"type":"string","minLength":1},"variantValue":{"type":"string","minLength":1},"price":{"type":"number","minimum":0},"salePrice":{"anyOf":[{"anyOf":[{"not":{}},{"type":"number","minimum":0}]},{"type":"null"}]},"itemAmount":{"anyOf":[{"anyOf":[{"not":{}},{"type":"integer","minimum":0}]},{"type":"null"}]},"sortOrder":{"type":"integer","minimum":0}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_promocodes":{"post":{"operationId":"list_promocodes","summary":"List promocodes for the authenticated tenant, newest first. Paginated by id cursor.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/create_promocode":{"post":{"operationId":"create_promocode","summary":"Create a new promocode. `code` must be unique per tenant. `discountType` is PERCENTAGE or FIXED_AMOUNT. Audited.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64},"discountType":{"type":"string","enum":["PERCENTAGE","FIXED_AMOUNT"]},"discountValue":{"type":"number","exclusiveMinimum":0},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"maxUses":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"isActive":{"type":"boolean"}},"required":["code","discountType","discountValue"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_promocode":{"post":{"operationId":"update_promocode","summary":"Update mutable promocode fields. At least one field is required. Audited.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"code":{"type":"string","minLength":1,"maxLength":64},"discountType":{"type":"string","enum":["PERCENTAGE","FIXED_AMOUNT"]},"discountValue":{"type":"number","exclusiveMinimum":0},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"maxUses":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}]},"isActive":{"type":"boolean"}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/toggle_promocode":{"post":{"operationId":"toggle_promocode","summary":"Enable or disable a promocode by setting `isActive`. Audited as enable/disable.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"active":{"type":"boolean"}},"required":["id","active"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/delete_promocode":{"post":{"operationId":"delete_promocode","summary":"Permanently delete a promocode. Requires admin scope and explicit `confirm: true`. Destructive.","x-requiredScope":"admin","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"confirm":{"type":"boolean","const":true}},"required":["id","confirm"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_settings":{"post":{"operationId":"get_settings","summary":"Return current storefront general settings (SEO/general copy/logo) from `App.config`. Excludes theme, monetization, and checkout — use the dedicated tools for those.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_general":{"post":{"operationId":"update_general","summary":"Update storefront general settings. Composite: pass any subset of `title`, `name`, `description`, `keywords`, `logoUrl`, `darkLogoUrl`. Other config fields are preserved.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"keywords":{"type":"string","maxLength":500},"logoUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"string","const":""}]},"darkLogoUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"string","const":""}]}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_bot":{"post":{"operationId":"get_bot","summary":"Return whether the store Telegram bot is connected and its username. Never returns the bot token.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/connect_bot":{"post":{"operationId":"connect_bot","summary":"Validate and connect a BotFather token, then register the storefront webhook. The token is never returned or audited.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","pattern":"^\\d{8,10}:[A-Za-z0-9_-]{35,}$"}},"required":["token"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_welcome_message":{"post":{"operationId":"get_welcome_message","summary":"Return the shopper bot welcome message.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_welcome_message":{"post":{"operationId":"update_welcome_message","summary":"Update the shopper bot welcome message. Supports {{first_name}} and {{shop_name}}.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":4000}},"required":["message"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_store_settings":{"post":{"operationId":"get_store_settings","summary":"Return the store currency and primary language.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_store_settings":{"post":{"operationId":"update_store_settings","summary":"Update store currency and/or primary language. A currency change relabels all product prices and requires confirm: true when products exist.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"language":{"type":"string","enum":["en","ru"]},"confirm":{"type":"boolean"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/get_theme":{"post":{"operationId":"get_theme","summary":"Return the current storefront theme block (colors, mode, typography, radius).","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_theme":{"post":{"operationId":"update_theme","summary":"Update the storefront theme. Composite: pass any subset of color/mode/typography fields. Hex colors are normalized to lowercase `#rrggbb`. Other config fields are preserved.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"primaryColor":{"type":"string","minLength":1},"secondaryColor":{"$ref":"#/properties/primaryColor"},"mode":{"type":"string","enum":["light","dark","system"]},"fontFamilySans":{"type":"string"},"fontFamilySerif":{"type":"string"},"fontFamilyMono":{"type":"string"},"fontStylesheetHref":{"type":"string","format":"uri"},"letterSpacingEm":{"type":"number"},"borderRadiusRem":{"type":"number"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/upload_image":{"post":{"operationId":"upload_image","summary":"Upload an image to tenant storage. Supply either a public URL or a base64-encoded payload. Returns the resulting public URL. Requires `write` scope. URL fetches are sandboxed: only http(s), public IPs only (no RFC 1918, loopback, link-local, or metadata IPs), 10s timeout, 5MB cap, mime-sniffed.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"base64":{"type":"string","minLength":1},"mimeType":{"type":"string"},"folder":{"type":"string","enum":["logos","products"]}},"required":["folder"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/list_winbacks":{"post":{"operationId":"list_winbacks","summary":"List active win-back automation configurations.","x-requiredScope":"read","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/create_winback":{"post":{"operationId":"create_winback","summary":"Create a win-back automation. Requires a plan with messaging.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":80},"trigger":{"type":"string","enum":["FAVORITED","ABANDONED_CHECKOUT"]},"enabled":{"type":"boolean"},"waitDays":{"type":"integer","minimum":0,"maximum":30},"discountPercent":{"type":"integer","minimum":5,"maximum":50},"expiryHours":{"type":"integer","minimum":1,"maximum":168},"messageTemplate":{"type":"string","minLength":1,"maxLength":1500},"buttons":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":40},"kind":{"type":"string","enum":["product","shop"]}},"required":["label","kind"],"additionalProperties":false},"maxItems":2}},"required":["title","trigger","enabled","waitDays","discountPercent","expiryHours","messageTemplate","buttons"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}},"/v1/update_winback":{"post":{"operationId":"update_winback","summary":"Replace a win-back automation configuration. Requires a plan with messaging.","x-requiredScope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":80},"trigger":{"type":"string","enum":["FAVORITED","ABANDONED_CHECKOUT"]},"enabled":{"type":"boolean"},"waitDays":{"type":"integer","minimum":0,"maximum":30},"discountPercent":{"type":"integer","minimum":5,"maximum":50},"expiryHours":{"type":"integer","minimum":1,"maximum":168},"messageTemplate":{"type":"string","minLength":1,"maxLength":1500},"buttons":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":40},"kind":{"type":"string","enum":["product","shop"]}},"required":["label","kind"],"additionalProperties":false},"maxItems":2}},"required":["id","title","trigger","enabled","waitDays","discountPercent","expiryHours","messageTemplate","buttons"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Tool completed"},"400":{"description":"Invalid input"},"401":{"description":"Invalid token"},"403":{"description":"Insufficient scope"},"404":{"description":"Unknown tool or missing record"},"429":{"description":"Rate limited"}}}}}}