{"openapi":"3.1.0","info":{"title":"SellerSheet Tool API","version":"2026.10.31.26","description":"Every SellerSheet MCP tool as an HTTP operation. Authenticate with an API key (kind \"api\") from the Dashboard; read /api/v1/guide.md first."},"servers":[{"url":"https://api.sellersheetai.com/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A SellerSheet API key (the Dashboard's \"Your own apps\" card, not shown yet). An MCP key is refused here with 401."}},"schemas":{"Envelope":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{},"human_action":{"type":"string"}}},"Error":{"type":"object","properties":{"notification":{"type":"object"},"error_code":{"type":"string"},"errors":{"type":["array","null"]},"retry_after":{"type":"integer"}}}}},"paths":{"/tools/get_user_context":{"post":{"operationId":"get_user_context","summary":"Get the user's plan, stores, workspace folders, permissions, credits and the skills catalog.","description":"Get the user's plan, stores, workspace folders, permissions, credits and the skills catalog. Call it first in every session; every other tool takes one of its store_refs.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_user_context"},"tags":["sellersheet"],"x-title":"Get User Context","x-access":"read","x-family":null,"x-returns":[{"field":"data.canUseMcp","type":"bool","description":"false when no tool can run — relay data.message, stop."},{"field":"mcp_server_version","description":"changed mid-session → ask the user to reconnect."},{"field":"data.workspace","description":"{org_id, name, slug, role, is_personal, reach} — the key's home"},{"field":"data.workspace.org","description":"pays calls naming no store; the limits and credits below are its. reach 'all': every organization below (a store's calls bill its own);"},{"description":"'org': this one only."},{"field":"data.organizations","description":"[{org_id, name, role, plan, credits_balance, note}] — all of the user's; relay note."},{"field":"data.ownedStoreInfo","description":"stores the user manages; each store carries organization."},{"field":"data.ownedStoreInfo.max_stores","description":"the plan's store cap."},{"field":"data.ownedStoreInfo.number_of_stores_used","description":"stores counted against it."},{"field":"data.ownedStoreInfo.owned_stores","description":"[{store_name, country_code, region_code, seller_id, store_id, store_refs, enabled_marketplaces, available_marketplaces, sync_status, paused_reason, store_auth_time, ads_auth_time, profile_ids, amc}]. amc: AMC per Ads country, {CC: {status: on|creating|failed, instance_id}}; none = off."},{"field":"data.ownedStoreInfo.data.ownedStoreInfo.owned_stores.store_refs","description":"one `<store>-<CC>` per marketplace, passed verbatim; a CC in"},{"description":"available_marketplaces is not activated and is refused — ask which enabled"},{"description":"one to target. sync_status 'paused': the plan no longer covers the store —"},{"description":"reports frozen, every call refused; relay paused_reason, do not retry."},{"field":"data.sharedStoreInfo.shared_stores","description":"granted stores (no sync_status, marketplaces)"},{"field":"data.noonAccountInfo.accounts","description":"[{account_name, noon_account_id, project_code, region_code, marketplaces, store_refs, status, auth_error_code}] — noon tools take one of these store_refs (`<account>-<CC>`) verbatim."},{"field":"data.subscriptionInfo","description":"{plan, max_stores, max_orders, effective_plan, ops, limits, orders}. orders.status 'approaching' or 'over' → tell the user to upgrade at https://sellersheetai.com/billing (refused only when the order gate is on: order_quota_exceeded). limits.concurrent_calls: the in-flight ceiling (null = none; above it concurrency_limit_exceeded + retry_after — run calls in turn)."},{"field":"data.subscriptionInfo.ops.mcp_ops_used / mcp_ops_limit","description":"the Free monthly pool."},{"field":"data.workspace_config","description":"Drive ids — userSettingByFolder {sellerSheetFolderId, storeReportsFolderId, adsReportsFolderId, imagesFolderId, listingsFolderId, shipmentsFolderId, invoicesFolderId}; userSettingBySpreadsheet {salesSpreadsheetId, catalogSpreadsheetId, fbaSpreadsheetId, aplusSpreadsheetId, storeReportsSpreadsheetId, adsReportsSpreadsheetId, fbaInventorySpreadsheetId}; sa_folder_access {folder_id, ok, checked_at, error} (ok: the AI can write there)."},{"field":"data.mcpAccessInfo","description":"{mcp_mode 'open' | 'restricted', mcp_permissions: [{store_id, store_name, marketplace, sp_access, ads_access}]} — effective access ('none' | 'read' | 'write'); a member gets the lower of key and grant."},{"field":"data.credits","description":"{balance, rates, route, routes, topup_url}. Check balance before a paid tool (empty → 402; credits_quote prices a call). rates is the Official card — this workspace pays routes[key = route].rates; quote those or credits_quote, never compute. Only its owner or an admin switches the route (Billing & Credits)."},{"field":"data.skills_catalog","description":"the public skills and their install commands."},{"field":"data.skills_update","description":"{installed, latest, update_available, message, commands} — when update_available is true relay message and ask before running the agent's update command (never auto-update); false → say nothing; null → you passed no version."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"installed_skills_version":{"default":"","title":"Installed Skills Version","type":"string","description":"the `version:` of any installed SellerSheet SKILL.md (one bundle version for all), so data.skills_update is computed here. Omit if you cannot read local files."}},"title":"get_user_contextArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"canUseMcp":{"description":"false when no tool can run — relay data.message, stop."},"workspace":{"description":"{org_id, name, slug, role, is_personal, reach} — the key's home","properties":{"org":{"description":"pays calls naming no store; the limits and credits below are its. reach 'all': every organization below (a store's calls bill its own);"}}},"organizations":{"description":"[{org_id, name, role, plan, credits_balance, note}] — all of the user's; relay note."},"ownedStoreInfo":{"description":"stores the user manages; each store carries organization.","properties":{"max_stores":{"description":"the plan's store cap."},"number_of_stores_used":{"description":"stores counted against it."},"owned_stores":{"description":"[{store_name, country_code, region_code, seller_id, store_id, store_refs, enabled_marketplaces, available_marketplaces, sync_status, paused_reason, store_auth_time, ads_auth_time, profile_ids, amc}]. amc: AMC per Ads country, {CC: {status: on|creating|failed, instance_id}}; none = off."},"data":{"properties":{"ownedStoreInfo":{"properties":{"owned_stores":{"properties":{"store_refs":{"description":"one `<store>-<CC>` per marketplace, passed verbatim; a CC in"}}}}}}}}},"sharedStoreInfo":{"properties":{"shared_stores":{"description":"granted stores (no sync_status, marketplaces)"}}},"noonAccountInfo":{"properties":{"accounts":{"description":"[{account_name, noon_account_id, project_code, region_code, marketplaces, store_refs, status, auth_error_code}] — noon tools take one of these store_refs (`<account>-<CC>`) verbatim."}}},"subscriptionInfo":{"description":"{plan, max_stores, max_orders, effective_plan, ops, limits, orders}. orders.status 'approaching' or 'over' → tell the user to upgrade at https://sellersheetai.com/billing (refused only when the order gate is on: order_quota_exceeded). limits.concurrent_calls: the in-flight ceiling (null = none; above it concurrency_limit_exceeded + retry_after — run calls in turn).","properties":{"ops":{"properties":{"mcp_ops_used":{"description":"the Free monthly pool."}}}}},"workspace_config":{"description":"Drive ids — userSettingByFolder {sellerSheetFolderId, storeReportsFolderId, adsReportsFolderId, imagesFolderId, listingsFolderId, shipmentsFolderId, invoicesFolderId}; userSettingBySpreadsheet {salesSpreadsheetId, catalogSpreadsheetId, fbaSpreadsheetId, aplusSpreadsheetId, storeReportsSpreadsheetId, adsReportsSpreadsheetId, fbaInventorySpreadsheetId}; sa_folder_access {folder_id, ok, checked_at, error} (ok: the AI can write there)."},"mcpAccessInfo":{"description":"{mcp_mode 'open' | 'restricted', mcp_permissions: [{store_id, store_name, marketplace, sp_access, ads_access}]} — effective access ('none' | 'read' | 'write'); a member gets the lower of key and grant."},"credits":{"description":"{balance, rates, route, routes, topup_url}. Check balance before a paid tool (empty → 402; credits_quote prices a call). rates is the Official card — this workspace pays routes[key = route].rates; quote those or credits_quote, never compute. Only its owner or an admin switches the route (Billing & Credits)."},"skills_catalog":{"description":"the public skills and their install commands."},"skills_update":{"description":"{installed, latest, update_available, message, commands} — when update_available is true relay message and ask before running the agent's update command (never auto-update); false → say nothing; null → you passed no version."}}},"human_action":{"type":"string"},"mcp_server_version":{"description":"changed mid-session → ask the user to reconnect."},"mcp_ops_limit":{"description":"the Free monthly pool."}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reports_createReport":{"post":{"operationId":"reports_createReport","summary":"Submit one SP-API report request; returns reportId at once.","description":"Submit one SP-API report request; returns reportId at once. Check reports_getReports first for a recent DONE report to reuse, then poll reports_getReport until processingStatus is DONE. Many report types are already synced into SellerSheet's warehouse — query_report_data answers from it without an Amazon request (list_report_syncs shows which types the store syncs); request a report only for a type or window the warehouse lacks. Amazon SP-API · createReport · POST /reports/2021-06-30/reports","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reports_createReport"},"tags":["amazon_sp"],"x-title":"Create SP-API Report","x-access":"read","x-family":"sp.reports_2021-06-30","x-returns":[{"field":"data.reportId","description":"poll it with reports_getReport."},{"field":"data.processingStatus","description":"always the literal 'IN_QUEUE' — Amazon's createReport carries only reportId; never treat it as a poll result."},{"field":"data.reportType","description":"the normalised constant. data.marketplaceIds: the list used."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"reportType":{"title":"Reporttype","type":"string","description":"the SP-API reportType constant (e.g. 'GET_MERCHANT_LISTINGS_ALL_DATA') or its human-readable name ('All Listings Report'). An open set of 100+ values — pick by intent; reports_getReports shows what already exists for the store."},"dataStartTime":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Datastarttime","description":"ISO 8601 window ('2024-01-01T00:00:00Z'), required for date-range report types; omit for snapshot reports."},"dataEndTime":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Dataendtime","description":"ISO 8601 window ('2024-01-01T00:00:00Z'), required for date-range report types; omit for snapshot reports."},"marketplaceIds":{"anyOf":[{"items":{"type":"string"},"maxItems":25,"type":"array"},{"type":"null"}],"default":null,"title":"Marketplaceids","description":"optional 1–25 marketplaceId strings; omit and the server uses the store's own marketplace — pass a list only to span extra marketplaces."},"reportOptions":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Reportoptions","description":"optional {key: value}, free-form per reportType; the known analytics and vendor types are validated before the call. Brand Analytics SEARCH_TERMS, MARKET_BASKET and REPEAT_PURCHASE require {\"reportPeriod\": DAY | WEEK | MONTH | QUARTER} (REPEAT_PURCHASE: WEEK | MONTH | QUARTER) with aligned dates (WEEK = Sunday to Saturday, MONTH = 1st to last day); SEARCH_QUERY_PERFORMANCE also requires \"asin\"; GET_SALES_AND_TRAFFIC_REPORT takes {\"dateGranularity\": DAY | WEEK | MONTH, \"asinGranularity\": PARENT | CHILD | SKU}; vendor sales and inventory require {\"reportPeriod\", \"distributorView\": MANUFACTURING | SOURCING, \"sellingProgram\": RETAIL | BUSINESS | FRESH}. Omit for reports without options (orders, inventory, listings …)."}},"required":["store","reportType"],"title":"reports_createReportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reportId":{"description":"poll it with reports_getReport."},"processingStatus":{"description":"always the literal 'IN_QUEUE' — Amazon's createReport carries only reportId; never treat it as a poll result."},"reportType":{"description":"the normalised constant. data.marketplaceIds: the list used."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reports_getReport":{"post":{"operationId":"reports_getReport","summary":"Get one report's status; when DONE it returns a presigned download URL (data.documentUrl), never the rows — download and process the file yourself (no inline document, preview or s","description":"Get one report's status; when DONE it returns a presigned download URL (data.documentUrl), never the rows — download and process the file yourself (no inline document, preview or sheet copy), then write only the curated result with write_sheet. Reports take 1–15 minutes depending on type and date range. Amazon SP-API · getReport · GET /reports/2021-06-30/reports/{reportId} Amazon SP-API · getReportDocument · GET /reports/2021-06-30/documents/{reportDocumentId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reports_getReport"},"tags":["amazon_sp"],"x-title":"Get SP-API Report","x-access":"read","x-family":"sp.reports_2021-06-30","x-returns":[{"field":"data.reportId","description":"same as input."},{"field":"data.processingStatus","description":"'IN_QUEUE' | 'IN_PROGRESS' | 'DONE' | 'CANCELLED' | 'FATAL'"},{"field":"data.reportType","description":"SP-API constant for this report."},{"field":"data.reportName","description":"human-readable report name — use it to label output."},{"field":"data.documentUrl","description":"(DONE) presigned S3 URL for the raw document."},{"field":"data.compressionAlgorithm","description":"(DONE) 'GZIP' or null — how documentUrl bytes are compressed."},{"field":"data.urlExpiresInSeconds","description":"(DONE) documentUrl TTL, typically 300."},{"field":"data.error_details","description":"(FATAL/CANCELLED) why Amazon rejected it."}],"x-notes":{"Params (Amazon schema; getReport)":["reportId*: string"],"Params (Amazon schema; getReportDocument)":["reportDocumentId*: string","enableContentEncodingUrlHeader: boolean"],"Gotchas":["data.compressionAlgorithm GZIP means the bytes are raw gzip (the URL forces","    identity encoding) — decompress them yourself.","A body starting with { or [ is a JSON analytics report (Brand Analytics, Sales &","    Traffic) — read its dataBy… arrays; anything else is a tab-separated file with","    a header row. Never read a whole report into context.","The URL expires after data.urlExpiresInSeconds (~300 s); call again for a fresh one.","Without shell or URL access, give the user the link — the server never returns","    report contents."],"Workflow":["1. Read data.processingStatus.","2. DONE: download data.documentUrl yourself and analyze it.","3. IN_QUEUE or IN_PROGRESS: wait 2–5 minutes, then call again.","4. FATAL or CANCELLED: read data.error_details. A FATAL with no error document is","   usually Amazon's regeneration cooldown (an identical report finished recently) —","   reuse the newest DONE report from reports_getReports instead of re-creating it."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"reportId":{"title":"Reportid","type":"string","description":"Amazon report ID returned by reports_createReport or reports_getReports."}},"required":["store","reportId"],"title":"reports_getReportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reportId":{"description":"same as input."},"processingStatus":{"description":"'IN_QUEUE' | 'IN_PROGRESS' | 'DONE' | 'CANCELLED' | 'FATAL'"},"reportType":{"description":"SP-API constant for this report."},"reportName":{"description":"human-readable report name — use it to label output."},"documentUrl":{"description":"(DONE) presigned S3 URL for the raw document."},"compressionAlgorithm":{"description":"(DONE) 'GZIP' or null — how documentUrl bytes are compressed."},"urlExpiresInSeconds":{"description":"(DONE) documentUrl TTL, typically 300."},"error_details":{"description":"(FATAL/CANCELLED) why Amazon rejected it."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reports_getReports":{"post":{"operationId":"reports_getReports","summary":"List the SP-API reports Amazon already holds for the store.","description":"List the SP-API reports Amazon already holds for the store. Call it BEFORE reports_createReport: a recent DONE report (the first entry is the newest) is fetched with reports_getReport and saves the 1–15 minute wait for a new one. Amazon SP-API · getReports · GET /reports/2021-06-30/reports","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reports_getReports"},"tags":["amazon_sp"],"x-title":"Search SP-API Reports","x-access":"read","x-family":"sp.reports_2021-06-30","x-returns":[{"field":"data.count","description":"reports in this page."},{"field":"data.reports","description":"[{reportId (for reports_getReport), reportType, processingStatus, createdTime, dataStartTime, dataEndTime, marketplaceIds, reportScheduleId (when scheduled), reportDocumentId (when DONE)}], newest first."},{"field":"data.nextToken","description":"only when more pages exist — pass it back as nextToken (every other filter is then ignored)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"reportType":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reporttype","description":"one SP-API reportType constant or human-readable name — the one-value shortcut for reportTypes. Amazon requires reportType or reportTypes unless nextToken pages an earlier result."},"reportTypes":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Reporttypes","description":"1–10 constants or names, matched as OR (e.g. ['GET_MERCHANT_LISTINGS_ALL_DATA', 'GET_FBA_INVENTORY_AGED_DATA']) — auditing several types costs ONE call against an endpoint limited to 0.0222 req/s. Wins over reportType when both are given."},"processingStatuses":{"anyOf":[{"items":{"enum":["CANCELLED","DONE","FATAL","IN_PROGRESS","IN_QUEUE"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Processingstatuses","description":"the statuses to keep (e.g. ['DONE']); default all. Allowed: CANCELLED | DONE | FATAL | IN_PROGRESS | IN_QUEUE."},"marketplaceIds":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Marketplaceids","description":"optional marketplaceId strings; omit for the store's own marketplace. Ignored with nextToken."},"createdSince":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Createdsince","description":"ISO 8601 bounds on the report's creation time."},"createdUntil":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Createduntil","description":"ISO 8601 bounds on the report's creation time."},"pageSize":{"default":10,"maximum":100,"minimum":1,"title":"Pagesize","type":"integer","description":"1–100 (default 10)."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"reports_getReportsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"count":{"description":"reports in this page."},"reports":{"description":"[{reportId (for reports_getReport), reportType, processingStatus, createdTime, dataStartTime, dataEndTime, marketplaceIds, reportScheduleId (when scheduled), reportDocumentId (when DONE)}], newest first."},"nextToken":{"description":"only when more pages exist — pass it back as nextToken (every other filter is then ignored)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reports_cancelReport":{"post":{"operationId":"reports_cancelReport","summary":"Cancel a report Amazon has not started yet (processingStatus IN_QUEUE); an IN_PROGRESS report can no longer be cancelled.","description":"Cancel a report Amazon has not started yet (processingStatus IN_QUEUE); an IN_PROGRESS report can no longer be cancelled. Amazon SP-API · cancelReport · DELETE /reports/2021-06-30/reports/{reportId} Use this when reports_createReport was triggered with the wrong type / window and you want to stop it before it takes a rate-limit slot a corrected request needs. Confirm with reports_getReport.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reports_cancelReport"},"tags":["amazon_sp"],"x-title":"Cancel SP-API Report","x-access":"read","x-family":"sp.reports_2021-06-30","x-returns":[{"field":"data.reportId","description":"same as input."},{"field":"data.processingStatus","description":"'CANCELLED' on success."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"reportId":{"title":"Reportid","type":"string","description":"The reportId returned by reports_createReport."}},"required":["store","reportId"],"title":"reports_cancelReportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reportId":{"description":"same as input."},"processingStatus":{"description":"'CANCELLED' on success."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reports_createReportSchedule":{"post":{"operationId":"reports_createReportSchedule","summary":"Set up a recurring Amazon report.","description":"Set up a recurring Amazon report. Replaces re-calling reports_createReport on a cron — Amazon generates one report per period automatically. An Amazon schedule only produces documents you download yourself; for a report type SellerSheet already syncs, query_report_data reads the warehouse instead. Amazon SP-API · createReportSchedule · POST /reports/2021-06-30/schedules Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reports_createReportSchedule"},"tags":["amazon_sp"],"x-title":"Create SP-API Report Schedule","x-access":"write","x-family":"sp.reports_2021-06-30","x-returns":[{"field":"data.reportScheduleId","description":"Amazon schedule ID — track this in your sheet."},{"field":"data.reportType","description":"normalized SP-API constant."},{"field":"data.period","description":"the scheduled period."},{"field":"data.marketplaceIds","description":"the marketplace list actually used (derived from store when you omitted it)."}],"x-notes":{"Gotchas":["A schedule with the same reportType and marketplaceIds replaces the existing one","(Amazon cancels the old schedule)."],"Workflow":["1. Create the schedule (e.g. period P1D for a daily report).","2. reports_getReports with the same reportType lists the reports it produces.","3. reports_getReport downloads each."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"reportType":{"title":"Reporttype","type":"string","description":"SP-API reportType constant (e.g. 'GET_FBA_INVENTORY_AGED_DATA') OR human-readable name. Same value space as reports_createReport. A schedule with the same reportType and marketplaceIds REPLACES (cancels) the existing one."},"period":{"enum":["PT5M","PT15M","PT30M","PT1H","PT2H","PT4H","PT8H","PT12H","P1D","P2D","P3D","PT84H","P7D","P14D","P15D","P18D","P30D","P1M"],"title":"Period","type":"string","description":"how often Amazon generates the report, an ISO 8601 duration. Sub-daily (PT5M…PT12H) is only valid for near-real-time report types; P1D = daily, P7D = weekly, P30D/P1M = monthly. Amazon enforces which subset a given reportType accepts. Allowed: PT5M | PT15M | PT30M | PT1H | PT2H | PT4H | PT8H | PT12H | P1D | P2D | P3D | PT84H | P7D | P14D | P15D | P18D | P30D | P1M."},"marketplaceIds":{"anyOf":[{"items":{"type":"string"},"maxItems":25,"type":"array"},{"type":"null"}],"default":null,"title":"Marketplaceids","description":"OPTIONAL list[str] of Amazon marketplaceId strings, 1–25 entries (e.g. ['A39IBJ37TRP1C6']). Omit to let the server derive the single marketplace from the store's country — supply a list only to schedule against extra marketplaces."},"nextReportCreationTime":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Nextreportcreationtime","description":"optional ISO 8601 datetime (e.g. '2024-01-01T00:00:00Z') — the first scheduled run. Omit to let Amazon pick the next period boundary."},"reportOptions":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Reportoptions","description":"optional dict of report-specific options (same per-type options as reports_createReport; free-form per reportType)."}},"required":["store","reportType","period"],"title":"reports_createReportScheduleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reportScheduleId":{"description":"Amazon schedule ID — track this in your sheet."},"reportType":{"description":"normalized SP-API constant."},"period":{"description":"the scheduled period."},"marketplaceIds":{"description":"the marketplace list actually used (derived from store when you omitted it)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reports_getReportSchedules":{"post":{"operationId":"reports_getReportSchedules","summary":"List active report schedules for one or more reportTypes.","description":"List active report schedules for one or more reportTypes. Amazon SP-API · getReportSchedules · GET /reports/2021-06-30/schedules Amazon REQUIRES at least one reportType filter — there is no \"list all schedules\" endpoint. To audit everything, call once per reportType you've scheduled.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reports_getReportSchedules"},"tags":["amazon_sp"],"x-title":"List SP-API Report Schedules","x-access":"read","x-family":"sp.reports_2021-06-30","x-returns":[{"field":"data.schedules","description":"list[dict], each with reportScheduleId, reportType, period, nextReportCreationTime (ISO 8601), marketplaceIds, reportOptions."},{"field":"data.count","description":"number of schedules found."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"reportTypes":{"items":{},"title":"Reporttypes","type":"array","description":"list[str] of SP-API constants or human names, 1–10 entries, e.g. ['GET_FBA_INVENTORY_AGED_DATA','GET_VENDOR_REAL_TIME_INVENTORY_REPORT']."}},"required":["store","reportTypes"],"title":"reports_getReportSchedulesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"schedules":{"description":"list[dict], each with reportScheduleId, reportType, period, nextReportCreationTime (ISO 8601), marketplaceIds, reportOptions."},"count":{"description":"number of schedules found."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reports_getReportSchedule":{"post":{"operationId":"reports_getReportSchedule","summary":"Fetch one report schedule by its reportScheduleId.","description":"Fetch one report schedule by its reportScheduleId. Returns period, nextReportCreationTime, marketplaceIds, reportOptions. Amazon SP-API · getReportSchedule · GET /reports/2021-06-30/schedules/{reportScheduleId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reports_getReportSchedule"},"tags":["amazon_sp"],"x-title":"Get SP-API Report Schedule","x-access":"read","x-family":"sp.reports_2021-06-30","x-returns":[{"field":"data.schedule","description":"dict with reportScheduleId, reportType, period, nextReportCreationTime (ISO 8601), marketplaceIds, reportOptions."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"reportScheduleId":{"title":"Reportscheduleid","type":"string","description":"id from reports_createReportSchedule or reports_getReportSchedules."}},"required":["store","reportScheduleId"],"title":"reports_getReportScheduleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"schedule":{"description":"dict with reportScheduleId, reportType, period, nextReportCreationTime (ISO 8601), marketplaceIds, reportOptions."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reports_cancelReportSchedule":{"post":{"operationId":"reports_cancelReportSchedule","summary":"Cancel a recurring report schedule.","description":"Cancel a recurring report schedule. After cancellation, no further reports are created for this schedule. Reports already produced remain available. Amazon SP-API · cancelReportSchedule · DELETE /reports/2021-06-30/schedules/{reportScheduleId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reports_cancelReportSchedule"},"tags":["amazon_sp"],"x-title":"Cancel SP-API Report Schedule","x-access":"destructive","x-family":"sp.reports_2021-06-30","x-returns":[{"field":"data.reportScheduleId","description":"same as input."},{"field":"data.cancelled","description":"True on success."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"reportScheduleId":{"title":"Reportscheduleid","type":"string","description":"id to cancel."}},"required":["store","reportScheduleId"],"title":"reports_cancelReportScheduleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reportScheduleId":{"description":"same as input."},"cancelled":{"description":"True on success."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_impex_GetExportCategoryList":{"post":{"operationId":"noon_impex_GetExportCategoryList","summary":"List the noon export categories this account can request, each with its required and optional params — call it before noon_impex_CreateExport.","description":"List the noon export categories this account can request, each with its required and optional params — call it before noon_impex_CreateExport. noon API · ImpexService_GetExportCategoryList · GET /impex/v1/export/category/list Docs: https://noon-docs.noonpartners.dev/docs/api-reference/impex/impex-service-get-export-category-list","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_impex_GetExportCategoryList"},"tags":["noon"],"x-title":"Noon Impex Get Export Category List","x-access":"read","x-family":"noon","x-returns":[{"field":"data.categories","description":"[{code, required[], optional[]}] — pass code as exportCategoryCode and every required name in params."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."}},"required":["store"],"title":"noon_impex_GetExportCategoryListArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"categories":{"description":"[{code, required[], optional[]}] — pass code as exportCategoryCode and every required name in params."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_impex_CreateExport":{"post":{"operationId":"noon_impex_CreateExport","summary":"Start a noon export (a report file) and return its export_code at once; noon builds the file asynchronously.","description":"Start a noon export (a report file) and return its export_code at once; noon builds the file asynchronously. noon API · ImpexService_CreateExport · POST /impex/v1/export/create Docs: https://noon-docs.noonpartners.dev/docs/api-reference/impex/impex-service-create-export","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_impex_CreateExport"},"tags":["noon"],"x-title":"Noon Impex Create Export","x-access":"read","x-family":"noon","x-returns":[{"field":"data.export_code","description":"pass it as exportCode to noon_impex_GetExportStatus."}],"x-notes":{"Workflow":["1. noon_impex_GetExportCategoryList — pick a code and its required params.","2. This tool.","3. noon_impex_GetExportStatus until export_status is COMPLETE, then","   noon_impex_download_export."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"exportCategoryCode":{"title":"Exportcategorycode","type":"string","description":"a code from noon_impex_GetExportCategoryList (a known code the list omits is still sent as-is and noon decides), e.g. 'fbn_inventoryv2_aging' (no params), 'noon_noonoms_ordersexport' (params.from_date + params.to_date), 'noon_catalog_catalogexport' (params.noon_status 'live' or 'not_live')."},"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Params","description":"the category's params (names from noon_impex_GetExportCategoryList). Dates are 'YYYY-MM-DD'. `country` / `country_code` is filled from the store ref (lowercased where noon needs it) and `lang` defaults to 'en' when the category takes them — pass them only to override."}},"required":["store","exportCategoryCode"],"title":"noon_impex_CreateExportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"export_code":{"description":"pass it as exportCode to noon_impex_GetExportStatus."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_impex_GetExportStatus":{"post":{"operationId":"noon_impex_GetExportStatus","summary":"Poll a noon export by its export_code; when it is COMPLETE, call noon_impex_download_export.","description":"Poll a noon export by its export_code; when it is COMPLETE, call noon_impex_download_export. noon API · ImpexService_GetExportStatus · POST /impex/v1/export/status Docs: https://noon-docs.noonpartners.dev/docs/api-reference/impex/impex-service-get-export-status","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_impex_GetExportStatus"},"tags":["noon"],"x-title":"Noon Impex Get Export Status","x-access":"read","x-family":"noon","x-returns":[{"field":"data.export_status","description":"PENDING | QUEUE | RUNNING | COMPLETE | ERROR — poll again every 30–60 s while PENDING, QUEUE or RUNNING; ERROR is final (create a new export)."},{"field":"data.download_url","description":"a public signed URL, present only when COMPLETE."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"exportCode":{"title":"Exportcode","type":"string","description":"data.export_code from noon_impex_CreateExport."}},"required":["store","exportCode"],"title":"noon_impex_GetExportStatusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"export_status":{"description":"PENDING | QUEUE | RUNNING | COMPLETE | ERROR — poll again every 30–60 s while PENDING, QUEUE or RUNNING; ERROR is final (create a new export)."},"download_url":{"description":"a public signed URL, present only when COMPLETE."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_impex_download_export":{"post":{"operationId":"noon_impex_download_export","summary":"Download and parse a COMPLETE noon export; the full file is also saved to the operator's Drive when a reports folder is configured.","description":"Download and parse a COMPLETE noon export; the full file is also saved to the operator's Drive when a reports folder is configured.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_impex_download_export"},"tags":["noon"],"x-title":"Noon Impex Download Export","x-access":"write","x-family":null,"x-returns":[{"field":"data.columns","description":"the CSV header."},{"field":"data.preview","description":"the first 20 rows, each an array aligned to columns — never the full file."},{"field":"data.row_count / data.hasMore","description":"total rows; true when the preview is not the whole file."},{"field":"data.download_url","description":"the full CSV (a public signed URL)."},{"field":"data.drive_url","description":"the Drive copy, only when a reports folder is configured."},{"field":"data.oversize","description":"true when the file is over 5 MB — only its first rows were read, row_count is null and nothing was saved to Drive; fetch download_url for the rest."}],"x-notes":{"Gotchas":["Before COMPLETE the call is refused (HTTP 400 naming the status) — poll","noon_impex_GetExportStatus first."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"exportCode":{"title":"Exportcode","type":"string","description":"data.export_code from noon_impex_CreateExport, once export_status is COMPLETE."}},"required":["store","exportCode"],"title":"noon_impex_download_exportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"columns":{"description":"the CSV header."},"preview":{"description":"the first 20 rows, each an array aligned to columns — never the full file."},"row_count":{"description":"total rows; true when the preview is not the whole file."},"hasMore":{"description":"total rows; true when the preview is not the whole file."},"download_url":{"description":"the full CSV (a public signed URL)."},"drive_url":{"description":"the Drive copy, only when a reports folder is configured."},"oversize":{"description":"true when the file is over 5 MB — only its first rows were read, row_count is null and nothing was saved to Drive; fetch download_url for the rest."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_stock_GetStock":{"post":{"operationId":"noon_stock_GetStock","summary":"Read the stock quantity noon holds for each (warehouse_code, partner_sku) pair — before a restock or reprice; change quantities with noon_stock_UpdateStock.","description":"Read the stock quantity noon holds for each (warehouse_code, partner_sku) pair — before a restock or reprice; change quantities with noon_stock_UpdateStock. noon API · StockService_GetStock · POST /stock/v1/stock-list Docs: https://noon-docs.noonpartners.dev/docs/api-reference/stock/stock-service-get-stock","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_stock_GetStock"},"tags":["noon"],"x-title":"Noon Stock Get Stock","x-access":"read","x-family":"noon","x-returns":[{"field":"data.items[]","description":"one per pair — warehouse_code, partner_sku, qty (the total available stock last pushed to noon), processing_time, stock_updated_at, status {status_code, message} (the per-row result)."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["warehouse_code*: string","partner_sku*: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the pairs to read (required) — warehouse_code, a warehouse_code from noon_warehouse_platform_ListWarehouses, and partner_sku, your own SKU."}},"required":["store"],"title":"noon_stock_GetStockArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"one per pair — warehouse_code, partner_sku, qty (the total available stock last pushed to noon), processing_time, stock_updated_at, status {status_code, message} (the per-row result)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_stock_UpdateStock":{"post":{"operationId":"noon_stock_UpdateStock","summary":"Overwrite the available stock (and optionally processing_time) noon holds per warehouse_code + partner_sku; check each row's status, then re-read with noon_stock_GetStock.","description":"Overwrite the available stock (and optionally processing_time) noon holds per warehouse_code + partner_sku; check each row's status, then re-read with noon_stock_GetStock. noon API · StockService_UpdateStock · POST /stock/v1/stock-update Docs: https://noon-docs.noonpartners.dev/docs/api-reference/stock/stock-service-update-stock Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_stock_UpdateStock"},"tags":["noon"],"x-title":"Noon Stock Update Stock","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.items[]","description":"warehouse_code, partner_sku, status {status_code, message}; rows pass or fail independently."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["warehouse_code*: string","partner_sku*: string","qty: integer","processing_time: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the rows to write (required) — warehouse_code, a warehouse_code from noon_warehouse_platform_ListWarehouses; partner_sku; qty, the new total available stock; processing_time, the new handling time. Blank optional fields are dropped."}},"required":["store"],"title":"noon_stock_UpdateStockArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"warehouse_code, partner_sku, status {status_code, message}; rows pass or fail independently."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_pricing_BatchGetPricing":{"post":{"operationId":"noon_pricing_BatchGetPricing","summary":"Read the current price, msrp and is_active noon holds for a batch of partner SKUs — the authoritative state before repricing, or to confirm an upsert took effect.","description":"Read the current price, msrp and is_active noon holds for a batch of partner SKUs — the authoritative state before repricing, or to confirm an upsert took effect. noon API · PricingService_BatchGetPricing · POST /pricing/v1/pricing/get Docs: https://noon-docs.noonpartners.dev/docs/api-reference/pricing/pricing-service-batch-get-pricing","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_pricing_BatchGetPricing"},"tags":["noon"],"x-title":"Noon Pricing Batch Get Pricing","x-access":"read","x-family":"noon","x-returns":[{"field":"data.items[]","description":"partner_sku, country_code, price, msrp (the crossed-out list price), is_active, status {status_code, message} (the per-row result)."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["partner_sku*: string","country_code*: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the rows to read (required) — partner_sku, your own SKU, and country_code 'ae', 'sa' or 'eg' in any case (the server lowercases it); omit country_code to use the store ref's marketplace."}},"required":["store"],"title":"noon_pricing_BatchGetPricingArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"partner_sku, country_code, price, msrp (the crossed-out list price), is_active, status {status_code, message} (the per-row result)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_pricing_BatchUpsertPricing":{"post":{"operationId":"noon_pricing_BatchUpsertPricing","summary":"Create or update price, msrp and is_active for a batch of partner SKUs; only the fields you pass change.","description":"Create or update price, msrp and is_active for a batch of partner SKUs; only the fields you pass change. Check each row's status, then confirm with noon_pricing_BatchGetPricing. noon API · PricingService_BatchUpsertPricing · POST /pricing/v1/pricing/upsert Docs: https://noon-docs.noonpartners.dev/docs/api-reference/pricing/pricing-service-batch-upsert-pricing Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_pricing_BatchUpsertPricing"},"tags":["noon"],"x-title":"Noon Pricing Batch Upsert Pricing","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.items[]","description":"partner_sku, country_code, status {status_code, message} — the per-row write result; no prices are echoed."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["partner_sku*: string","country_code*: string","price: number","msrp: number","is_active: boolean"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the rows to write (required) — partner_sku; country_code 'ae', 'sa' or 'eg' in any case (the server lowercases it; omit it to use the store ref's marketplace); price, the selling price; msrp, the crossed-out list price; is_active, false stops the item selling on noon. Blank optional fields are dropped."}},"required":["store"],"title":"noon_pricing_BatchUpsertPricingArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"partner_sku, country_code, status {status_code, message} — the per-row write result; no prices are echoed."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_offer_GetProductOffers":{"post":{"operationId":"noon_offer_GetProductOffers","summary":"Get a partner SKU's offers in every country and why any is not buyable — the check to run when a SKU shows live but does not sell (noon_status='live' does not mean purchasable).","description":"Get a partner SKU's offers in every country and why any is not buyable — the check to run when a SKU shows live but does not sell (noon_status='live' does not mean purchasable). noon API · OfferService_GetProductOffers · GET /offer/v1/product/{partner_sku} Docs: https://noon-docs.noonpartners.dev/docs/api-reference/offer/offer-service-get-product-offers","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_offer_GetProductOffers"},"tags":["noon"],"x-title":"Noon Offer Get Product Offers","x-access":"read","x-family":"noon","x-returns":[{"field":"data.offer.offers[]","description":"offer_code, country_code, business_model, price {amount, currency}, is_active (enabled for this business model and country), active_net_stock, live_status (buyable on the storefront right now), offer_issues[] {reason, subreason, description} — the blocker (e.g. price, stock, compliance) on an offer whose live_status is false; empty when the offer is healthy."},{"field":"data.offer.sku / data.offer.title / data.offer.brand","description":"noon's SKU and listing."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"partner_sku":{"title":"Partner Sku","type":"string","description":"your own SKU for the product."}},"required":["store","partner_sku"],"title":"noon_offer_GetProductOffersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"offer":{"properties":{"offers":{"description":"offer_code, country_code, business_model, price {amount, currency}, is_active (enabled for this business model and country), active_net_stock, live_status (buyable on the storefront right now), offer_issues[] {reason, subreason, description} — the blocker (e.g. price, stock, compliance) on an offer whose live_status is false; empty when the offer is healthy."},"sku":{"description":"noon's SKU and listing."},"title":{"description":"noon's SKU and listing."},"brand":{"description":"noon's SKU and listing."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_catalog_BarcodeSkuMap":{"post":{"operationId":"noon_catalog_BarcodeSkuMap","summary":"Map existing partner SKUs to barcodes (UPC/EAN/ISBN) on noon, synchronously, so warehouse systems know what a scanned barcode is; a new barcode is created.","description":"Map existing partner SKUs to barcodes (UPC/EAN/ISBN) on noon, synchronously, so warehouse systems know what a scanned barcode is; a new barcode is created. For a bulk load use noon_catalog_CreateBarcodeImport (async; inline rows or a file). noon API · CatplatService_SkuBarcodeMap · POST /catplat/v1/barcode/map Docs: https://noon-docs.noonpartners.dev/docs/api-reference/catalog/catplat-service-sku-barcode-map Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_catalog_BarcodeSkuMap"},"tags":["noon"],"x-title":"Noon Catalog Barcode SKU Map","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.items[]","description":"barcode, partner_sku, status {status_code, message}; rows succeed or fail independently."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["barcode*: string","partner_sku*: string","force_map: boolean"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the rows to map (required) — barcode and partner_sku (an SKU already in your catalog), each at most 100 characters; force_map true overrides any existing mapping between the same barcode and partner_sku."}},"required":["store"],"title":"noon_catalog_BarcodeSkuMapArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"barcode, partner_sku, status {status_code, message}; rows succeed or fail independently."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_catalog_ChildSkuDelete":{"post":{"operationId":"noon_catalog_ChildSkuDelete","summary":"DELETE child (sellable variant) SKUs from the noon catalog — DESTRUCTIVE, irreversible.","description":"DELETE child (sellable variant) SKUs from the noon catalog — DESTRUCTIVE, irreversible. Use it to retire one size or variation; to remove a whole product and every variation under it, use noon_catalog_ParentSkuDelete (cascades). noon API · CatplatService_ChildSkuDelete · POST /catplat/v1/sku/child/delete Docs: https://noon-docs.noonpartners.dev/docs/api-reference/catalog/catplat-service-child-sku-delete Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_catalog_ChildSkuDelete"},"tags":["noon"],"x-title":"Noon Catalog Child SKU Delete","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.items[]","description":"partner_sku, zsku_child, status {status_code, message}; rows can fail independently."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["partner_sku*: string","zsku_child*: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the rows to delete (required), each with EXACTLY ONE identifier — partner_sku (the child SKU) or zsku_child (noon's child ZSKU). A row with both, or neither, is refused: noon's identifier is a oneof, although the schema below marks both required."}},"required":["store"],"title":"noon_catalog_ChildSkuDeleteArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"partner_sku, zsku_child, status {status_code, message}; rows can fail independently."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_catalog_ParentSkuDelete":{"post":{"operationId":"noon_catalog_ParentSkuDelete","summary":"DELETE parent SKUs from the noon catalog — DESTRUCTIVE and CASCADES: the non-sellable base product and every child SKU under it are removed.","description":"DELETE parent SKUs from the noon catalog — DESTRUCTIVE and CASCADES: the non-sellable base product and every child SKU under it are removed. Use it to remove an entire product; confirm intent first — it is irreversible. noon API · CatplatService_ParentSkuDelete · POST /catplat/v1/sku/parent/delete Docs: https://noon-docs.noonpartners.dev/docs/api-reference/catalog/catplat-service-parent-sku-delete Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_catalog_ParentSkuDelete"},"tags":["noon"],"x-title":"Noon Catalog Parent SKU Delete","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.items[]","description":"parent_partner_sku, zsku_parent, variants[] {partner_sku, zsku_child} removed by the cascade, status {status_code, message}."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["parent_partner_sku*: string","zsku_parent*: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the rows to delete (required), each with EXACTLY ONE identifier — parent_partner_sku (the parent/base SKU) or zsku_parent (noon's parent ZSKU). A row with both, or neither, is refused: noon's identifier is a oneof, although the schema below marks both required."}},"required":["store"],"title":"noon_catalog_ParentSkuDeleteArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"parent_partner_sku, zsku_parent, variants[] {partner_sku, zsku_child} removed by the cascade, status {status_code, message}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_catalog_GenerateImportSignedUrl":{"post":{"operationId":"noon_catalog_GenerateImportSignedUrl","summary":"Get a short-lived GCS signed URL to upload a barcode-import file to noon — step 1 of a file-based import, for more rows than is practical inline (over 10,000; smaller batches go in","description":"Get a short-lived GCS signed URL to upload a barcode-import file to noon — step 1 of a file-based import, for more rows than is practical inline (over 10,000; smaller batches go inline on noon_catalog_CreateBarcodeImport). No SellerSheet tool uploads the file: the operator's own script POSTs it to data.url with data.fields; then create the import with noon_catalog_CreateBarcodeImport. noon API · CatplatService_GenerateImportSignedUrl · POST /catplat/v1/import/generate-import-signed-url Docs: https://noon-docs.noonpartners.dev/docs/api-reference/catalog/catplat-service-generate-import-signed-url","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_catalog_GenerateImportSignedUrl"},"tags":["noon"],"x-title":"Noon Catalog Generate Import Signed URL","x-access":"read","x-family":"noon","x-returns":[{"field":"data.url","description":"the signed POST endpoint."},{"field":"data.fields","description":"the GCS policy form fields to send with the file in a multipart POST."},{"field":"data.identifier","description":"noon's reference for the uploaded file."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"file_type":{"title":"File Type","type":"string","description":"the file's format — a value from the Body block except FILE_TYPE_UNSPECIFIED, which is refused."}},"required":["store","file_type"],"title":"noon_catalog_GenerateImportSignedUrlArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"url":{"description":"the signed POST endpoint."},"fields":{"description":"the GCS policy form fields to send with the file in a multipart POST."},"identifier":{"description":"noon's reference for the uploaded file."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_catalog_CreateBarcodeImport":{"post":{"operationId":"noon_catalog_CreateBarcodeImport","summary":"Create an ASYNCHRONOUS bulk barcode-to-partner_sku import on noon — for mapping barcodes in bulk.","description":"Create an ASYNCHRONOUS bulk barcode-to-partner_sku import on noon — for mapping barcodes in bulk. It returns a reference at once; poll noon_catalog_GetImportStatus for the outcome. Pass EXACTLY ONE data source — file_url, bq_table or items (the schema below marks all three required; noon takes one). noon API · CatplatService_CreateBarcodeImport · POST /catplat/v1/import/barcode Docs: https://noon-docs.noonpartners.dev/docs/api-reference/catalog/catplat-service-create-barcode-import Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_catalog_CreateBarcodeImport"},"tags":["noon"],"x-title":"Noon Catalog Create Barcode Import","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.import_reference","description":"poll it with noon_catalog_GetImportStatus."},{"field":"data.client_reference","description":"your id, echoed."}],"x-notes":{"Body (noon schema)":["file_url*: string","bq_table*: string","items*: {data*: [{partner_sku*, barcode*, force_sync*}]}","config*: {is_notification_required*, force_sync*}","client_reference*: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"file_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"File Url","description":"an HTTP/HTTPS or GCS path to a CSV, TSV, XLSX, JSON or Parquet file (e.g. one uploaded through noon_catalog_GenerateImportSignedUrl)."},"bq_table":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Bq Table","description":"a BigQuery table reference."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"inline rows, at most 10,000 — a plain list of {partner_sku, barcode, force_sync} (the server wraps it in data); partner_sku must already exist in the catalog, force_sync true overrides an existing mapping of that barcode and SKU."},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Config","description":"optional {is_notification_required (default false — a WHIP notification on completion), force_sync (overwrite existing mappings for the whole request)}."},"client_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Client Reference","description":"optional id of your own — unique, at most 100 characters; noon_catalog_GetImportStatus accepts it in place of import_reference."}},"required":["store"],"title":"noon_catalog_CreateBarcodeImportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"import_reference":{"description":"poll it with noon_catalog_GetImportStatus."},"client_reference":{"description":"your id, echoed."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_catalog_GetImportStatus":{"post":{"operationId":"noon_catalog_GetImportStatus","summary":"Poll a noon bulk import until it is final, then read which rows were rejected and why.","description":"Poll a noon bulk import until it is final, then read which rows were rejected and why. noon API · CatplatService_GetImportStatus · GET /catplat/v1/import/status/{reference} Docs: https://noon-docs.noonpartners.dev/docs/api-reference/catalog/catplat-service-get-import-status","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_catalog_GetImportStatus"},"tags":["noon"],"x-title":"Noon Catalog Get Import Status","x-access":"read","x-family":"noon","x-returns":[{"field":"data.import_status","description":"IMPORT_STATUS_PENDING, IMPORT_STATUS_PROCESSING, IMPORT_STATUS_COMPLETED, IMPORT_STATUS_FAILED or IMPORT_STATUS_PARTIAL (noon's model) — keep polling until it is COMPLETED, FAILED or PARTIAL, which are final."},{"field":"data.report.fields.failed_count / data.report.fields.error_summary","description":"the rejected rows and why ([{count, status_message}])."},{"field":"data.report.fields.report_url","description":"GCS link to the full per-row report."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"reference":{"title":"Reference","type":"string","description":"the import_reference from noon_catalog_CreateBarcodeImport, or the client_reference you set on it (required)."}},"required":["store","reference"],"title":"noon_catalog_GetImportStatusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"import_status":{"description":"IMPORT_STATUS_PENDING, IMPORT_STATUS_PROCESSING, IMPORT_STATUS_COMPLETED, IMPORT_STATUS_FAILED or IMPORT_STATUS_PARTIAL (noon's model) — keep polling until it is COMPLETED, FAILED or PARTIAL, which are final."},"report":{"properties":{"fields":{"properties":{"failed_count":{"description":"the rejected rows and why ([{count, status_message}])."},"error_summary":{"description":"the rejected rows and why ([{count, status_message}])."},"report_url":{"description":"GCS link to the full per-row report."}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_warehouse_platform_ListWarehouses":{"post":{"operationId":"noon_warehouse_platform_ListWarehouses","summary":"List the warehouses on the noon partner account, up to 500 per page — to find the warehouse_code the stock tools take.","description":"List the warehouses on the noon partner account, up to 500 per page — to find the warehouse_code the stock tools take. noon API · WarehousePlatformService_ListWarehouses · POST /warehouse-platform/v1/warehouses/list Docs: https://noon-docs.noonpartners.dev/docs/api-reference/warehouse_platform/warehouse-platform-service-list-warehouses","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_warehouse_platform_ListWarehouses"},"tags":["noon"],"x-title":"Noon Warehouse Platform List Warehouses","x-access":"read","x-family":"noon","x-returns":[{"field":"data.warehouses[]","description":"warehouse_code (pass it to the stock tools), display_name, fulfillment_system_code, is_active (usable for fulfillment)."},{"field":"data.next_token","description":"pass it back for the next page; '' on the last page."}],"x-notes":{"Body (noon schema)":["next_token: string","filters: {fulfillment_system_code}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.next_token; omit for the first page."},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Filters","description":"optional {fulfillment_system_code} to restrict to one fulfillment system; keep the same filters on every page of one cursor."}},"required":["store"],"title":"noon_warehouse_platform_ListWarehousesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"warehouses":{"description":"warehouse_code (pass it to the stock tools), display_name, fulfillment_system_code, is_active (usable for fulfillment)."},"next_token":{"description":"pass it back for the next page; '' on the last page."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_xborder_pricing_BatchGetTransferPrice":{"post":{"operationId":"noon_xborder_pricing_BatchGetTransferPrice","summary":"Read the cross-border USD transfer price, MSRP and active state noon holds for up to 1000 partner SKUs — check them before noon_xborder_pricing_BatchUpsertTransferPrice.","description":"Read the cross-border USD transfer price, MSRP and active state noon holds for up to 1000 partner SKUs — check them before noon_xborder_pricing_BatchUpsertTransferPrice. noon API · XborderPricingService_BatchGetTransferPrice · POST /xborder-pricing/v1/transfer-price/get Docs: https://noon-docs.noonpartners.dev/docs/api-reference/xborder-pricing/xborder-pricing-service-batch-get-transfer-price","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_xborder_pricing_BatchGetTransferPrice"},"tags":["noon"],"x-title":"Noon Xborder Pricing Batch Get Transfer Price","x-access":"read","x-family":"noon","x-returns":[{"field":"data.items[]","description":"partner_sku, transfer_price_usd, msrp_usd, is_active, status {status_code, message} (the per-row result)."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["partner_sku*: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the SKUs to read (required), at most 1000 per call."}},"required":["store"],"title":"noon_xborder_pricing_BatchGetTransferPriceArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"partner_sku, transfer_price_usd, msrp_usd, is_active, status {status_code, message} (the per-row result)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_xborder_pricing_BatchUpsertTransferPrice":{"post":{"operationId":"noon_xborder_pricing_BatchUpsertTransferPrice","summary":"Set or change the USD transfer price and MSRP noon uses to list a SKU cross-border, or toggle it active, for a batch of SKUs.","description":"Set or change the USD transfer price and MSRP noon uses to list a SKU cross-border, or toggle it active, for a batch of SKUs. Run noon_xborder_pricing_BatchUpsertProduct first for a brand-new cross-border item (its dimensions and weight must exist). noon API · XborderPricingService_BatchUpsertTransferPrice · POST /xborder-pricing/v1/transfer-price/upsert Docs: https://noon-docs.noonpartners.dev/docs/api-reference/xborder-pricing/xborder-pricing-service-batch-upsert-transfer-price Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_xborder_pricing_BatchUpsertTransferPrice"},"tags":["noon"],"x-title":"Noon Xborder Pricing Batch Upsert Transfer Price","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.items[]","description":"partner_sku, status {status_code, message} — the per-row write result; no prices are echoed."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["partner_sku*: string","transfer_price_usd: number","msrp_usd: number","is_active: boolean"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the rows to write (required), at most 1000 per call — partner_sku plus the fields to set (is_active true = Active, false = Inactive); blank fields are dropped."}},"required":["store"],"title":"noon_xborder_pricing_BatchUpsertTransferPriceArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"partner_sku, status {status_code, message} — the per-row write result; no prices are echoed."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_xborder_pricing_BatchUpsertProduct":{"post":{"operationId":"noon_xborder_pricing_BatchUpsertProduct","summary":"Create or update the cross-border product record noon needs to ship a SKU cross-border (dimensions, weights, HS code) — when onboarding a new cross-border SKU, before its noon_xbor","description":"Create or update the cross-border product record noon needs to ship a SKU cross-border (dimensions, weights, HS code) — when onboarding a new cross-border SKU, before its noon_xborder_pricing_BatchUpsertTransferPrice takes effect, or when its size, weight or HS code changes. noon API · XborderPricingService_BatchUpsertProduct · POST /xborder-pricing/v1/product/upsert Docs: https://noon-docs.noonpartners.dev/docs/api-reference/xborder-pricing/xborder-pricing-service-batch-upsert-product Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_xborder_pricing_BatchUpsertProduct"},"tags":["noon"],"x-title":"Noon Xborder Pricing Batch Upsert Product","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.items[]","description":"partner_sku, status {status_code, message} — the per-row create/update result."}],"x-notes":{"Body (noon schema): {items: [item]}, each item":["partner_sku*: string","dimensions_cm: {length*, width*, height*}","vm_weight_cm: number","actual_weight_kg: number","hs_code: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the rows to write (required), at most 1000 per call — partner_sku plus the fields to set: dimensions in cm (all three when given), vm_weight_cm (the volumetric weight, as noon's schema names it), actual_weight_kg in kg, hs_code (the Harmonized System customs code). Rows are sent as given."}},"required":["store"],"title":"noon_xborder_pricing_BatchUpsertProductArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"partner_sku, status {status_code, message} — the per-row create/update result."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_ListEligibleItems":{"post":{"operationId":"noon_inbound_ListEligibleItems","summary":"List the catalog SKUs noon accepts on an FBN inbound shipment (ASN), with their storage_type — step 1 of an ASN.","description":"List the catalog SKUs noon accepts on an FBN inbound shipment (ASN), with their storage_type — step 1 of an ASN. Only active items with a mapped barcode, a title and an uploaded image are returned. noon API · AsnService_ListEligibleItems · GET /fbn/inbound/v1/catalog/items Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-list-eligible-items","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_ListEligibleItems"},"tags":["noon"],"x-title":"Noon Inbound List Eligible Items","x-access":"read","x-family":"noon","x-returns":[{"field":"data.items[]","description":"partner_sku, sku (noon SKU), title, image_url, storage_type (STORAGE_TYPE_STANDARD, STORAGE_TYPE_OVERSIZE or STORAGE_TYPE_BULKY; STORAGE_TYPE_UNSPECIFIED when not yet classified) — pass storage_type unchanged to noon_inbound_UpdateShipmentItems."},{"field":"data.next_token","description":"'' when there are no more pages."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"partner_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Partner Sku","description":"optional filter by your SKU (partial match; sent as search.partner_sku)."},"page_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"items per page; noon's default 100, max 1000."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.next_token; omit for the first page."}},"required":["store"],"title":"noon_inbound_ListEligibleItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"partner_sku, sku (noon SKU), title, image_url, storage_type (STORAGE_TYPE_STANDARD, STORAGE_TYPE_OVERSIZE or STORAGE_TYPE_BULKY; STORAGE_TYPE_UNSPECIFIED when not yet classified) — pass storage_type unchanged to noon_inbound_UpdateShipmentItems."},"next_token":{"description":"'' when there are no more pages."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_CreateShipment":{"post":{"operationId":"noon_inbound_CreateShipment","summary":"Create an FBN inbound shipment (ASN) header in CREATED status with no items — step 2, after noon_inbound_ListEligibleItems.","description":"Create an FBN inbound shipment (ASN) header in CREATED status with no items — step 2, after noon_inbound_ListEligibleItems. Idempotent: the same exref_nr + shipment_type returns the existing ASN instead of a duplicate. noon API · AsnService_CreateShipment · POST /fbn/inbound/v1/shipment/create Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-create-shipment Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_CreateShipment"},"tags":["noon"],"x-title":"Noon Inbound Create Shipment","x-access":"write","x-family":"noon","x-returns":[{"field":"data.shipment.asn_nr","description":"the new ASN — pass it as asn_nr to noon_inbound_UpdateShipmentItems."},{"field":"data.shipment.status","description":"ASN_STATUS_CREATED (the header shape of noon_inbound_GetShipment)."}],"x-notes":{"Workflow":["1. noon_inbound_UpdateShipmentItems — add the lines.","2. noon_inbound_UpdateShipmentStatus with action SEAL.","3. noon_inbound_GetSlotAvailability, then noon_inbound_ScheduleShipment."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"exref_nr":{"title":"Exref Nr","type":"string","description":"your external reference (e.g. a PO number) — required, unique per shipment_type within the account."},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country Code","description":"the destination country code (e.g. AE, SA); omit it to use the store ref's marketplace."},"shipment_type":{"anyOf":[{"enum":["SHIPMENT_TYPE_UNSPECIFIED","SHIPMENT_TYPE_FBN_GLOBAL"],"type":"string"},{"type":"null"}],"default":null,"title":"Shipment Type","description":"the ASN's shipment type — SHIPMENT_TYPE_FBN_GLOBAL is noon's only usable value, and the one sent when this is omitted. Allowed: SHIPMENT_TYPE_UNSPECIFIED | SHIPMENT_TYPE_FBN_GLOBAL."}},"required":["store","exref_nr"],"title":"noon_inbound_CreateShipmentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipment":{"properties":{"asn_nr":{"description":"the new ASN — pass it as asn_nr to noon_inbound_UpdateShipmentItems."},"status":{"description":"ASN_STATUS_CREATED (the header shape of noon_inbound_GetShipment)."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_UpdateShipmentItems":{"post":{"operationId":"noon_inbound_UpdateShipmentItems","summary":"Add items to, or change quantities on, a CREATED noon ASN — upsert by partner_sku (an existing SKU's qty is overwritten), at most 1000 per call; then SEAL it with noon_inbound_Upda","description":"Add items to, or change quantities on, a CREATED noon ASN — upsert by partner_sku (an existing SKU's qty is overwritten), at most 1000 per call; then SEAL it with noon_inbound_UpdateShipmentStatus. Items cannot change after sealing. noon API · AsnService_UpdateShipmentItems · POST /fbn/inbound/v1/shipment/items/update Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-update-shipment-items Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_UpdateShipmentItems"},"tags":["noon"],"x-title":"Noon Inbound Update Shipment Items","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.shipment","description":"the refreshed ASN header (as noon_inbound_GetShipment) — expected_qty and total_sku_count reflect the upsert; noon returns no per-item status."}],"x-notes":{"Body (noon schema)":["asn_nr*: string","items*: [{partner_sku*, qty*, storage_type*}]","items.storage_type: STORAGE_TYPE_UNSPECIFIED | STORAGE_TYPE_STANDARD | STORAGE_TYPE_OVERSIZE | STORAGE_TYPE_BULKY"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"asn_nr":{"title":"Asn Nr","type":"string","description":"the noon ASN number (from noon_inbound_ListShipments). Right after noon_inbound_CreateShipment it is data.shipment.asn_nr."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"the lines (required) — partner_sku, qty (units) and storage_type: the full value (e.g. STORAGE_TYPE_STANDARD), sent verbatim — copy it from noon_inbound_ListEligibleItems."}},"required":["store","asn_nr"],"title":"noon_inbound_UpdateShipmentItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipment":{"description":"the refreshed ASN header (as noon_inbound_GetShipment) — expected_qty and total_sku_count reflect the upsert; noon returns no per-item status."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_DeleteShipmentItems":{"post":{"operationId":"noon_inbound_DeleteShipmentItems","summary":"Remove items from a CREATED noon ASN, at most 1000 per call — to fix a draft before sealing; to change a quantity use noon_inbound_UpdateShipmentItems.","description":"Remove items from a CREATED noon ASN, at most 1000 per call — to fix a draft before sealing; to change a quantity use noon_inbound_UpdateShipmentItems. Removing every item is allowed (the ASN stays CREATED); nothing can be removed after sealing. noon API · AsnService_DeleteShipmentItems · POST /fbn/inbound/v1/shipment/items/delete Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-delete-shipment-items Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_DeleteShipmentItems"},"tags":["noon"],"x-title":"Noon Inbound Delete Shipment Items","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.shipment","description":"the refreshed ASN header (as noon_inbound_GetShipment) — expected_qty and total_sku_count reflect the removal."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"asn_nr":{"title":"Asn Nr","type":"string","description":"the noon ASN number (from noon_inbound_ListShipments)."},"partner_skus":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Partner Skus","description":"the partner_sku values to remove (required)."}},"required":["store","asn_nr"],"title":"noon_inbound_DeleteShipmentItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipment":{"description":"the refreshed ASN header (as noon_inbound_GetShipment) — expected_qty and total_sku_count reflect the removal."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_ListShipmentItems":{"post":{"operationId":"noon_inbound_ListShipmentItems","summary":"List the items on a noon ASN in any status, with product details (paginated) — to verify a draft or sealed ASN's contents.","description":"List the items on a noon ASN in any status, with product details (paginated) — to verify a draft or sealed ASN's contents. noon API · AsnService_ListShipmentItems · GET /fbn/inbound/v1/shipment/{asn_nr}/items Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-list-shipment-items","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_ListShipmentItems"},"tags":["noon"],"x-title":"Noon Inbound List Shipment Items","x-access":"read","x-family":"noon","x-returns":[{"field":"data.items[]","description":"partner_sku, sku (noon SKU), title, qty, image_url, storage_type."},{"field":"data.total_sku_count","description":"distinct SKUs on the ASN, across all pages."},{"field":"data.next_token","description":"pass it back for the next page; '' on the last page."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"asn_nr":{"title":"Asn Nr","type":"string","description":"the noon ASN number (from noon_inbound_ListShipments)."},"page_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"items per page; noon's default and maximum are 1000."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.next_token; omit for the first page."}},"required":["store","asn_nr"],"title":"noon_inbound_ListShipmentItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"partner_sku, sku (noon SKU), title, qty, image_url, storage_type."},"total_sku_count":{"description":"distinct SKUs on the ASN, across all pages."},"next_token":{"description":"pass it back for the next page; '' on the last page."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_GetShipment":{"post":{"operationId":"noon_inbound_GetShipment","summary":"Get one noon ASN's header (no items) — its lifecycle status and receiving progress, at any time.","description":"Get one noon ASN's header (no items) — its lifecycle status and receiving progress, at any time. noon API · AsnService_GetShipment · GET /fbn/inbound/v1/shipment/{asn_nr} Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-get-shipment","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_GetShipment"},"tags":["noon"],"x-title":"Noon Inbound Get Shipment","x-access":"read","x-family":"noon","x-returns":[{"field":"data.shipment.status","description":"ASN_STATUS_CREATED, ASN_STATUS_SEALED, ASN_STATUS_SCHEDULED, ASN_STATUS_RECEIVING, ASN_STATUS_INBOUNDED, ASN_STATUS_CANCELED or ASN_STATUS_EXPIRED."},{"field":"data.shipment.dst_warehouse_code / schedule_date / schedule_slot / delivery_type","description":"null until scheduled."},{"field":"data.shipment.expected_qty / qty_received / qty_putaway / total_sku_count","description":"planned, received and put-away units; distinct SKUs."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"asn_nr":{"title":"Asn Nr","type":"string","description":"the noon ASN number (from noon_inbound_ListShipments)."}},"required":["store","asn_nr"],"title":"noon_inbound_GetShipmentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipment":{"properties":{"status":{"description":"ASN_STATUS_CREATED, ASN_STATUS_SEALED, ASN_STATUS_SCHEDULED, ASN_STATUS_RECEIVING, ASN_STATUS_INBOUNDED, ASN_STATUS_CANCELED or ASN_STATUS_EXPIRED."},"dst_warehouse_code":{"description":"null until scheduled."},"expected_qty":{"description":"planned, received and put-away units; distinct SKUs."}}}}},"human_action":{"type":"string"},"schedule_date":{"description":"null until scheduled."},"schedule_slot":{"description":"null until scheduled."},"delivery_type":{"description":"null until scheduled."},"qty_received":{"description":"planned, received and put-away units; distinct SKUs."},"qty_putaway":{"description":"planned, received and put-away units; distinct SKUs."},"total_sku_count":{"description":"planned, received and put-away units; distinct SKUs."}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_ListShipments":{"post":{"operationId":"noon_inbound_ListShipments","summary":"List noon ASN headers (no items), optionally by status or destination country — to find a draft or audit history (paginated).","description":"List noon ASN headers (no items), optionally by status or destination country — to find a draft or audit history (paginated). noon API · AsnService_ListShipments · GET /fbn/inbound/v1/shipment/list Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-list-shipments","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_ListShipments"},"tags":["noon"],"x-title":"Noon Inbound List Shipments","x-access":"read","x-family":"noon","x-returns":[{"field":"data.shipments[]","description":"ASN headers, each the shape of noon_inbound_GetShipment's data.shipment."},{"field":"data.total_count","description":"noon's total number of shipments for the account."},{"field":"data.next_token","description":"pass it back for the next page; '' on the last page."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"status":{"anyOf":[{"enum":["ASN_STATUS_UNSPECIFIED","ASN_STATUS_CREATED","ASN_STATUS_SEALED","ASN_STATUS_SCHEDULED","ASN_STATUS_RECEIVING","ASN_STATUS_INBOUNDED","ASN_STATUS_CANCELED","ASN_STATUS_EXPIRED"],"type":"string"},{"type":"null"}],"default":null,"title":"Status","description":"filter by ASN status, sent verbatim as noon's filter.status; omit it to list every status. Allowed: ASN_STATUS_UNSPECIFIED | ASN_STATUS_CREATED | ASN_STATUS_SEALED | ASN_STATUS_SCHEDULED | ASN_STATUS_RECEIVING | ASN_STATUS_INBOUNDED | ASN_STATUS_CANCELED | ASN_STATUS_EXPIRED."},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country Code","description":"filter by destination country (e.g. AE, SA)."},"page_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"shipments per page; noon's default 50, max 200."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.next_token; omit for the first page."}},"required":["store"],"title":"noon_inbound_ListShipmentsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipments":{"description":"ASN headers, each the shape of noon_inbound_GetShipment's data.shipment."},"total_count":{"description":"noon's total number of shipments for the account."},"next_token":{"description":"pass it back for the next page; '' on the last page."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_UpdateShipment":{"post":{"operationId":"noon_inbound_UpdateShipment","summary":"Set free-form metadata (misc, e.g.","description":"Set free-form metadata (misc, e.g. 3PL flags) on a noon ASN in CREATED, SEALED or SCHEDULED status — refused once inbound has started or the ASN is EXPIRED or CANCELED. Not for items (noon_inbound_UpdateShipmentItems) or status (noon_inbound_UpdateShipmentStatus). noon API · AsnService_UpdateShipment · POST /fbn/inbound/v1/shipment/update Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-update-shipment Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_UpdateShipment"},"tags":["noon"],"x-title":"Noon Inbound Update Shipment","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.shipment","description":"the updated ASN header (as noon_inbound_GetShipment)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"asn_nr":{"title":"Asn Nr","type":"string","description":"the noon ASN number (from noon_inbound_ListShipments)."},"misc":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Misc","description":"the metadata object (required); noon has not finalized its schema, so it is a free-form dict."}},"required":["store","asn_nr"],"title":"noon_inbound_UpdateShipmentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipment":{"description":"the updated ASN header (as noon_inbound_GetShipment)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_UpdateShipmentStatus":{"post":{"operationId":"noon_inbound_UpdateShipmentStatus","summary":"Seal, cancel or reschedule a noon ASN.","description":"Seal, cancel or reschedule a noon ASN. SEAL once the items are set, then noon_inbound_GetSlotAvailability and noon_inbound_ScheduleShipment; RESCHEDULE frees a booked slot so it can be booked again; CANCEL aborts. noon API · AsnService_UpdateShipmentStatus · POST /fbn/inbound/v1/shipment/status/update Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-update-shipment-status Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_UpdateShipmentStatus"},"tags":["noon"],"x-title":"Noon Inbound Update Shipment Status","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.shipment.status","description":"the new status."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"asn_nr":{"title":"Asn Nr","type":"string","description":"the noon ASN number (from noon_inbound_ListShipments)."},"action":{"title":"Action","type":"string","description":"SEAL, CANCEL or RESCHEDULE — any case, the STATUS_ACTION_ prefix optional; STATUS_ACTION_UNSPECIFIED is refused. SEAL finalizes a draft with at least one item (CREATED -> SEALED); CANCEL works from CREATED, SEALED or SCHEDULED (-> CANCELED); RESCHEDULE moves a SCHEDULED ASN back to SEALED."}},"required":["store","asn_nr","action"],"title":"noon_inbound_UpdateShipmentStatusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipment":{"properties":{"status":{"description":"the new status."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_GetSlotAvailability":{"post":{"operationId":"noon_inbound_GetSlotAvailability","summary":"Get the destination warehouses and check-in days / time slots open to a SEALED noon ASN — after sealing it with noon_inbound_UpdateShipmentStatus, before noon_inbound_ScheduleShipm","description":"Get the destination warehouses and check-in days / time slots open to a SEALED noon ASN — after sealing it with noon_inbound_UpdateShipmentStatus, before noon_inbound_ScheduleShipment. Only future dates with remaining capacity are returned. noon API · AsnService_GetSlotAvailability · GET /fbn/inbound/v1/shipment/{asn_nr}/schedule/slot_availability Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-get-slot-availability","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_GetSlotAvailability"},"tags":["noon"],"x-title":"Noon Inbound Get Slot Availability","x-access":"read","x-family":"noon","x-returns":[{"field":"data.warehouses[]","description":"at most 100 — warehouse {warehouse_code, name, address, city, location}, days[] (at most 30) {date YYYY-MM-DD, slots[] (at most 8) {start, end} as HH:MM}; pass warehouse_code, one date and one slot to noon_inbound_ScheduleShipment."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"asn_nr":{"title":"Asn Nr","type":"string","description":"the noon ASN number (from noon_inbound_ListShipments)."}},"required":["store","asn_nr"],"title":"noon_inbound_GetSlotAvailabilityArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"warehouses":{"description":"at most 100 — warehouse {warehouse_code, name, address, city, location}, days[] (at most 30) {date YYYY-MM-DD, slots[] (at most 8) {start, end} as HH:MM}; pass warehouse_code, one date and one slot to noon_inbound_ScheduleShipment."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_inbound_ScheduleShipment":{"post":{"operationId":"noon_inbound_ScheduleShipment","summary":"Book a SEALED noon ASN for inbound delivery at a warehouse, date and time slot from noon_inbound_GetSlotAvailability — the final step; it also assigns the destination warehouse (SE","description":"Book a SEALED noon ASN for inbound delivery at a warehouse, date and time slot from noon_inbound_GetSlotAvailability — the final step; it also assigns the destination warehouse (SEALED -> SCHEDULED). Refused when the warehouse is ineligible, the slot is gone or the date is past. noon API · AsnService_ScheduleShipment · POST /fbn/inbound/v1/shipment/schedule Docs: https://noon-docs.noonpartners.dev/docs/api-reference/inbound/asn-service-schedule-shipment Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_inbound_ScheduleShipment"},"tags":["noon"],"x-title":"Noon Inbound Schedule Shipment","x-access":"write","x-family":"noon","x-returns":[{"field":"data.shipment","description":"now ASN_STATUS_SCHEDULED, with dst_warehouse_code, schedule_date and schedule_slot set."}],"x-notes":{"Body (noon schema)":["asn_nr*: string","dst_warehouse_code*: string","schedule_date*: string","schedule_slot*: {start*, end*}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"asn_nr":{"title":"Asn Nr","type":"string","description":"the noon ASN number (from noon_inbound_ListShipments)."},"dst_warehouse_code":{"title":"Dst Warehouse Code","type":"string","description":"a warehouse_code from noon_inbound_GetSlotAvailability (required)."},"schedule_date":{"title":"Schedule Date","type":"string","description":"one of that warehouse's dates, 'YYYY-MM-DD' (required)."},"schedule_slot":{"additionalProperties":true,"title":"Schedule Slot","type":"object","description":"one of that day's slots, {start: 'HH:MM', end: 'HH:MM'} (required)."}},"required":["store","asn_nr","dst_warehouse_code","schedule_date","schedule_slot"],"title":"noon_inbound_ScheduleShipmentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipment":{"description":"now ASN_STATUS_SCHEDULED, with dst_warehouse_code, schedule_date and schedule_slot set."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_returns_ListReturnReferences":{"post":{"operationId":"noon_returns_ListReturnReferences","summary":"Look up the purchased items being returned that match a scanned barcode, across the merchants you can access, with every barcode reference on each — when a return arrives and you n","description":"Look up the purchased items being returned that match a scanned barcode, across the merchants you can access, with every barcode reference on each — when a return arrives and you need the SKU and purchase it belongs to. noon API · ReturnReferenceService_ListReturnReferences · POST /returns/v1/return-references/list Docs: https://noon-docs.noonpartners.dev/docs/api-reference/returns/return-reference-service-list-return-references","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_returns_ListReturnReferences"},"tags":["noon"],"x-title":"Noon Returns List Return References","x-access":"read","x-family":"noon","x-returns":[{"field":"data.items[]","description":"at most 200 — mp_code (marketplace), purchase_item_nr (the purchased item being returned), partner_sku, merchant_code, references[] {barcode, barcode_type: awb_nr or rms_barcode}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"barcode":{"title":"Barcode","type":"string","description":"the barcode to look up (required)."},"merchant_codes":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Merchant Codes","description":"optional merchant codes to scope the search to (at most 200, ones you can access); omit it to scope to the account's default project."}},"required":["store","barcode"],"title":"noon_returns_ListReturnReferencesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"at most 200 — mp_code (marketplace), purchase_item_nr (the purchased item being returned), partner_sku, merchant_code, references[] {barcode, barcode_type: awb_nr or rms_barcode}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_content_ListCategories":{"post":{"operationId":"noon_content_ListCategories","summary":"List every product category code in the noon catalog — to choose a new product's category before creating it; then read its fields with noon_content_ListCategoryAttributes.","description":"List every product category code in the noon catalog — to choose a new product's category before creating it; then read its fields with noon_content_ListCategoryAttributes. noon API · ContentService_ListCategories · POST /content/v1/categories/list Docs: https://noon-docs.noonpartners.dev/docs/api-reference/content/content-service-list-categories","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_content_ListCategories"},"tags":["noon"],"x-title":"Noon Content List Categories","x-access":"read","x-family":"noon","x-returns":[{"field":"data.categories","description":"unique codes, each the full path 'family-type-subtype' of a product type — pass one as category to noon_content_UpsertProduct and as category_code to noon_content_ListCategoryAttributes."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Filters","description":"optional dict sent verbatim as the request body — noon documents no filter fields, so omit it for the full list."}},"required":["store"],"title":"noon_content_ListCategoriesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"categories":{"description":"unique codes, each the full path 'family-type-subtype' of a product type — pass one as category to noon_content_UpsertProduct and as category_code to noon_content_ListCategoryAttributes."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_content_ListCategoryAttributes":{"post":{"operationId":"noon_content_ListCategoryAttributes","summary":"Get the attribute schema a product in one category must satisfy — read it before building the attributes of noon_content_UpsertProduct: every is_mandatory attribute needs a value m","description":"Get the attribute schema a product in one category must satisfy — read it before building the attributes of noon_content_UpsertProduct: every is_mandatory attribute needs a value matching its attribute_type and allowed values. noon API · ContentService_ListCategoryAttributes · POST /content/v1/categories/attributes/list Docs: https://noon-docs.noonpartners.dev/docs/api-reference/content/content-service-list-category-attributes","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_content_ListCategoryAttributes"},"tags":["noon"],"x-title":"Noon Content List Category Attributes","x-access":"read","x-family":"noon","x-returns":[{"field":"data.attributes[]","description":"attribute_code, is_mandatory, attribute_type (ATTRIBUTE_TYPE_TEXT, _SELECT, _NUMERIC, _METRIC, _BOOL, _DATETIME, _FILE or _JSONDICT), is_localizable (one value per language), is_multivalued / max_values, min_characters / max_characters, attribute_options (the allowed SELECT values), attribute_metric_units (the allowed METRIC units); the other validation limits (number_min / number_max, date_min / date_max, size in kilobytes, allowed_mimetypes, additional_validation_regex) as noon returns them."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"category_code":{"title":"Category Code","type":"string","description":"a category code from noon_content_ListCategories (required)."}},"required":["store","category_code"],"title":"noon_content_ListCategoryAttributesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"attributes":{"description":"attribute_code, is_mandatory, attribute_type (ATTRIBUTE_TYPE_TEXT, _SELECT, _NUMERIC, _METRIC, _BOOL, _DATETIME, _FILE or _JSONDICT), is_localizable (one value per language), is_multivalued / max_values, min_characters / max_characters, attribute_options (the allowed SELECT values), attribute_metric_units (the allowed METRIC units); the other validation limits (number_min / number_max, date_min / date_max, size in kilobytes, allowed_mimetypes, additional_validation_regex) as noon returns them."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_content_GetContent":{"post":{"operationId":"noon_content_GetContent","summary":"Fetch a noon product's stored content, images and per-language completeness / QC status — to check whether a listing is complete and approved.","description":"Fetch a noon product's stored content, images and per-language completeness / QC status — to check whether a listing is complete and approved. It is active only when completeness is 100 and QC is QC_STATUS_APPROVED. noon API · ContentService_GetContent · POST /content/v1/product/content/get Docs: https://noon-docs.noonpartners.dev/docs/api-reference/content/content-service-get-content","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_content_GetContent"},"tags":["noon"],"x-title":"Noon Content Get Content","x-access":"read","x-family":"noon","x-returns":[{"field":"data.attributes","description":"the stored content, attribute_code -> {values: [{value, language, sort}]}."},{"field":"data.images[]","description":"url, sort, visibility, review_status (REVIEW_STATUS_VALID, _PENDING or _INVALID), issues[] {code, message}."},{"field":"data.statuses[]","description":"per language (LANGUAGE_EN or LANGUAGE_AR) — content {completeness '0'–'100', missing_attributes, invalid_attributes}; qc {status QC_STATUS_NOT_ELIGIBLE, QC_STATUS_PENDING, QC_STATUS_APPROVED or QC_STATUS_REJECTED, rejection_reasons, comment}; overall_status OVERALL_STATUS_ACTIVE or OVERALL_STATUS_INACTIVE; errors[] {code, message}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"sku_parent":{"title":"Sku Parent","type":"string","description":"the sku_parent noon_content_UpsertProduct returned (required)."}},"required":["store","sku_parent"],"title":"noon_content_GetContentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"attributes":{"description":"the stored content, attribute_code -> {values: [{value, language, sort}]}."},"images":{"description":"url, sort, visibility, review_status (REVIEW_STATUS_VALID, _PENDING or _INVALID), issues[] {code, message}."},"statuses":{"description":"per language (LANGUAGE_EN or LANGUAGE_AR) — content {completeness '0'–'100', missing_attributes, invalid_attributes}; qc {status QC_STATUS_NOT_ELIGIBLE, QC_STATUS_PENDING, QC_STATUS_APPROVED or QC_STATUS_REJECTED, rejection_reasons, comment}; overall_status OVERALL_STATUS_ACTIVE or OVERALL_STATUS_INACTIVE; errors[] {code, message}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_content_UpsertProduct":{"post":{"operationId":"noon_content_UpsertProduct","summary":"Create or update a product listing on noon — new partner_skus create a product, known ones update the product they belong to.","description":"Create or update a product listing on noon — new partner_skus create a product, known ones update the product they belong to. Read noon_content_ListCategoryAttributes for the category first; save data.sku_parent and poll noon_content_GetContent until completeness reaches 100. noon API · ContentService_UpsertProduct · POST /content/v1/product/upsert Docs: https://noon-docs.noonpartners.dev/docs/api-reference/content/content-service-upsert-product Gate: approve — interactive: show the change (noon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_content_UpsertProduct"},"tags":["noon"],"x-title":"Noon Content Upsert Product","x-access":"destructive","x-family":"noon","x-returns":[{"field":"data.sku_parent","description":"the product's id — save it; noon_content_GetContent takes it."},{"field":"data.variants[]","description":"every variant of the product (also those not sent) — sku, partner_sku, psku_code, size."},{"field":"data.status","description":"{status_code, message}."}],"x-notes":{"Body (noon schema)":["skus*: [{partner_sku*, size}]","brand*: string","category*: string","images*: [{url*, sort*}]","attributes*: object"],"Gotchas":["noon refuses an unknown attribute or a value outside its options as an error naming","it. A missing is_mandatory attribute is NOT refused: noon saves the product and lists","it in noon_content_GetContent's missing_attributes once it has processed the content."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"skus":{"items":{},"title":"Skus","type":"array","description":"the variations (required, non-empty) — partner_sku, unique across all your products, and size, required when there is more than one SKU (e.g. 'Large', '42', 'S'); on update every SKU must belong to the same parent product."},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Brand","description":"the product's brand name."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Category","description":"a category code from noon_content_ListCategories."},"images":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Images","description":"optional [{url (a direct public URL), sort (1-based slot)}] — each sort is a slot: an image replaces that slot, a slot you leave out keeps noon's image."},"attributes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Attributes","description":"optional attribute_code -> {values: [{value, language, sort}]} — language is noon's English or Arabic language value, as noon_content_GetContent lists it (one value per language on a localizable attribute), sort orders a multivalued list; a METRIC attribute travels with its '<code>_unit' attribute in the same call. An attribute you leave out keeps its value on noon — nothing is removed. A number may be sent as text."}},"required":["store","skus"],"title":"noon_content_UpsertProductArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sku_parent":{"description":"the product's id — save it; noon_content_GetContent takes it."},"variants":{"description":"every variant of the product (also those not sent) — sku, partner_sku, psku_code, size."},"status":{"description":"{status_code, message}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_content_prepare_publish_queue_template":{"post":{"operationId":"noon_content_prepare_publish_queue_template","summary":"Build the ordered column spec for a noon Publish Queue sheet by merging noon's attribute schema for every category the sheet holds — call it before writing or extending the sheet.","description":"Build the ordered column spec for a noon Publish Queue sheet by merging noon's attribute schema for every category the sheet holds — call it before writing or extending the sheet. Category is per family (a column), not sheet-wide, so pass every distinct category code.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_content_prepare_publish_queue_template"},"tags":["noon"],"x-title":"Noon Content Prepare Publish Queue Template","x-access":"read","x-family":null,"x-returns":[{"field":"data.category_codes","description":"every code merged, in request order; data.category_code: the same codes comma-joined."},{"field":"data.language / data.image_columns","description":"as requested."},{"field":"data.columns","description":"[{key (row 5), name (row 6), guide (row 4), required (gold name), tier formula | identity | mandatory | facet | optional, type TEXT | SELECT | NUMERIC | METRIC | UNIT | BOOL | DATETIME | FILE | JSONDICT | null, language 'en' | 'ar' | null, attribute_code, options, units, multivalued, max_values, min_characters, max_characters, categories (codes the column belongs to — empty = every family), mandatory_for (codes that require it)}]."}],"x-notes":{"Gotchas":["The sheet is the Amazon Publish Queue's layout: row 1 banner, row 2 labels Store ✎ |","Language ✎ | Last Result, row 3 their values, row 4 guides, row 5 keys (hidden), row 6","names, rows 7+ one row per SKU. Columns A–F are imagePreview, Partner SKU, Parent Group","Key, Parent Child Variation, Size Variation, Category Code (noon's own bulk-template","trio for variations); Brand, images and attributes follow. A row-5 key is","`<attribute_code>[_en|_ar][#*]`: `_en`/`_ar` = the value's language, `#*` = several","values in one cell, one per line (line order = sort); `main_image_url` /","`image_url_<n>` = image slot n. Rows sharing a Parent Group Key are one product, each","row one size with its own Partner SKU and Size Variation; the row marked Parent holds","the product details (category, brand, images, attributes), Child rows only add sizes. A","product without sizes is one row with the trio blank."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"category_code":{"default":"","title":"Category Code","type":"string","description":"a single code (legacy) — only when you have exactly one and no list."},"language":{"default":"en","title":"Language","type":"string","description":"'en' (default) | 'en_ar' — the latter emits paired _en/_ar columns for every localizable attribute."},"image_columns":{"default":8,"title":"Image Columns","type":"integer","description":"main_image_url + image_url_2..N (default 8)."},"category_codes":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Category Codes","description":"all distinct category codes on the sheet, one per product family (from noon_content_ListCategories); preferred over category_code and wins when both are given. One of the two is required."}},"required":["store"],"title":"noon_content_prepare_publish_queue_templateArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"category_codes":{"description":"every code merged, in request order; data.category_code: the same codes comma-joined."},"language":{"description":"as requested."},"image_columns":{"description":"as requested."},"columns":{"description":"[{key (row 5), name (row 6), guide (row 4), required (gold name), tier formula | identity | mandatory | facet | optional, type TEXT | SELECT | NUMERIC | METRIC | UNIT | BOOL | DATETIME | FILE | JSONDICT | null, language 'en' | 'ar' | null, attribute_code, options, units, multivalued, max_values, min_characters, max_characters, categories (codes the column belongs to — empty = every family), mandatory_for (codes that require it)}]."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_content_load_publish_queue_content":{"post":{"operationId":"noon_content_load_publish_queue_content","summary":"Load an existing noon product into a noon Publish Queue sheet for editing — one GetContent shaped onto the sheet's row-5 keys, with the columns the sheet still lacks and the produc","description":"Load an existing noon product into a noon Publish Queue sheet for editing — one GetContent shaped onto the sheet's row-5 keys, with the columns the sheet still lacks and the product's category. Write data.cells by key, append data.new_columns at the right end, then change the product with noon_content_UpsertProduct. noon returns no child SKUs.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_content_load_publish_queue_content"},"tags":["noon"],"x-title":"Noon Content Load Publish Queue Content","x-access":"read","x-family":null,"x-returns":[{"field":"data.cells","description":"{row-5 key: cell text} — several values one per line, images by slot."},{"field":"data.new_columns","description":"[{key, name, guide, attribute_code, language, multivalued}] — attributes noon holds that the sheet has no column for."},{"field":"data.category_code","description":"the product's category, derived from noon's own data ('' when noon's data is incomplete)."},{"field":"data.content","description":"GetContent's response — sku_parent, attributes, images, statuses."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim."},"sku_parent":{"title":"Sku Parent","type":"string","description":"the product's noon id (Z…), the sheet's Parent Group Key (required)."},"keys":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Keys","description":"the sheet's row-5 keys in column order (read_sheet row 5); omitted = every attribute comes back as a new column."},"language":{"default":"en","title":"Language","type":"string","description":"the sheet's Language cell — 'en' or 'en_ar'; a new localizable column gets `_en` only, or `_en` and `_ar`."}},"required":["store","sku_parent"],"title":"noon_content_load_publish_queue_contentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"cells":{"description":"{row-5 key: cell text} — several values one per line, images by slot."},"new_columns":{"description":"[{key, name, guide, attribute_code, language, multivalued}] — attributes noon holds that the sheet has no column for."},"category_code":{"description":"the product's category, derived from noon's own data ('' when noon's data is incomplete)."},"content":{"description":"GetContent's response — sku_parent, attributes, images, statuses."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/noon_content_draft_from_amazon_asin":{"post":{"operationId":"noon_content_draft_from_amazon_asin","summary":"Turn one of your Amazon listings into a noon listing draft in SellerSheet.","description":"Turn one of your Amazon listings into a noon listing draft in SellerSheet. The draft holds the product of the listing's colour with every size, a ranked noon category, Amazon's English (and Arabic) copy, its images and the attributes that map exactly. Nothing is sent to noon and no AI runs (free). Review the draft with the user; create a new listing from data.drafts[].upsert with noon_content_UpsertProduct, or on the SellerSheet web app. A draft whose partner SKU already exists on noon (its existing list: live or not, or held by SellerSheet) gets no upsert: sending its fields would UPDATE that listing — only on the user's explicit word. Drafts after the third come back as summaries: open them on the SellerSheet web app (noon Catalog → Drafts) — converting the same colour again makes another draft. noon API · ContentService_ListCategories · POST /content/v1/categories/list noon API · ContentService_ListCategoryAttributes · POST /content/v1/categories/attributes/list Amazon SP-API · getCatalogItem · GET /catalog/2022-04-01/items/{asin} Amazon SP-API · searchCatalogItems · GET /catalog/2022-04-01/items Docs: https://noon-docs.noonpartners.dev/docs/api-reference/content/content-service-list-categories Docs: https://noon-docs.noonpartners.dev/docs/api-reference/content/content-service-list-category-attributes","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/noon_content_draft_from_amazon_asin"},"tags":["noon"],"x-title":"Noon Content Draft From Amazon ASIN","x-access":"write","x-family":"noon","x-returns":[{"field":"data.draft_id","description":"the draft of the listing's colour (the first when several were made)."},{"field":"data.drafts[]","description":"one per colour drafted. The first 3 in full — draft_id, group (the colour), partner_skus, category, existing (partner SKUs that already exist on noon), asins, alternatives [{code, score}] (the next best noon categories), skus [{partner_sku, size}] (partner_sku = your Amazon SKU, blank for an ASIN you do not list), notes (what to check), missing_required (category attributes still empty) and upsert (the UpsertProduct body) — or, when upsert is null, attributes {row-5"},{"field":"data.drafts[].key","description":"value}, copy {en, ar} and images [{url, sort}] instead. Every further draft"},{"description":"only as {draft_id, group, partner_skus, category, existing}; data.summarised counts"},{"description":"them."},{"field":"data.family","description":"the Amazon family's ASINs that were read; data.groups: its colour count."},{"field":"data.facts","description":"only with include_facts."}],"x-notes":{"Params (Amazon schema; getCatalogItem)":["asin*: string","marketplaceIds*: [string]","includedData: attributes | classifications | dimensions | identifiers | images | productTypes | relationships | salesRanks | summaries | vendorDetails (list)","locale: string"],"Params (Amazon schema; searchCatalogItems)":["identifiers: [string] (max 20)","identifiersType: ASIN | EAN | GTIN | ISBN | JAN | MINSAN | SKU | UPC","marketplaceIds*: [string] (max 1)","includedData: attributes | classifications | dimensions | identifiers | images | productTypes | relationships | salesRanks | summaries | vendorDetails (list)","locale: string","sellerId: string","keywords: [string] (max 20)","brandNames: [string]","classificationIds: [string]","pageSize: integer (max 20)","pageToken: string","keywordsLocale: string"],"Body (Amazon schema; ContentService_ListCategoryAttributes)":["category_code*: string"],"Gotchas":["upsert is also null while a partner SKU, a size or the category is missing."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the noon account ref `<account>-<CC>` (name-country, e.g. 'myNoon-AE') — one of get_user_context's noon store_refs, verbatim. Its marketplace is the draft's noon marketplace; owner or admin of the organization only."},"amazon_store":{"title":"Amazon Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. The Amazon store the listing is on."},"asin":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Asin","description":"the ASIN (e.g. 'B0XXXXXXXX'). The Amazon listing — pass it or seller_sku, not both; a variation parent ASIN drafts every colour of its family."},"seller_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Sku","description":"your Amazon seller SKU of the listing, instead of asin."},"include_facts":{"default":false,"title":"Include Facts","type":"boolean","description":"true adds data.facts — Amazon's trimmed attributes of the first draft, the evidence for filling the category's other attributes. Default false."}},"required":["store","amazon_store"],"title":"noon_content_draft_from_amazon_asinArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"draft_id":{"description":"the draft of the listing's colour (the first when several were made)."},"drafts":{"description":"one per colour drafted. The first 3 in full — draft_id, group (the colour), partner_skus, category, existing (partner SKUs that already exist on noon), asins, alternatives [{code, score}] (the next best noon categories), skus [{partner_sku, size}] (partner_sku = your Amazon SKU, blank for an ASIN you do not list), notes (what to check), missing_required (category attributes still empty) and upsert (the UpsertProduct body) — or, when upsert is null, attributes {row-5","items":{"properties":{"key":{"description":"value}, copy {en, ar} and images [{url, sort}] instead. Every further draft"}}}},"family":{"description":"the Amazon family's ASINs that were read; data.groups: its colour count."},"facts":{"description":"only with include_facts."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/read_sheet":{"post":{"operationId":"read_sheet","summary":"Read cell values from a range.","description":"Read cell values from a range. To get the formulas, formats, notes and links of a few cells in one call, use get_sheet_cell.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/read_sheet"},"tags":["google_workspace"],"x-title":"Read Sheet","x-access":"read","x-family":null,"x-returns":[{"field":"values","description":"the rows, at the top level (not under data). Google leaves out trailing empty rows and cells, so pad a short row before you map columns by position."},{"field":"rowCount","description":"the number of rows returned, up to the last non-empty row (not the height of the range)."}],"x-notes":{"Gotchas":["The spreadsheet must be shared with SellerSheet's Google service account as Editor","(workbooks set up by the SellerSheet sidebar already are); a permission error means","the user has to share it."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation, e.g. 'Store Reports!A1:I100'. For tab names with hyphens / spaces / parens (e.g. 'STA-BoxFirst!A1'), pass the bare name — the MCP layer single-quotes it internally where the Google Sheets API requires (otherwise the API parses 'STA-BoxFirst' as a subtraction and returns 400 once the tab has formula content)."},"value_render_option":{"default":"FORMATTED_VALUE","title":"Value Render Option","type":"string","description":"How to render cell values. Default: 'FORMATTED_VALUE'. 'FORMATTED_VALUE' — display values (what users see). Default. 'FORMULA' — raw formulas, e.g. '=IMAGE(\"url\")' or '=SUM(A1:A10)'. Use this to read URLs from =IMAGE() formula cells. 'UNFORMATTED_VALUE' — raw numbers/dates without formatting. Note: =IMAGE() cells read back as '' under the default FORMATTED_VALUE (the image has no display text) — pass value_render_option='FORMULA' to see the underlying URL. Note: written datetimes read back as the sheet's DISPLAYED format (locale-dependent) under FORMATTED_VALUE — use 'UNFORMATTED_VALUE' to get the raw date serial for math/sorting."}},"required":["spreadsheet_id","range_"],"title":"read_sheetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"description":"the rows, at the top level (not under data). Google leaves out trailing empty rows and cells, so pad a short row before you map columns by position."},"rowCount":{"description":"the number of rows returned, up to the last non-empty row (not the height of the range)."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/write_sheet":{"post":{"operationId":"write_sheet","summary":"Write a 2D block of values to a range; every cell is parsed as if typed (USER_ENTERED).","description":"Write a 2D block of values to a range; every cell is parsed as if typed (USER_ENTERED). Use it for any block whose cells differ — mixed values and formulas, or a full table. To fill ONE formula down a bounded range (relative references shift per row), write_sheet_formula does it in one call.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/write_sheet"},"tags":["google_workspace"],"x-title":"Write Sheet","x-access":"destructive","x-family":null,"x-returns":[{"field":"written","description":"the number of rows written (top level, not under data)."}],"x-notes":{"Gotchas":["How Sheets parses a string cell (USER_ENTERED):","  - \"=SUM(B:B)\"           → a live formula","  - \"2026-05-12\"          → date serial (sortable, DATEVALUE-able)","  - \"2026-05-12 14:30:00\" → datetime serial","  - \"1234.56\"             → number 1234.56","  - \"15%\"                 → 0.15 with percent display","  - \"Plain text\"          → string (unchanged)","  - \"'=literal text\"      → literal string (apostrophe escapes the leading =)","  - \"'07023\"              → string \"07023\" with the leading zero kept","The spreadsheet must be shared with SellerSheet's Google service account as Editor","(workbooks set up by the SellerSheet sidebar already are); a permission error means","the user has to share it."],"Example":["# Mixed values + formula in one call:","write_sheet(\"1ABC\", \"Sheet1!A1:B3\", [","    [\"Month\", \"Sales\"],","    [\"Jan\", 1000],","    [\"Total\", \"=SUM(B2:B2)\"]","])","# Bulk-write 76 IMAGE formulas in one call: pass a 76×1 `values` list","# (one formula string per row) to 'Sheet1!A2:A77'.","# Force a literal \"=SUM\" as text:","write_sheet(\"1ABC\", \"Sheet1!A1\", [[\"'=SUM(B:B)\"]])"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 target. The top-left cell ('Sheet1!A1') is enough — the block expands right and down; a multi-cell range must be at least as large as `values`."},"values":{"items":{},"title":"Values","type":"array","description":"2D list, one inner list per row. Cells can be strings (incl. \"=formulas\", date strings, number strings), numbers, booleans, or null for blank. A dropdown cell is not checked against its list — write one of the options get_sheet_cell's dropdown.values lists, verbatim."}},"required":["spreadsheet_id","range_","values"],"title":"write_sheetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"written":{"description":"the number of rows written (top level, not under data)."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/setup_sheet":{"post":{"operationId":"setup_sheet","summary":"Create a tab if it is missing, write a key row and a label row, and format them.","description":"Create a tab if it is missing, write a key row and a label row, and format them.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/setup_sheet"},"tags":["google_workspace"],"x-title":"Setup Sheet","x-access":"write","x-family":null,"x-returns":[{"description":"{ sheetId: N, created: bool, formatted: true }"}],"x-notes":{"Gotchas":["Writes `headers` to row 1 and `labels` to row 2 as plain text (no formula parsing),","hides row 1 when hide_row1 is set, freezes freeze_rows rows, and paints row 2 bold","white on header_row_color. An existing tab is reused (created false) and nothing","below row 2 is cleared. No cell notes are written; add them with update_sheet_note.","The yellow / light-yellow / gray header fills and green label row of older","SellerSheet guides are retired; SellerSheet tabs use one navy header band whose","font colour marks required, optional and auto columns."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."},"headers":{"items":{},"title":"Headers","type":"array","description":"Row 1 key names, e.g. ['storeName', 'reportId', 'processingStatus']."},"labels":{"items":{},"title":"Labels","type":"array","description":"Row 2 display labels, e.g. ['Store Name', 'Report ID', 'Status']."},"header_row_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Header Row Color","description":"RGB list 0.0–1.0 for the default row 2 background. Default: [0.204, 0.659, 0.325] (Google green). Override per-column with format_sheet_range after setup."},"hide_row1":{"default":true,"title":"Hide Row1","type":"boolean","description":"Hide the key-name row. Default: true."},"freeze_rows":{"default":2,"title":"Freeze Rows","type":"integer","description":"Number of rows to freeze from top. Default: 2."}},"required":["spreadsheet_id","sheet_name","headers","labels"],"title":"setup_sheetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/clear_sheet_range":{"post":{"operationId":"clear_sheet_range","summary":"Clear the values in a range.","description":"Clear the values in a range. Formatting, notes and data validation stay.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/clear_sheet_range"},"tags":["google_workspace"],"x-title":"Clear Sheet Range","x-access":"destructive","x-family":null,"x-returns":[{"field":"data.cleared","description":"the range that was cleared."}],"x-notes":{"Example":["clear_sheet_range(\"1ABC...\", \"Sheet1!A1:Z100\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A1:Z100')."}},"required":["spreadsheet_id","range_"],"title":"clear_sheet_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"cleared":{"description":"the range that was cleared."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_sheet_metadata":{"post":{"operationId":"get_sheet_metadata","summary":"Get the spreadsheet's metadata: title, locale, time zone and every tab's properties.","description":"Get the spreadsheet's metadata: title, locale, time zone and every tab's properties. For tab names and sheetIds only, list_sheet_tabs is much smaller.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_sheet_metadata"},"tags":["google_workspace"],"x-title":"Get Sheet Metadata","x-access":"read","x-family":null,"x-returns":[{"field":"data.properties","description":"title, locale, timeZone."},{"field":"data.sheets[]","description":"each tab's properties (sheetId, title, index, gridProperties rowCount / columnCount / frozenRowCount) plus its protectedRanges, merges, basicFilter, charts and conditionalFormats."},{"field":"data.namedRanges[] / data.spreadsheetUrl","description":"the named ranges and the URL."}],"x-notes":{"Gotchas":["The spreadsheet must be shared with SellerSheet's Google service account as Editor","(workbooks set up by the SellerSheet sidebar already are); a permission error means","the user has to share it."],"Example":["get_sheet_metadata(\"1ABC...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."}},"required":["spreadsheet_id"],"title":"get_sheet_metadataArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"properties":{"description":"title, locale, timeZone."},"sheets":{"description":"each tab's properties (sheetId, title, index, gridProperties rowCount / columnCount / frozenRowCount) plus its protectedRanges, merges, basicFilter, charts and conditionalFormats."},"namedRanges":{"description":"the named ranges and the URL."},"spreadsheetUrl":{"description":"the named ranges and the URL."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/add_sheet_tab":{"post":{"operationId":"add_sheet_tab","summary":"Add a new tab to the spreadsheet.","description":"Add a new tab to the spreadsheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/add_sheet_tab"},"tags":["google_workspace"],"x-title":"Add Sheet Tab","x-access":"write","x-family":null,"x-returns":[{"field":"data.sheetId","description":"the new tab's integer id (what sheet_batch_update takes)."},{"field":"data.sheetName","description":"its name."}],"x-notes":{"Example":["add_sheet_tab(\"1ABC...\", \"New Tab\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."}},"required":["spreadsheet_id","sheet_name"],"title":"add_sheet_tabArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sheetId":{"description":"the new tab's integer id (what sheet_batch_update takes)."},"sheetName":{"description":"its name."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/rename_sheet_tab":{"post":{"operationId":"rename_sheet_tab","summary":"Rename an existing tab.","description":"Rename an existing tab.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/rename_sheet_tab"},"tags":["google_workspace"],"x-title":"Rename Sheet Tab","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Example":["rename_sheet_tab(\"1ABC...\", \"Old Name\", \"New Name\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"old_name":{"title":"Old Name","type":"string","description":"Current tab name."},"new_name":{"title":"New Name","type":"string","description":"New tab name."}},"required":["spreadsheet_id","old_name","new_name"],"title":"rename_sheet_tabArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/delete_sheet_tab":{"post":{"operationId":"delete_sheet_tab","summary":"Delete a tab from the spreadsheet.","description":"Delete a tab from the spreadsheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/delete_sheet_tab"},"tags":["google_workspace"],"x-title":"Delete Sheet Tab","x-access":"destructive","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Example":["delete_sheet_tab(\"1ABC...\", \"Old Tab\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."}},"required":["spreadsheet_id","sheet_name"],"title":"delete_sheet_tabArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/copy_sheet_tab":{"post":{"operationId":"copy_sheet_tab","summary":"Copy a tab, with all its formatting, into another spreadsheet (or the same one).","description":"Copy a tab, with all its formatting, into another spreadsheet (or the same one). Its main use is restoring a broken SellerSheet tab (wrong columns, deleted headers, corrupted formatting) from the master template.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/copy_sheet_tab"},"tags":["google_workspace"],"x-title":"Copy Sheet Tab","x-access":"write","x-family":null,"x-returns":[{"field":"data.sheetId","description":"the copy's tab id."},{"field":"data.sheetName","description":"its final name — the source name when copying across spreadsheets, 'Copy of <name>' within one."}],"x-notes":{"Workflow":["1. Read data.workspace_config.userSettingBySpreadsheet.storeReportsSpreadsheetId","   from get_user_context.","2. Call this tool with the master template as source and that id as dest."],"Gotchas":["Across spreadsheets, a tab with the same name in dest is replaced, data included,","once the copy has landed, so the fresh copy keeps the name; a failed copy leaves","dest as it was. Within one spreadsheet nothing is deleted and Google names the copy","'Copy of <name>' — rename it with rename_sheet_tab.","Google's copy (sheets.copyTo) keeps formatting, frozen panes, column widths and","hidden rows — unlike read + write.","Pass a hyphenated tab name ('STA-BoxFirst') bare — the server quotes it.","The spreadsheet must be shared with SellerSheet's Google service account as Editor","(workbooks set up by the SellerSheet sidebar already are); a permission error means","the user has to share it."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"source_spreadsheet_id":{"title":"Source Spreadsheet Id","type":"string","description":"Spreadsheet ID to copy from — the SellerSheet master template is 1BVm1knCy_9DZGtCsaD9dKjvRVBMnF2_Vj7kyRiENF40."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."},"dest_spreadsheet_id":{"title":"Dest Spreadsheet Id","type":"string","description":"Spreadsheet ID to copy into."},"keep_rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Keep Rows","description":"after copying, clear the cell values below this row (formats stay). Omit it, or pass 0, to keep everything. E.g. 3 keeps rows 1–3."}},"required":["source_spreadsheet_id","sheet_name","dest_spreadsheet_id"],"title":"copy_sheet_tabArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sheetId":{"description":"the copy's tab id."},"sheetName":{"description":"its final name — the source name when copying across spreadsheets, 'Copy of <name>' within one."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/list_sheet_tabs":{"post":{"operationId":"list_sheet_tabs","summary":"List all tabs in the spreadsheet.","description":"List all tabs in the spreadsheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/list_sheet_tabs"},"tags":["google_workspace"],"x-title":"List Sheet Tabs","x-access":"read","x-family":null,"x-returns":[{"field":"data.tabs[]","description":"{title, sheetId, index, gridProperties (rowCount, columnCount, frozenRowCount…)}. sheetId is the integer id that sheet_batch_update takes."},{"field":"data.count","description":"the number of tabs."}],"x-notes":{"Gotchas":["The spreadsheet must be shared with SellerSheet's Google service account as Editor","(workbooks set up by the SellerSheet sidebar already are); a permission error means","the user has to share it."],"Example":["list_sheet_tabs(\"1ABC...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."}},"required":["spreadsheet_id"],"title":"list_sheet_tabsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"tabs":{"description":"{title, sheetId, index, gridProperties (rowCount, columnCount, frozenRowCount…)}. sheetId is the integer id that sheet_batch_update takes."},"count":{"description":"the number of tabs."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/freeze_sheet_panes":{"post":{"operationId":"freeze_sheet_panes","summary":"Freeze rows and/or columns in a sheet.","description":"Freeze rows and/or columns in a sheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/freeze_sheet_panes"},"tags":["google_workspace"],"x-title":"Freeze Sheet Panes","x-access":"write","x-family":null,"x-returns":[{"field":"data.rows / data.cols","description":"the frozen counts after the call."}],"x-notes":{"Example":["freeze_sheet_panes(\"1ABC...\", \"Sheet1\", rows=2, cols=1)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."},"rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Rows","description":"the rows to freeze from the top / the columns to freeze from the left. Omit one to keep its current count; pass 0 to unfreeze it."},"cols":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Cols","description":"the rows to freeze from the top / the columns to freeze from the left. Omit one to keep its current count; pass 0 to unfreeze it."}},"required":["spreadsheet_id","sheet_name"],"title":"freeze_sheet_panesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"rows":{"description":"the frozen counts after the call."},"cols":{"description":"the frozen counts after the call."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/merge_sheet_cells":{"post":{"operationId":"merge_sheet_cells","summary":"Merge cells in a range.","description":"Merge cells in a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/merge_sheet_cells"},"tags":["google_workspace"],"x-title":"Merge Sheet Cells","x-access":"destructive","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Gotchas":["Every range here must name its tab and both ends ('Tab!A1:D10'); a range without a","tab ('A1:D10') or with an open end ('Tab!A:D') is refused."],"Example":["merge_sheet_cells(\"1ABC...\", \"Sheet1!A1:B2\", \"MERGE_ALL\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A1:B2')."},"merge_type":{"default":"MERGE_ALL","title":"Merge Type","type":"string","description":"MERGE_ALL (one merged cell, the default), MERGE_COLUMNS (one merge per column) or MERGE_ROWS (one merge per row)."}},"required":["spreadsheet_id","range_"],"title":"merge_sheet_cellsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/unmerge_sheet_cells":{"post":{"operationId":"unmerge_sheet_cells","summary":"Unmerge cells in a range.","description":"Unmerge cells in a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/unmerge_sheet_cells"},"tags":["google_workspace"],"x-title":"Unmerge Sheet Cells","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Gotchas":["Every range here must name its tab and both ends ('Tab!A1:D10'); a range without a","tab ('A1:D10') or with an open end ('Tab!A:D') is refused."],"Example":["unmerge_sheet_cells(\"1ABC...\", \"Sheet1!A1:B2\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A1:B2')."}},"required":["spreadsheet_id","range_"],"title":"unmerge_sheet_cellsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/sort_sheet_range":{"post":{"operationId":"sort_sheet_range","summary":"Sort a range by specified columns.","description":"Sort a range by specified columns.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/sort_sheet_range"},"tags":["google_workspace"],"x-title":"Sort Sheet Range","x-access":"destructive","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Gotchas":["Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused."],"Example":["sort_sheet_range(\"1ABC...\", \"Sheet1!A2:D100\", [{'dimensionIndex': 0, 'sortOrder': 'ASCENDING'}])"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A2:D100')."},"sort_specs":{"items":{},"title":"Sort Specs","type":"array","description":"[{dimensionIndex, sortOrder}]. dimensionIndex is a 0-based column index (A=0, B=1, …); sortOrder is ASCENDING or DESCENDING. Every row of range_ moves, so start range_ below the header row (e.g. 'Sheet1!A2:D100')."}},"required":["spreadsheet_id","range_","sort_specs"],"title":"sort_sheet_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/create_sheet_filter":{"post":{"operationId":"create_sheet_filter","summary":"Create a filter view on a range: a named, saved filter anyone can open from Data > Filter views without touching the tab's one basic filter (set_sheet_basic_filter sets that).","description":"Create a filter view on a range: a named, saved filter anyone can open from Data > Filter views without touching the tab's one basic filter (set_sheet_basic_filter sets that).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/create_sheet_filter"},"tags":["google_workspace"],"x-title":"Create Sheet Filter","x-access":"write","x-family":null,"x-returns":[{"field":"data.filterViewId","description":"the new filter view's id."},{"field":"data.title","description":"its name."}],"x-notes":{"Gotchas":["The view starts with no criteria; set them, or delete the view, with","sheet_batch_update (updateFilterView / deleteFilterView with data.filterViewId).","Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused."],"Example":["create_sheet_filter(\"1ABC...\", \"Sheet1!A1:D100\", \"My Filter\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range, header row included (e.g. 'Sheet1!A1:D100')."},"title":{"title":"Title","type":"string","description":"the filter view's name."}},"required":["spreadsheet_id","range_","title"],"title":"create_sheet_filterArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"filterViewId":{"description":"the new filter view's id."},"title":{"description":"its name."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/set_sheet_number_format":{"post":{"operationId":"set_sheet_number_format","summary":"Set number format for a range.","description":"Set number format for a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/set_sheet_number_format"},"tags":["google_workspace"],"x-title":"Set Sheet Number Format","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Gotchas":["Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused."],"Example":["set_sheet_number_format(\"1ABC...\", \"Sheet1!A1:A100\", \"CURRENCY\", \"$#,##0.00\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A1:A100')."},"format_type":{"title":"Format Type","type":"string","description":"NUMBER, CURRENCY, PERCENT, DATE, TIME, DATE_TIME, SCIENTIFIC or TEXT."},"pattern":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Pattern","description":"optional custom pattern (e.g. '#,##0.00'); omit it to use the spreadsheet locale's default for the type."}},"required":["spreadsheet_id","range_","format_type"],"title":"set_sheet_number_formatArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/resize_sheet_columns":{"post":{"operationId":"resize_sheet_columns","summary":"Resize columns in a sheet.","description":"Resize columns in a sheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/resize_sheet_columns"},"tags":["google_workspace"],"x-title":"Resize Sheet Columns","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Example":["resize_sheet_columns(\"1ABC...\", \"Sheet1\", 0, 3, 150)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."},"start_col":{"title":"Start Col","type":"integer","description":"Start column index (0-based)."},"end_col":{"title":"End Col","type":"integer","description":"End column index (exclusive)."},"width":{"title":"Width","type":"integer","description":"Width in pixels."}},"required":["spreadsheet_id","sheet_name","start_col","end_col","width"],"title":"resize_sheet_columnsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/resize_sheet_rows":{"post":{"operationId":"resize_sheet_rows","summary":"Resize rows in a sheet.","description":"Resize rows in a sheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/resize_sheet_rows"},"tags":["google_workspace"],"x-title":"Resize Sheet Rows","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Example":["resize_sheet_rows(\"1ABC...\", \"Sheet1\", 0, 10, 30)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."},"start_row":{"title":"Start Row","type":"integer","description":"Start row index (0-based)."},"end_row":{"title":"End Row","type":"integer","description":"End row index (exclusive)."},"height":{"title":"Height","type":"integer","description":"Height in pixels."}},"required":["spreadsheet_id","sheet_name","start_row","end_row","height"],"title":"resize_sheet_rowsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/insert_sheet_rows_cols":{"post":{"operationId":"insert_sheet_rows_cols","summary":"Insert rows or columns in a sheet.","description":"Insert rows or columns in a sheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/insert_sheet_rows_cols"},"tags":["google_workspace"],"x-title":"Insert Sheet Rows Columns","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Example":["insert_sheet_rows_cols(\"1ABC...\", \"Sheet1\", \"ROWS\", 5, 10)  # Insert 5 rows at index 5"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."},"dimension":{"title":"Dimension","type":"string","description":"'ROWS' or 'COLUMNS'."},"start_index":{"title":"Start Index","type":"integer","description":"Start index (0-based)."},"end_index":{"title":"End Index","type":"integer","description":"End index (exclusive)."}},"required":["spreadsheet_id","sheet_name","dimension","start_index","end_index"],"title":"insert_sheet_rows_colsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/find_replace_in_sheet":{"post":{"operationId":"find_replace_in_sheet","summary":"Find and replace text in a sheet.","description":"Find and replace text in a sheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/find_replace_in_sheet"},"tags":["google_workspace"],"x-title":"Find Replace in Sheet","x-access":"destructive","x-family":null,"x-returns":[{"field":"data.occurrencesChanged","description":"the number of replacements (0 = nothing matched)."},{"field":"data.valuesChanged / data.formulasChanged / data.rowsChanged / data.sheetsChanged","description":"Google's per-kind counts."}],"x-notes":{"Example":["find_replace_in_sheet(\"1ABC...\", \"old\", \"new\", \"Sheet1\", match_case=True)","find_replace_in_sheet(\"1ABC...\", \"oldSheetId\", \"newSheetId\", include_formulas=True)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"find":{"title":"Find","type":"string","description":"Text to find."},"replace":{"title":"Replace","type":"string","description":"Replacement text."},"sheet_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sheet Name","description":"the tab name. Omit it to search every tab."},"match_case":{"default":false,"title":"Match Case","type":"boolean","description":"Match case (default: False)."},"match_entire":{"default":false,"title":"Match Entire","type":"boolean","description":"Match entire cell (default: False)."},"regex":{"default":false,"title":"Regex","type":"boolean","description":"Use regex (default: False)."},"include_formulas":{"default":false,"title":"Include Formulas","type":"boolean","description":"Also search and replace inside formula strings (default: False). Use this to update IMPORTRANGE spreadsheet IDs in formula cells."}},"required":["spreadsheet_id","find","replace"],"title":"find_replace_in_sheetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"occurrencesChanged":{"description":"the number of replacements (0 = nothing matched)."},"valuesChanged":{"description":"Google's per-kind counts."},"formulasChanged":{"description":"Google's per-kind counts."},"rowsChanged":{"description":"Google's per-kind counts."},"sheetsChanged":{"description":"Google's per-kind counts."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_sheet_notes":{"post":{"operationId":"get_sheet_notes","summary":"Get notes from a range.","description":"Get notes from a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_sheet_notes"},"tags":["google_workspace"],"x-title":"Get Sheet Notes","x-access":"read","x-family":null,"x-returns":[{"field":"data.notes[]","description":"{sheet, row, col, note} for each cell in range_ that has a note, in reading order; row and col are 0-based (A1 = 0, 0)."},{"field":"data.count","description":"the number of notes."}],"x-notes":{"Example":["get_sheet_notes(\"1ABC...\", \"Sheet1!A1:D100\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A1:D100')."}},"required":["spreadsheet_id","range_"],"title":"get_sheet_notesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"notes":{"description":"{sheet, row, col, note} for each cell in range_ that has a note, in reading order; row and col are 0-based (A1 = 0, 0)."},"count":{"description":"the number of notes."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/update_sheet_note":{"post":{"operationId":"update_sheet_note","summary":"Update note on a cell or range.","description":"Update note on a cell or range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/update_sheet_note"},"tags":["google_workspace"],"x-title":"Update Sheet Note","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Gotchas":["Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused."],"Example":["update_sheet_note(\"1ABC...\", \"Sheet1!A1\", \"This is a note\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"'Tab!A1', or a block 'Tab!A1:C3' in which every cell gets the same note."},"note":{"default":"","title":"Note","type":"string","description":"Note text (empty string to clear)."}},"required":["spreadsheet_id","range_"],"title":"update_sheet_noteArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_sheet_links":{"post":{"operationId":"get_sheet_links","summary":"Get hyperlinks from a range.","description":"Get hyperlinks from a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_sheet_links"},"tags":["google_workspace"],"x-title":"Get Sheet Links","x-access":"read","x-family":null,"x-returns":[{"field":"data.links[]","description":"{sheet, row, col, text, url} for each cell in range_ with a hyperlink, in reading order; text is the displayed text, row and col are 0-based (A1 = 0, 0)."},{"field":"data.count","description":"the number of links."}],"x-notes":{"Example":["get_sheet_links(\"1ABC...\", \"Sheet1!A1:D100\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A1:D100')."}},"required":["spreadsheet_id","range_"],"title":"get_sheet_linksArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"links":{"description":"{sheet, row, col, text, url} for each cell in range_ with a hyperlink, in reading order; text is the displayed text, row and col are 0-based (A1 = 0, 0)."},"count":{"description":"the number of links."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/read_sheet_format":{"post":{"operationId":"read_sheet_format","summary":"Read cell formatting from a range.","description":"Read cell formatting from a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/read_sheet_format"},"tags":["google_workspace"],"x-title":"Read Sheet Format","x-access":"read","x-family":null,"x-returns":[{"field":"data.formats[]","description":"{sheet, row, col, value, format} per cell. row and col are 0-based (A1 = 0, 0). format is the userEnteredFormat (what was set on the cell), not the effective look after conditional formatting; get_sheet_cell returns both."}],"x-notes":{"Example":["read_sheet_format(\"1ABC...\", \"Sheet1!A1:D100\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A1:D100')."}},"required":["spreadsheet_id","range_"],"title":"read_sheet_formatArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"formats":{"description":"{sheet, row, col, value, format} per cell. row and col are 0-based (A1 = 0, 0). format is the userEnteredFormat (what was set on the cell), not the effective look after conditional formatting; get_sheet_cell returns both."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/list_sheet_named_ranges":{"post":{"operationId":"list_sheet_named_ranges","summary":"List all named ranges in the spreadsheet.","description":"List all named ranges in the spreadsheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/list_sheet_named_ranges"},"tags":["google_workspace"],"x-title":"List Sheet Named Ranges","x-access":"read","x-family":null,"x-returns":[{"field":"data.namedRanges[]","description":"{namedRangeId, name, range}. range is a GridRange {sheetId, startRowIndex, endRowIndex, startColumnIndex, endColumnIndex}: 0-based, with exclusive ends, not A1."},{"field":"data.count","description":"the number of named ranges."}],"x-notes":{"Example":["list_sheet_named_ranges(\"1ABC...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."}},"required":["spreadsheet_id"],"title":"list_sheet_named_rangesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"namedRanges":{"description":"{namedRangeId, name, range}. range is a GridRange {sheetId, startRowIndex, endRowIndex, startColumnIndex, endColumnIndex}: 0-based, with exclusive ends, not A1."},"count":{"description":"the number of named ranges."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_sheet_named_range":{"post":{"operationId":"get_sheet_named_range","summary":"Get a specific named range.","description":"Get a specific named range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_sheet_named_range"},"tags":["google_workspace"],"x-title":"Get Sheet Named Range","x-access":"read","x-family":null,"x-returns":[{"field":"data.namedRange","description":"{namedRangeId, name, range}. range is a GridRange (0-based, exclusive ends). An unknown name is refused (HTTP 404)."}],"x-notes":{"Example":["get_sheet_named_range(\"1ABC...\", \"MyRange\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"name":{"title":"Name","type":"string","description":"Name of the named range."}},"required":["spreadsheet_id","name"],"title":"get_sheet_named_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"namedRange":{"description":"{namedRangeId, name, range}. range is a GridRange (0-based, exclusive ends). An unknown name is refused (HTTP 404)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/add_sheet_named_range":{"post":{"operationId":"add_sheet_named_range","summary":"Add a new named range.","description":"Add a new named range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/add_sheet_named_range"},"tags":["google_workspace"],"x-title":"Add Sheet Named Range","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Gotchas":["Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused."],"Example":["add_sheet_named_range(\"1ABC...\", \"MyRange\", \"Sheet1!A1:D100\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"name":{"title":"Name","type":"string","description":"Name for the named range."},"range_":{"title":"Range","type":"string","description":"A1 notation range (e.g. 'Sheet1!A1:D100')."}},"required":["spreadsheet_id","name","range_"],"title":"add_sheet_named_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/delete_sheet_named_range":{"post":{"operationId":"delete_sheet_named_range","summary":"Delete a named range.","description":"Delete a named range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/delete_sheet_named_range"},"tags":["google_workspace"],"x-title":"Delete Sheet Named Range","x-access":"destructive","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Example":["delete_sheet_named_range(\"1ABC...\", \"MyRange\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"name":{"title":"Name","type":"string","description":"Name of the named range to delete."}},"required":["spreadsheet_id","name"],"title":"delete_sheet_named_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/append_sheet_rows":{"post":{"operationId":"append_sheet_rows","summary":"Append rows below the last non-empty row of the columns in range_.","description":"Append rows below the last non-empty row of the columns in range_. Writing starts at range_'s leftmost column.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/append_sheet_rows"},"tags":["google_workspace"],"x-title":"Append Sheet Rows","x-access":"write","x-family":null,"x-returns":[{"field":"data.appended","description":"the number of rows written."}],"x-notes":{"Gotchas":["Cells are written RAW, not parsed: '=SUM(A:A)' lands as text and '2026-05-12' as a","string. Use write_sheet at the next row when the rows carry formulas or dates.","Calls that append to the same tab must run one after another: each finds the next","empty row, so two at once write to the same row.","The spreadsheet must be shared with SellerSheet's Google service account as Editor","(workbooks set up by the SellerSheet sidebar already are); a permission error means","the user has to share it."],"Example":["# Append from column A","append_sheet_rows(\"1ABC...\", \"Sheet1!A:Z\", [[\"val1\", \"val2\", \"val3\"]])","# Append from column C","append_sheet_rows(\"1ABC...\", \"Sheet1!C:Z\", [[\"c_val\", \"d_val\"]])"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"Column-only A1 notation, no row numbers ('Sheet1!A:Z', not 'Sheet1!A1:Z10' — a row-bounded range is refused with a 400). Examples: 'Sheet1!A:Z'  → appends from column A 'Sheet1!C:Z'  → appends from column C 'C:Z'         → appends from column C of the spreadsheet's first tab"},"values":{"items":{},"title":"Values","type":"array","description":"2D list of rows to append."}},"required":["spreadsheet_id","range_","values"],"title":"append_sheet_rowsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"appended":{"description":"the number of rows written."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/format_sheet_range":{"post":{"operationId":"format_sheet_range","summary":"Set the fill colour, font colour, bold and font size of a range.","description":"Set the fill colour, font colour, bold and font size of a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/format_sheet_range"},"tags":["google_workspace"],"x-title":"Format Sheet Range","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Gotchas":["The API truncates each colour channel to a byte, so compute R/255 and round up at","the 4th decimal (#28334F → [0.1569, 0.2, 0.3099]).","Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused.","The yellow / light-yellow / gray header fills and green label row of older","SellerSheet guides are retired; SellerSheet tabs use one navy header band whose","font colour marks required, optional and auto columns."],"Example":["format_sheet_range(\"1ABC...\", \"Sheet1!A1:D1\", font_color=[1, 1, 1], bold=True,","                   font_size=10)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation with sheet name, e.g. 'SP Campaigns!A2:AA2'."},"background_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Background Color","description":"RGB floats 0–1, e.g. [0.0589, 0.6197, 0.4393] (#0F9E70). On its own it changes only the fill."},"font_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Font Color","description":"bold true/false; font colour as RGB floats 0–1 (e.g. [1, 1, 1] for white); size in points. Each one you pass is set; one you leave out keeps its current value."},"bold":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Bold","description":"bold true/false; font colour as RGB floats 0–1 (e.g. [1, 1, 1] for white); size in points. Each one you pass is set; one you leave out keeps its current value."},"font_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Font Size","description":"bold true/false; font colour as RGB floats 0–1 (e.g. [1, 1, 1] for white); size in points. Each one you pass is set; one you leave out keeps its current value."}},"required":["spreadsheet_id","range_"],"title":"format_sheet_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/hide_sheet_rows":{"post":{"operationId":"hide_sheet_rows","summary":"Hide rows in a sheet, or show hidden rows again.","description":"Hide rows in a sheet, or show hidden rows again.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/hide_sheet_rows"},"tags":["google_workspace"],"x-title":"Hide Sheet Rows","x-access":"write","x-family":null,"x-returns":[{"field":"data.startRow / data.endRow / data.hidden","description":"the rows changed and their new state."}],"x-notes":{"Example":["hide_sheet_rows(\"1ABC...\", \"SP Campaigns\", 1)  # Hide row 1 (machine names)","hide_sheet_rows(\"1ABC...\", \"SP Campaigns\", 1, hidden=False)  # Show it again"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."},"start_row":{"title":"Start Row","type":"integer","description":"First row to hide (1-based)."},"end_row":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"End Row","description":"Last row to hide inclusive (1-based). Defaults to start_row."},"hidden":{"default":true,"title":"Hidden","type":"boolean","description":"true (default) hides the rows; false shows them again."}},"required":["spreadsheet_id","sheet_name","start_row"],"title":"hide_sheet_rowsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"startRow":{"description":"the rows changed and their new state."},"endRow":{"description":"the rows changed and their new state."},"hidden":{"description":"the rows changed and their new state."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/set_sheet_basic_filter":{"post":{"operationId":"set_sheet_basic_filter","summary":"Set a basic filter (column dropdown arrows) on a header row range.","description":"Set a basic filter (column dropdown arrows) on a header row range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/set_sheet_basic_filter"},"tags":["google_workspace"],"x-title":"Set Sheet Basic Filter","x-access":"write","x-family":null,"x-returns":[{"description":"Success confirmation."}],"x-notes":{"Gotchas":["Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused."],"Example":["set_sheet_basic_filter(\"1ABC...\", \"SP Campaigns!A4:AA4\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 notation with sheet name covering the header row, e.g. 'SP Campaigns!A4:AA4'."}},"required":["spreadsheet_id","range_"],"title":"set_sheet_basic_filterArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/write_sheet_formula":{"post":{"operationId":"write_sheet_formula","summary":"Fill one formula into a cell — or across EVERY cell of a range.","description":"Fill one formula into a cell — or across EVERY cell of a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/write_sheet_formula"},"tags":["google_workspace"],"x-title":"Write Sheet Formula","x-access":"destructive","x-family":null,"x-returns":[{"field":"data.cellCount","description":"the cells filled."},{"field":"data.multiCell","description":"true when one formula was fanned out across the range (string mode only)."}],"x-notes":{"Gotchas":["Pass a bare formula string and the target range:","- Single cell ('Sheet1!A1')  → written via values.update (USER_ENTERED).","- Multi-cell range ('_raw_ppc!J2:J45') → the SAME formula is filled","  into every cell via one batchUpdate.repeatCell call, and Google","  increments the relative references per cell (so '=B2*C2' in row 2","  becomes '=B3*C3' in row 3, and so on). The success message reports","  the real filled extent, e.g. \"Formula filled across _raw_ppc!J2:J45","  (44 cells, relative references adjusted per cell)\".","Use write_sheet directly when:","- Mixing values and formulas in the same block","- Each cell needs a DIFFERENT formula (pass an explicit 2D list)","- You want explicit 2D shape control","This is a real fan-out: unlike write_sheet with a 1-row 2D list, it does NOT","leave J3:J45 empty.","Every range here must name its tab and both ends ('Tab!A1:D10'); a range without a","tab ('A1:D10') or with an open end ('Tab!A:D') is refused. A single cell is exempt."],"Example":["write_sheet_formula(\"1ABC\", \"Sheet1!A1\", \"=SUM(B:B)\")","write_sheet_formula(\"1ABC\", \"Inventory!Q9\", \"=SPARKLINE(_raw_woc!C2:P2)\")","# Same formula fanned across a bounded range — relative refs adjust per row:","write_sheet_formula(\"1ABC\", \"_raw_ppc!J2:J45\", \"=IF(G2>0,F2/G2,\\\"\\\")\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"a single cell ('Sheet1!A1'), or a block that names its tab and both row ends ('Sheet1!A2:A45'). 'A2:A45' and 'A2:A' are refused."},"formula":{"anyOf":[{"type":"string"},{"items":{},"type":"array"}],"title":"Formula","description":"Formula string starting with '='. Also accepts a 2D list of formula strings (one per cell) — in that mode it behaves exactly like write_sheet (no fan-out; each cell gets its own literal formula), kept for compatibility."}},"required":["spreadsheet_id","range_","formula"],"title":"write_sheet_formulaArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"cellCount":{"description":"the cells filled."},"multiCell":{"description":"true when one formula was fanned out across the range (string mode only)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/add_sheet_chart":{"post":{"operationId":"add_sheet_chart","summary":"Insert a native Google Sheets chart over a range of data.","description":"Insert a native Google Sheets chart over a range of data. The first column of `data_range` is the domain (x-axis / labels). Remaining columns become series. For PIE the first column is labels and the second is values.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/add_sheet_chart"},"tags":["google_workspace"],"x-title":"Add Sheet Chart","x-access":"write","x-family":null,"x-returns":[{"description":"{ chartId: int, sheetId: int }"}],"x-notes":{"Gotchas":["Every range here must name its tab and both ends ('Tab!A1:D10'); a range without a","tab ('A1:D10') or with an open end ('Tab!A:D') is refused."],"Example":["add_sheet_chart(","    spreadsheet_id='1ABC...',","    data_range='Budget!A10:G14',","    chart_type='COLUMN',","    title='Monthly contribution',","    anchor_range='Budget!I10',","    stacked_type='STACKED',",")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"data_range":{"title":"Data Range","type":"string","description":"A1 range INCLUDING the header row, e.g. 'Competitors!B3:C18' or 'Budget!A10:D14'. At least 2 columns (labels + one series); PIE reads only the first two."},"chart_type":{"title":"Chart Type","type":"string","description":"BAR, COLUMN, LINE, AREA, SCATTER, COMBO, or PIE."},"title":{"default":"","title":"Title","type":"string","description":"Chart title."},"anchor_range":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Anchor Range","description":"Single-cell A1 for the chart anchor (e.g. 'Competitors!H3'). Omit to place just to the right of data_range."},"width_pixels":{"default":600,"title":"Width Pixels","type":"integer","description":"chart size in pixels, default 600 × 371."},"height_pixels":{"default":371,"title":"Height Pixels","type":"integer","description":"chart size in pixels, default 600 × 371."},"legend_position":{"default":"BOTTOM_LEGEND","title":"Legend Position","type":"string","description":"BOTTOM_LEGEND / LEFT_LEGEND / RIGHT_LEGEND / TOP_LEGEND / NO_LEGEND."},"x_axis_title":{"default":"","title":"X Axis Title","type":"string","description":"Axis labels."},"y_axis_title":{"default":"","title":"Y Axis Title","type":"string","description":"Axis labels."},"stacked_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Stacked Type","description":"'STACKED' or 'PERCENT_STACKED' for bar/column/area."}},"required":["spreadsheet_id","data_range","chart_type"],"title":"add_sheet_chartArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/add_sheet_conditional_format":{"post":{"operationId":"add_sheet_conditional_format","summary":"Add a conditional formatting rule to a range: a boolean rule (the default) that formats the cells meeting a condition, or a 2- or 3-stop colour gradient.","description":"Add a conditional formatting rule to a range: a boolean rule (the default) that formats the cells meeting a condition, or a 2- or 3-stop colour gradient.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/add_sheet_conditional_format"},"tags":["google_workspace"],"x-title":"Add Sheet Conditional Format","x-access":"write","x-family":null,"x-returns":[{"description":"{ sheetId: int, applied: true }"}],"x-notes":{"Gotchas":["A boolean rule needs at least one of background_color, font_color or bold, or it","is refused.","The rule is inserted first (index 0), above every existing rule on the tab.","Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused."],"Example":["# Green rows where rank ≤ 10","add_sheet_conditional_format(","    spreadsheet_id='1ABC...',","    range_='Competitors!A4:F18',","    rule_type='NUMBER_LESS_THAN_EQ',","    values=['10'],","    background_color=[0.85, 0.92, 0.83],","    bold=True,",")","# Green (low) → yellow → red (high) on the gap_ratio column","add_sheet_conditional_format(","    spreadsheet_id='1ABC...',","    range_='VOC!D4:D14',","    gradient=True,","    min_color=[0.57, 0.77, 0.49],","    mid_color=[1.0, 0.95, 0.6],","    max_color=[0.91, 0.26, 0.21],","    min_value='MIN',","    mid_value='NUMBER:5',","    max_value='MAX',",")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 range with sheet name (e.g. 'VOC!C4:C18')."},"rule_type":{"default":"NUMBER_GREATER","title":"Rule Type","type":"string","description":"the boolean condition; ignored when gradient is true. Allowed: NUMBER_GREATER (default), NUMBER_GREATER_THAN_EQ, NUMBER_LESS, NUMBER_LESS_THAN_EQ, NUMBER_EQ, NUMBER_NOT_EQ, NUMBER_BETWEEN, NUMBER_NOT_BETWEEN, TEXT_CONTAINS, TEXT_NOT_CONTAINS, TEXT_STARTS_WITH, TEXT_ENDS_WITH, TEXT_EQ, BLANK, NOT_BLANK, CUSTOM_FORMULA."},"values":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Values","description":"the condition's values — one for most types, two for NUMBER_BETWEEN / NUMBER_NOT_BETWEEN, one formula ('=…') for CUSTOM_FORMULA, none for BLANK / NOT_BLANK."},"background_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Background Color","description":"the format a boolean rule applies; colours are RGB floats 0–1."},"font_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Font Color","description":"the format a boolean rule applies; colours are RGB floats 0–1."},"bold":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Bold","description":"the format a boolean rule applies; colours are RGB floats 0–1."},"gradient":{"default":false,"title":"Gradient","type":"boolean","description":"true for a colour-scale rule instead of a boolean one."},"min_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Min Color","description":"RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop."},"mid_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Mid Color","description":"RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop."},"max_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Max Color","description":"RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop."},"min_value":{"default":"MIN","title":"Min Value","type":"string","description":"where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given."},"mid_value":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mid Value","description":"where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given."},"max_value":{"default":"MAX","title":"Max Value","type":"string","description":"where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given."}},"required":["spreadsheet_id","range_"],"title":"add_sheet_conditional_formatArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/group_sheet_rows_cols":{"post":{"operationId":"group_sheet_rows_cols","summary":"Group rows or columns (creates a collapsible [+] toggle in the sheet).","description":"Group rows or columns (creates a collapsible [+] toggle in the sheet).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/group_sheet_rows_cols"},"tags":["google_workspace"],"x-title":"Group Sheet Rows Columns","x-access":"write","x-family":null,"x-returns":[{"description":"{ sheetId, grouped: true }"}],"x-notes":{"Gotchas":["Only the relevant axis of the range is used, and it needs both ends:","dimension='COLUMNS': 'Sheet1!C1:F1' or 'Sheet1!C:F' groups columns C-F.","dimension='ROWS': 'Sheet1!A5:A20' or 'Sheet1!5:20' groups rows 5-20.","Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused.","Groups can be nested (up to 8 levels). To nest, group a subset of","an already-grouped range."],"Example":["group_sheet_rows_cols(\"1ABC...\", \"Listing!F1:J1\", \"COLUMNS\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 range with sheet name, e.g. 'Listing!F1:J1'."},"dimension":{"default":"COLUMNS","title":"Dimension","type":"string","description":"'COLUMNS' or 'ROWS'."}},"required":["spreadsheet_id","range_"],"title":"group_sheet_rows_colsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ungroup_sheet_rows_cols":{"post":{"operationId":"ungroup_sheet_rows_cols","summary":"Remove a row/column group (ungroup).","description":"Remove a row/column group (ungroup).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ungroup_sheet_rows_cols"},"tags":["google_workspace"],"x-title":"Ungroup Sheet Rows Columns","x-access":"write","x-family":null,"x-returns":[{"description":"{ sheetId, ungrouped: true }"}],"x-notes":{"Gotchas":["Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused.","The grouped axis needs both ends ('Tab!C:F', 'Tab!5:20')."],"Example":["ungroup_sheet_rows_cols(\"1ABC...\", \"Listing!F1:J1\", \"COLUMNS\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 range with sheet name."},"dimension":{"default":"COLUMNS","title":"Dimension","type":"string","description":"'COLUMNS' or 'ROWS'."}},"required":["spreadsheet_id","range_"],"title":"ungroup_sheet_rows_colsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/collapse_sheet_group":{"post":{"operationId":"collapse_sheet_group","summary":"Collapse (collapsed=True) or expand the row or column groups that lie inside range_.","description":"Collapse (collapsed=True) or expand the row or column groups that lie inside range_. This flips each group's toggle and hides or shows its rows or columns. A range with no group inside is refused; to show rows hidden without a group, use hide_sheet_rows with hidden false.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/collapse_sheet_group"},"tags":["google_workspace"],"x-title":"Collapse Sheet Group","x-access":"write","x-family":null,"x-returns":[{"description":"{ sheetId, collapsed: bool, groups: the number of groups flipped }"}],"x-notes":{"Gotchas":["Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused.","The grouped axis needs both ends ('Tab!C:F', 'Tab!5:20')."],"Example":["collapse_sheet_group(\"1ABC...\", \"Listing!F1:J1\", \"COLUMNS\", True)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 range covering the grouped dimension."},"dimension":{"default":"COLUMNS","title":"Dimension","type":"string","description":"'COLUMNS' or 'ROWS'."},"collapsed":{"default":true,"title":"Collapsed","type":"boolean","description":"True to collapse, False to expand."}},"required":["spreadsheet_id","range_"],"title":"collapse_sheet_groupArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/protect_sheet_range":{"post":{"operationId":"protect_sheet_range","summary":"Protect a range from editing.","description":"Protect a range from editing.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/protect_sheet_range"},"tags":["google_workspace"],"x-title":"Protect Sheet Range","x-access":"write","x-family":null,"x-returns":[{"description":"{ protectedRangeId: int, sheetId: int }"}],"x-notes":{"Gotchas":["warning_only=False (default): hard-lock. Only editors can modify.","warning_only=True: shows a warning dialog, but anyone can proceed.","Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused.","If editors is not provided, only the spreadsheet owner can edit the","protected range."],"Example":["protect_sheet_range(","    \"1ABC...\", \"KPIs!A1:E20\",","    description=\"KPI targets - do not edit\",","    editors=[\"admin@example.com\"],",")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 range with sheet name, e.g. 'KPIs!A1:E20'."},"description":{"default":"","title":"Description","type":"string","description":"Label shown when a non-editor tries to edit."},"warning_only":{"default":false,"title":"Warning Only","type":"boolean","description":"If True, show a warning but don't block."},"editors":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Editors","description":"email addresses allowed to edit. Hard lock only: Google does not support editors when warning_only is true."}},"required":["spreadsheet_id","range_"],"title":"protect_sheet_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/unprotect_sheet_range":{"post":{"operationId":"unprotect_sheet_range","summary":"Remove protection from a range.","description":"Remove protection from a range. Take the protectedRangeId from protect_sheet_range, or for an older protection from get_sheet_metadata data.sheets[].protectedRanges[].protectedRangeId.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/unprotect_sheet_range"},"tags":["google_workspace"],"x-title":"Unprotect Sheet Range","x-access":"write","x-family":null,"x-returns":[{"description":"{ deleted: true }"}],"x-notes":{"Example":["unprotect_sheet_range(\"1ABC...\", 123456)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"protected_range_id":{"title":"Protected Range Id","type":"integer","description":"The ID returned by protect_sheet_range."}},"required":["spreadsheet_id","protected_range_id"],"title":"unprotect_sheet_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/sheet_batch_update":{"post":{"operationId":"sheet_batch_update","summary":"Apply several raw Sheets API v4 requests (spreadsheets.batchUpdate) in one call.","description":"Apply several raw Sheets API v4 requests (spreadsheets.batchUpdate) in one call. Use it for 3+ structural operations at once (write values + format header + autofit columns + freeze panes); a single operation reads better through its dedicated tool (write_sheet, format_sheet_range), because the raw request shape is verbose.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/sheet_batch_update"},"tags":["google_workspace"],"x-title":"Sheet Batch Update","x-access":"destructive","x-family":null,"x-returns":[{"field":"data.replies","description":"one reply per request, in order; requests that return nothing get an empty reply, and addSheet's reply carries the new sheetId."},{"field":"data.requestCount","description":"the number of requests applied."}],"x-notes":{"Gotchas":["Google applies the requests in order, as one unit: one invalid request fails the","whole call and nothing is applied.","Request reference:","https: //developers.google.com/sheets/api/reference/rest/v4/spreadsheets/batchUpdate"],"Example":["Bold a header row and autofit two columns in one call.","sheet_batch_update(\"1ABC...\", [","    {\"repeatCell\": {","        \"range\": {\"sheetId\": 0, \"startRowIndex\": 0, \"endRowIndex\": 1,","                  \"startColumnIndex\": 0, \"endColumnIndex\": 4},","        \"cell\": {\"userEnteredFormat\": {\"textFormat\": {\"bold\": True}}},","        \"fields\": \"userEnteredFormat.textFormat.bold\",","    }},","    {\"autoResizeDimensions\": {","        \"dimensions\": {\"sheetId\": 0, \"dimension\": \"COLUMNS\",","                       \"startIndex\": 0, \"endIndex\": 4},","    }},","])"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"requests":{"items":{},"title":"Requests","type":"array","description":"a non-empty list of Sheets v4 Request objects, e.g. updateCells, repeatCell, updateBorders, mergeCells, addBanding, autoResizeDimensions, updateSheetProperties, updateDimensionProperties, insertDimension, deleteDimension, addProtectedRange. Ranges are GridRange objects: the integer sheetId (list_sheet_tabs), a 0-based start*Index and an exclusive end*Index. Colours are {red, green, blue} floats 0–1."}},"required":["spreadsheet_id","requests"],"title":"sheet_batch_updateArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"replies":{"description":"one reply per request, in order; requests that return nothing get an empty reply, and addSheet's reply carries the new sheetId."},"requestCount":{"description":"the number of requests applied."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/import_sheet_tsv":{"post":{"operationId":"import_sheet_tsv","summary":"Server-side parse + write of TSV (tab-separated) text.","description":"Server-side parse + write of TSV (tab-separated) text. Use this to dump SP-API report previews, clipboard pastes, or any raw TSV blob directly into a sheet without pre-splitting on the client. The server splits on newlines then tabs, trims trailing empty rows, and writes every cell as text (RAW): '14' stays the string \"14\" and formulas are not evaluated. Use write_sheet when the values must be numbers, dates or formulas.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/import_sheet_tsv"},"tags":["google_workspace"],"x-title":"Import Sheet TSV","x-access":"destructive","x-family":null,"x-returns":[{"field":"data.rowCount / data.colCount","description":"the size of the block written (colCount = the widest row)."},{"field":"data.written","description":"rows written (0 for empty text)."}],"x-notes":{"Example":["import_sheet_tsv(\"1ABC...\", \"Inventory!A1\",","    \"sku\\tasin\\tqty\\nA001\\tB000ABC\\t14\\nA002\\tB000DEF\\t7\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"the top-left anchor cell, e.g. 'Sheet1!A1'. The block expands right and down."},"tsv_text":{"title":"Tsv Text","type":"string","description":"Raw TSV text. Lines separated by \\n (or \\r\\n); cells separated by \\t. Empty trailing lines are ignored."}},"required":["spreadsheet_id","range_","tsv_text"],"title":"import_sheet_tsvArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"rowCount":{"description":"the size of the block written (colCount = the widest row)."},"colCount":{"description":"the size of the block written (colCount = the widest row)."},"written":{"description":"rows written (0 for empty text)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/paste_sheet_with_format":{"post":{"operationId":"paste_sheet_with_format","summary":"Write values AND apply uniform format to the same range — saves a round-trip vs calling write_sheet then format_sheet_range.","description":"Write values AND apply uniform format to the same range — saves a round-trip vs calling write_sheet then format_sheet_range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/paste_sheet_with_format"},"tags":["google_workspace"],"x-title":"Paste Sheet with Format","x-access":"destructive","x-family":null,"x-returns":[{"field":"data.rowsWritten","description":"the rows written."},{"field":"data.formatApplied","description":"false when no format argument was given."}],"x-notes":{"Gotchas":["Every range here must name its tab and both ends ('Tab!A1:D10'); a range without a","tab ('A1:D10') or with an open end ('Tab!A:D') is refused."],"Example":["Write 3 currency cells, formatted as bold USD currency.","paste_sheet_with_format(\"1ABC...\", \"Summary!B2:B4\",","    [[1234.5], [678.9], [42.0]],","    bold=True,","    number_format_type=\"CURRENCY\",","    number_format_pattern=\"$#,##0.00\",",")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"the whole target block with its tab name ('Summary!A1:D10'). The format lands on exactly this range, so an anchor cell formats only that cell. A range the format step cannot use is refused before anything is written."},"values":{"items":{},"title":"Values","type":"array","description":"2D list of values to write. Formulas allowed (USER_ENTERED)."},"background_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Background Color","description":"RGB list 0.0–1.0, e.g. [1.0, 0.898, 0.4]."},"font_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Font Color","description":"bold true/false; font colour as RGB floats 0–1; size in points. Each one you pass is set; one you leave out keeps its current value."},"bold":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Bold","description":"bold true/false; font colour as RGB floats 0–1; size in points. Each one you pass is set; one you leave out keeps its current value."},"font_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Font Size","description":"bold true/false; font colour as RGB floats 0–1; size in points. Each one you pass is set; one you leave out keeps its current value."},"number_format_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Number Format Type","description":"'NUMBER' | 'CURRENCY' | 'PERCENT' | 'DATE' | 'TIME' | 'DATE_TIME' | 'TEXT' | 'SCIENTIFIC'. Optional."},"number_format_pattern":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Number Format Pattern","description":"Sheets pattern string (e.g. '#,##0.00', '$#,##0.00', '0.00%'). Optional."}},"required":["spreadsheet_id","range_","values"],"title":"paste_sheet_with_formatArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"rowsWritten":{"description":"the rows written."},"formatApplied":{"description":"false when no format argument was given."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/apply_sheet_table_style":{"post":{"operationId":"apply_sheet_table_style","summary":"Style an already-written range as a table: a bold, coloured, centred header row, alternating row bands, thin grey borders and a frozen header.","description":"Style an already-written range as a table: a bold, coloured, centred header row, alternating row bands, thin grey borders and a frozen header. Use it after writing the data; for a single fill or font change, use format_sheet_range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/apply_sheet_table_style"},"tags":["google_workspace"],"x-title":"Apply Sheet Table Style","x-access":"write","x-family":null,"x-returns":[{"field":"data.bandedRangeId","description":"the id of the new banding."},{"field":"data.frozeHeader / data.addedBorders","description":"what was applied."}],"x-notes":{"Gotchas":["Every range here must name its tab and both ends ('Tab!A1:D10'); a range without a","tab ('A1:D10') or with an open end ('Tab!A:D') is refused."],"Example":["apply_sheet_table_style(\"1ABC...\", \"Summary!A1:D10\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 range with at least 2 rows, e.g. 'Summary!A1:D20'. Its first row is the header; the remaining rows get the alternating bands."},"header_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Header Color","description":"RGB floats 0–1. Defaults: [0.27, 0.45, 0.77] (blue), [1, 1, 1] (white), [0.95, 0.95, 0.95] (light grey)."},"header_text_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Header Text Color","description":"RGB floats 0–1. Defaults: [0.27, 0.45, 0.77] (blue), [1, 1, 1] (white), [0.95, 0.95, 0.95] (light grey)."},"alt_row_color":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Alt Row Color","description":"RGB floats 0–1. Defaults: [0.27, 0.45, 0.77] (blue), [1, 1, 1] (white), [0.95, 0.95, 0.95] (light grey)."},"freeze_header":{"default":true,"title":"Freeze Header","type":"boolean","description":"Freeze rows above + including the header row. Default True."},"add_borders":{"default":true,"title":"Add Borders","type":"boolean","description":"Apply thin borders. Default True."}},"required":["spreadsheet_id","range_"],"title":"apply_sheet_table_styleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"bandedRangeId":{"description":"the id of the new banding."},"frozeHeader":{"description":"what was applied."},"addedBorders":{"description":"what was applied."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/autofit_sheet_columns":{"post":{"operationId":"autofit_sheet_columns","summary":"Auto-resize columns to fit their content — wraps Sheets `autoResizeDimensions`.","description":"Auto-resize columns to fit their content — wraps Sheets `autoResizeDimensions`. No more guessing pixel widths.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/autofit_sheet_columns"},"tags":["google_workspace"],"x-title":"Autofit Sheet Columns","x-access":"write","x-family":null,"x-returns":[{"field":"data.startCol / data.endCol","description":"the column span fitted (0-based, end exclusive)."},{"field":"data.sheetId","description":"the tab's id."}],"x-notes":{"Example":["# autofit columns A–F","autofit_sheet_columns(\"1ABC...\", \"Summary\", start_col=0, end_col=6)","# autofit the whole tab","autofit_sheet_columns(\"1ABC...\", \"Summary\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"sheet_name":{"title":"Sheet Name","type":"string","description":"the tab name."},"start_col":{"default":0,"title":"Start Col","type":"integer","description":"0-based start column index. Default 0 (column A)."},"end_col":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"End Col","description":"0-based exclusive end. None = autofit every column the tab has (uses gridProperties.columnCount)."}},"required":["spreadsheet_id","sheet_name"],"title":"autofit_sheet_columnsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"startCol":{"description":"the column span fitted (0-based, end exclusive)."},"endCol":{"description":"the column span fitted (0-based, end exclusive)."},"sheetId":{"description":"the tab's id."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/set_sheet_borders":{"post":{"operationId":"set_sheet_borders","summary":"Add cell borders to a range.","description":"Add cell borders to a range. Each side is set independently; a side you leave out keeps its current border.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/set_sheet_borders"},"tags":["google_workspace"],"x-title":"Set Sheet Borders","x-access":"write","x-family":null,"x-returns":[{"field":"data.sides","description":"the sides written (camelCase, e.g. innerHorizontal)."}],"x-notes":{"Gotchas":["At least one side is required.","Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the","bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused."],"Example":["set_sheet_borders(\"1ABC...\", \"Summary!A1:C3\",","    top={\"style\": \"SOLID_THICK\", \"color\": [1.0, 0.0, 0.0]},","    bottom={\"style\": \"SOLID_THICK\", \"color\": [1.0, 0.0, 0.0]},","    left={\"style\": \"SOLID_THICK\", \"color\": [1.0, 0.0, 0.0]},","    right={\"style\": \"SOLID_THICK\", \"color\": [1.0, 0.0, 0.0]},",")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 range with sheet name, e.g. 'Summary!A1:D5'."},"top":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Top","description":"{style, color} for the outer edges; omit a side to leave it unchanged."},"bottom":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Bottom","description":"{style, color} for the outer edges; omit a side to leave it unchanged."},"left":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Left","description":"{style, color} for the outer edges; omit a side to leave it unchanged."},"right":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Right","description":"{style, color} for the outer edges; omit a side to leave it unchanged."},"inner_horizontal":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Inner Horizontal","description":"the lines between rows / between columns, same shape. style: SOLID (default, 1 px), SOLID_MEDIUM (2 px), SOLID_THICK (3 px), DASHED, DOTTED, DOUBLE, or NONE (clears that side). color: RGB floats 0–1, default black."},"inner_vertical":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Inner Vertical","description":"the lines between rows / between columns, same shape. style: SOLID (default, 1 px), SOLID_MEDIUM (2 px), SOLID_THICK (3 px), DASHED, DOTTED, DOUBLE, or NONE (clears that side). color: RGB floats 0–1, default black."}},"required":["spreadsheet_id","range_"],"title":"set_sheet_bordersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sides":{"description":"the sides written (camelCase, e.g. innerHorizontal)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/copy_sheet_format":{"post":{"operationId":"copy_sheet_format","summary":"Copy formatting only (no values) from source range to target range.","description":"Copy formatting only (no values) from source range to target range. Sheets paste-special equivalent — use this to propagate a formatted block (header style, conditional fills) to a new region without clobbering its values.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/copy_sheet_format"},"tags":["google_workspace"],"x-title":"Copy Sheet Format","x-access":"write","x-family":null,"x-returns":[{"field":"data.sourceSheetId / data.targetSheetId","description":"the tabs involved."}],"x-notes":{"Gotchas":["A target that is a multiple of the source's height or width repeats the format, so","one header row's style fills 'Report!A2:D500' in one call. A smaller target still","receives the whole source.","Source and target must be in the same spreadsheet.","Every range here must name its tab and both ends ('Tab!A1:D10'); a range without a","tab ('A1:D10') or with an open end ('Tab!A:D') is refused."],"Example":["copy_sheet_format(\"1ABC...\", \"Template!A1:D1\", \"Q1 Report!A1:D1\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"source_range":{"title":"Source Range","type":"string","description":"A1 source range (e.g. 'Template!A1:D1')."},"target_range":{"title":"Target Range","type":"string","description":"A1 target range (e.g. 'Report!A1:D1')."}},"required":["spreadsheet_id","source_range","target_range"],"title":"copy_sheet_formatArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sourceSheetId":{"description":"the tabs involved."},"targetSheetId":{"description":"the tabs involved."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_sheet_cell":{"post":{"operationId":"get_sheet_cell","summary":"Read everything about a cell or a small range in one call: value, formula, format, note, hyperlink and dropdown.","description":"Read everything about a cell or a small range in one call: value, formula, format, note, hyperlink and dropdown. Replaces read_sheet + read_sheet_format + get_sheet_notes when the AI needs a cell's complete state. To pick a dropdown value: read the cell's dropdown here, then write one of its values exactly as listed with write_sheet — a write is not checked against the list (even a strict one): any other value is kept and only marked invalid on the sheet.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_sheet_cell"},"tags":["google_workspace"],"x-title":"Get Sheet Cell","x-access":"read","x-family":null,"x-returns":[{"field":"data.cells[r][c]","description":"one dict per cell, padded to the full range, with the fields of the groups asked for — value: {value, formatted_value, formula, effective_value} (value is what was entered, a formula cell gives its formula; effective_value is the computed result); format: {user_entered_format, effective_format}; note; hyperlink; dropdown: {values, strict} for a list, {source_range, strict} for a list fed by a range, or null — the same shape add_sheet_dropdown writes and echoes."},{"field":"data.rows / data.cols","description":"the grid size."},{"field":"data.row / data.col","description":"the 0-based origin of the top-left cell."},{"description":"The top-left cell's fields also appear flat on data."}],"x-notes":{"Example":["get_sheet_cell(\"1ABC...\", \"Summary!B5\")","get_sheet_cell(\"1ABC...\", \"Plan!K9:N9\", include=[\"value\", \"dropdown\"])"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"A1 range, e.g. 'Summary!A1' or 'Summary!A1:C10'. A multi-cell range returns every cell in data.cells. A range of more than 500 cells is refused; use read_sheet or read_sheet_format for larger ranges."},"include":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Include","description":"the groups to read; omit for all. Allowed: value | format | note | hyperlink | dropdown. Ask only for what you need — format is about 1 KB a cell, so checking dropdowns on a row is include=['value', 'dropdown']."}},"required":["spreadsheet_id","range_"],"title":"get_sheet_cellArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"rows":{"description":"the grid size."},"cols":{"description":"the grid size."},"row":{"description":"the 0-based origin of the top-left cell."},"col":{"description":"the 0-based origin of the top-left cell."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/insert_sheet_sparkline":{"post":{"operationId":"insert_sheet_sparkline","summary":"Insert an in-cell SPARKLINE chart by writing the formula for you.","description":"Insert an in-cell SPARKLINE chart by writing the formula for you. Sheets SPARKLINEs are tiny inline charts — use them in dashboard rows (one per metric) instead of full add_sheet_chart calls. Much smaller footprint, much faster.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/insert_sheet_sparkline"},"tags":["google_workspace"],"x-title":"Insert Sheet Sparkline","x-access":"write","x-family":null,"x-returns":[{"field":"data.formula","description":"the SPARKLINE formula written to data.targetCell."}],"x-notes":{"Example":["insert_sheet_sparkline(\"1ABC...\", \"Dash!F1\", \"Dash!A1:E1\",","                       sparkline_type=\"line\", color=\"red\")","# Column type with explicit RGB green","insert_sheet_sparkline(\"1ABC...\", \"Dash!F2\", \"Dash!A2:E2\",","                       sparkline_type=\"column\",","                       color=[0.0, 0.8, 0.0])"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"target_cell":{"title":"Target Cell","type":"string","description":"A1 target cell to host the sparkline (e.g. 'Dash!F2')."},"data_range":{"title":"Data Range","type":"string","description":"the data series as it would appear in a formula, without '=' (e.g. 'Sales!B2:G2'). Pass the tab name bare ('STA-BoxFirst!B2:G2'); the server quotes it."},"sparkline_type":{"default":"line","title":"Sparkline Type","type":"string","description":"'line' (default) | 'column' | 'winloss'."},"color":{"default":null,"title":"color","type":"string","description":"Optional. Either a Sheets color name string ('red', 'blue', etc.) OR an RGB list [r,g,b] floats 0–1 which is converted to a #RRGGBB hex literal."},"line_width":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Line Width","description":"Optional integer (only applies to 'line' type)."}},"required":["spreadsheet_id","target_cell","data_range"],"title":"insert_sheet_sparklineArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"formula":{"description":"the SPARKLINE formula written to data.targetCell."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/add_sheet_dropdown":{"post":{"operationId":"add_sheet_dropdown","summary":"Set, replace or remove the dropdown on a range — the one dropdown tool.","description":"Set, replace or remove the dropdown on a range — the one dropdown tool. Pass values for a fixed list, source_range for a list kept in other cells, or values=[] to remove the dropdown. The reply echoes the rule as written, in the shape get_sheet_cell reads, so no second read is needed to check it. Writing a value into a dropdown cell is write_sheet, with one of the values exactly as listed.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/add_sheet_dropdown"},"tags":["google_workspace"],"x-title":"Add Sheet Dropdown","x-access":"write","x-family":null,"x-returns":[{"field":"data.dropdown","description":"the rule as written — {values, strict} or {source_range, strict}; null when the dropdown was removed."},{"field":"data.range / data.rowCount / data.colCount","description":"the cells it covers (a count is null on an open side)."}],"x-notes":{"Example":["add_sheet_dropdown(\"1ABC...\", \"Plan!D2:D100\",","                   values=[\"PENDING\", \"IN_PROGRESS\", \"DONE\", \"CANCELLED\"])","add_sheet_dropdown(\"1ABC...\", \"Plan!E2:E100\", source_range=\"Lists!A2:A30\")","add_sheet_dropdown(\"1ABC...\", \"Plan!D2:D100\", values=[])   # remove"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spreadsheet_id":{"title":"Spreadsheet Id","type":"string","description":"the spreadsheet ID (from its URL or get_sheet_metadata)."},"range_":{"title":"Range","type":"string","description":"the cells to put the dropdown on, an A1 range that names its tab ('Plan!D2:D100'); an open end runs to the edge ('Plan!D2:D', 'Plan!A:D')."},"values":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Values","description":"the options, in order; a number is sent as its text ('1'). values=[] removes the dropdown from range_. Pass this or source_range, not both."},"source_range":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source Range","description":"the cells that hold the options, an A1 range that names its tab ('Lists!A2:A30'); the dropdown follows them when they change. The echo and get_sheet_cell quote a tab name that needs it (\"'my-tab'!A2:A30\")."},"strict":{"default":true,"title":"Strict","type":"boolean","description":"True (default) = the sheet rejects a value a person types that is not an option; False = it keeps the value and marks it invalid. Neither applies to write_sheet: a written value is kept as written, so write an option verbatim."}},"required":["spreadsheet_id","range_"],"title":"add_sheet_dropdownArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"dropdown":{"description":"the rule as written — {values, strict} or {source_range, strict}; null when the dropdown was removed."},"range":{"description":"the cells it covers (a count is null on an open side)."},"rowCount":{"description":"the cells it covers (a count is null on an open side)."},"colCount":{"description":"the cells it covers (a count is null on an open side)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/create_doc_in_folder":{"post":{"operationId":"create_doc_in_folder","summary":"Create a new blank Google Doc inside a Drive folder.","description":"Create a new blank Google Doc inside a Drive folder.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/create_doc_in_folder"},"tags":["google_workspace"],"x-title":"Create Doc in Folder","x-access":"write","x-family":null,"x-returns":[{"description":"{ documentId: str, url: str }"}],"x-notes":{"Example":["create_doc_in_folder(title=\"Q1 Brand Brief\", folderId=\"1ABC...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"title":"Title","type":"string","description":"Document title."},"folderId":{"title":"Folderid","type":"string","description":"a Drive folder SellerSheet can write to — e.g. get_user_context's data.workspace_config.userSettingByFolder.sellerSheetFolderId (writable when data.workspace_config.sa_folder_access.ok is true)."}},"required":["title","folderId"],"title":"create_doc_in_folderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_doc":{"post":{"operationId":"get_doc","summary":"Get the full Docs API document resource (body, headers, styles, revisionId).","description":"Get the full Docs API document resource (body, headers, styles, revisionId). Use this when you need to map characters to indices — read body.content[*].startIndex/endIndex to find where a paragraph or text run begins. For plain text only, use get_doc_text instead.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_doc"},"tags":["google_workspace"],"x-title":"Get Doc","x-access":"read","x-family":null,"x-returns":[{"description":"The Docs API document resource (structural)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."}},"required":["documentId"],"title":"get_docArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_doc_text":{"post":{"operationId":"get_doc_text","summary":"Extract the plain text of the document body, table cells included (headers and footers are not).","description":"Extract the plain text of the document body, table cells included (headers and footers are not). Offsets in `text` are not document indices — use find_doc_text or get_doc for those.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_doc_text"},"tags":["google_workspace"],"x-title":"Get Doc Text","x-access":"read","x-family":null,"x-returns":[{"description":"{ text: str, length: int }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."}},"required":["documentId"],"title":"get_doc_textArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_doc_metadata":{"post":{"operationId":"get_doc_metadata","summary":"Get document title, revisionId, and documentStyle.","description":"Get document title, revisionId, and documentStyle.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_doc_metadata"},"tags":["google_workspace"],"x-title":"Get Doc Metadata","x-access":"read","x-family":null,"x-returns":[{"description":"{ documentId, title, revisionId, documentStyle }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."}},"required":["documentId"],"title":"get_doc_metadataArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/insert_doc_text":{"post":{"operationId":"insert_doc_text","summary":"Insert text at a specific index.","description":"Insert text at a specific index. If index is null/omitted, append to end.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/insert_doc_text"},"tags":["google_workspace"],"x-title":"Insert Doc Text","x-access":"write","x-family":null,"x-returns":[{"description":"{ inserted: true, chars: N }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"text":{"title":"Text","type":"string","description":"Text to insert. Include trailing '\\n' to start a new paragraph."},"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Index","description":"a 1-based body index from find_doc_text or get_doc; it must fall inside an existing paragraph (not at a table's start index). Omit to append at the end — the same as append_doc_text."}},"required":["documentId","text"],"title":"insert_doc_textArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/append_doc_text":{"post":{"operationId":"append_doc_text","summary":"Append text to the end of the document body.","description":"Append text to the end of the document body.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/append_doc_text"},"tags":["google_workspace"],"x-title":"Append Doc Text","x-access":"write","x-family":null,"x-returns":[{"description":"{ appended: true, chars: N }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"text":{"title":"Text","type":"string","description":"Text to append. It lands before the document's final newline, so it joins the last paragraph unless that paragraph is empty — start it with '\\n' to begin a new paragraph after existing text."}},"required":["documentId","text"],"title":"append_doc_textArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/replace_doc_text":{"post":{"operationId":"replace_doc_text","summary":"Find and replace text across the entire document.","description":"Find and replace text across the entire document.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/replace_doc_text"},"tags":["google_workspace"],"x-title":"Replace Doc Text","x-access":"destructive","x-family":null,"x-returns":[{"description":"{ occurrencesChanged: N }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"find":{"title":"Find","type":"string","description":"Text to find (literal, not regex)."},"replace":{"default":"","title":"Replace","type":"string","description":"Replacement text. Default: empty (deletes occurrences)."},"matchCase":{"default":false,"title":"Matchcase","type":"boolean","description":"If True, match is case-sensitive. Default: False."}},"required":["documentId","find"],"title":"replace_doc_textArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/delete_doc_range":{"post":{"operationId":"delete_doc_range","summary":"Delete a content range by index.","description":"Delete a content range by index.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/delete_doc_range"},"tags":["google_workspace"],"x-title":"Delete Doc Range","x-access":"destructive","x-family":null,"x-returns":[{"description":"{ deleted: true }"}],"x-notes":{"Gotchas":["Docs refuses deleting the body's final newline, part of a table, or the newline","before a table or section break without the element itself; a range across a","paragraph end merges the two paragraphs."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"startIndex":{"title":"Startindex","type":"integer","description":"start index, inclusive (from find_doc_text or get_doc)."},"endIndex":{"title":"Endindex","type":"integer","description":"end index, exclusive."}},"required":["documentId","startIndex","endIndex"],"title":"delete_doc_rangeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/clear_doc":{"post":{"operationId":"clear_doc","summary":"Delete all content from the document body.","description":"Delete all content from the document body. The final trailing newline is preserved (Docs API requirement).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/clear_doc"},"tags":["google_workspace"],"x-title":"Clear Doc","x-access":"destructive","x-family":null,"x-returns":[{"description":"{ cleared: bool }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."}},"required":["documentId"],"title":"clear_docArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/update_doc_text_style":{"post":{"operationId":"update_doc_text_style","summary":"Apply character-level text styles to an index range (from find_doc_text or get_doc).","description":"Apply character-level text styles to an index range (from find_doc_text or get_doc). To style every occurrence of a word or phrase, style_doc_text_by_match finds and styles in one call. At least one style attribute must be provided.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/update_doc_text_style"},"tags":["google_workspace"],"x-title":"Update Doc Text Style","x-access":"write","x-family":null,"x-returns":[{"description":"{ styled: true }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"startIndex":{"title":"Startindex","type":"integer","description":"Range start (inclusive)."},"endIndex":{"title":"Endindex","type":"integer","description":"Range end (exclusive)."},"bold":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Bold","description":"boolean toggles."},"italic":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Italic","description":"boolean toggles."},"underline":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Underline","description":"boolean toggles."},"strikethrough":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Strikethrough","description":"boolean toggles."},"fontSize":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Fontsize","description":"Point size (float)."},"fontFamily":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Fontfamily","description":"Font family name, e.g. \"Roboto\"."},"foregroundColor":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Foregroundcolor","description":"RGB list 0.0–1.0, e.g. [0.2, 0.4, 0.8]."},"backgroundColor":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Backgroundcolor","description":"RGB list 0.0–1.0."},"linkUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Linkurl","description":"URL to convert the range into a hyperlink."}},"required":["documentId","startIndex","endIndex"],"title":"update_doc_text_styleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/update_doc_paragraph_style":{"post":{"operationId":"update_doc_paragraph_style","summary":"Apply paragraph-level style to a range.","description":"Apply paragraph-level style to a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/update_doc_paragraph_style"},"tags":["google_workspace"],"x-title":"Update Doc Paragraph Style","x-access":"write","x-family":null,"x-returns":[{"description":"{ styled: true }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"startIndex":{"title":"Startindex","type":"integer","description":"Range start (inclusive)."},"endIndex":{"title":"Endindex","type":"integer","description":"Range end (exclusive)."},"namedStyleType":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Namedstyletype","description":"NORMAL_TEXT, TITLE, SUBTITLE, HEADING_1..HEADING_6."},"alignment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Alignment","description":"START, CENTER, END, JUSTIFIED."},"lineSpacing":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Linespacing","description":"Percentage — 100 = single, 150 = 1.5x, 200 = double."},"indentStartPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Indentstartpt","description":"Left indent in points."},"indentEndPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Indentendpt","description":"Right indent in points."},"indentFirstLinePt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Indentfirstlinept","description":"First-line indent (pt). Useful for indented prose."},"spaceAbovePt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Spaceabovept","description":"Vertical space above paragraph (pt)."},"spaceBelowPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Spacebelowpt","description":"Vertical space below paragraph (pt)."},"keepWithNext":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Keepwithnext","description":"If True, keep with next paragraph on same page."}},"required":["documentId","startIndex","endIndex"],"title":"update_doc_paragraph_styleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/apply_doc_bullets":{"post":{"operationId":"apply_doc_bullets","summary":"Convert paragraphs in a range into a bulleted or numbered list.","description":"Convert paragraphs in a range into a bulleted or numbered list. Each existing paragraph (separated by '\\n') becomes one list item. To add a new list, write_doc_structured's bullets / numbered block inserts and bullets the lines in one call; use this tool on paragraphs already in the document.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/apply_doc_bullets"},"tags":["google_workspace"],"x-title":"Apply Doc Bullets","x-access":"write","x-family":null,"x-returns":[{"description":"{ bulleted: true }"}],"x-notes":{"Gotchas":["Leading tabs set each paragraph's nesting level and are removed by the call, so","indices after the range shift — re-read with find_doc_text or get_doc before the","next index-based edit."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"startIndex":{"title":"Startindex","type":"integer","description":"Range start (inclusive)."},"endIndex":{"title":"Endindex","type":"integer","description":"Range end (exclusive)."},"preset":{"default":"BULLET_DISC_CIRCLE_SQUARE","title":"Preset","type":"string","description":"a Docs API bulletPreset, e.g. BULLET_DISC_CIRCLE_SQUARE, BULLET_CHECKBOX, BULLET_STAR_CIRCLE_SQUARE, NUMBERED_DECIMAL_ALPHA_ROMAN, NUMBERED_DECIMAL_NESTED, NUMBERED_UPPERALPHA_ALPHA_ROMAN. Default: BULLET_DISC_CIRCLE_SQUARE."}},"required":["documentId","startIndex","endIndex"],"title":"apply_doc_bulletsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/remove_doc_bullets":{"post":{"operationId":"remove_doc_bullets","summary":"Remove bullet/number glyphs from paragraphs in a range.","description":"Remove bullet/number glyphs from paragraphs in a range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/remove_doc_bullets"},"tags":["google_workspace"],"x-title":"Remove Doc Bullets","x-access":"write","x-family":null,"x-returns":[{"field":"bulletsRemoved","description":"true."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"startIndex":{"title":"Startindex","type":"integer","description":"first body index of the range (from find_doc_text or get_doc)."},"endIndex":{"title":"Endindex","type":"integer","description":"end index of the range, exclusive."}},"required":["documentId","startIndex","endIndex"],"title":"remove_doc_bulletsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"bulletsRemoved":{"description":"true."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/insert_doc_section_break":{"post":{"operationId":"insert_doc_section_break","summary":"Insert a section break (Docs adds a newline before it; not allowed inside a table, header or footer).","description":"Insert a section break (Docs adds a newline before it; not allowed inside a table, header or footer). Styling the new section (columns, margins) needs doc_batch_update with an updateSectionStyle request.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/insert_doc_section_break"},"tags":["google_workspace"],"x-title":"Insert Doc Section Break","x-access":"write","x-family":null,"x-returns":[{"description":"{ inserted: true }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"sectionType":{"default":"NEXT_PAGE","title":"Sectiontype","type":"string","description":"NEXT_PAGE (start on new page) or CONTINUOUS."},"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Index","description":"Insertion index. Omit to append."}},"required":["documentId"],"title":"insert_doc_section_breakArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/update_doc_document_style":{"post":{"operationId":"update_doc_document_style","summary":"Update document-level properties: margins, page size, background.","description":"Update document-level properties: margins, page size, background.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/update_doc_document_style"},"tags":["google_workspace"],"x-title":"Update Doc Document Style","x-access":"write","x-family":null,"x-returns":[{"description":"{ styled: true }"}],"x-notes":{"Gotchas":["Common page sizes in points:","US Letter     612 x 792    (default)","A4            595 x 842","Legal         612 x 1008","Tabloid       792 x 1224","Common margins (points): 72 = 1\", 54 = 0.75\", 36 = 0.5\"."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"marginTopPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Margintoppt","description":"Page margins."},"marginBottomPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Marginbottompt","description":"Page margins."},"marginLeftPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Marginleftpt","description":"Page margins."},"marginRightPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Marginrightpt","description":"Page margins."},"pageWidthPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Pagewidthpt","description":"Page dimensions."},"pageHeightPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Pageheightpt","description":"Page dimensions."},"backgroundColor":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Backgroundcolor","description":"RGB list 0.0–1.0 for the page background."},"useEvenPageHeaderFooter":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Useevenpageheaderfooter","description":"Different header/footer on even pages."},"useFirstPageHeaderFooter":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Usefirstpageheaderfooter","description":"Different header/footer on first page."}},"required":["documentId"],"title":"update_doc_document_styleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/create_doc_header":{"post":{"operationId":"create_doc_header","summary":"Create a document header and optionally fill it with initial text.","description":"Create a document header and optionally fill it with initial text. If the document already has a default header, returns its headerId with created=false — text is still prepended to it, so pass text only once.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/create_doc_header"},"tags":["google_workspace"],"x-title":"Create Doc Header","x-access":"write","x-family":null,"x-returns":[{"description":"{ headerId: str, created: bool }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"text":{"default":"","title":"Text","type":"string","description":"Optional initial header text."}},"required":["documentId"],"title":"create_doc_headerArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/create_doc_footer":{"post":{"operationId":"create_doc_footer","summary":"Create a document footer and optionally fill it with initial text.","description":"Create a document footer and optionally fill it with initial text. If the document already has a default footer, returns its footerId with created=false — text is still prepended to it, so pass text only once.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/create_doc_footer"},"tags":["google_workspace"],"x-title":"Create Doc Footer","x-access":"write","x-family":null,"x-returns":[{"description":"{ footerId: str, created: bool }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"text":{"default":"","title":"Text","type":"string","description":"Optional initial footer text."}},"required":["documentId"],"title":"create_doc_footerArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/find_doc_text":{"post":{"operationId":"find_doc_text","summary":"Find every occurrence of a text substring and return its index ranges.","description":"Find every occurrence of a text substring and return its index ranges. Use this before calling update_doc_text_style to apply styles to specific words/phrases without computing indices by hand.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/find_doc_text"},"tags":["google_workspace"],"x-title":"Find Doc Text","x-access":"read","x-family":null,"x-returns":[{"description":"{ matches: [{startIndex, endIndex, text}, ...], count: N }"}],"x-notes":{"Gotchas":["Searches top-level body paragraphs one styled run at a time: text inside tables,","headers or footers, or a phrase whose words carry different styles (e.g. half","bold), returns no match — replace_doc_text still reaches it."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"needle":{"title":"Needle","type":"string","description":"Literal text to find (not regex)."},"matchCase":{"default":false,"title":"Matchcase","type":"boolean","description":"If True, case-sensitive match."}},"required":["documentId","needle"],"title":"find_doc_textArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/style_doc_text_by_match":{"post":{"operationId":"style_doc_text_by_match","summary":"Find every occurrence of `needle` and apply the given text style.","description":"Find every occurrence of `needle` and apply the given text style. Combines find_doc_text + update_doc_text_style in one call.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/style_doc_text_by_match"},"tags":["google_workspace"],"x-title":"Style Doc Text by Match","x-access":"write","x-family":null,"x-returns":[{"description":"{ matches: N }"}],"x-notes":{"Example":["make every occurrence of \"SellerSheet\" bold and blue:","style_doc_text_by_match(","    documentId=..., needle=\"SellerSheet\",","    bold=True, foregroundColor=[0.12, 0.35, 0.85],",")"],"Gotchas":["Matches through find_doc_text's search, so text inside tables, headers or footers,","or a phrase split across differently-styled runs, is not styled (matches: 0)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"needle":{"title":"Needle","type":"string","description":"Literal text to find."},"matchCase":{"default":false,"title":"Matchcase","type":"boolean","description":"Case-sensitive match."},"bold":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Bold","description":"set true or false; omit to leave as is."},"italic":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Italic","description":"set true or false; omit to leave as is."},"underline":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Underline","description":"set true or false; omit to leave as is."},"strikethrough":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Strikethrough","description":"set true or false; omit to leave as is."},"fontSize":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Fontsize","description":"points."},"fontFamily":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Fontfamily","description":"e.g. 'Arial'."},"foregroundColor":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Foregroundcolor","description":"[r, g, b] in 0–1."},"backgroundColor":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Backgroundcolor","description":"[r, g, b] in 0–1."},"linkUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Linkurl","description":"make every match a link to this URL."}},"required":["documentId","needle"],"title":"style_doc_text_by_matchArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/set_doc_table_cell_text":{"post":{"operationId":"set_doc_table_cell_text","summary":"Replace the text content of a specific table cell.","description":"Replace the text content of a specific table cell. tableIndex is 0-based across the body's top-level tables (in document order). row and column are 0-based cell coordinates. The cell's first paragraph is replaced; further paragraphs in the cell stay.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/set_doc_table_cell_text"},"tags":["google_workspace"],"x-title":"Set Doc Table Cell Text","x-access":"destructive","x-family":null,"x-returns":[{"description":"{ tableIndex, row, column, chars }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"tableIndex":{"title":"Tableindex","type":"integer","description":"Which table to target (0 = first table)."},"row":{"title":"Row","type":"integer","description":"Cell row (0-based)."},"column":{"title":"Column","type":"integer","description":"Cell column (0-based)."},"text":{"title":"Text","type":"string","description":"Plain text to place in the cell."}},"required":["documentId","tableIndex","row","column","text"],"title":"set_doc_table_cell_textArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/write_doc_structured":{"post":{"operationId":"write_doc_structured","summary":"Build a document from a list of semantic blocks in ONE call.","description":"Build a document from a list of semantic blocks in ONE call. Use it to write a whole document or append a new section: blocks are appended at the end of the body in order (clearFirst=true replaces the body first). For edits inside existing text use the index-based doc tools.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/write_doc_structured"},"tags":["google_workspace"],"x-title":"Write Doc Structured","x-access":"destructive","x-family":null,"x-returns":[{"description":"{ blocksWritten: N }"}],"x-notes":{"Gotchas":["Each block is a separate write: an unknown type or a bad block fails the call","(400) after the earlier blocks are already in the document — fix it and re-run","with clearFirst=true.","Block types and shapes:","{\"type\": \"title\", \"text\": str}","{\"type\": \"subtitle\", \"text\": str}","{\"type\": \"heading\", \"level\": 1..6, \"text\": str,"," \"alignment\"?: \"START\"|\"CENTER\"|\"END\"|\"JUSTIFIED\"}","{\"type\": \"paragraph\", \"text\": str,"," \"bold\"?: bool, \"italic\"?: bool, \"underline\"?: bool, \"fontSize\"?: float,"," \"fontFamily\"?: str, \"foregroundColor\"?: [r,g,b], \"backgroundColor\"?: [r,g,b],"," \"alignment\"?: str, \"linkUrl\"?: str}","{\"type\": \"bullets\", \"items\": [str, ...],"," \"preset\"?: \"BULLET_DISC_CIRCLE_SQUARE\"}","{\"type\": \"numbered\", \"items\": [str, ...],"," \"preset\"?: \"NUMBERED_DECIMAL_ALPHA_ROMAN\"}","{\"type\": \"table\", \"rows\": int, \"columns\": int,"," \"cells\"?: [[\"A1\",\"B1\"], [\"A2\",\"B2\"], ...]}","{\"type\": \"image\", \"uri\": str, \"widthPt\"?: float, \"heightPt\"?: float}"," (size applies only when both are given)","{\"type\": \"page_break\"}","{\"type\": \"section_break\", \"sectionType\"?: \"NEXT_PAGE\"|\"CONTINUOUS\"}","{\"type\": \"horizontal_rule\"}","{\"type\": \"quote\", \"text\": str}","{\"type\": \"spacer\"}"],"Example":["write_doc_structured(documentId=doc_id, clearFirst=True, blocks=[","    {\"type\": \"title\", \"text\": \"Q1 Brand Audit\"},","    {\"type\": \"subtitle\", \"text\": \"SellerSheet — April 2026\"},","    {\"type\": \"horizontal_rule\"},","    {\"type\": \"heading\", \"level\": 1, \"text\": \"Executive Summary\"},","    {\"type\": \"paragraph\", \"text\": \"Revenue grew 24% YoY...\"},","    {\"type\": \"heading\", \"level\": 2, \"text\": \"Key Findings\"},","    {\"type\": \"bullets\", \"items\": [","        \"A+ content live on 82% of ASINs\",","        \"CTR up 18% after title rewrite\",","        \"Inventory cover: 45 days\",","    ]},","    {\"type\": \"page_break\"},","    {\"type\": \"heading\", \"level\": 1, \"text\": \"Data\"},","    {\"type\": \"table\", \"rows\": 3, \"columns\": 3, \"cells\": [","        [\"Metric\", \"Q4\", \"Q1\"],","        [\"Revenue\", \"$420k\", \"$521k\"],","        [\"CTR\", \"0.72%\", \"0.85%\"],","    ]},","    {\"type\": \"quote\", \"text\": \"Numbers tell the story, design tells the truth.\"},","])"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"blocks":{"items":{},"title":"Blocks","type":"array","description":"Ordered list of block dicts."},"clearFirst":{"default":false,"title":"Clearfirst","type":"boolean","description":"If True, clear existing body before writing."}},"required":["documentId","blocks"],"title":"write_doc_structuredArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/insert_doc_heading":{"post":{"operationId":"insert_doc_heading","summary":"Convenience: insert a line of text and apply HEADING_{level}.","description":"Convenience: insert a line of text and apply HEADING_{level}.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/insert_doc_heading"},"tags":["google_workspace"],"x-title":"Insert Doc Heading","x-access":"write","x-family":null,"x-returns":[{"description":"{ insertedAt: int, endIndex: int }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"text":{"title":"Text","type":"string","description":"Heading text. A trailing newline is added automatically."},"level":{"default":1,"title":"Level","type":"integer","description":"1..6."},"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Index","description":"a body index at the start of a paragraph (from find_doc_text or get_doc). Omit to append — the heading then joins the last paragraph unless that paragraph is empty."}},"required":["documentId","text"],"title":"insert_doc_headingArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/insert_doc_page_break":{"post":{"operationId":"insert_doc_page_break","summary":"Insert a page break.","description":"Insert a page break. Omit index to append at end of body.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/insert_doc_page_break"},"tags":["google_workspace"],"x-title":"Insert Doc Page Break","x-access":"write","x-family":null,"x-returns":[{"description":"{ inserted: true }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Index","description":"Insertion index. Omit to append."}},"required":["documentId"],"title":"insert_doc_page_breakArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/insert_doc_table":{"post":{"operationId":"insert_doc_table","summary":"Insert an empty table.","description":"Insert an empty table. Fill cells with set_doc_table_cell_text (tableIndex counts tables in document order), or create and fill a table in one call with write_doc_structured's table block.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/insert_doc_table"},"tags":["google_workspace"],"x-title":"Insert Doc Table","x-access":"write","x-family":null,"x-returns":[{"description":"{ inserted: true }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"rows":{"title":"Rows","type":"integer","description":"Number of rows (>=1)."},"columns":{"title":"Columns","type":"integer","description":"Number of columns (>=1)."},"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Index","description":"Insertion index. Omit to append."}},"required":["documentId","rows","columns"],"title":"insert_doc_tableArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/insert_doc_image":{"post":{"operationId":"insert_doc_image","summary":"Insert an inline image from a public URL.","description":"Insert an inline image from a public URL.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/insert_doc_image"},"tags":["google_workspace"],"x-title":"Insert Doc Image","x-access":"write","x-family":null,"x-returns":[{"description":"{ inserted: true }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"imageUri":{"title":"Imageuri","type":"string","description":"a publicly readable URL (at most 2 kB) of a PNG, JPEG or GIF under 50 MB and 25 megapixels — a .webp is refused."},"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Index","description":"Insertion index. Omit to append."},"widthPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Widthpt","description":"size in points, applied only when BOTH are given (one alone is ignored); the image is scaled to fit inside that box, keeping its aspect ratio."},"heightPt":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Heightpt","description":"size in points, applied only when BOTH are given (one alone is ignored); the image is scaled to fit inside that box, keeping its aspect ratio."}},"required":["documentId","imageUri"],"title":"insert_doc_imageArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/doc_batch_update":{"post":{"operationId":"doc_batch_update","summary":"Escape hatch: apply a raw Docs API batchUpdate Requests list.","description":"Escape hatch: apply a raw Docs API batchUpdate Requests list. Use it for operations no other doc tool exposes (named ranges, table-cell merges, footnotes, section styles); the list is applied atomically — one invalid request fails them all. Request shapes are documented at https://developers.google.com/docs/api/reference/rest/v1/documents/request","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/doc_batch_update"},"tags":["google_workspace"],"x-title":"Doc Batch Update","x-access":"destructive","x-family":null,"x-returns":[{"field":"replies","description":"one entry per request, in order (e.g. replies[0].createHeader.headerId); an empty requests list returns replies: [] without calling Google."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"requests":{"items":{},"title":"Requests","type":"array","description":"List of Docs API Request objects."}},"required":["documentId","requests"],"title":"doc_batch_updateArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"replies":{"description":"one entry per request, in order (e.g. replies[0].createHeader.headerId); an empty requests list returns replies: [] without calling Google."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/rename_doc":{"post":{"operationId":"rename_doc","summary":"Rename a Google Doc via the Drive API.","description":"Rename a Google Doc via the Drive API.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/rename_doc"},"tags":["google_workspace"],"x-title":"Rename Doc","x-access":"write","x-family":null,"x-returns":[{"description":"{ documentId, title }"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"documentId":{"title":"Documentid","type":"string","description":"the Google Docs document ID."},"newTitle":{"title":"Newtitle","type":"string","description":"New title."}},"required":["documentId","newTitle"],"title":"rename_docArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/find_or_create_folder":{"post":{"operationId":"find_or_create_folder","summary":"Find a subfolder by name inside parentId, or create it if missing.","description":"Find a subfolder by name inside parentId, or create it if missing.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/find_or_create_folder"},"tags":["google_workspace"],"x-title":"Find or Create Folder","x-access":"write","x-family":null,"x-returns":[{"field":"folderId","description":"The folder ID (existing or newly created)."}],"x-notes":{"Example":["find_or_create_folder(name=\"Reports\", parentId=\"1ABC...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"title":"Name","type":"string","description":"Folder name to find or create."},"parentId":{"title":"Parentid","type":"string","description":"Drive folder ID to search within."}},"required":["name","parentId"],"title":"find_or_create_folderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"folderId":{"description":"The folder ID (existing or newly created)."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/find_file_in_folder":{"post":{"operationId":"find_file_in_folder","summary":"Find the first Google Sheet in a folder whose name contains a substring — only spreadsheets match; for any other file type use search_drive_files with rawQuery and parentId.","description":"Find the first Google Sheet in a folder whose name contains a substring — only spreadsheets match; for any other file type use search_drive_files with rawQuery and parentId.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/find_file_in_folder"},"tags":["google_workspace"],"x-title":"Find File in Folder","x-access":"read","x-family":null,"x-returns":[{"field":"fileId","description":"Spreadsheet ID of first match, or null if not found."},{"field":"found","description":"Boolean indicating if a match was found."}],"x-notes":{"Example":["find_file_in_folder(folderId=\"1ABC...\", nameContains=\"report_2026\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folderId":{"title":"Folderid","type":"string","description":"Drive folder ID to search within."},"nameContains":{"title":"Namecontains","type":"string","description":"Substring to match in file names."}},"required":["folderId","nameContains"],"title":"find_file_in_folderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"description":"Spreadsheet ID of first match, or null if not found."},"found":{"description":"Boolean indicating if a match was found."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/create_spreadsheet_in_folder":{"post":{"operationId":"create_spreadsheet_in_folder","summary":"Create a new empty Google Sheet in a Drive folder — for light builds, or when you have no local filesystem.","description":"Create a new empty Google Sheet in a Drive folder — for light builds, or when you have no local filesystem. For a multi-tab workbook (more than ~15 write/format calls), build an .xlsx locally and import it in one call with start_drive_upload (mimeType = the xlsx type, convertTo = 'application/vnd.google-apps.spreadsheet'); formulas, formats, notes, frozen panes, dropdowns and charts survive the conversion.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/create_spreadsheet_in_folder"},"tags":["google_workspace"],"x-title":"Create Spreadsheet in Folder","x-access":"write","x-family":null,"x-returns":[{"field":"spreadsheetId","description":"The new spreadsheet ID."},{"field":"url","description":"Direct URL to the spreadsheet."}],"x-notes":{"Example":["create_spreadsheet_in_folder(title=\"Store Reports\", folderId=\"1ABC...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"title":"Title","type":"string","description":"Spreadsheet title."},"folderId":{"title":"Folderid","type":"string","description":"Target Drive folder ID."}},"required":["title","folderId"],"title":"create_spreadsheet_in_folderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"spreadsheetId":{"description":"The new spreadsheet ID."},"url":{"description":"Direct URL to the spreadsheet."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/move_file_to_folder":{"post":{"operationId":"move_file_to_folder","summary":"Move a file to a new parent folder.","description":"Move a file to a new parent folder.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/move_file_to_folder"},"tags":["google_workspace"],"x-title":"Move File to Folder","x-access":"write","x-family":null,"x-returns":[{"field":"success","description":"Boolean indicating successful move."}],"x-notes":{"Example":["move_file_to_folder(fileId=\"1XYZ...\", newParentId=\"1ABC...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileId":{"title":"Fileid","type":"string","description":"the Drive file ID."},"newParentId":{"title":"Newparentid","type":"string","description":"Target folder ID."}},"required":["fileId","newParentId"],"title":"move_file_to_folderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"description":"Boolean indicating successful move."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/list_drive_files":{"post":{"operationId":"list_drive_files","summary":"List the files directly inside a folder of your SellerSheet workspace.","description":"List the files directly inside a folder of your SellerSheet workspace.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/list_drive_files"},"tags":["google_workspace"],"x-title":"List Drive Files","x-access":"read","x-family":null,"x-returns":[{"field":"files","description":"List of file objects with id, name, mimeType, size, modifiedTime, parents."}],"x-notes":{"Example":["list_drive_files(parentId=\"1ABC...\", max=50)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parentid","description":"the folder to list — the SellerSheet folder the sidebar created or any folder inside it. Omitted, it covers that folder and the workspace folders in it (Listings, StoreReports, Shipments, …), direct children of each. A folder outside the workspace, or one SellerSheet cannot see, is refused."},"max":{"default":20,"title":"Max","type":"integer","description":"files to return, 1–1000 (Drive's pageSize cap); there is no next page — raise max or narrow parentId. Default: 20."}},"title":"list_drive_filesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"description":"List of file objects with id, name, mimeType, size, modifiedTime, parents."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/search_drive_files":{"post":{"operationId":"search_drive_files","summary":"Search files by text or raw Drive query inside your SellerSheet workspace.","description":"Search files by text or raw Drive query inside your SellerSheet workspace.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/search_drive_files"},"tags":["google_workspace"],"x-title":"Search Drive Files","x-access":"read","x-family":null,"x-returns":[{"field":"files","description":"List of file objects with id, name, mimeType, size, modifiedTime."}],"x-notes":{"Example":["search_drive_files(query=\"invoice\", max=10)","search_drive_files(query=\"mimeType='application/pdf'\", rawQuery=True)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"title":"Query","type":"string","description":"Search text or raw Drive query string."},"rawQuery":{"default":false,"title":"Rawquery","type":"boolean","description":"true sends query as a Drive v3 `q` expression (e.g. \"name contains 'invoice' and mimeType = 'application/pdf'\") — add \"and trashed = false\" yourself, it is not appended. False (default) matches query against names and file content (fullText contains), trash excluded."},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parentid","description":"the folder to search — the SellerSheet folder the sidebar created or any folder inside it; Drive matches direct children only. Omitted, it covers that folder and the workspace folders in it. A folder outside the workspace is refused."},"max":{"default":20,"title":"Max","type":"integer","description":"Maximum number of files to return (default 20)."}},"required":["query"],"title":"search_drive_filesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"description":"List of file objects with id, name, mimeType, size, modifiedTime."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_drive_file":{"post":{"operationId":"get_drive_file","summary":"Get file metadata.","description":"Get file metadata.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_drive_file"},"tags":["google_workspace"],"x-title":"Get Drive File","x-access":"read","x-family":null,"x-returns":[{"field":"file","description":"File metadata dict with id, name, mimeType, size, modifiedTime, parents, webViewLink."}],"x-notes":{"Example":["get_drive_file(fileId=\"1XYZ...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileId":{"title":"Fileid","type":"string","description":"the Drive file ID."}},"required":["fileId"],"title":"get_drive_fileArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"description":"File metadata dict with id, name, mimeType, size, modifiedTime, parents, webViewLink."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/copy_drive_file":{"post":{"operationId":"copy_drive_file","summary":"Copy a file, returns new file ID.","description":"Copy a file, returns new file ID.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/copy_drive_file"},"tags":["google_workspace"],"x-title":"Copy Drive File","x-access":"write","x-family":null,"x-returns":[{"field":"fileId","description":"New file ID."}],"x-notes":{"Example":["copy_drive_file(fileId=\"1XYZ...\", name=\"Copy of Report\", parentId=\"1ABC...\")","copy_drive_file(fileId=\"<xlsx id>\", name=\"Q3 Model\",","                convertTo=\"application/vnd.google-apps.spreadsheet\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileId":{"title":"Fileid","type":"string","description":"the Drive file ID."},"name":{"title":"Name","type":"string","description":"Name for the copied file."},"parentId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parentid","description":"Optional target folder ID."},"convertTo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Convertto","description":"Optional Google Workspace target mimeType — Drive converts on copy. E.g. copy an .xlsx Drive file with convertTo='application/vnd.google-apps.spreadsheet' to get a native Google Sheet copy (the source file is untouched)."}},"required":["fileId","name"],"title":"copy_drive_fileArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"description":"New file ID."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/rename_drive_file":{"post":{"operationId":"rename_drive_file","summary":"Rename a file.","description":"Rename a file.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/rename_drive_file"},"tags":["google_workspace"],"x-title":"Rename Drive File","x-access":"write","x-family":null,"x-returns":[{"field":"success","description":"Boolean indicating successful rename."}],"x-notes":{"Example":["rename_drive_file(fileId=\"1XYZ...\", newName=\"Updated Report 2026\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileId":{"title":"Fileid","type":"string","description":"the Drive file ID."},"newName":{"title":"Newname","type":"string","description":"New file name."}},"required":["fileId","newName"],"title":"rename_drive_fileArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"description":"Boolean indicating successful rename."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/delete_drive_file":{"post":{"operationId":"delete_drive_file","summary":"Delete or trash a file.","description":"Delete or trash a file.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/delete_drive_file"},"tags":["google_workspace"],"x-title":"Delete Drive File","x-access":"destructive","x-family":null,"x-returns":[{"field":"success","description":"Boolean indicating successful deletion."}],"x-notes":{"Example":["delete_drive_file(fileId=\"1XYZ...\")","delete_drive_file(fileId=\"1XYZ...\", permanent=True)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileId":{"title":"Fileid","type":"string","description":"the Drive file ID."},"permanent":{"default":false,"title":"Permanent","type":"boolean","description":"If true, permanently delete. If false, move to trash (default false)."}},"required":["fileId"],"title":"delete_drive_fileArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"description":"Boolean indicating successful deletion."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/save_url_to_drive":{"post":{"operationId":"save_url_to_drive","summary":"Save an Amazon image-CDN file (media-amazon.com, ssl-images-amazon.com and their .cn twins; at most 10 MB) straight to a Drive folder — the server streams it.","description":"Save an Amazon image-CDN file (media-amazon.com, ssl-images-amazon.com and their .cn twins; at most 10 MB) straight to a Drive folder — the server streams it. Any other host, including cdn.sellersheetai.com, is refused (403); use start_drive_upload for those.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/save_url_to_drive"},"tags":["google_workspace"],"x-title":"Save URL to Drive","x-access":"write","x-family":null,"x-returns":[{"field":"fileId","description":"the new Drive file's ID."},{"field":"name","description":"the name it was saved under."},{"field":"size","description":"bytes written."}],"x-notes":{"Example":["save_url_to_drive(url=\"https://m.media-amazon.com/images/I/61abc.jpg\", parentId=\"1ABC...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"url":{"title":"Url","type":"string","description":"https URL of the file (e.g. https://m.media-amazon.com/images/I/....jpg)."},"parentId":{"title":"Parentid","type":"string","description":"Target Drive folder ID."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name","description":"Optional file name. Defaults to the URL's basename."}},"required":["url","parentId"],"title":"save_url_to_driveArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"description":"the new Drive file's ID."},"name":{"description":"the name it was saved under."},"size":{"description":"bytes written."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/start_drive_upload":{"post":{"operationId":"start_drive_upload","summary":"Begin a direct upload of LOCAL bytes to Drive.","description":"Begin a direct upload of LOCAL bytes to Drive. The server returns an uploadUrl (a Google resumable session); you then PUT the file bytes DIRECTLY to that URL — the bytes never pass through the SellerSheet server. Use this for files you have on disk that are not reachable by URL (for URL sources use save_url_to_drive instead).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/start_drive_upload"},"tags":["google_workspace"],"x-title":"Start Drive Upload","x-access":"write","x-family":null,"x-returns":[{"field":"uploadUrl","description":"PUT the file bytes here, e.g. `curl -X PUT -H \"Content-Type: <mimeType>\" --data-binary @FILE \"<uploadUrl>\"`."},{"field":"expiresInDays","description":"Session validity (7)."},{"field":"howTo","description":"Recipe string. The PUT response body is the new file resource — read \"id\" from it to get the Drive fileId."}],"x-notes":{"Example":["start_drive_upload(parentId=\"1ABC...\", name=\"report.pdf\", mimeType=\"application/pdf\")","# xlsx -> native Google Sheet import:","start_drive_upload(parentId=\"1ABC...\", name=\"Q3 Model\",","    mimeType=\"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",","    convertTo=\"application/vnd.google-apps.spreadsheet\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parentId":{"title":"Parentid","type":"string","description":"Target Drive folder ID."},"name":{"title":"Name","type":"string","description":"File name to create in Drive."},"mimeType":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mimetype","description":"Optional MIME type OF THE BYTES YOU WILL PUT (default application/octet-stream)."},"convertTo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Convertto","description":"Optional Google Workspace target type — Drive converts the uploaded bytes on arrival. E.g. upload an .xlsx (mimeType='application/vnd.openxmlformats-officedocument.spreadsheetml.sheet') with convertTo='application/vnd.google-apps.spreadsheet' and the created file is a NATIVE Google Sheet (formulas, formats, dropdowns, notes, frozen panes preserved). When converting, your PUT request's Content-Type header must equal mimeType."}},"required":["parentId","name"],"title":"start_drive_uploadArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"uploadUrl":{"description":"PUT the file bytes here, e.g. `curl -X PUT -H \"Content-Type: <mimeType>\" --data-binary @FILE \"<uploadUrl>\"`."},"expiresInDays":{"description":"Session validity (7)."},"howTo":{"description":"Recipe string. The PUT response body is the new file resource — read \"id\" from it to get the Drive fileId."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/list_drive_permissions":{"post":{"operationId":"list_drive_permissions","summary":"List all permissions on a file.","description":"List all permissions on a file.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/list_drive_permissions"},"tags":["google_workspace"],"x-title":"List Drive Permissions","x-access":"read","x-family":null,"x-returns":[{"field":"permissions","description":"List of permission objects with id, type, role, emailAddress, domain, displayName."}],"x-notes":{"Example":["list_drive_permissions(fileId=\"1XYZ...\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileId":{"title":"Fileid","type":"string","description":"the Drive file ID."}},"required":["fileId"],"title":"list_drive_permissionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"description":"List of permission objects with id, type, role, emailAddress, domain, displayName."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/share_drive_file":{"post":{"operationId":"share_drive_file","summary":"Share a file with one person (email) or a whole domain (domain; email wins if both are passed).","description":"Share a file with one person (email) or a whole domain (domain; email wins if both are passed). Drive sends no notification email — tell the person yourself.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/share_drive_file"},"tags":["google_workspace"],"x-title":"Share Drive File","x-access":"write","x-family":null,"x-returns":[{"field":"permissionId","description":"Permission ID."}],"x-notes":{"Example":["share_drive_file(fileId=\"1XYZ...\", role=\"reader\", email=\"user@example.com\")","share_drive_file(fileId=\"1XYZ...\", role=\"reader\", domain=\"example.com\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileId":{"title":"Fileid","type":"string","description":"the Drive file ID."},"role":{"title":"Role","type":"string","description":"'reader', 'commenter' or 'writer'."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Email","description":"Email address to share with (for user sharing)."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Domain","description":"Domain to share with (for domain sharing)."}},"required":["fileId","role"],"title":"share_drive_fileArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"permissionId":{"description":"Permission ID."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/unshare_drive_file":{"post":{"operationId":"unshare_drive_file","summary":"Remove a permission from a file.","description":"Remove a permission from a file.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/unshare_drive_file"},"tags":["google_workspace"],"x-title":"Unshare Drive File","x-access":"destructive","x-family":null,"x-returns":[{"field":"success","description":"Boolean indicating successful removal."}],"x-notes":{"Example":["unshare_drive_file(fileId=\"1XYZ...\", permissionId=\"12345\")"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fileId":{"title":"Fileid","type":"string","description":"the Drive file ID."},"permissionId":{"title":"Permissionid","type":"string","description":"Permission ID to remove."}},"required":["fileId","permissionId"],"title":"unshare_drive_fileArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"description":"Boolean indicating successful removal."}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/orders_searchOrders":{"post":{"operationId":"orders_searchOrders","summary":"Search orders (Orders v2026-01-01): ONE Amazon page plus data.nextToken, the full v2026 filter set, and line items INLINE on each order (order.orderItems) — no separate items call.","description":"Search orders (Orders v2026-01-01): ONE Amazon page plus data.nextToken, the full v2026 filter set, and line items INLINE on each order (order.orderItems) — no separate items call. To sync a window, repeat with the same filters and pagination_token = data.nextToken until it is null; for an incremental sync pass last_updated_after = your last watermark. For one known order id use orders_getOrder. Amazon SP-API · searchOrders · GET /orders/2026-01-01/orders","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/orders_searchOrders"},"tags":["amazon_sp"],"x-title":"Orders Search Orders","x-access":"read","x-family":"sp.orders_2026-01-01","x-returns":[{"field":"data.orders / data.count","description":"this page's orders (line items at order.orderItems) and how many."},{"field":"data.nextToken","description":"pass it as pagination_token; null on the last page."},{"field":"data.createdBefore / data.lastUpdatedBefore","description":"the upper bound Amazon actually applied (clamped to ~2 minutes before the request) — whichever is non-null is the \"after\" watermark of your next incremental sync; use it instead of your own clock or you leave a gap."}],"x-notes":{"Gotchas":["Provide EXACTLY ONE of created_after or last_updated_after (the matching \"before\"","is optional); mixing the two pairs is InvalidInput."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"created_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created After","description":"ISO 8601 with the Z suffix ('2026-04-20T00:00:00Z') — v2026 rejects a naive timestamp. Exactly ONE of created_after or last_updated_after is required (Amazon refuses none or both)."},"created_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created Before","description":"ISO 8601 with the Z suffix ('2026-04-20T00:00:00Z') — v2026 rejects a naive timestamp. Exactly ONE of created_after or last_updated_after is required (Amazon refuses none or both)."},"last_updated_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Last Updated After","description":"the same rule; last_updated_after is the incremental-sync watermark."},"last_updated_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Last Updated Before","description":"the same rule; last_updated_after is the incremental-sync watermark."},"fulfillment_statuses":{"anyOf":[{"items":{"enum":["PENDING_AVAILABILITY","PENDING","UNSHIPPED","PARTIALLY_SHIPPED","SHIPPED","CANCELLED","UNFULFILLABLE"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Fulfillment Statuses","description":"the fulfillment states to keep. v2026 has no orderStatuses filter and no flat orderStatus field — filter here, or pass included_data ['FULFILLMENT'] and read order.fulfillment.fulfillmentStatus. Allowed: PENDING_AVAILABILITY | PENDING | UNSHIPPED | PARTIALLY_SHIPPED | SHIPPED | CANCELLED | UNFULFILLABLE."},"marketplace_ids":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Marketplace Ids","description":"OMIT it — the search is then scoped to the store ref's marketplace; a list (≤50) searches exactly those marketplaces and mixes their orders."},"fulfilled_by":{"anyOf":[{"items":{"enum":["MERCHANT","AMAZON"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Fulfilled By","description":"who fulfils the order; omit for both. Allowed: MERCHANT | AMAZON."},"included_data":{"anyOf":[{"items":{"enum":["RECIPIENT","PROCEEDS","EXPENSE","PROMOTION","CANCELLATION","FULFILLMENT","PACKAGES","TAX","PAYMENT","FULFILLMENT_ORDERS"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Included Data","description":"expansion selectors per order, as on orders_getOrder — PACKAGES carries tracking inline. Allowed (the subset that needs no Restricted Data Token): RECIPIENT | PROCEEDS | EXPENSE | PROMOTION | CANCELLATION | FULFILLMENT | PACKAGES | TAX | PAYMENT | FULFILLMENT_ORDERS."},"max_results_per_page":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Max Results Per Page","description":"1–100 (default 100)."},"pagination_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"orders_searchOrdersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"orders":{"description":"this page's orders (line items at order.orderItems) and how many."},"count":{"description":"this page's orders (line items at order.orderItems) and how many."},"nextToken":{"description":"pass it as pagination_token; null on the last page."},"createdBefore":{"description":"the upper bound Amazon actually applied (clamped to ~2 minutes before the request) — whichever is non-null is the \"after\" watermark of your next incremental sync; use it instead of your own clock or you leave a gap."},"lastUpdatedBefore":{"description":"the upper bound Amazon actually applied (clamped to ~2 minutes before the request) — whichever is non-null is the \"after\" watermark of your next incremental sync; use it instead of your own clock or you leave a gap."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/orders_getOrder":{"post":{"operationId":"orders_getOrder","summary":"Get one order (Orders v2026-01-01) with its line items inline (order.orderItems) and any included_data expansions.","description":"Get one order (Orders v2026-01-01) with its line items inline (order.orderItems) and any included_data expansions. To find orders by date or status use orders_searchOrders. Amazon SP-API · getOrder · GET /orders/2026-01-01/orders/{orderId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/orders_getOrder"},"tags":["amazon_sp"],"x-title":"Orders Get Order","x-access":"read","x-family":"sp.orders_2026-01-01","x-returns":[{"field":"data.order","description":"the order — line items at data.order.orderItems[], identifiers under"},{"field":"data.order.product","description":"{orderItemId, quantityOrdered, product: {asin, title, sellerSku,"},{"description":"condition, price}}."},{"field":"data.includedData","description":"the selectors applied."}],"x-notes":{"Gotchas":["- Line items are not an includedData option — they come back on every call.","- Read item['product']['sellerSku'], not item['sellerSku']: the identifiers are","    nested under product, not flat on the item."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"order_id":{"title":"Order Id","type":"string","description":"e.g. '113-1234567-8901234'."},"included_data":{"anyOf":[{"items":{"enum":["RECIPIENT","PROCEEDS","EXPENSE","PROMOTION","CANCELLATION","FULFILLMENT","PACKAGES","TAX","PAYMENT","FULFILLMENT_ORDERS"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Included Data","description":"expansion selectors; omit for the order and its line items with no expansions. PROCEEDS (revenue breakdown), EXPENSE (costs), PROMOTION (discounts), CANCELLATION, FULFILLMENT (how it ships, plus per-item quantityFulfilled / quantityUnfulfilled), PACKAGES (packages and tracking), TAX, PAYMENT (payment method), FULFILLMENT_ORDERS (linked MCF orders), RECIPIENT (order.recipient.deliveryAddress — city / countryCode / postalCode)."}},"required":["store","order_id"],"title":"orders_getOrderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"order":{"description":"the order — line items at data.order.orderItems[], identifiers under","properties":{"product":{"description":"{orderItemId, quantityOrdered, product: {asin, title, sellerSku,"}}},"includedData":{"description":"the selectors applied."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_createInboundPlan":{"post":{"operationId":"fbaInbound_createInboundPlan","summary":"Create an FBA inbound plan on Amazon (single-step).","description":"Create an FBA inbound plan on Amazon (single-step). Amazon SP-API · createInboundPlan · POST /inbound/fba/2024-03-20/inboundPlans Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Use it to run the steps one by one — Split First, an India (IN) plan (fbaInbound_orchestrate_packing fails there because IN has no packing options), or a re-plan; for an ordinary Box First plan prefer fbaInbound_orchestrate_packing. Box First and Split First create the plan the same way; they differ only in the next call (Box First: fbaInbound_generatePackingOptions; Split First: fbaInbound_generatePlacementOptions). The store ref sets destinationMarketplaces.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_createInboundPlan"},"tags":["amazon_sp"],"x-title":"FBA Inbound Create Inbound Plan","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.inboundPlanId","description":"write this to STA sheet immediately (38-char id)."},{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus — creation is ASYNC (HTTP 202), so the plan is not usable until that operation reports SUCCESS."}],"x-notes":{"Body (Amazon schema)":["destinationMarketplaces*: [string] (exactly 1) (max 20 chars)","items*: [{expiration, labelOwner*: AMAZON | SELLER | NONE, manufacturingLotCode (max 256 chars), msku* (max 255 chars), prepOwner*: AMAZON | SELLER | NONE, quantity* (1–500000)}] (1–2000)","name: string (max 40 chars)","sourceAddress*: {addressLine1* (max 180 chars), addressLine2 (max 60 chars), city* (max 30 chars), companyName (max 50 chars), countryCode* (2–2 chars), districtOrCounty (max 50 chars), email (max 1024 chars), name* (max 50 chars), phoneNumber* (max 20 chars), postalCode* (max 32 chars), stateOrProvinceCode (max 64 chars)}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_name":{"title":"Plan Name","type":"string","description":"the plan's name, 1–40 characters."},"source_address":{"additionalProperties":true,"title":"Source Address","type":"object","description":"AddressInput. Required: name, addressLine1, city, countryCode (2-char ISO 3166-1 alpha-2), postalCode, phoneNumber. Optional: addressLine2, companyName, districtOrCounty, email, stateOrProvinceCode."},"items":{"items":{},"title":"Items","type":"array","description":"list of item dicts, 1-2000 items. Each: msku (required, maxLength 255), quantity (required, 1-500000), labelOwner (required), prepOwner (required). Optional per item: expiration (YYYY-MM-DD), manufacturingLotCode. labelOwner (who applies FNSKU labels). Allowed: AMAZON | SELLER | NONE. prepOwner (who performs unit prep). Allowed: AMAZON | SELLER | NONE. prepOwner is region- and SKU-dependent live: AMAZON is refused in MENA (FBA_INB_0237 \"Amazon does not provide prep service in the current region\" — use SELLER), and a SKU that requires no prep refuses SELLER (\"does not require prepOwner but SELLER was assigned\" — use NONE)."}},"required":["store","plan_name","source_address","items"],"title":"fbaInbound_createInboundPlanArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"inboundPlanId":{"description":"write this to STA sheet immediately (38-char id)."},"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus — creation is ASYNC (HTTP 202), so the plan is not usable until that operation reports SUCCESS."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_confirmPlacementOption":{"post":{"operationId":"fbaInbound_confirmPlacementOption","summary":"Confirm one placement option of an inbound plan; the server waits until Amazon's operation finishes.","description":"Confirm one placement option of an inbound plan; the server waits until Amazon's operation finishes. Next, generate and confirm transportation for the plan's shipments (or use fbaInbound_confirm_plan_options for placement + transport in one call). Amazon SP-API · confirmPlacementOption · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions/{placementOptionId}/confirmation Amazon SP-API · getInboundOperationStatus · GET /inbound/fba/2024-03-20/operations/{operationId} Gate: commit, choice, fee-bearing — interactive: restate the option and the amount, wait for a typed CONFIRM; autopilot: only within the seller's instruction, named rule (one option, no tie) and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_confirmPlacementOption"},"tags":["amazon_sp"],"x-title":"FBA Inbound Confirm Placement Option","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.inboundPlanId","description":"confirmed plan ID."},{"field":"data.placementOptionId","description":"confirmed option ID."},{"field":"data.confirmed","description":"true once Amazon's operation reached SUCCESS."}],"x-notes":{"Workflow":["1. The human picks one placementOptionId — from fbaInbound_listPlacementOptions, or","   the plan workbook's \"2.\" chip (row 6; the id is the text before the first space).","2. Call this tool."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"placement_option_id":{"maxLength":38,"minLength":38,"title":"Placement Option Id","type":"string","description":"the placementOptionId (from fbaInbound_listPlacementOptions)."}},"required":["store","plan_id","placement_option_id"],"title":"fbaInbound_confirmPlacementOptionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"inboundPlanId":{"description":"confirmed plan ID."},"placementOptionId":{"description":"confirmed option ID."},"confirmed":{"description":"true once Amazon's operation reached SUCCESS."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_get_labels":{"post":{"operationId":"fbaInbound_get_labels","summary":"Download the box-label PDF of a confirmed shipment (v0 getLabels): the server fetches Amazon's downloadURL, cuts the pages to the label size and returns the PDF base64.","description":"Download the box-label PDF of a confirmed shipment (v0 getLabels): the server fetches Amazon's downloadURL, cuts the pages to the label size and returns the PDF base64. For per-unit FNSKU item labels use fbaInbound_createMarketplaceItemLabels. Amazon SP-API · getLabels · GET /fba/inbound/v0/shipments/{shipmentId}/labels Amazon SP-API · getShipment · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_get_labels"},"tags":["amazon_sp"],"x-title":"FBA Inbound Get Labels","x-access":"write","x-family":"sp.fulfillmentInboundV0","x-returns":[{"field":"data.labelData","description":"the PDF, base64 — decode and print."},{"field":"data.labelSize / data.pageCount / data.pageType","description":"what was applied."},{"field":"data.downloadURL","description":"Amazon's presigned URL."},{"field":"data.driveUrl / data.driveFileId / data.fileName","description":"the saved PDF — only with sta_spreadsheet_id or plan_folder_id."},{"field":"data.planFolderId / data.links / data.skipped","description":"the folder, which cells became links ({staOptions, manageShipments}) and why a save was skipped."}],"x-notes":{"Gotchas":["Not every page type works on every shipment — Amazon answers \"Please check the","parameter request or call GetValidPageTypesForShipment\" when it disagrees (on a","Non-Partnered shipment PackageLabel_Letter_2 is refused where","PackageLabel_Plain_Paper succeeds): treat the enum as candidates and fall back to","PackageLabel_Plain_Paper."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"inbound_plan_id":{"maxLength":38,"minLength":38,"title":"Inbound Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed). An FBA confirmation id (FBA1234ABCD) also works — Amazon keys labels on it; the server resolves it (data.shipmentConfirmationId)."},"page_type":{"default":"PackageLabel_Letter_2","enum":["PackageLabel_Letter_2","PackageLabel_Letter_4","PackageLabel_Letter_6","PackageLabel_Letter_6_CarrierLeft","PackageLabel_A4_2","PackageLabel_A4_4","PackageLabel_Plain_Paper","PackageLabel_Plain_Paper_CarrierBottom","PackageLabel_Thermal","PackageLabel_Thermal_Unified","PackageLabel_Thermal_NonPCP","PackageLabel_Thermal_No_Carrier_Rotation"],"title":"Page Type","type":"string","description":"the label sheet layout — not every layout suits every shipment (Gotchas). Default: PackageLabel_Letter_2. Allowed: PackageLabel_Letter_2 | PackageLabel_Letter_4 | PackageLabel_Letter_6 | PackageLabel_Letter_6_CarrierLeft | PackageLabel_A4_2 | PackageLabel_A4_4 | PackageLabel_Plain_Paper | PackageLabel_Plain_Paper_CarrierBottom | PackageLabel_Thermal | PackageLabel_Thermal_Unified | PackageLabel_Thermal_NonPCP | PackageLabel_Thermal_No_Carrier_Rotation."},"label_type":{"default":"BARCODE_2D","enum":["BARCODE_2D","UNIQUE","PALLET"],"title":"Label Type","type":"string","description":"the kind of label — BARCODE_2D box labels, UNIQUE for Transparency-enrolled items, PALLET for LTL/FTL (with number_of_pallets). Default: BARCODE_2D."},"number_of_packages":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Number Of Packages","description":"package labels to print — pass it with page_size on a Non-Partnered or LTL shipment."},"package_labels_to_print":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Package Labels To Print","description":"CartonIds, to reprint a subset."},"number_of_pallets":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Number Of Pallets","description":"pallet labels; with label_type PALLET only."},"page_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"1–1000; REQUIRED on Non-Partnered and LTL shipments (Amazon: \"pageSize must be provided for Non-Partnered and LTL Shipments\")."},"page_start_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Page Start Index","description":"REQUIRED with page_size on Non-Partnered LTL shipments."},"label_size":{"default":"","title":"Label Size","type":"string","description":"the plan workbook's \"FBA Box Label Size\" (row 9) — '100x150 mm', '100x100 mm' (bare WxH = mm; '4x6 in' works). Pages are CUT, never scaled: 100x150 keeps Amazon's page as is, 100x100 keeps the top square (where the label sits). Blank = Amazon's bytes untouched."},"sta_spreadsheet_id":{"default":"","title":"Sta Spreadsheet Id","type":"string","description":"the plan workbook (mode A) — the server saves <FBA id>.pdf into the plan's Drive folder and turns three cells into links (STA-Options FBA ID, Manage Shipments fbaId and fbaLabel); you write nothing for them. Omit it in mode B and archive the PDF yourself (start_drive_upload) if the user wants it."},"plan_folder_id":{"default":"","title":"Plan Folder Id","type":"string","description":"override the Drive folder (rare)."},"fba_spreadsheet_id":{"default":"","title":"Fba Spreadsheet Id","type":"string","description":"override the FBA spreadsheet for the Manage Shipments link (defaults to the workspace setting)."}},"required":["store","inbound_plan_id","shipment_id"],"title":"fbaInbound_get_labelsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"labelData":{"description":"the PDF, base64 — decode and print."},"labelSize":{"description":"what was applied."},"pageCount":{"description":"what was applied."},"pageType":{"description":"what was applied."},"downloadURL":{"description":"Amazon's presigned URL."},"driveUrl":{"description":"the saved PDF — only with sta_spreadsheet_id or plan_folder_id."},"driveFileId":{"description":"the saved PDF — only with sta_spreadsheet_id or plan_folder_id."},"fileName":{"description":"the saved PDF — only with sta_spreadsheet_id or plan_folder_id."},"planFolderId":{"description":"the folder, which cells became links ({staOptions, manageShipments}) and why a save was skipped."},"links":{"description":"the folder, which cells became links ({staOptions, manageShipments}) and why a save was skipped."},"skipped":{"description":"the folder, which cells became links ({staOptions, manageShipments}) and why a save was skipped."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_updateShipmentTrackingDetails":{"post":{"operationId":"fbaInbound_updateShipmentTrackingDetails","summary":"Upload carrier tracking for one shipment to Amazon.","description":"Upload carrier tracking for one shipment to Amazon. Amazon SP-API · updateShipmentTrackingDetails · PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/trackingDetails Amazon SP-API · getInboundOperationStatus · GET /inbound/fba/2024-03-20/operations/{operationId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Async — the server polls the returned operationId to completion. This is the non-Amazon-partnered (USE_YOUR_OWN_CARRIER) flow. TrackingDetailsInput is a union of exactly two shapes — supply ONE. Small Parcel tracking is per BOX, so ONE call carries every box of the shipment; there is no carrier field on this operation at all.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_updateShipmentTrackingDetails"},"tags":["amazon_sp"],"x-title":"FBA Inbound Update Shipment Tracking Details","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.uploaded","description":"True once the operation reached SUCCESS."},{"field":"data.operation","description":"the final getInboundOperationStatus payload."}],"x-notes":{"Workflow":["1. fbaInbound_listShipmentBoxes — the boxId (FBAxxxxxxxx) of every box.","2. Call this tool once per shipment with all its boxes."],"Body (Amazon schema; updateShipmentTrackingDetails)":["trackingDetails*: {ltlTrackingDetail: {billOfLadingNumber, freightBillNumber*}, spdTrackingDetail: {spdTrackingItems*}}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"spd_tracking_items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Spd Tracking Items","description":"Small Parcel (SPD) tracking, one entry per box: [{boxId, trackingId}]. boxId is the FBAxxxxxxxx ID from fbaInbound_listShipmentBoxes / fbaInbound_create_packing_list (maxLength 1024); trackingId is the carrier's number (maxLength 64). Pass exactly one of spd_tracking_items / ltl_tracking_detail — both or neither is refused. boxIds exist only after the shipment's transportation is confirmed."},"ltl_tracking_detail":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Ltl Tracking Detail","description":"LTL/FTL freight tracking, shipment-level: {freightBillNumber: [str] (required, exactly 1), billOfLadingNumber: str (optional, ≤1024)}."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_updateShipmentTrackingDetailsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"uploaded":{"description":"True once the operation reached SUCCESS."},"operation":{"description":"the final getInboundOperationStatus payload."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_sync_shipment_status":{"post":{"operationId":"fbaInbound_sync_shipment_status","summary":"One shipment's current Amazon status plus a terminal flag — a cheap poll; for the full shipment object use fbaInbound_getShipment.","description":"One shipment's current Amazon status plus a terminal flag — a cheap poll; for the full shipment object use fbaInbound_getShipment. Poll a shipment until data.terminal is true. Amazon SP-API · getShipment · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_sync_shipment_status"},"tags":["amazon_sp"],"x-title":"FBA Inbound Sync Shipment Status","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.status","description":"current shipment status string."},{"field":"data.terminal","description":"true for CLOSED, CANCELLED, ABANDONED and DELETED; SHIPPED and the later in-transit, delivered, checked-in and receiving states are not terminal — poll those again later (hours, not seconds)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_sync_shipment_statusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"current shipment status string."},"terminal":{"description":"true for CLOSED, CANCELLED, ABANDONED and DELETED; SHIPPED and the later in-transit, delivered, checked-in and receiving states are not terminal — poll those again later (hours, not seconds)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_create_sta_sheet":{"post":{"operationId":"fbaInbound_create_sta_sheet","summary":"Create the plan workbook for an FBA inbound plan — the SAME workbook the sidebar's \"Create STA SS\" builds, so the sidebar buttons can continue any step: the stepper tab (STA-BoxFir","description":"Create the plan workbook for an FBA inbound plan — the SAME workbook the sidebar's \"Create STA SS\" builds, so the sidebar buttons can continue any step: the stepper tab (STA-BoxFirst / STA-SplitFirst) copied from the master template into a workbook named after the plan in its own folder under Shipments/<store>/<CC>/<yyyy>/<MM>/; the Product Info IMPORTRANGE re-targeted to the FBA spreadsheet, row 9 filled by label, MSKUs from row 14, a _state tab (STA_CREATED). The human clicks the STA tab's D3 cell once (\"Allow access\" — the server cannot grant it), then fills Box No. (column A) per item row — Split First: Total Qty (column F) — before fbaInbound_orchestrate_packing.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_create_sta_sheet"},"tags":["sellersheet"],"x-title":"FBA Inbound Create STA Sheet","x-access":"write","x-family":null,"x-returns":[{"field":"data.staSpreadsheetId / data.spreadsheetUrl / data.tabName / data.gid","description":"the new workbook and its stepper tab."},{"field":"data.planFolderId / data.planFolderUrl / data.planFolderName","description":"the plan's Drive folder."},{"field":"data.importrangeGranted","description":"always false here (the D3 click above)."},{"field":"data.addressKeyKnown","description":"false only when no warehouse_code was given or Shipment Setting could not be read — the human fills Send From Address (D9)."},{"field":"data.manageShipmentsFormulas","description":"{planFolder, planName} — write both into the plan's Manage Shipments row (columns by row-1 key) so the sidebar finds the workbook."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_name":{"title":"Plan Name","type":"string","description":"the plan name (the plan's Manage Shipments row)."},"skus":{"items":{},"title":"Skus","type":"array","description":"the plan's MSKUs (the Manage Shipments SKUs cell, newline-split)."},"case_packed":{"default":"YES","title":"Case Packed","type":"string","description":"'YES' (default) | 'NO'."},"pallet_packed":{"default":"NO","title":"Pallet Packed","type":"string","description":"'YES' | 'NO' (default)."},"shipping_mode":{"default":"","title":"Shipping Mode","type":"string","description":"the row-9 Shipping Mode GROUP (narrows the transport dropdown later); empty = every mode. Allowed: SPD | LTL / FTL."},"shipping_solution":{"default":"","title":"Shipping Solution","type":"string","description":"the row-9 Shipping Solution; empty = both. Allowed: AMAZON_PARTNERED_CARRIER | USE_YOUR_OWN_CARRIER."},"preferred_carrier":{"default":"Other","title":"Preferred Carrier","type":"string","description":"e.g. 'DHL', 'UPS'; default 'Other'."},"fulfillment_split":{"default":"Box First, Split Later","title":"Fulfillment Split","type":"string","description":"text containing 'Split First' picks STA-SplitFirst, anything else STA-BoxFirst (default 'Box First, Split Later')."},"ship_date":{"default":"","title":"Ship Date","type":"string","description":"ISO dates (e.g. '2026-04-07')."},"delivery_window_start_date":{"default":"","title":"Delivery Window Start Date","type":"string","description":"ISO dates (e.g. '2026-04-07')."},"unit_of_weight":{"default":"KG","title":"Unit Of Weight","type":"string","description":"the row-9 units; defaults 'KG' and 'CM'."},"unit_of_dimension":{"default":"CM","title":"Unit Of Dimension","type":"string","description":"the row-9 units; defaults 'KG' and 'CM'."},"fnsku_label_size":{"default":"50x30 mm","title":"Fnsku Label Size","type":"string","description":"the row-9 label sizes; defaults '50x30 mm' and '100x100 mm'."},"fba_box_label_size":{"default":"100x100 mm","title":"Fba Box Label Size","type":"string","description":"the row-9 label sizes; defaults '50x30 mm' and '100x100 mm'."},"warehouse_code":{"default":"","title":"Warehouse Code","type":"string","description":"the Shipment Setting row's code (e.g. 'CN'); row 9 gets the key '<store>-<CC>-<code>' the sidebar resolves to the address. Refused before anything is created when that key is not a complete Shipment Setting row — the refusal lists the codes that exist."},"fba_spreadsheet_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Fba Spreadsheet Id","description":"the user's SellerSheet FBA spreadsheet (defaults to the workspace setting) — the Product Info donor and Manage Shipments."},"parent_folder_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Folder Id","description":"Drive folder override."},"source_spreadsheet_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source Spreadsheet Id","description":"older name for fba_spreadsheet_id (that one wins)."}},"required":["store","plan_name","skus"],"title":"fbaInbound_create_sta_sheetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"staSpreadsheetId":{"description":"the new workbook and its stepper tab."},"spreadsheetUrl":{"description":"the new workbook and its stepper tab."},"tabName":{"description":"the new workbook and its stepper tab."},"gid":{"description":"the new workbook and its stepper tab."},"planFolderId":{"description":"the plan's Drive folder."},"planFolderUrl":{"description":"the plan's Drive folder."},"planFolderName":{"description":"the plan's Drive folder."},"importrangeGranted":{"description":"always false here (the D3 click above)."},"addressKeyKnown":{"description":"false only when no warehouse_code was given or Shipment Setting could not be read — the human fills Send From Address (D9)."},"manageShipmentsFormulas":{"description":"{planFolder, planName} — write both into the plan's Manage Shipments row (columns by row-1 key) so the sidebar finds the workbook."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_orchestrate_packing":{"post":{"operationId":"fbaInbound_orchestrate_packing","summary":"Create an FBA inbound plan through to PLACEMENT OPTIONS and stop: setPrepDetails → createInboundPlan → generate and confirm the packing option → setPackingInformation → generatePla","description":"Create an FBA inbound plan through to PLACEMENT OPTIONS and stop: setPrepDetails → createInboundPlan → generate and confirm the packing option → setPackingInformation → generatePlacementOptions, each operation polled. Allow ~60 s. The human then picks a placement option for fbaInbound_generate_shipment_options. The marketplace comes from the store ref. Requires SP write access. Amazon SP-API · setPrepDetails · POST /inbound/fba/2024-03-20/items/prepDetails Amazon SP-API · createInboundPlan · POST /inbound/fba/2024-03-20/inboundPlans Amazon SP-API · getInboundOperationStatus · GET /inbound/fba/2024-03-20/operations/{operationId} Amazon SP-API · generatePackingOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions Amazon SP-API · listPackingOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions Amazon SP-API · confirmPackingOption · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions/{packingOptionId}/confirmation Amazon SP-API · setPackingInformation · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingInformation Amazon SP-API · generatePlacementOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions Amazon SP-API · listPlacementOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions Amazon SP-API · getShipment · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId} Amazon SP-API · listShipmentBoxes · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/boxes Gate: approve, choice — interactive: show the change and the option (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change, within named rule (one option, no tie); otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_orchestrate_packing"},"tags":["amazon_sp"],"x-title":"FBA Inbound Orchestrate Packing","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.planId","description":"the inbound plan."},{"field":"data.packingOptionId / data.packingGroupId","description":"the confirmed packing."},{"field":"data.requiresHumanSelection","description":"true when several packing options need a human choice — data.packingOptions lists them and nothing further was done."},{"field":"data.placementOptions","description":"[{placementOptionId, status, expiration, shipmentCount, shipmentIds, placementFee, currency, aiRank, aiRec, shipments: [{shipmentId, warehouseId}]}] ranked by fee."},{"field":"data.totalQty / data.totalBoxes","description":"the plan's totals."}],"x-notes":{"Params (Amazon schema; getInboundOperationStatus)":["operationId*: string (max 38 chars)"],"Params (Amazon schema; generatePackingOptions)":["inboundPlanId*: string (max 38 chars)"],"Params (Amazon schema; listPackingOptions)":["inboundPlanId*: string (max 38 chars)","pageSize: integer (1–20)","paginationToken: string (max 1024 chars)"],"Params (Amazon schema; confirmPackingOption)":["inboundPlanId*: string (max 38 chars)","packingOptionId*: string (max 38 chars)"],"Params (Amazon schema; setPackingInformation)":["inboundPlanId*: string (max 38 chars)"],"Params (Amazon schema; generatePlacementOptions)":["inboundPlanId*: string (max 38 chars)"],"Params (Amazon schema; listPlacementOptions)":["inboundPlanId*: string (max 38 chars)","pageSize: integer (1–20)","paginationToken: string (max 1024 chars)","… (8 more lines; the Docs link above)"],"Body (Amazon schema; setPrepDetails)":["marketplaceId*: string (max 20 chars)","mskuPrepDetails*: [{msku* (max 255 chars), prepCategory*, prepTypes*}] (1–100)","mskuPrepDetails.prepCategory: ADULT | BABY | FC_PROVIDED | FRAGILE | GRANULAR | HANGER | LIQUID | PERFORATED | SET | SHARP | SMALL | TEXTILE | UNKNOWN | NONE","mskuPrepDetails.prepTypes: [ITEM_BLACK_SHRINKWRAP | ITEM_BLANKSTK | ITEM_BOXING | ITEM_BUBBLEWRAP | ITEM_CAP_SEALING | ITEM_DEBUNDLE | ITEM_HANG_GARMENT | ITEM_LABELING | ITEM_NO_PREP | ITEM_POLYBAGGING | ITEM_RMOVHANG | ITEM_SETCREAT | ITEM_SETSTK | ITEM_SIOC | ITEM_SUFFOSTK | ITEM_TAPING]","Full schema: the Docs link above."],"Body (Amazon schema; createInboundPlan)":["destinationMarketplaces*: [string] (exactly 1) (max 20 chars)","items*: [{expiration, labelOwner*: AMAZON | SELLER | NONE, manufacturingLotCode (max 256 chars), msku* (max 255 chars), prepOwner*: AMAZON | SELLER | NONE, quantity* (1–500000)}] (1–2000)","sourceAddress*: {addressLine1* (max 180 chars), addressLine2 (max 60 chars), city* (max 30 chars), companyName (max 50 chars), countryCode* (2–2 chars), districtOrCounty (max 50 chars), email (max 1024 chars), name* (max 50 chars), phoneNumber* (max 20 chars), postalCode* (max 32 chars), stateOrProvinceCode (max 64 chars)}","+ 1 more: name","Full schema: the Docs link above."],"Body (Amazon schema; setPackingInformation): {packageGroupings: [PackageGroupingInput]} (min 1), each item":["boxes*: [{contentInformationSource*, dimensions*: {height*, length*, unitOfMeasurement*, width*}, items: [{expiration, labelOwner*, manufacturingLotCode, msku*, prepOwner*, quantity*}], quantity* (1–10000),","  weight*: {unit*, value*}}] (1–5000)","… (8 more lines; Full schema: the Docs link above.)"],"Workflow":["With a plan workbook, read the item rows (row 14 on) by the row-1 machine keys —","boxNo (\"1\", or \"2~4\" for boxes 2 to 4; several rows with one boxNo share a box),","msku, qtyPerBox, boxDimensions (\"LxWxH\"), boxWeight, labelOwner, prepOwner,","prepCategory, prepTypes — never by column letter, and build items (totals) and boxes","from them. Afterwards show the placement options (placementFee, shipmentCount,","warehouses; aiRank 1 = lowest fee) and let the HUMAN pick; the stepper, Manage","Shipments and _state cells to write are in the fba-inbound skill."],"Gotchas":["A packing option with several packing groups is refused (the compound packs one","group) — run fbaInbound_setPackingInformation per packingGroupId instead."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_name":{"title":"Plan Name","type":"string","description":"createInboundPlan name, ≤40 chars."},"source_address":{"additionalProperties":true,"title":"Source Address","type":"object","description":"{name, addressLine1, city, countryCode (ISO 3166-1 alpha-2), postalCode, phoneNumber} required; addressLine2, companyName, districtOrCounty, email, stateOrProvinceCode optional."},"items":{"items":{},"title":"Items","type":"array","description":"1–2000 plan-level totals (not per box): [{msku (≤255), quantity (1–500000), labelOwner, prepOwner, expiration (YYYY-MM-DD, optional), manufacturingLotCode (optional, ≤256)}]. labelOwner and prepOwner: AMAZON | SELLER | NONE."},"boxes":{"items":{},"title":"Boxes","type":"array","description":"1–5000 box specs: [{contentInformationSource, dimensions: {length, width, height, unitOfMeasurement IN | CM}, weight: {value, unit LB | KG}, quantity (1–10000 boxes of this spec), items: [{msku, quantity, labelOwner, prepOwner}]}]. contentInformationSource: BOX_CONTENT_PROVIDED (items required) | MANUAL_PROCESS | BARCODE_2D (both without items)."},"msku_prep_details":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Msku Prep Details","description":"1–100 of [{msku, prepCategory, prepTypes}], all three required — the prep the plan's MSKUs need (values in the setPrepDetails body below)."},"selected_packing_option_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Selected Packing Option Id","description":"second call only — the human's packingOptionId from data.packingOptions, sent with plan_id and the same items and boxes; the plan is continued, never re-created."},"plan_id":{"default":"","title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans). Second call: the first call's data.planId with selected_packing_option_id. Alone, it continues THAT plan from generatePackingOptions — a plan_id never creates a second plan."},"sta_spreadsheet_id":{"default":"","title":"Sta Spreadsheet Id","type":"string","description":"the plan workbook's spreadsheet id (from fbaInbound_create_sta_sheet) — the server then renders the STA-Options tab (fee summary, one block per placement with every shipment's warehouse, status, Total QTY, Boxes, Weight and Volume); omit it and nothing touches a sheet."}},"required":["store","plan_name","source_address","items","boxes"],"title":"fbaInbound_orchestrate_packingArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"planId":{"description":"the inbound plan."},"packingOptionId":{"description":"the confirmed packing."},"packingGroupId":{"description":"the confirmed packing."},"requiresHumanSelection":{"description":"true when several packing options need a human choice — data.packingOptions lists them and nothing further was done."},"placementOptions":{"description":"[{placementOptionId, status, expiration, shipmentCount, shipmentIds, placementFee, currency, aiRank, aiRec, shipments: [{shipmentId, warehouseId}]}] ranked by fee."},"totalQty":{"description":"the plan's totals."},"totalBoxes":{"description":"the plan's totals."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_generate_shipment_options":{"post":{"operationId":"fbaInbound_generate_shipment_options","summary":"The transportation options + delivery windows for ONE placement option: the cheapest `limit` partnered options per shipping mode and, when named, one carrier type.","description":"The transportation options + delivery windows for ONE placement option: the cheapest `limit` partnered options per shipping mode and, when named, one carrier type. Nothing is selected — the HUMAN picks ONE transportationOptionId per shipment (+ ONE deliveryWindowOptionId for own carrier); then fbaInbound_confirm_plan_options with those ids. 30–60 s. Amazon SP-API · listPlacementOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions Amazon SP-API · generateTransportationOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions Amazon SP-API · getInboundOperationStatus · GET /inbound/fba/2024-03-20/operations/{operationId} Amazon SP-API · listTransportationOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions Amazon SP-API · getShipment · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId} Amazon SP-API · listShipmentBoxes · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/boxes Amazon SP-API · generateDeliveryWindowOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions Amazon SP-API · listDeliveryWindowOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Mode A: pass sta_spreadsheet_id and the server fills the picked STA-Options block; mode B: omit it. The answer is a view of Amazon's list (duplicates collapsed, constant fields dropped); data.counts carries Amazon's totals.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_generate_shipment_options"},"tags":["amazon_sp"],"x-title":"FBA Inbound Generate Shipment Options","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.placementFee / data.currency","description":"the picked placement's fee."},{"field":"data.shipments","description":"[{shipmentId, warehouseId, destination, status, totals,"},{"field":"data.shipments.partnered","description":"[{transportationOptionId, shippingMode, carrierName, carrierCode,"},{"description":"cost, currency, preconditions}] cheapest first; ownCarrier: [same, no cost];"},{"description":"deliveryWindows: [{deliveryWindowOptionId, startDate, endDate,"},{"description":"availabilityType}] earliest first; deliveryWindowsValidUntil}]."},{"field":"data.counts","description":"{partnered, ownCarrier, deliveryWindows} — Amazon's totals."}],"x-notes":{"Params (Amazon schema; listPlacementOptions)":["inboundPlanId*: string (max 38 chars)","pageSize: integer (1–20)","paginationToken: string (max 1024 chars)"],"Params (Amazon schema; generateTransportationOptions)":["inboundPlanId*: string (max 38 chars)"],"Params (Amazon schema; getInboundOperationStatus)":["operationId*: string (max 38 chars)"],"Params (Amazon schema; listTransportationOptions)":["inboundPlanId*: string (max 38 chars)","pageSize: integer (1–20)","paginationToken: string (max 1024 chars)","placementOptionId: string (max 38 chars)","shipmentId: string (max 38 chars)"],"Params (Amazon schema; getShipment)":["inboundPlanId*: string (max 38 chars)","shipmentId*: string (max 38 chars)"],"Params (Amazon schema; listShipmentBoxes)":["inboundPlanId*: string (max 38 chars)","… (11 more lines; the Docs link above)"],"Body (Amazon schema; generateTransportationOptions)":["placementOptionId*: string (38–38 chars)","shipmentTransportationConfigurations*: [{contactInformation: {email, name*, phoneNumber*},","  freightInformation: {declaredValue, freightClass}, pallets: [{dimensions, quantity*, stackability,","    weight}], readyToShipWindow*: {start*}, shipmentId* (38–38 chars)}] (min 1)","  shipmentTransportationConfigurations.pallets.dimensions.unitOfMeasurement: IN | CM","  shipmentTransportationConfigurations.pallets.stackability: STACKABLE | NON_STACKABLE","  shipmentTransportationConfigurations.pallets.weight.unit: LB | KG"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"placement_option_id":{"maxLength":38,"minLength":38,"title":"Placement Option Id","type":"string","description":"the placementOptionId (from fbaInbound_listPlacementOptions)."},"ship_date":{"default":"","title":"Ship Date","type":"string","description":"REQUIRED, YYYY-MM-DD — the ready-to-ship date (sent as readyToShipWindow.start). Amazon marks windows that start before it AVAILABLE: offer only windows starting on or after it (and the delivery-window start date, when given)."},"pallet_info":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Pallet Info","description":"freight config for FREIGHT_* modes, sent on every shipment: {freightInformation: {declaredValue: {amount: N, code: 'USD'}, freightClass: 'FC_50'}, pallets: [{dimensions: {length, width, height, unitOfMeasurement: 'IN'|'CM'}, weight: {value, unit: 'LB'|'KG'}, quantity: N, stackability: 'STACKABLE'|'NON_STACKABLE'}]}. freightClass. Allowed: NONE | FC_50 | FC_55 | FC_60 | FC_65 | FC_70 | FC_77_5 | FC_85 | FC_92_5 | FC_100 | FC_110 | FC_125 | FC_150 | FC_175 | FC_200 | FC_250 | FC_300 | FC_400 | FC_500."},"limit":{"default":3,"title":"Limit","type":"integer","description":"the cheapest partnered options per shipping mode per shipment (default 3; 0 = all); own-carrier options are never capped. For a carrier not shown, read fbaInbound_listTransportationOptions."},"shipping_solution":{"default":"","title":"Shipping Solution","type":"string","description":"ONE carrier type, or empty for both; partnered-only skips the delivery windows unless a quote requires one. Allowed: AMAZON_PARTNERED_CARRIER | USE_YOUR_OWN_CARRIER."},"shipping_mode":{"default":"","title":"Shipping Mode","type":"string","description":"the Shipping Mode GROUP (the plan's row 9), or empty for every mode; no match → that shipment's full list, and the notification says so. Allowed: SPD | LTL / FTL."},"sta_spreadsheet_id":{"default":"","title":"Sta Spreadsheet Id","type":"string","description":"the plan workbook's spreadsheet id (mode A); omit for mode B."}},"required":["store","plan_id","placement_option_id"],"title":"fbaInbound_generate_shipment_optionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"placementFee":{"description":"the picked placement's fee."},"currency":{"description":"the picked placement's fee."},"shipments":{"description":"[{shipmentId, warehouseId, destination, status, totals,","properties":{"partnered":{"description":"[{transportationOptionId, shippingMode, carrierName, carrierCode,"}}},"counts":{"description":"{partnered, ownCarrier, deliveryWindows} — Amazon's totals."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_confirm_plan_options":{"post":{"operationId":"fbaInbound_confirm_plan_options","summary":"Confirm the human's placement option and, per shipment, the transport option (+ delivery window) in one call — after the human approved them from fbaInbound_generate_shipment_optio","description":"Confirm the human's placement option and, per shipment, the transport option (+ delivery window) in one call — after the human approved them from fbaInbound_generate_shipment_options. Amazon SP-API · listPlacementOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions Amazon SP-API · confirmPlacementOption · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions/{placementOptionId}/confirmation Amazon SP-API · getInboundOperationStatus · GET /inbound/fba/2024-03-20/operations/{operationId} Amazon SP-API · confirmDeliveryWindowOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions/{deliveryWindowOptionId}/confirmation Amazon SP-API · confirmTransportationOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions/confirmation Amazon SP-API · getShipment · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId} Amazon SP-API · listTransportationOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions Amazon SP-API · listDeliveryWindowOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions Gate: commit, choice, fee-bearing — interactive: restate the option and the amount, wait for a typed CONFIRM; autopilot: only within the seller's instruction, named rule (one option, no tie) and stated limits; otherwise ask. Mode A (plan workbook): pass sta_spreadsheet_id and the server writes the chosen options (as the dropdown texts), FBA ID, Reference ID, Warehouse ID and Status into the picked STA-Options block — the sidebar's Confirm on that tab. Mode B: omit it. Server chains confirmPlacementOption → confirmDeliveryWindowOptions (only for entries that carry deliveryWindowOptionId) → confirmTransportationOptions, polling each operation to SUCCESS. All option ids are 38 chars except deliveryWindowOptionId (36-38).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_confirm_plan_options"},"tags":["amazon_sp"],"x-title":"FBA Inbound Confirm Plan Options","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.confirmedShipments","description":"[{shipmentId, shipmentConfirmationId, fbaId, referenceId, warehouseId, status}]"},{"field":"data.placementOptionId","description":"the confirmed option."}],"x-notes":{"Workflow":["1. Read the human's placement pick (mode A: the \"2.\" chip's row-6 cell — the id is","   the text before the first space; mode B: the handover file) and, per shipment,","   their transport choice (+ window) from fbaInbound_generate_shipment_options.","2. Call this tool.","3. Record data.confirmedShipments as the fba-inbound skill describes (row 12, the","   \"4.\" chip, Manage Shipments, _state); shipmentConfirmationId feeds","   fbaInbound_get_labels."],"Params (Amazon schema; listPlacementOptions)":["inboundPlanId*: string (max 38 chars)","pageSize: integer (1–20)","paginationToken: string (max 1024 chars)"],"Params (Amazon schema; confirmPlacementOption)":["inboundPlanId*: string (max 38 chars)","placementOptionId*: string (max 38 chars)"],"Params (Amazon schema; getInboundOperationStatus)":["operationId*: string (max 38 chars)"],"Params (Amazon schema; confirmDeliveryWindowOptions)":["inboundPlanId*: string (max 38 chars)","shipmentId*: string (max 38 chars)","deliveryWindowOptionId*: string (max 38 chars)"],"Params (Amazon schema; confirmTransportationOptions)":["inboundPlanId*: string (max 38 chars)"],"Params (Amazon schema; getShipment)":["inboundPlanId*: string (max 38 chars)","shipmentId*: string (max 38 chars)"],"Params (Amazon schema; listTransportationOptions)":["… (10 more lines; the Docs link above)"],"Body (Amazon schema; confirmTransportationOptions): {transportationSelections":["[TransportationSelection]} (min 1), each item:","  contactInformation: {email (max 1024 chars), name* (max 50 chars), phoneNumber* (max 20 chars)}","  shipmentId*: string (38–38 chars)","  transportationOptionId*: string (38–38 chars)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"placement_option_id":{"maxLength":38,"minLength":38,"title":"Placement Option Id","type":"string","description":"the placementOptionId (from fbaInbound_listPlacementOptions). One already ACCEPTED — after fbaInbound_confirmPlacementOption, or a first run whose transport step failed — is not confirmed again; the shipment steps run."},"shipment_confirmations":{"items":{},"title":"Shipment Confirmations","type":"array","description":"one entry per shipment in the placement option: [{shipmentId (38 chars), transportOptionId (38 chars; sent as Amazon's transportationOptionId), deliveryWindowOptionId, contactInformation}]. deliveryWindowOptionId — required when the chosen transport option's preconditions ask for a confirmed delivery window (own-carrier options do). contactInformation — {name ≤50, phoneNumber ≤20, email?}, REQUIRED for Amazon-partnered (PCP) options (Amazon: \"does not support confirming PCP options without contact info\")."},"sta_spreadsheet_id":{"default":"","title":"Sta Spreadsheet Id","type":"string","description":"the plan workbook's spreadsheet id (mode A); omit for mode B."}},"required":["store","plan_id","placement_option_id","shipment_confirmations"],"title":"fbaInbound_confirm_plan_optionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"confirmedShipments":{"description":"[{shipmentId, shipmentConfirmationId, fbaId, referenceId, warehouseId, status}]"},"placementOptionId":{"description":"the confirmed option."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_create_packing_list":{"post":{"operationId":"fbaInbound_create_packing_list","summary":"Packing list from Amazon's OWN box contents.","description":"Packing list from Amazon's OWN box contents. Call AFTER fbaInbound_confirm_plan_options. Amazon SP-API · listShipmentBoxes · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/boxes For every confirmed shipment the server reads listShipmentBoxes — each box's canonical boxId (FBAxxxxxxxx, assigned only after confirmation), name, dimensions, weight and items[{msku, fnsku, asin, quantity, labelOwner}] — and returns one row per box × item. Mixed boxes and multi-shipment placements need nothing from the sheet. Never invent box IDs from STA data — always fetch from Amazon. Mode A (plan workbook): pass sta_spreadsheet_id and the server writes the sidebar's FINAL `Inbound PL` tab into it — 11 columns (Image, Box ID, Template, FNSKU, MSKU, ASIN, Quantity, Weight, Weight Unit, Dimensions, Unit of Measurement), navy header, frozen row, guide note, Image formula — and removes a stale STA-PL tab, exactly as the sidebar's Confirm does. You write nothing there. Mode B: omit it and present data.amazonBoxes in the user's preferred form with those same 11 columns (no shipment column). Box labels per shipment come from fbaInbound_get_labels; tracking numbers go to Manage Shipments.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_create_packing_list"},"tags":["amazon_sp"],"x-title":"FBA Inbound Create Packing List","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.amazonBoxes","description":"[{amazonBoxId, shipmentId, boxName, msku, fnsku, asin, qty, labelOwner, boxDimensions (\"LxWxH\"), dimUnit, boxWeight, weightUnit, itemsInBox}] — amazonBoxId is FBAxxxxxxxx; use it for fbaInbound_updateShipmentTrackingDetails."},{"field":"data.inboundPl","description":"{tab: 'Inbound PL', rows} — mode A only."}],"x-notes":{"Workflow":["1. fbaInbound_confirm_plan_options completed — confirmedShipments in _state / handover file"],"Params (Amazon schema)":["inboundPlanId*: string (max 38 chars)","shipmentId*: string (max 38 chars)","pageSize: integer (1–1000)","paginationToken: string (max 1024 chars)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"sta_spreadsheet_id":{"default":"","title":"Sta Spreadsheet Id","type":"string","description":"the plan workbook (mode A) — '' in mode B."},"confirmed_shipments":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Confirmed Shipments","description":"REQUIRED — data.confirmedShipments of fbaInbound_confirm_plan_options as is (only shipmentId is read); a list without a shipmentId is refused."},"sta_item_rows":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Sta Item Rows","description":"ignored since 2026-09-24 (it used to be cross-joined onto every box); kept so older callers keep working."},"fba_spreadsheet_id":{"default":"","title":"Fba Spreadsheet Id","type":"string","description":"override the FBA spreadsheet whose Product Info feeds the Image column (defaults to the workspace setting)."}},"required":["store","plan_id"],"title":"fbaInbound_create_packing_listArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"amazonBoxes":{"description":"[{amazonBoxId, shipmentId, boxName, msku, fnsku, asin, qty, labelOwner, boxDimensions (\"LxWxH\"), dimUnit, boxWeight, weightUnit, itemsInBox}] — amazonBoxId is FBAxxxxxxxx; use it for fbaInbound_updateShipmentTrackingDetails."},"inboundPl":{"description":"{tab: 'Inbound PL', rows} — mode A only."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_get_plan_status":{"post":{"operationId":"fbaInbound_get_plan_status","summary":"List every placement option of an inbound plan (all pages) — a quick existence and stage probe before a phase.","description":"List every placement option of an inbound plan (all pages) — a quick existence and stage probe before a phase. For the plan's own status and shipments use fbaInbound_getInboundPlan. Amazon SP-API · listPlacementOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions Use this at the start of each phase to validate _state before taking irreversible actions.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_get_plan_status"},"tags":["amazon_sp"],"x-title":"FBA Inbound Get Plan Status","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.planId","description":"the plan ID."},{"field":"data.placementOptions","description":"ALL placement options — this compound scans every page deliberately (it is an existence/state probe). For a paged read use fbaInbound_listPlacementOptions."}],"x-notes":{"Workflow":["1. Read _state tab: stage and planId","2. Call this tool with the stored planId","3. If placement options empty → plan may not exist or stage < PACKING_GENERATED","4. If API error → reconcile with human before proceeding"],"Params (Amazon schema)":["inboundPlanId*: string (max 38 chars)","pageSize: integer (1–20)","paginationToken: string (max 1024 chars)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."}},"required":["store","plan_id"],"title":"fbaInbound_get_plan_statusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"planId":{"description":"the plan ID."},"placementOptions":{"description":"ALL placement options — this compound scans every page deliberately (it is an existence/state probe). For a paged read use fbaInbound_listPlacementOptions."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_cancelInboundPlan":{"post":{"operationId":"fbaInbound_cancelInboundPlan","summary":"Cancel an FBA inbound plan.","description":"Cancel an FBA inbound plan. IRREVERSIBLE — always confirm with human before calling. Amazon SP-API · cancelInboundPlan · PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/cancellation Amazon SP-API · getInboundOperationStatus · GET /inbound/fba/2024-03-20/operations/{operationId} Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_cancelInboundPlan"},"tags":["amazon_sp"],"x-title":"FBA Inbound Cancel Inbound Plan","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.cancelled","description":"true once the cancellation operation reached SUCCESS (a refused or FAILED cancellation raises instead)."},{"field":"data.operation","description":"the final getInboundOperationStatus payload."}],"x-notes":{"Gotchas":["Amazon may charge for a cancellation outside the void window — 24 h for","Amazon-partnered small parcel, 1 h for partnered LTL; say so when asking the human."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."}},"required":["store","plan_id"],"title":"fbaInbound_cancelInboundPlanArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"cancelled":{"description":"true once the cancellation operation reached SUCCESS (a refused or FAILED cancellation raises instead)."},"operation":{"description":"the final getInboundOperationStatus payload."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_getInboundPlan":{"post":{"operationId":"fbaInbound_getInboundPlan","summary":"Fetch the raw inbound plan object from Amazon (read-only).","description":"Fetch the raw inbound plan object from Amazon (read-only). Amazon SP-API · getInboundPlan · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId} Use at the start of any phase to inspect plan state: status, packing and placement options, shipments. This is a fast single-call read, not a compound op.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_getInboundPlan"},"tags":["amazon_sp"],"x-title":"FBA Inbound Get Inbound Plan","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.plan","description":"{inboundPlanId, name, status (ACTIVE, VOIDED, SHIPPED or ERRORED), sourceAddress, packingOptions [{packingOptionId, status}], placementOptions [{placementOptionId, status}], shipments [{shipmentId, status}]} — shipments fill in only after a placement option is confirmed."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."}},"required":["store","plan_id"],"title":"fbaInbound_getInboundPlanArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"plan":{"description":"{inboundPlanId, name, status (ACTIVE, VOIDED, SHIPPED or ERRORED), sourceAddress, packingOptions [{packingOptionId, status}], placementOptions [{placementOptionId, status}], shipments [{shipmentId, status}]} — shipments fill in only after a placement option is confirmed."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_getInboundOperationStatus":{"post":{"operationId":"fbaInbound_getInboundOperationStatus","summary":"Poll getInboundOperationStatus for a previously started async operation.","description":"Poll getInboundOperationStatus for a previously started async operation. Amazon SP-API · getInboundOperationStatus · GET /inbound/fba/2024-03-20/operations/{operationId} Every fbaInbound_* tool that answers data.operationId — fbaInbound_createInboundPlan, the generate*/confirm*/set* tools, fbaInbound_updateShipmentSourceAddress, fbaInbound_updateItemComplianceDetails, fbaInbound_cancelSelfShipAppointment — is finished only when this reports SUCCESS. operationStatus enum (exactly): 'IN_PROGRESS', 'SUCCESS', 'FAILED'. Poll every 5-10 seconds until status is not IN_PROGRESS.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_getInboundOperationStatus"},"tags":["amazon_sp"],"x-title":"FBA Inbound Get Inbound Operation Status","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.status","description":"current operationStatus string."},{"field":"data.operationProblems","description":"[{code, message, severity (WARNING or ERROR), details}] — on FAILED it names the cause; the call itself still answers HTTP 200."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"operation_id":{"maxLength":38,"minLength":36,"title":"Operation Id","type":"string","description":"operationId returned by a generate_*/confirm_* call (UUID, length 36-38)."}},"required":["store","operation_id"],"title":"fbaInbound_getInboundOperationStatusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"current operationStatus string."},"operationProblems":{"description":"[{code, message, severity (WARNING or ERROR), details}] — on FAILED it names the cause; the call itself still answers HTTP 200."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_generateDeliveryWindowOptions":{"post":{"operationId":"fbaInbound_generateDeliveryWindowOptions","summary":"Start generating delivery window options for one shipment (USE_YOUR_OWN_CARRIER).","description":"Start generating delivery window options for one shipment (USE_YOUR_OWN_CARRIER). Amazon SP-API · generateDeliveryWindowOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Non-partnered carrier flow only. Amazon generates available delivery windows asynchronously — poll the returned operationId, then call fbaInbound_listDeliveryWindowOptions. Not supported in the IN marketplace (\"GenerateDeliveryWindowOptions is not supported for the Indian marketplace\") — on IN, confirm transportation directly without a delivery window.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_generateDeliveryWindowOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound Generate Delivery Window Options","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},{"field":"data.status","description":"'IN_PROGRESS'."}],"x-notes":{"Workflow":["1. fbaInbound_generateTransportationOptions for the placement reached SUCCESS (an","   own-carrier option exists).","2. Call this tool per shipment, poll the operation, then","   fbaInbound_listDeliveryWindowOptions.","3. Confirm the window (fbaInbound_confirmDeliveryWindowOptions, after the placement","   is confirmed) BEFORE fbaInbound_confirmTransportationOptions."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_generateDeliveryWindowOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},"status":{"description":"'IN_PROGRESS'."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listDeliveryWindowOptions":{"post":{"operationId":"fbaInbound_listDeliveryWindowOptions","summary":"List delivery window options for a shipment (after generate completed).","description":"List delivery window options for a shipment (after generate completed). Amazon SP-API · listDeliveryWindowOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions Call after fbaInbound_getInboundOperationStatus returns SUCCESS for fbaInbound_generateDeliveryWindowOptions' operation. Returns ONE Amazon page — follow data.nextToken for more.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listDeliveryWindowOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Delivery Window Options","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.deliveryWindowOptions","description":"[{deliveryWindowOptionId, startDate, endDate, validUntil, availabilityType (AVAILABLE, BLOCKED, CONGESTED or DISCOUNTED)}] — confirm one before validUntil."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"options per page, 1-100. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_listDeliveryWindowOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"deliveryWindowOptions":{"description":"[{deliveryWindowOptionId, startDate, endDate, validUntil, availabilityType (AVAILABLE, BLOCKED, CONGESTED or DISCOUNTED)}] — confirm one before validUntil."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_generateTransportationOptions":{"post":{"operationId":"fbaInbound_generateTransportationOptions","summary":"Start generating transportation options for a placement option (async).","description":"Start generating transportation options for a placement option (async). Wraps generateTransportationOptions. After it completes (poll operationId), call fbaInbound_listTransportationOptions. Amazon SP-API · generateTransportationOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_generateTransportationOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound Generate Transportation Options","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},{"field":"data.status","description":"'IN_PROGRESS'."}],"x-notes":{"Body (Amazon schema)":["placementOptionId*: string (38–38 chars)","shipmentTransportationConfigurations*: [{contactInformation: {email, name*, phoneNumber*},","  freightInformation: {declaredValue, freightClass}, pallets: [{dimensions, quantity*, stackability,","    weight}], readyToShipWindow*: {start*}, shipmentId* (38–38 chars)}] (min 1)","  shipmentTransportationConfigurations.pallets.dimensions.unitOfMeasurement: IN | CM","  shipmentTransportationConfigurations.pallets.stackability: STACKABLE | NON_STACKABLE","  shipmentTransportationConfigurations.pallets.weight.unit: LB | KG"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"placement_option_id":{"maxLength":38,"minLength":38,"title":"Placement Option Id","type":"string","description":"the placementOptionId (from fbaInbound_listPlacementOptions)."},"shipment_transportation_configurations":{"items":{},"title":"Shipment Transportation Configurations","type":"array","description":"one entry per shipment of the placement option (its shipmentIds), shaped as the Body block below. readyToShipWindow.start is a date-time with minutes, 'yyyy-MM-ddTHH:mmZ' (e.g. '2026-06-01T00:00Z'). contactInformation is optional. freightInformation and pallets are for freight modes only; freightClass is NONE or FC_50 … FC_500 (Amazon lists the values only in prose); declaredValue.code is ISO 4217."}},"required":["store","plan_id","placement_option_id","shipment_transportation_configurations"],"title":"fbaInbound_generateTransportationOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},"status":{"description":"'IN_PROGRESS'."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listTransportationOptions":{"post":{"operationId":"fbaInbound_listTransportationOptions","summary":"List transportation options after generateTransportationOptions completed.","description":"List transportation options after generateTransportationOptions completed. Amazon SP-API · listTransportationOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions Returns ONE Amazon page — follow data.nextToken for more. Pass placement_option_id or shipment_id — Amazon requires at least one.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listTransportationOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Transportation Options","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.transportationOptions","description":"[{transportationOptionId, shipmentId, shippingSolution (Amazon-partnered or your own carrier), shippingMode, carrier {name, alphaCode}, quote.cost (absent on own-carrier options), preconditions (a confirmed delivery window precondition means: confirm a delivery window first)}]."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"placement_option_id":{"anyOf":[{"maxLength":38,"minLength":38,"type":"string"},{"type":"null"}],"default":null,"title":"Placement Option Id","description":"the placementOptionId (from fbaInbound_listPlacementOptions)."},"shipment_id":{"anyOf":[{"maxLength":38,"minLength":38,"type":"string"},{"type":"null"}],"default":null,"title":"Shipment Id","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"page_size":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"options per page, 1-20. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id"],"title":"fbaInbound_listTransportationOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"transportationOptions":{"description":"[{transportationOptionId, shipmentId, shippingSolution (Amazon-partnered or your own carrier), shippingMode, carrier {name, alphaCode}, quote.cost (absent on own-carrier options), preconditions (a confirmed delivery window precondition means: confirm a delivery window first)}]."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_confirmTransportationOptions":{"post":{"operationId":"fbaInbound_confirmTransportationOptions","summary":"Confirm the chosen transportation option per shipment (write, async).","description":"Confirm the chosen transportation option per shipment (write, async). Wraps confirmTransportationOptions. Amazon SP-API · confirmTransportationOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions/confirmation Gate: commit, choice, fee-bearing — interactive: restate the option and the amount, wait for a typed CONFIRM; autopilot: only within the seller's instruction, named rule (one option, no tie) and stated limits; otherwise ask. The placement option must already be confirmed. IRREVERSIBLE for the plan: once this succeeds, transportation options can no longer be generated or confirmed. The fbaInbound_confirm_plan_options compound does this step for you — use this atomic tool for the Split First flow. An option whose preconditions ask for a confirmed delivery window needs fbaInbound_confirmDeliveryWindowOptions for that shipment first. contactInformation is optional in the model but REQUIRED live for AMAZON_PARTNERED_CARRIER options — Amazon refuses with \"ConfirmTransportationOptions does not support confirming PCP options without contact info\". name + phoneNumber required when present.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_confirmTransportationOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound Confirm Transportation Options","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},{"field":"data.status","description":"'IN_PROGRESS'."}],"x-notes":{"Body (Amazon schema): {transportationSelections: [TransportationSelection]} (min 1), each item":["contactInformation: {email (max 1024 chars), name* (max 50 chars), phoneNumber* (max 20 chars)}","shipmentId*: string (38–38 chars)","transportationOptionId*: string (38–38 chars)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"transportation_selections":{"items":{},"title":"Transportation Selections","type":"array","description":"one entry per shipment, shaped as the Body block below — the transportationOptionId the human chose (from fbaInbound_listTransportationOptions) and, for Amazon-partnered options, contactInformation."}},"required":["store","plan_id","transportation_selections"],"title":"fbaInbound_confirmTransportationOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},"status":{"description":"'IN_PROGRESS'."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_generatePackingOptions":{"post":{"operationId":"fbaInbound_generatePackingOptions","summary":"Start generating packing options for a plan (async).","description":"Start generating packing options for a plan (async). Amazon SP-API · generatePackingOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. After generate completes, call fbaInbound_listPackingOptions to see options. The fbaInbound_orchestrate_packing compound op does this automatically for Box First. Box First only — Split First skips packing options. Use it to run Box First step by step or to re-generate. Not supported in the IN marketplace — Amazon refuses with \"GeneratePackingOptions is not supported for the Indian marketplace\". For IN plans skip packing options: fbaInbound_generatePlacementOptions (with custom_placement) then fbaInbound_setPackingInformation.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_generatePackingOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound Generate Packing Options","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},{"field":"data.status","description":"'IN_PROGRESS'."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."}},"required":["store","plan_id"],"title":"fbaInbound_generatePackingOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},"status":{"description":"'IN_PROGRESS'."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listPackingOptions":{"post":{"operationId":"fbaInbound_listPackingOptions","summary":"List packing options after generatePackingOptions completed.","description":"List packing options after generatePackingOptions completed. Amazon SP-API · listPackingOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions Returns ONE Amazon page — follow data.nextToken for more. Use to let a human select a packingOptionId, then call fbaInbound_confirmPackingOption.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listPackingOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Packing Options","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.packingOptions","description":"list of packing option objects each with packingOptionId and packingGroups list."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"page_size":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"options per page, 1-20. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id"],"title":"fbaInbound_listPackingOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"packingOptions":{"description":"list of packing option objects each with packingOptionId and packingGroups list."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_confirmPackingOption":{"post":{"operationId":"fbaInbound_confirmPackingOption","summary":"Confirm a packing option (Amazon write — irreversible for this plan).","description":"Confirm a packing option (Amazon write — irreversible for this plan). Amazon SP-API · confirmPackingOption · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions/{packingOptionId}/confirmation Gate: approve, choice — interactive: show the change and the option (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change, within named rule (one option, no tie); otherwise ask. After SUCCESS, call fbaInbound_setPackingInformation with one grouping per packingGroupId of the confirmed option (its packingGroups in fbaInbound_listPackingOptions), then fbaInbound_generatePlacementOptions.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_confirmPackingOption"},"tags":["amazon_sp"],"x-title":"FBA Inbound Confirm Packing Option","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},{"field":"data.status","description":"'IN_PROGRESS'."}],"x-notes":{"Workflow":["1. fbaInbound_generatePackingOptions completed (poll until SUCCESS)","2. fbaInbound_listPackingOptions — human or AI selects packingOptionId","3. Confirm with human before calling (this commits the packing structure)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"packing_option_id":{"maxLength":38,"minLength":38,"title":"Packing Option Id","type":"string","description":"packingOptionId selected from fbaInbound_listPackingOptions."}},"required":["store","plan_id","packing_option_id"],"title":"fbaInbound_confirmPackingOptionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},"status":{"description":"'IN_PROGRESS'."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_setPackingInformation":{"post":{"operationId":"fbaInbound_setPackingInformation","summary":"Set box packing information per shipment/group (Amazon write, async).","description":"Set box packing information per shipment/group (Amazon write, async). Wraps setPackingInformation; poll the returned operationId to SUCCESS. Amazon SP-API · setPackingInformation · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingInformation Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Each grouping keys EITHER by packingGroupId (Box First) OR shipmentId (Split First). After this completes, call fbaInbound_generatePlacementOptions.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_setPackingInformation"},"tags":["amazon_sp"],"x-title":"FBA Inbound Set Packing Information","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},{"field":"data.status","description":"'IN_PROGRESS'."}],"x-notes":{"Body (Amazon schema): {packageGroupings: [PackageGroupingInput]} (min 1), each item":["boxes*: [{contentInformationSource*, dimensions*: {height*, length*, unitOfMeasurement*, width*}, items: [{expiration, labelOwner*, manufacturingLotCode, msku*, prepOwner*, quantity*}], quantity* (1–10000),","  weight*: {unit*, value*}}] (1–5000)","boxes.contentInformationSource: BOX_CONTENT_PROVIDED | MANUAL_PROCESS | BARCODE_2D","boxes.dimensions.unitOfMeasurement: IN | CM","boxes.items.labelOwner: AMAZON | SELLER | NONE","boxes.items.prepOwner: AMAZON | SELLER | NONE","boxes.weight.unit: LB | KG","packingGroupId: string (38–38 chars)","shipmentId: string (38–38 chars)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"package_groupings":{"items":{},"title":"Package Groupings","type":"array","description":"1+ groupings, shaped as the Body block below — each keyed by packingGroupId (Box First, from the confirmed packing option) OR shipmentId (Split First), with boxes: 1–5000 box specs, quantity = how many identical boxes. contentInformationSource BOX_CONTENT_PROVIDED carries the box's items; MANUAL_PROCESS and BARCODE_2D boxes carry none."}},"required":["store","plan_id","package_groupings"],"title":"fbaInbound_setPackingInformationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},"status":{"description":"'IN_PROGRESS'."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_generatePlacementOptions":{"post":{"operationId":"fbaInbound_generatePlacementOptions","summary":"Start generating placement options for a plan (async).","description":"Start generating placement options for a plan (async). Amazon SP-API · generatePlacementOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Where this sits depends on the workflow (Amazon's guides agree on both): Box First (pack first) — call AFTER fbaInbound_setPackingInformation completes; Split First (pack later) — call straight after fbaInbound_createInboundPlan, BEFORE fbaInbound_setPackingInformation. In both, the placement option is confirmed BEFORE transportation options are confirmed. Poll until SUCCESS, then call fbaInbound_get_plan_status to list the placement options. India: plans destined to the IN marketplace REQUIRE custom_placement — Amazon refuses the call without it (\"CustomPlacement details are required for inbound plans with destinations in IN\"). IN also has no packing-options step (generatePackingOptions is not supported there); generate placement first, then fbaInbound_setPackingInformation.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_generatePlacementOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound Generate Placement Options","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},{"field":"data.status","description":"'IN_PROGRESS'."}],"x-notes":{"Body (Amazon schema): {customPlacement: [CustomPlacementInput]}, each item":["items*: [{expiration, labelOwner*: AMAZON | SELLER | NONE, manufacturingLotCode (max 256 chars), msku* (max 255 chars), prepOwner*: AMAZON | SELLER | NONE, quantity* (1–500000)}] (1–2000)","warehouseId*: string (max 1024 chars)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"custom_placement":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Custom Placement","description":"optional list of custom placements, REQUIRED for IN-destined plans. Each: {warehouseId (e.g. 'JPX1'), items: [{msku, quantity, labelOwner, prepOwner, expiration?, manufacturingLotCode?}]}. labelOwner/prepOwner Allowed: AMAZON | SELLER | NONE."}},"required":["store","plan_id"],"title":"fbaInbound_generatePlacementOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."},"status":{"description":"'IN_PROGRESS'."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listInboundPlans":{"post":{"operationId":"fbaInbound_listInboundPlans","summary":"List inbound plans for a store (one page per call).","description":"List inbound plans for a store (one page per call). Amazon SP-API · listInboundPlans · GET /inbound/fba/2024-03-20/inboundPlans Use to find existing plans before creating a new one or to audit plan state. For a single plan's full object use fbaInbound_getInboundPlan. Amazon's list can currently miss ACTIVE plans (seen with a ship-from address outside the marketplace country). A plan you created that is not listed is not gone: read it with fbaInbound_getInboundPlan by the id recorded at creation (the Manage Shipments row, the plan workbook). Follow nextToken until it is '' — a page can hold fewer than page_size plans while more remain.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listInboundPlans"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Inbound Plans","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.inboundPlans","description":"list of plan summaries (inboundPlanId, name, status)."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"status":{"anyOf":[{"enum":["ACTIVE","VOIDED","SHIPPED"],"type":"string"},{"type":"null"}],"default":null,"title":"Status","description":"optional plan status filter. Allowed: ACTIVE | VOIDED | SHIPPED."},"sort_by":{"anyOf":[{"enum":["LAST_UPDATED_TIME","CREATION_TIME"],"type":"string"},{"type":"null"}],"default":null,"title":"Sort By","description":"optional sort field. Allowed: LAST_UPDATED_TIME | CREATION_TIME."},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"title":"Sort Order","description":"ASC or DESC."},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"plans per page, 1-30. Optional (Amazon default 10)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"fbaInbound_listInboundPlansArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"inboundPlans":{"description":"list of plan summaries (inboundPlanId, name, status)."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listInboundPlanItems":{"post":{"operationId":"fbaInbound_listInboundPlanItems","summary":"List the items (msku/fnsku/quantity/prep) in an inbound plan (read, one page).","description":"List the items (msku/fnsku/quantity/prep) in an inbound plan (read, one page). Amazon SP-API · listInboundPlanItems · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/items","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listInboundPlanItems"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Inbound Plan Items","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.items","description":"list of plan item objects."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"items per page, 1-1000. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id"],"title":"fbaInbound_listInboundPlanItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"list of plan item objects."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listInboundPlanBoxes":{"post":{"operationId":"fbaInbound_listInboundPlanBoxes","summary":"List all boxes in an inbound plan (read, one page).","description":"List all boxes in an inbound plan (read, one page). Amazon SP-API · listInboundPlanBoxes · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/boxes","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listInboundPlanBoxes"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Inbound Plan Boxes","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.boxes","description":"list of box objects (boxId, dimensions, weight, items)."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"boxes per page, 1-1000. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id"],"title":"fbaInbound_listInboundPlanBoxesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"boxes":{"description":"list of box objects (boxId, dimensions, weight, items)."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listInboundPlanPallets":{"post":{"operationId":"fbaInbound_listInboundPlanPallets","summary":"List all pallets in an inbound plan (read, one page; LTL/FTL freight).","description":"List all pallets in an inbound plan (read, one page; LTL/FTL freight). Amazon SP-API · listInboundPlanPallets · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/pallets","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listInboundPlanPallets"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Inbound Plan Pallets","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.pallets","description":"list of pallet objects (packageId, dimensions, weight)."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"pallets per page, 1-1000. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id"],"title":"fbaInbound_listInboundPlanPalletsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"pallets":{"description":"list of pallet objects (packageId, dimensions, weight)."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listPlacementOptions":{"post":{"operationId":"fbaInbound_listPlacementOptions","summary":"List placement options for a plan (read, one page).","description":"List placement options for a plan (read, one page). Amazon SP-API · listPlacementOptions · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions Lighter-weight alternative to fbaInbound_get_plan_status when you only need the placement options list. Confirm one via fbaInbound_confirm_plan_options.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listPlacementOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Placement Options","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.placementOptions","description":"list of placement option objects with fees."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"page_size":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"options per page, 1-20. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id"],"title":"fbaInbound_listPlacementOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"placementOptions":{"description":"list of placement option objects with fees."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listPackingGroupItems":{"post":{"operationId":"fbaInbound_listPackingGroupItems","summary":"List items in a packing group (read, one page; Box First).","description":"List items in a packing group (read, one page; Box First). Amazon SP-API · listPackingGroupItems · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingGroups/{packingGroupId}/items","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listPackingGroupItems"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Packing Group Items","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.items","description":"list of item objects in the packing group."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"packing_group_id":{"maxLength":38,"minLength":38,"title":"Packing Group Id","type":"string","description":"packingGroupId from fbaInbound_listPackingOptions."},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"items per page, 1-100. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id","packing_group_id"],"title":"fbaInbound_listPackingGroupItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"list of item objects in the packing group."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listPackingGroupBoxes":{"post":{"operationId":"fbaInbound_listPackingGroupBoxes","summary":"List boxes in a packing group (read, one page; provided via setPackingInformation).","description":"List boxes in a packing group (read, one page; provided via setPackingInformation). Amazon SP-API · listPackingGroupBoxes · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingGroups/{packingGroupId}/boxes","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listPackingGroupBoxes"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Packing Group Boxes","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.boxes","description":"list of box objects in the packing group."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"packing_group_id":{"maxLength":38,"minLength":38,"title":"Packing Group Id","type":"string","description":"the packingGroupId (from fbaInbound_listPackingOptions' packingGroups)."},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"boxes per page, 1-100. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id","packing_group_id"],"title":"fbaInbound_listPackingGroupBoxesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"boxes":{"description":"list of box objects in the packing group."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_getShipment":{"post":{"operationId":"fbaInbound_getShipment","summary":"Fetch a single shipment object from Amazon (read).","description":"Fetch a single shipment object from Amazon (read). Amazon SP-API · getShipment · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId} Returns the full shipment: status, source/destination addresses, shipmentConfirmationId, amazonReferenceId, placementOptionId.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_getShipment"},"tags":["amazon_sp"],"x-title":"FBA Inbound Get Shipment","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.shipment","description":"the full shipment object."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_getShipmentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipment":{"description":"the full shipment object."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listShipmentItems":{"post":{"operationId":"fbaInbound_listShipmentItems","summary":"List item packages in a shipment (read, one page).","description":"List item packages in a shipment (read, one page). Amazon SP-API · listShipmentItems · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/items","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listShipmentItems"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Shipment Items","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.items","description":"list of shipment item objects (msku/fnsku/quantity)."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"items per page, 1-1000. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_listShipmentItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"list of shipment item objects (msku/fnsku/quantity)."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listShipmentBoxes":{"post":{"operationId":"fbaInbound_listShipmentBoxes","summary":"List boxes in a shipment (read, one page).","description":"List boxes in a shipment (read, one page). Amazon SP-API · listShipmentBoxes · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/boxes boxId (FBAxxxxxxxx) is the box key for SPD tracking upload via fbaInbound_updateShipmentTrackingDetails; it appears only after the shipment's transportation is confirmed (before that a box has only packageId). Prefer this over fbaInbound_create_packing_list when you only need the box IDs.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listShipmentBoxes"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Shipment Boxes","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.boxes","description":"list of box objects (boxId, dimensions, items)."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"boxes per page, 1-1000. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_listShipmentBoxesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"boxes":{"description":"list of box objects (boxId, dimensions, items)."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listShipmentPallets":{"post":{"operationId":"fbaInbound_listShipmentPallets","summary":"List pallets in a shipment (read, one page; LTL/FTL freight).","description":"List pallets in a shipment (read, one page; LTL/FTL freight). Amazon SP-API · listShipmentPallets · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/pallets","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listShipmentPallets"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Shipment Pallets","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.pallets","description":"list of pallet objects."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"pallets per page, 1-1000. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_listShipmentPalletsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"pallets":{"description":"list of pallet objects."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listItemComplianceDetails":{"post":{"operationId":"fbaInbound_listItemComplianceDetails","summary":"List inbound compliance (tax) details for MSKUs (read).","description":"List inbound compliance (tax) details for MSKUs (read). Amazon SP-API · listItemComplianceDetails · GET /inbound/fba/2024-03-20/items/compliance Mainly relevant for the India (IN) marketplace — the store ref names it. Missing tax details are set with fbaInbound_updateItemComplianceDetails.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listItemComplianceDetails"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Item Compliance Details","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.complianceDetails","description":"list of compliance detail objects."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"mskus":{"items":{"maxLength":255,"type":"string"},"title":"Mskus","type":"array","description":"list of merchant SKUs (max 100)."}},"required":["store","mskus"],"title":"fbaInbound_listItemComplianceDetailsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"complianceDetails":{"description":"list of compliance detail objects."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listPrepDetails":{"post":{"operationId":"fbaInbound_listPrepDetails","summary":"Get preparation details + owner constraints for MSKUs (read).","description":"Get preparation details + owner constraints for MSKUs (read). Amazon SP-API · listPrepDetails · GET /inbound/fba/2024-03-20/items/prepDetails Use before fbaInbound_setPrepDetails to see the current prep category, prep types, and the owner constraints: labelOwnerConstraint / prepOwnerConstraint (AMAZON_ONLY, NONE_ONLY or SELLER_ONLY) and allOwnersConstraint (MUST_MATCH).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listPrepDetails"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Prep Details","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.mskuPrepDetails","description":"list of prep detail objects."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"mskus":{"items":{"maxLength":255,"type":"string"},"title":"Mskus","type":"array","description":"list of merchant SKUs (max 100)."}},"required":["store","mskus"],"title":"fbaInbound_listPrepDetailsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"mskuPrepDetails":{"description":"list of prep detail objects."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_listShipmentContentUpdatePreviews":{"post":{"operationId":"fbaInbound_listShipmentContentUpdatePreviews","summary":"List content update previews in a shipment (read, one page).","description":"List content update previews in a shipment (read, one page). Amazon SP-API · listShipmentContentUpdatePreviews · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/contentUpdatePreviews After fbaInbound_generateShipmentContentUpdatePreviews completes, list the previews, pick one, and confirm via fbaInbound_confirmShipmentContentUpdatePreview.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_listShipmentContentUpdatePreviews"},"tags":["amazon_sp"],"x-title":"FBA Inbound List Shipment Content Update Previews","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.contentUpdatePreviews","description":"[{contentUpdatePreviewId, expiration, requestedUpdates {boxes, items}, transportationOption (quote.cost is the NEW cost)}] — confirm before expiration."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"page_size":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"previews per page, 1-20. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_listShipmentContentUpdatePreviewsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"contentUpdatePreviews":{"description":"[{contentUpdatePreviewId, expiration, requestedUpdates {boxes, items}, transportationOption (quote.cost is the NEW cost)}] — confirm before expiration."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_getShipmentContentUpdatePreview":{"post":{"operationId":"fbaInbound_getShipmentContentUpdatePreview","summary":"Fetch a single content update preview (read).","description":"Fetch a single content update preview (read). Amazon SP-API · getShipmentContentUpdatePreview · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/contentUpdatePreviews/{contentUpdatePreviewId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_getShipmentContentUpdatePreview"},"tags":["amazon_sp"],"x-title":"FBA Inbound Get Shipment Content Update Preview","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.preview","description":"{contentUpdatePreviewId, expiration, requestedUpdates {boxes, items}, transportationOption (quote.cost is the NEW cost)}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"content_update_preview_id":{"maxLength":38,"minLength":38,"title":"Content Update Preview Id","type":"string","description":"the contentUpdatePreviewId (from fbaInbound_listShipmentContentUpdatePreviews)."}},"required":["store","plan_id","shipment_id","content_update_preview_id"],"title":"fbaInbound_getShipmentContentUpdatePreviewArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"preview":{"description":"{contentUpdatePreviewId, expiration, requestedUpdates {boxes, items}, transportationOption (quote.cost is the NEW cost)}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_getSelfShipAppointmentSlots":{"post":{"operationId":"fbaInbound_getSelfShipAppointmentSlots","summary":"List available self-ship appointment slots (read, one page).","description":"List available self-ship appointment slots (read, one page). Amazon SP-API · getSelfShipAppointmentSlots · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/selfShipAppointmentSlots Call after fbaInbound_generateSelfShipAppointmentSlots completes (poll the operation). Then pick a slotId and call fbaInbound_scheduleSelfShipAppointment. Only available in MX, BR, EG, SA, AE and IN.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_getSelfShipAppointmentSlots"},"tags":["amazon_sp"],"x-title":"FBA Inbound Get Self Ship Appointment Slots","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.selfShipAppointmentSlots","description":"list of slot objects (slotId, slotTime{startTime, endTime})."},{"field":"data.expiresAt","description":"when the generated slot set stops being bookable."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"slots per page, 1-100. Optional (Amazon default)."},"pagination_token":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Pagination Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_getSelfShipAppointmentSlotsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"selfShipAppointmentSlots":{"description":"list of slot objects (slotId, slotTime{startTime, endTime})."},"expiresAt":{"description":"when the generated slot set stops being bookable."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_getDeliveryChallanDocument":{"post":{"operationId":"fbaInbound_getDeliveryChallanDocument","summary":"Fetch the delivery challan document of an India (IN) shipment that uses Amazon-partnered (PCP) transport (read).","description":"Fetch the delivery challan document of an India (IN) shipment that uses Amazon-partnered (PCP) transport (read). Amazon SP-API · getDeliveryChallanDocument · GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryChallanDocument","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_getDeliveryChallanDocument"},"tags":["amazon_sp"],"x-title":"FBA Inbound Get Delivery Challan Document","x-access":"read","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.document.documentDownload.uri","description":"the challan PDF's download URL."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_getDeliveryChallanDocumentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"document":{"properties":{"documentDownload":{"properties":{"uri":{"description":"the challan PDF's download URL."}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_confirmDeliveryWindowOptions":{"post":{"operationId":"fbaInbound_confirmDeliveryWindowOptions","summary":"Confirm a delivery window option for a shipment (write, async).","description":"Confirm a delivery window option for a shipment (write, async). Amazon SP-API · confirmDeliveryWindowOptions · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions/{deliveryWindowOptionId}/confirmation Gate: commit, choice — interactive: restate the option, wait for a typed CONFIRM; autopilot: only within the seller's instruction, named rule (one option, no tie) and stated limits; otherwise ask. USE_YOUR_OWN_CARRIER flow. Pick a deliveryWindowOptionId from fbaInbound_listDeliveryWindowOptions, confirm it, then poll the operation. A placement option must be confirmed first; a transportation option whose preconditions ask for a confirmed delivery window can be confirmed only after this. Once confirmed, no new windows can be generated (the chosen one can still be updated before the shipment closes).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_confirmDeliveryWindowOptions"},"tags":["amazon_sp"],"x-title":"FBA Inbound Confirm Delivery Window Options","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"delivery_window_option_id":{"maxLength":38,"minLength":36,"title":"Delivery Window Option Id","type":"string","description":"the deliveryWindowOptionId (from fbaInbound_listDeliveryWindowOptions; 36–38 chars)."}},"required":["store","plan_id","shipment_id","delivery_window_option_id"],"title":"fbaInbound_confirmDeliveryWindowOptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_updateInboundPlanName":{"post":{"operationId":"fbaInbound_updateInboundPlanName","summary":"Rename an inbound plan (write, synchronous).","description":"Rename an inbound plan (write, synchronous). Amazon SP-API · updateInboundPlanName · PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/name Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_updateInboundPlanName"},"tags":["amazon_sp"],"x-title":"FBA Inbound Update Inbound Plan Name","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.updated","description":"true — Amazon applied the name synchronously; nothing to poll."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"name":{"maxLength":40,"title":"Name","type":"string","description":"new plan name (maxLength 40)."}},"required":["store","plan_id","name"],"title":"fbaInbound_updateInboundPlanNameArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"updated":{"description":"true — Amazon applied the name synchronously; nothing to poll."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_updateShipmentName":{"post":{"operationId":"fbaInbound_updateShipmentName","summary":"Rename a shipment (write, synchronous).","description":"Rename a shipment (write, synchronous). Amazon SP-API · updateShipmentName · PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/name Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_updateShipmentName"},"tags":["amazon_sp"],"x-title":"FBA Inbound Update Shipment Name","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.updated","description":"true — Amazon applied the name synchronously; nothing to poll."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"name":{"maxLength":100,"title":"Name","type":"string","description":"new shipment name (maxLength 100)."}},"required":["store","plan_id","shipment_id","name"],"title":"fbaInbound_updateShipmentNameArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"updated":{"description":"true — Amazon applied the name synchronously; nothing to poll."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_updateShipmentSourceAddress":{"post":{"operationId":"fbaInbound_updateShipmentSourceAddress","summary":"Update a shipment's source address (write, async).","description":"Update a shipment's source address (write, async). Amazon SP-API · updateShipmentSourceAddress · PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/sourceAddress Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Only allowed before carriers are confirmed. Existing transportation options are invalidated — regenerate them after SUCCESS.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_updateShipmentSourceAddress"},"tags":["amazon_sp"],"x-title":"FBA Inbound Update Shipment Source Address","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}],"x-notes":{"Body (Amazon schema)":["address*: {addressLine1* (max 180 chars), addressLine2 (max 60 chars), city* (max 30 chars), companyName (max 50 chars), countryCode* (2–2 chars), districtOrCounty (max 50 chars), email (max 1024 chars), name* (max 50 chars), phoneNumber* (max 20 chars), postalCode* (max 32 chars), stateOrProvinceCode (max 64 chars)}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"address":{"additionalProperties":true,"title":"Address","type":"object","description":"AddressInput dict (name, addressLine1, city, countryCode, postalCode, phoneNumber required)."}},"required":["store","plan_id","shipment_id","address"],"title":"fbaInbound_updateShipmentSourceAddressArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_createMarketplaceItemLabels":{"post":{"operationId":"fbaInbound_createMarketplaceItemLabels","summary":"Create FNSKU item labels for a list of MSKUs (write).","description":"Create FNSKU item labels for a list of MSKUs (write). Amazon SP-API · createMarketplaceItemLabels · POST /inbound/fba/2024-03-20/items/labels Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Returns download URIs for the label PDF. Unlike fbaInbound_get_labels (which prints box labels for a confirmed shipment), this prints per-unit FNSKU item labels for any MSKU.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_createMarketplaceItemLabels"},"tags":["amazon_sp"],"x-title":"FBA Inbound Create Marketplace Item Labels","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.documentDownloads","description":"list of {uri, downloadType, expiration}."}],"x-notes":{"Body (Amazon schema)":["height: number (25–100)","labelType*: STANDARD_FORMAT | THERMAL_PRINTING","localeCode: string (default en_US)","marketplaceId*: string (max 20 chars)","mskuQuantities*: [{msku* (max 255 chars), quantity* (1–10000)}] (1–100)","pageType: A4_21 | A4_24 | A4_24_64x33 | A4_24_66x35 | A4_24_70x36 | A4_24_70x37 | A4_24i | A4_27 | A4_40_52x29 | A4_44_48x25 | Letter_30","width: number (25–100)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"label_type":{"enum":["STANDARD_FORMAT","THERMAL_PRINTING"],"title":"Label Type","type":"string","description":"the print format — label sheets or a thermal printer. Allowed: STANDARD_FORMAT | THERMAL_PRINTING."},"msku_quantities":{"items":{},"title":"Msku Quantities","type":"array","description":"list of {msku, quantity} (max 100; quantity 1-10000)."},"page_type":{"anyOf":[{"enum":["A4_21","A4_24","A4_24_64x33","A4_24_66x35","A4_24_70x36","A4_24_70x37","A4_24i","A4_27","A4_40_52x29","A4_44_48x25","Letter_30"],"type":"string"},{"type":"null"}],"default":null,"title":"Page Type","description":"optional page layout — paper size, labels per page and, in some values, the label size in mm. Allowed: A4_21 | A4_24 | A4_24_64x33 | A4_24_66x35 | A4_24_70x36 | A4_24_70x37 | A4_24i | A4_27 | A4_40_52x29 | A4_44_48x25 | Letter_30."},"locale_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Locale Code","description":"optional locale, pattern xx_XX (e.g. 'en_US')."},"height":{"anyOf":[{"maximum":100,"minimum":25,"type":"number"},{"type":"null"}],"default":null,"title":"Height","description":"optional label height (25-100)."},"width":{"anyOf":[{"maximum":100,"minimum":25,"type":"number"},{"type":"null"}],"default":null,"title":"Width","description":"optional label width (25-100)."}},"required":["store","label_type","msku_quantities"],"title":"fbaInbound_createMarketplaceItemLabelsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"documentDownloads":{"description":"list of {uri, downloadType, expiration}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_updateItemComplianceDetails":{"post":{"operationId":"fbaInbound_updateItemComplianceDetails","summary":"Update India (IN) compliance tax details for MSKUs (write, async).","description":"Update India (IN) compliance tax details for MSKUs (write, async). Amazon SP-API · updateItemComplianceDetails · PUT /inbound/fba/2024-03-20/items/compliance Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. One operation per MSKU is created; data.operations lists each.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_updateItemComplianceDetails"},"tags":["amazon_sp"],"x-title":"FBA Inbound Update Item Compliance Details","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"first operation id (poll each in data.operations)."}],"x-notes":{"Body (Amazon schema)":["msku*: string (max 255 chars)","taxDetails*: {declaredValue: {amount*, code*}, hsnCode (max 1024 chars), taxRates: [{cessRate, gstRate, taxType}]}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"compliance_details":{"items":{},"title":"Compliance Details","type":"array","description":"list of {msku, taxDetails} dicts. taxDetails: {declaredValue: {amount, code (ISO 4217, 3-char)}, hsnCode, taxRates: [{cessRate, gstRate, taxType}]}. taxType. Allowed: CGST | SGST | IGST | TOTAL_TAX."}},"required":["store","compliance_details"],"title":"fbaInbound_updateItemComplianceDetailsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"first operation id (poll each in data.operations)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_setPrepDetails":{"post":{"operationId":"fbaInbound_setPrepDetails","summary":"Set preparation details (category + types) for MSKUs (write, async).","description":"Set preparation details (category + types) for MSKUs (write, async). Amazon SP-API · setPrepDetails · POST /inbound/fba/2024-03-20/items/prepDetails Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_setPrepDetails"},"tags":["amazon_sp"],"x-title":"FBA Inbound Set Prep Details","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}],"x-notes":{"Body (Amazon schema)":["marketplaceId*: string (max 20 chars)","mskuPrepDetails*: [{msku* (max 255 chars), prepCategory*, prepTypes*}] (1–100)","mskuPrepDetails.prepCategory: ADULT | BABY | FC_PROVIDED | FRAGILE | GRANULAR | HANGER | LIQUID | PERFORATED | SET | SHARP | SMALL | TEXTILE | UNKNOWN | NONE","mskuPrepDetails.prepTypes: [ITEM_BLACK_SHRINKWRAP | ITEM_BLANKSTK | ITEM_BOXING | ITEM_BUBBLEWRAP | ITEM_CAP_SEALING | ITEM_DEBUNDLE | ITEM_HANG_GARMENT | ITEM_LABELING | ITEM_NO_PREP | ITEM_POLYBAGGING | ITEM_RMOVHANG | ITEM_SETCREAT | ITEM_SETSTK | ITEM_SIOC | ITEM_SUFFOSTK | ITEM_TAPING]"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"msku_prep_details":{"items":{},"title":"Msku Prep Details","type":"array","description":"1–100 entries of {msku, prepCategory, prepTypes: [...]}, all three required — the prep each MSKU needs (values in the Body block below; ITEM_SIOC = ships in its own container)."}},"required":["store","msku_prep_details"],"title":"fbaInbound_setPrepDetailsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_generateShipmentContentUpdatePreviews":{"post":{"operationId":"fbaInbound_generateShipmentContentUpdatePreviews","summary":"Generate content update previews for revised box content (write, async).","description":"Generate content update previews for revised box content (write, async). Amazon SP-API · generateShipmentContentUpdatePreviews · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/contentUpdatePreviews Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Use to change box contents after a shipment is created — Amazon returns previews with the resulting transportation cost change. Both lists describe the shipment AFTER the update, in full — they are not deltas, and Amazon requires both. Timing window (live rules): allowed after fbaInbound_confirmTransportationOptions and BEFORE tracking details are set — once updateShipmentTrackingDetails has run (or the void window ends), Amazon refuses with FBA_INB_0262 \"Cannot add boxes because the void window has ended or the shipment is in a status that does not allow edits\", even while status is WORKING. Quantity changes are capped at 5% or 6 units per SKU, whichever is greater; a SKU can be removed only if its original quantity is ≤6; the shipment cannot be emptied.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_generateShipmentContentUpdatePreviews"},"tags":["amazon_sp"],"x-title":"FBA Inbound Generate Shipment Content Update Previews","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll until SUCCESS, then fbaInbound_listShipmentContentUpdatePreviews."}],"x-notes":{"Body (Amazon schema)":["boxes*: [{contentInformationSource*, dimensions*: {height*, length*, unitOfMeasurement*, width*}, items: [{expiration, labelOwner*, manufacturingLotCode, msku*, prepOwner*, quantity*}], packageId (38–38 chars), quantity* (1–10000), weight*: {unit*, value*}}] (1–5000)","boxes.contentInformationSource: BOX_CONTENT_PROVIDED | MANUAL_PROCESS | BARCODE_2D","boxes.dimensions.unitOfMeasurement: IN | CM","boxes.items.labelOwner: AMAZON | SELLER | NONE","boxes.items.prepOwner: AMAZON | SELLER | NONE","boxes.weight.unit: LB | KG","items*: [{expiration, labelOwner*: AMAZON | SELLER | NONE, manufacturingLotCode (max 256 chars), msku* (max 255 chars), prepOwner*: AMAZON | SELLER | NONE, quantity* (1–500000)}] (1–2000)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"boxes":{"items":{},"title":"Boxes","type":"array","description":"every box the shipment will contain after the update (1–5000), shaped as the Body block below; quantity = how many identical boxes. BOX_CONTENT_PROVIDED boxes carry their items; MANUAL_PROCESS and BARCODE_2D boxes carry none. packageId: REQUIRED to keep an existing box (from fbaInbound_listShipmentBoxes); a new box has none, and every existing box whose packageId you omit is removed."},"items":{"items":{},"title":"Items","type":"array","description":"every item the shipment will contain after the update (1–2000), shaped as the Body block below."}},"required":["store","plan_id","shipment_id","boxes","items"],"title":"fbaInbound_generateShipmentContentUpdatePreviewsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll until SUCCESS, then fbaInbound_listShipmentContentUpdatePreviews."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_confirmShipmentContentUpdatePreview":{"post":{"operationId":"fbaInbound_confirmShipmentContentUpdatePreview","summary":"Confirm a content update preview, accepting the cost change (write, async).","description":"Confirm a content update preview, accepting the cost change (write, async). Amazon SP-API · confirmShipmentContentUpdatePreview · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/contentUpdatePreviews/{contentUpdatePreviewId}/confirmation Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_confirmShipmentContentUpdatePreview"},"tags":["amazon_sp"],"x-title":"FBA Inbound Confirm Shipment Content Update Preview","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"content_update_preview_id":{"maxLength":38,"minLength":38,"title":"Content Update Preview Id","type":"string","description":"the contentUpdatePreviewId (from fbaInbound_listShipmentContentUpdatePreviews); confirm before the preview's expiration."}},"required":["store","plan_id","shipment_id","content_update_preview_id"],"title":"fbaInbound_confirmShipmentContentUpdatePreviewArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_generateSelfShipAppointmentSlots":{"post":{"operationId":"fbaInbound_generateSelfShipAppointmentSlots","summary":"Generate self-ship appointment slots for a shipment (write, async).","description":"Generate self-ship appointment slots for a shipment (write, async). Amazon SP-API · generateSelfShipAppointmentSlots · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/selfShipAppointmentSlots Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Self-ship (drop-off) flow. After SUCCESS, call fbaInbound_getSelfShipAppointmentSlots. Only available in MX, BR, EG, SA, AE and IN. Without the two dates Amazon picks the range.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_generateSelfShipAppointmentSlots"},"tags":["amazon_sp"],"x-title":"FBA Inbound Generate Self Ship Appointment Slots","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"desired_start_date":{"default":"","format":"date-time","title":"Desired Start Date","type":"string","description":"ISO 8601 date-time (e.g. '2026-10-20T00:00:00Z'); optional — without it Amazon picks the range."},"desired_end_date":{"default":"","format":"date-time","title":"Desired End Date","type":"string","description":"ISO 8601 date-time (e.g. '2026-10-27T00:00:00Z'); optional — without it Amazon picks the range."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_generateSelfShipAppointmentSlotsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_scheduleSelfShipAppointment":{"post":{"operationId":"fbaInbound_scheduleSelfShipAppointment","summary":"Book, or reschedule, a self-ship appointment on a chosen slot (write, synchronous).","description":"Book, or reschedule, a self-ship appointment on a chosen slot (write, synchronous). Amazon SP-API · scheduleSelfShipAppointment · POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/selfShipAppointmentSlots/{slotId}/schedule Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Only available in MX, BR, EG, SA, AE and IN; to reschedule call it again with the new slot_id and a reason_comment.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_scheduleSelfShipAppointment"},"tags":["amazon_sp"],"x-title":"FBA Inbound Schedule Self Ship Appointment","x-access":"write","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.selfShipAppointmentDetails","description":"the scheduled appointment."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"slot_id":{"maxLength":38,"minLength":38,"title":"Slot Id","type":"string","description":"slotId from fbaInbound_getSelfShipAppointmentSlots."},"reason_comment":{"anyOf":[{"enum":["APPOINTMENT_REQUESTED_BY_MISTAKE","VEHICLE_DELAY","SLOT_NOT_SUITABLE","OUTSIDE_CARRIER_BUSINESS_HOURS","UNFAVOURABLE_EXTERNAL_CONDITIONS","PROCUREMENT_DELAY","SHIPPING_PLAN_CHANGED","INCREASED_QUANTITY","OTHER"],"type":"string"},{"type":"null"}],"default":null,"title":"Reason Comment","description":"why the appointment is rescheduled; pass it when rescheduling. Allowed: APPOINTMENT_REQUESTED_BY_MISTAKE | VEHICLE_DELAY | SLOT_NOT_SUITABLE | OUTSIDE_CARRIER_BUSINESS_HOURS | UNFAVOURABLE_EXTERNAL_CONDITIONS | PROCUREMENT_DELAY | SHIPPING_PLAN_CHANGED | INCREASED_QUANTITY | OTHER."}},"required":["store","plan_id","shipment_id","slot_id"],"title":"fbaInbound_scheduleSelfShipAppointmentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"selfShipAppointmentDetails":{"description":"the scheduled appointment."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInbound_cancelSelfShipAppointment":{"post":{"operationId":"fbaInbound_cancelSelfShipAppointment","summary":"Cancel a self-ship appointment (write, async).","description":"Cancel a self-ship appointment (write, async). Amazon SP-API · cancelSelfShipAppointment · PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/selfShipAppointmentCancellation Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Only available in MX, BR, EG, SA, AE and IN.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInbound_cancelSelfShipAppointment"},"tags":["amazon_sp"],"x-title":"FBA Inbound Cancel Self Ship Appointment","x-access":"destructive","x-family":"sp.fulfillmentInbound_2024-03-20","x-returns":[{"field":"data.operationId","description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"plan_id":{"title":"Plan Id","type":"string","description":"the inboundPlanId (from fbaInbound_createInboundPlan or fbaInbound_listInboundPlans)."},"shipment_id":{"maxLength":38,"minLength":38,"title":"Shipment Id","type":"string","description":"the shipmentId (from the placement option's shipmentIds in fbaInbound_listPlacementOptions, or fbaInbound_getInboundPlan once a placement is confirmed)."},"reason_comment":{"anyOf":[{"enum":["APPOINTMENT_REQUESTED_BY_MISTAKE","VEHICLE_DELAY","SLOT_NOT_SUITABLE","OUTSIDE_CARRIER_BUSINESS_HOURS","UNFAVOURABLE_EXTERNAL_CONDITIONS","PROCUREMENT_DELAY","SHIPPING_PLAN_CHANGED","INCREASED_QUANTITY","OTHER"],"type":"string"},{"type":"null"}],"default":null,"title":"Reason Comment","description":"optional reason for the cancellation. Allowed: APPOINTMENT_REQUESTED_BY_MISTAKE | VEHICLE_DELAY | SLOT_NOT_SUITABLE | OUTSIDE_CARRIER_BUSINESS_HOURS | UNFAVOURABLE_EXTERNAL_CONDITIONS | PROCUREMENT_DELAY | SHIPPING_PLAN_CHANGED | INCREASED_QUANTITY | OTHER."}},"required":["store","plan_id","shipment_id"],"title":"fbaInbound_cancelSelfShipAppointmentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"operationId":{"description":"poll with fbaInbound_getInboundOperationStatus until SUCCESS."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInventory_getInventorySummaries":{"post":{"operationId":"fbaInventory_getInventorySummaries","summary":"Live FBA inventory for one or a few SKUs right now (read, one page) — e.g.","description":"Live FBA inventory for one or a few SKUs right now (read, one page) — e.g. fulfillable and inbound counts before a decision. For all SKUs, history or trends use query_report_data on rpt_get_afn_inventory_data, which the reporting server refreshes daily — never page through the catalog here. Scope it with seller_skus or seller_sku. Amazon SP-API · getInventorySummaries · GET /fba/inventory/v1/summaries","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInventory_getInventorySummaries"},"tags":["amazon_sp"],"x-title":"FBA Inventory Get Inventory Summaries","x-access":"read","x-family":"sp.fbaInventory","x-returns":[{"field":"data.inventorySummaries","description":"list of per-SKU summary objects."},{"field":"data.nextToken","description":"cursor for the next page; '' when this is the last."}],"x-notes":{"Params (Amazon schema)":["details: boolean","granularityType*: Marketplace","granularityId*: string","startDateTime: string","sellerSkus: [string] (max 50) — you may specify up to 50 SKUs","sellerSku: string","nextToken: string","marketplaceIds*: [string] (max 1)"],"Gotchas":["data.nextToken expires 30 seconds after it is issued; when paging a start_date_time","query, pass the same start_date_time with next_token."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"details":{"default":false,"title":"Details","type":"boolean","description":"include inventoryDetails (fulfillable/inbound/reserved breakdown)."},"seller_skus":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Seller Skus","description":"optional list of seller SKUs (max 50) to scope to."},"seller_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Sku","description":"optional single seller SKU; ignored when seller_skus is given."},"start_date_time":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Start Date Time","description":"optional ISO 8601, no earlier than 18 months ago — only summaries changed since then; overrides seller_skus / seller_sku, and changes in the inbound quantities are not detected."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"fbaInventory_getInventorySummariesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"inventorySummaries":{"description":"list of per-SKU summary objects."},"nextToken":{"description":"cursor for the next page; '' when this is the last."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaInboundEligibility_getItemEligibilityPreview":{"post":{"operationId":"fbaInboundEligibility_getItemEligibilityPreview","summary":"Check whether an ASIN is eligible for FBA inbound (or commingling) (read).","description":"Check whether an ASIN is eligible for FBA inbound (or commingling) (read). Amazon SP-API · getItemEligibilityPreview · GET /fba/inbound/v1/eligibility/itemPreview Call before creating an inbound plan to avoid rejected items. If not eligible, data.eligibility.ineligibilityReasonList explains why.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaInboundEligibility_getItemEligibilityPreview"},"tags":["amazon_sp"],"x-title":"FBA Inbound Eligibility Get Item Eligibility Preview","x-access":"read","x-family":"sp.fbaInbound","x-returns":[{"field":"data.eligibility","description":"{asin, program, isEligibleForProgram, ineligibilityReasonList}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"program":{"default":"INBOUND","enum":["INBOUND","COMMINGLING"],"title":"Program","type":"string","description":"the eligibility program — INBOUND is FBA inbound, COMMINGLING is stickerless (commingled) inventory. Default: INBOUND. Used only with program INBOUND (COMMINGLING takes no marketplace)."}},"required":["store","asin"],"title":"fbaInboundEligibility_getItemEligibilityPreviewArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"eligibility":{"description":"{asin, program, isEligibleForProgram, ineligibilityReasonList}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_getFulfillmentPreview":{"post":{"operationId":"fbaOutbound_getFulfillmentPreview","summary":"Preview an MCF order's fees and fulfillability BEFORE creating it.","description":"Preview an MCF order's fees and fulfillability BEFORE creating it. Amazon SP-API · getFulfillmentPreview · POST /fba/outbound/2020-07-01/fulfillmentOrders/preview Always preview first — it shows estimatedFees, isFulfillable, and available shippingSpeedCategory per option. Non-mutating.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_getFulfillmentPreview"},"tags":["amazon_sp"],"x-title":"FBA Outbound Get Fulfillment Preview","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.fulfillmentPreviews","description":"one per shippingSpeedCategory — {shippingSpeedCategory, isFulfillable, isCODCapable, estimatedFees, fulfillmentPreviewShipments, unfulfillablePreviewItems, orderUnfulfillableReasons, scheduledDeliveryInfo}; the last three say why a preview is not fulfillable or when it can arrive."}],"x-notes":{"Body (Amazon schema)":["marketplaceId: string","address*: {name*, addressLine1*, addressLine2, addressLine3, city, districtOrCounty, stateOrRegion, postalCode*, countryCode*, phone}","items*: [{sellerSku* (max 50 chars), quantity*, perUnitDeclaredValue: {currencyCode*, value*}, sellerFulfillmentOrderItemId* (max 50 chars)}]","shippingSpeedCategories: [Standard | Expedited | Priority | ScheduledDelivery]","includeCODFulfillmentPreview: boolean","includeDeliveryWindows: boolean","featureConstraints: [{featureName, featureFulfillmentPolicy: Required | NotRequired}]"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"address":{"additionalProperties":true,"title":"Address","type":"object","description":"Destination Address — name, addressLine1, postalCode, countryCode (ISO 3166-1 alpha-2) required; city/stateOrRegion/ phone optional."},"items":{"items":{},"title":"Items","type":"array","description":"list of preview items — each {sellerSku, quantity, sellerFulfillmentOrderItemId (your tracking id), optional perUnitDeclaredValue {currencyCode, value}}."},"shipping_speed_categories":{"anyOf":[{"items":{"enum":["Standard","Expedited","Priority","ScheduledDelivery"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Shipping Speed Categories","description":"optional list of speed categories to preview; ScheduledDelivery requires include_delivery_windows here and a delivery_window on create. Allowed: Standard | Expedited | Priority | ScheduledDelivery."},"include_cod":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Include Cod","description":"optional bool — include Cash-On-Delivery previews."},"include_delivery_windows":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Include Delivery Windows","description":"optional bool — include scheduledDeliveryInfo."},"feature_constraints":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Feature Constraints","description":"optional list of {featureName, featureFulfillmentPolicy} objects constraining carrier/packaging: featureName. Allowed: BLOCK_AMZL (block Amazon Logistics; surcharge) | BLANK_BOX (non-branded packaging) | OVERBOX | PACKING_SLIP | SIGNATURE_CONFIRMATION (US only; extra fee) | DELIVER_TOGETHER (ship all items together). featureFulfillmentPolicy Required rejects the order when the feature is unavailable."}},"required":["store","address","items"],"title":"fbaOutbound_getFulfillmentPreviewArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"fulfillmentPreviews":{"description":"one per shippingSpeedCategory — {shippingSpeedCategory, isFulfillable, isCODCapable, estimatedFees, fulfillmentPreviewShipments, unfulfillablePreviewItems, orderUnfulfillableReasons, scheduledDeliveryInfo}; the last three say why a preview is not fulfillable or when it can arrive."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_deliveryOffers":{"post":{"operationId":"fbaOutbound_deliveryOffers","summary":"Get estimated delivery options (date + expiry) for a SKU to a destination.","description":"Get estimated delivery options (date + expiry) for a SKU to a destination. Amazon SP-API · deliveryOffers · POST /fba/outbound/2020-07-01/deliveryOffers Non-mutating.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_deliveryOffers"},"tags":["amazon_sp"],"x-title":"Get Delivery Offers","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.deliveryOffers","description":"list each with expiresAt and dateRange."}],"x-notes":{"Body (Amazon schema)":["product*: {productIdentifier*: {merchantSku*}, amount: {unitOfMeasure*, value*}}","product.amount.unitOfMeasure: Eaches","terms*: {origin*: {countryCode*}, destination*: {deliveryAddress, ipAddress}}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"product":{"additionalProperties":true,"title":"Product","type":"object","description":"GetDeliveryOffersProduct — {productIdentifier: {merchantSku REQUIRED, maxLength 50}, optional amount {unitOfMeasure REQUIRED, value REQUIRED (decimal STRING, e.g. '1')}}. amount.unitOfMeasure. Allowed: Eaches (the only valid value — an integer count of units)."},"terms":{"additionalProperties":true,"title":"Terms","type":"object","description":"GetDeliveryOffersTerms — {origin: {countryCode REQUIRED, 2-letter ISO 3166-1 alpha-2}, destination: {deliveryAddress: {postalCode REQUIRED, countryCode REQUIRED 2-letter, optional addressLine1/2/3, city, districtOrCounty, stateOrRegion}, optional ipAddress}}. NOTE: the address is nested under destination.deliveryAddress — destination itself has no postalCode/countryCode."}},"required":["store","product","terms"],"title":"fbaOutbound_deliveryOffersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"deliveryOffers":{"description":"list each with expiresAt and dateRange."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_listAllFulfillmentOrders":{"post":{"operationId":"fbaOutbound_listAllFulfillmentOrders","summary":"List MCF fulfillment orders.","description":"List MCF fulfillment orders. Returns one Amazon page (mirrors Amazon). Amazon SP-API · listAllFulfillmentOrders · GET /fba/outbound/2020-07-01/fulfillmentOrders Amazon paginates chronologically from query_start_date and may return an EMPTY page with a continuation token for a window with no orders — that is Amazon's own behavior. Pass data.nextToken back as next_token to fetch the next page; keep going until nextToken is null.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_listAllFulfillmentOrders"},"tags":["amazon_sp"],"x-title":"FBA Outbound List All Fulfillment Orders","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.fulfillmentOrders","description":"list of order summaries (may be empty)."},{"field":"data.nextToken","description":"pass back as next_token for the next page (if present)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"query_start_date":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Query Start Date","description":"optional ISO-8601 — only orders updated at/after this."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"fbaOutbound_listAllFulfillmentOrdersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"fulfillmentOrders":{"description":"list of order summaries (may be empty)."},"nextToken":{"description":"pass back as next_token for the next page (if present)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_getFulfillmentOrder":{"post":{"operationId":"fbaOutbound_getFulfillmentOrder","summary":"Get one MCF fulfillment order with its items and shipments.","description":"Get one MCF fulfillment order with its items and shipments. Amazon SP-API · getFulfillmentOrder · GET /fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_getFulfillmentOrder"},"tags":["amazon_sp"],"x-title":"FBA Outbound Get Fulfillment Order","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.fulfillmentOrder","description":"header incl. fulfillmentOrderStatus."},{"field":"data.fulfillmentOrderItems / data.fulfillmentShipments","description":"detail — shipment packages carry packageNumber for fbaOutbound_getPackageTrackingDetails."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"seller_fulfillment_order_id":{"maxLength":40,"title":"Seller Fulfillment Order Id","type":"string","description":"the id you assigned when creating the order."}},"required":["store","seller_fulfillment_order_id"],"title":"fbaOutbound_getFulfillmentOrderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"fulfillmentOrder":{"description":"header incl. fulfillmentOrderStatus."},"fulfillmentOrderItems":{"description":"detail — shipment packages carry packageNumber for fbaOutbound_getPackageTrackingDetails."},"fulfillmentShipments":{"description":"detail — shipment packages carry packageNumber for fbaOutbound_getPackageTrackingDetails."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_getPackageTrackingDetails":{"post":{"operationId":"fbaOutbound_getPackageTrackingDetails","summary":"Get delivery tracking details for one outbound MCF package.","description":"Get delivery tracking details for one outbound MCF package. Amazon SP-API · getPackageTrackingDetails · GET /fba/outbound/2020-07-01/tracking","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_getPackageTrackingDetails"},"tags":["amazon_sp"],"x-title":"FBA Outbound Get Package Tracking Details","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.currentStatus","description":"Amazon's CurrentStatus (IN_TRANSIT, DELIVERED, RETURNING, UNDELIVERABLE, DELAYED, …), with currentStatusDescription."},{"field":"data.trackingNumber / data.carrierCode / data.customerTrackingLink","description":"the carrier and the buyer-facing tracking link."},{"field":"data.trackingEvents","description":"[{eventDate, eventCode, eventDescription, eventAddress}]."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"package_number":{"title":"Package Number","type":"integer","description":"integer packageNumber from a shipment package (fbaOutbound_getFulfillmentOrder → fulfillmentShipments[].fulfillmentShipmentPackage[])."}},"required":["store","package_number"],"title":"fbaOutbound_getPackageTrackingDetailsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"currentStatus":{"description":"Amazon's CurrentStatus (IN_TRANSIT, DELIVERED, RETURNING, UNDELIVERABLE, DELAYED, …), with currentStatusDescription."},"trackingNumber":{"description":"the carrier and the buyer-facing tracking link."},"carrierCode":{"description":"the carrier and the buyer-facing tracking link."},"customerTrackingLink":{"description":"the carrier and the buyer-facing tracking link."},"trackingEvents":{"description":"[{eventDate, eventCode, eventDescription, eventAddress}]."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_listReturnReasonCodes":{"post":{"operationId":"fbaOutbound_listReturnReasonCodes","summary":"List valid return reason codes for a SKU (call before fbaOutbound_createFulfillmentReturn).","description":"List valid return reason codes for a SKU (call before fbaOutbound_createFulfillmentReturn). Amazon SP-API · listReturnReasonCodes · GET /fba/outbound/2020-07-01/returnReasonCodes","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_listReturnReasonCodes"},"tags":["amazon_sp"],"x-title":"FBA Outbound List Return Reason Codes","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.reasonCodeDetails","description":"list of {returnReasonCode, description, translatedDescription}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"seller_sku":{"title":"Seller Sku","type":"string","description":"the SKU to return."},"seller_fulfillment_order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Fulfillment Order Id","description":"optional — scope reasons to one order."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language","description":"optional language tag for translated descriptions."}},"required":["store","seller_sku"],"title":"fbaOutbound_listReturnReasonCodesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reasonCodeDetails":{"description":"list of {returnReasonCode, description, translatedDescription}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_getFeatures":{"post":{"operationId":"fbaOutbound_getFeatures","summary":"List MCF features available in the store's marketplace + seller enrollment.","description":"List MCF features available in the store's marketplace + seller enrollment. Amazon SP-API · getFeatures · GET /fba/outbound/2020-07-01/features","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_getFeatures"},"tags":["amazon_sp"],"x-title":"FBA Outbound Get Features","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.features","description":"list of {featureName, sellerEligible}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."}},"required":["store"],"title":"fbaOutbound_getFeaturesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"features":{"description":"list of {featureName, sellerEligible}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_getFeatureInventory":{"post":{"operationId":"fbaOutbound_getFeatureInventory","summary":"List inventory SKUs eligible for a given MCF feature.","description":"List inventory SKUs eligible for a given MCF feature. Returns one page. Amazon SP-API · getFeatureInventory · GET /fba/outbound/2020-07-01/features/inventory/{featureName}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_getFeatureInventory"},"tags":["amazon_sp"],"x-title":"FBA Outbound Get Feature Inventory","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.featureSkus","description":"[{sellerSku, fnSku, asin, skuCount, overlappingSkus}] — skuCount is the units available for the feature."},{"field":"data.nextToken","description":"pass back as next_token for the next page (if present)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"feature_name":{"title":"Feature Name","type":"string","description":"feature to filter by, e.g. 'BLANK_BOX' or 'BLOCK_AMZL'. Amazon publishes no enum — fbaOutbound_getFeatures is the authoritative list for the store's marketplace."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."},"query_start_date":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Query Start Date","description":"optional ISO-8601 — only SKUs updated since then."}},"required":["store","feature_name"],"title":"fbaOutbound_getFeatureInventoryArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"featureSkus":{"description":"[{sellerSku, fnSku, asin, skuCount, overlappingSkus}] — skuCount is the units available for the feature."},"nextToken":{"description":"pass back as next_token for the next page (if present)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_getFeatureSKU":{"post":{"operationId":"fbaOutbound_getFeatureSKU","summary":"Get the count of one SKU eligible for a given MCF feature.","description":"Get the count of one SKU eligible for a given MCF feature. Amazon SP-API · getFeatureSKU · GET /fba/outbound/2020-07-01/features/inventory/{featureName}/{sellerSku}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_getFeatureSKU"},"tags":["amazon_sp"],"x-title":"FBA Outbound Get Feature SKU","x-access":"read","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.isEligible","description":"bool — whether the SKU can use this feature."},{"field":"data.ineligibleReasons","description":"list of reasons when isEligible is false."},{"field":"data.skuCount","description":"number of units available for the feature."},{"field":"data.fnSku / data.asin","description":"the item's fulfillment-network SKU and ASIN."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"feature_name":{"title":"Feature Name","type":"string","description":"feature to check, e.g. 'BLANK_BOX' or 'BLOCK_AMZL'. Amazon publishes no enum — fbaOutbound_getFeatures is the authoritative list for the store's marketplace."},"seller_sku":{"title":"Seller Sku","type":"string","description":"the SKU to check."}},"required":["store","feature_name","seller_sku"],"title":"fbaOutbound_getFeatureSKUArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"isEligible":{"description":"bool — whether the SKU can use this feature."},"ineligibleReasons":{"description":"list of reasons when isEligible is false."},"skuCount":{"description":"number of units available for the feature."},"fnSku":{"description":"the item's fulfillment-network SKU and ASIN."},"asin":{"description":"the item's fulfillment-network SKU and ASIN."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_createFulfillmentOrder":{"post":{"operationId":"fbaOutbound_createFulfillmentOrder","summary":"Create a Multi-Channel Fulfillment order — ships FBA inventory to a non-Amazon customer address.","description":"Create a Multi-Channel Fulfillment order — ships FBA inventory to a non-Amazon customer address. IRREVERSIBLE spend: run fbaOutbound_getFulfillmentPreview first for the fees and isFulfillable, and confirm with the human before submitting. Amazon SP-API · createFulfillmentOrder · POST /fba/outbound/2020-07-01/fulfillmentOrders Gate: commit, fee-bearing — interactive: restate the amount, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_createFulfillmentOrder"},"tags":["amazon_sp"],"x-title":"FBA Outbound Create Fulfillment Order","x-access":"write","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.sellerFulfillmentOrderId","description":"the order to poll with fbaOutbound_getFulfillmentOrder — Amazon returns no other payload."}],"x-notes":{"Body (Amazon schema)":["marketplaceId: string","sellerFulfillmentOrderId*: string (max 40 chars)","displayableOrderId*: string (max 40 chars)","displayableOrderDate*: string (date-time)","displayableOrderComment*: string (max 750 chars)","shippingSpeedCategory*: Standard | Expedited | Priority | ScheduledDelivery","deliveryWindow: {startDate*, endDate*}","destinationAddress*: {name*, addressLine1*, addressLine2, addressLine3, city, districtOrCounty, stateOrRegion, postalCode*, countryCode*, phone}","deliveryPreferences: {deliveryInstructions (max 250 chars), dropOffLocation: {type*, attributes}}","deliveryPreferences.dropOffLocation.type: FRONT_DOOR | DELIVERY_BOX | GAS_METER_BOX | BICYCLE_BASKET | GARAGE | RECEPTIONIST | FALLBACK_NEIGHBOR_DELIVERY | DO_NOT_LEAVE_UNATTENDED","fulfillmentAction: Ship | Hold","fulfillmentPolicy: FillOrKill | FillAll | FillAllAvailable","codSettings: {isCodRequired*, codCharge: {currencyCode*, value*}, codChargeTax: {currencyCode*, value*},","  shippingCharge: {currencyCode*, value*}, shippingChargeTax: {currencyCode*, value*}}","shipFromCountryCode: string","notificationEmails: [string] (max 64 chars)","featureConstraints: [{featureName, featureFulfillmentPolicy: Required | NotRequired}]","items*: [{sellerSku* (max 50 chars), sellerFulfillmentOrderItemId* (max 50 chars), quantity*, giftMessage (max 512 chars), displayableComment (max 250 chars), fulfillmentNetworkSku,","  perUnitDeclaredValue: {currencyCode*, value*}, perUnitPrice: {currencyCode*, value*}, perUnitTax:","    {currencyCode*, value*}}]","paymentInformation: [{paymentTransactionId*, paymentMode*, paymentDate*}]"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"seller_fulfillment_order_id":{"maxLength":40,"title":"Seller Fulfillment Order Id","type":"string","description":"your unique order id (≤40 chars)."},"displayable_order_id":{"maxLength":40,"title":"Displayable Order Id","type":"string","description":"the customer-facing order id on the packing slip (≤40)."},"displayable_order_date":{"format":"date-time","title":"Displayable Order Date","type":"string","description":"ISO-8601 timestamp shown to the customer."},"displayable_order_comment":{"maxLength":750,"title":"Displayable Order Comment","type":"string","description":"text on the recipient materials (≤750)."},"shipping_speed_category":{"enum":["Standard","Expedited","Priority","ScheduledDelivery"],"title":"Shipping Speed Category","type":"string","description":"required — the speed to ship at; ScheduledDelivery also needs delivery_window. Allowed: Standard | Expedited | Priority | ScheduledDelivery."},"destination_address":{"additionalProperties":true,"title":"Destination Address","type":"object","description":"{name, addressLine1, postalCode, countryCode (ISO alpha-2)} required, plus the usual address fields."},"items":{"items":{},"title":"Items","type":"array","description":"[{sellerSku (≤50), sellerFulfillmentOrderItemId (≤50, your own item id), quantity (int)} required; giftMessage (≤512), displayableComment (≤250), fulfillmentNetworkSku, perUnitDeclaredValue, perUnitPrice, perUnitTax (each a Money {currencyCode, value as a decimal string}) optional]."},"fulfillment_action":{"anyOf":[{"enum":["Ship","Hold"],"type":"string"},{"type":"null"}],"default":null,"title":"Fulfillment Action","description":"ship now or hold — Hold places an order hold, released later with fbaOutbound_updateFulfillmentOrder fulfillment_action Ship; Amazon cancels a held order after 14 days. Default: Ship."},"fulfillment_policy":{"anyOf":[{"enum":["FillOrKill","FillAll","FillAllAvailable"],"type":"string"},{"type":"null"}],"default":null,"title":"Fulfillment Policy","description":"what happens to unfulfillable items — FillOrKill cancels the order if any item is unfulfillable; FillAll ships every fulfillable item and keeps the order open until the rest ship or are cancelled (on Ship it turns Unfulfillable or CompletePartialled after 24 h); FillAllAvailable ships what is available now. Default: FillOrKill."},"cod_settings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Cod Settings","description":"{isCodRequired (bool, required), codCharge, codChargeTax, shippingCharge, shippingChargeTax (each a Money)}."},"ship_from_country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ship From Country Code","description":"ISO alpha-2 origin country."},"notification_emails":{"anyOf":[{"items":{"maxLength":64,"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Notification Emails","description":"addresses to notify (each ≤64)."},"feature_constraints":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Feature Constraints","description":"[{featureName, featureFulfillmentPolicy}] — featureName: BLOCK_AMZL (no Amazon Logistics; surcharge) | BLANK_BOX | OVERBOX | PACKING_SLIP | SIGNATURE_CONFIRMATION (US only; fee) | DELIVER_TOGETHER; featureFulfillmentPolicy: Required (reject the order if unavailable) | NotRequired."},"delivery_window":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Delivery Window","description":"{startDate, endDate} for ScheduledDelivery."},"delivery_preferences":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Delivery Preferences","description":"{deliveryInstructions (≤250), dropOffLocation: {type, attributes}} — JP marketplace only, applied best-effort."},"payment_information":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Payment Information","description":"[{paymentTransactionId, paymentMode, paymentDate (ISO-8601)}], all three required per record; required for India orders (as is items[].perUnitDeclaredValue)."}},"required":["store","seller_fulfillment_order_id","displayable_order_id","displayable_order_date","displayable_order_comment","shipping_speed_category","destination_address","items"],"title":"fbaOutbound_createFulfillmentOrderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sellerFulfillmentOrderId":{"description":"the order to poll with fbaOutbound_getFulfillmentOrder — Amazon returns no other payload."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_updateFulfillmentOrder":{"post":{"operationId":"fbaOutbound_updateFulfillmentOrder","summary":"Update or request shipment for an MCF order that has an order hold.","description":"Update or request shipment for an MCF order that has an order hold. Amazon SP-API · updateFulfillmentOrder · PUT /fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Only works on orders with status that allows updates (e.g. on Hold). Pass fulfillment_action='Ship' to release a held order.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_updateFulfillmentOrder"},"tags":["amazon_sp"],"x-title":"FBA Outbound Update Fulfillment Order","x-access":"destructive","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.sellerFulfillmentOrderId","description":"the updated order — re-read it with fbaOutbound_getFulfillmentOrder."}],"x-notes":{"Body (Amazon schema)":["marketplaceId: string","displayableOrderId: string (max 40 chars)","displayableOrderDate: string (date-time)","displayableOrderComment: string (max 750 chars)","shippingSpeedCategory: Standard | Expedited | Priority | ScheduledDelivery","destinationAddress: {name*, addressLine1*, addressLine2, addressLine3, city, districtOrCounty, stateOrRegion, postalCode*, countryCode*, phone}","fulfillmentAction: Ship | Hold","fulfillmentPolicy: FillOrKill | FillAll | FillAllAvailable","shipFromCountryCode: string","notificationEmails: [string] (max 64 chars)","featureConstraints: [{featureName, featureFulfillmentPolicy: Required | NotRequired}]","items: [{sellerSku, sellerFulfillmentOrderItemId* (max 50 chars), quantity*, giftMessage (max 512 chars), displayableComment (max 250 chars), fulfillmentNetworkSku, orderItemDisposition, perUnitDeclaredValue: {currencyCode*, value*}, perUnitPrice: {currencyCode*, value*}, perUnitTax: {currencyCode*, value*}}]"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"seller_fulfillment_order_id":{"maxLength":40,"title":"Seller Fulfillment Order Id","type":"string","description":"the order to update."},"displayable_order_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"title":"Displayable Order Id","description":"optional displayable field updates."},"displayable_order_date":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Displayable Order Date","description":"optional displayable field updates."},"displayable_order_comment":{"anyOf":[{"maxLength":750,"type":"string"},{"type":"null"}],"default":null,"title":"Displayable Order Comment","description":"optional displayable field updates."},"shipping_speed_category":{"anyOf":[{"enum":["Standard","Expedited","Priority","ScheduledDelivery"],"type":"string"},{"type":"null"}],"default":null,"title":"Shipping Speed Category","description":"optional new speed category. Allowed: Standard | Expedited | Priority | ScheduledDelivery."},"destination_address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Destination Address","description":"optional new Address."},"fulfillment_action":{"anyOf":[{"enum":["Ship","Hold"],"type":"string"},{"type":"null"}],"default":null,"title":"Fulfillment Action","description":"optional — Ship releases a held order. Allowed: Ship | Hold."},"fulfillment_policy":{"anyOf":[{"enum":["FillOrKill","FillAll","FillAllAvailable"],"type":"string"},{"type":"null"}],"default":null,"title":"Fulfillment Policy","description":"optional — what happens to unfulfillable items: FillOrKill cancels the whole order if any item is unfulfillable; FillAll ships every fulfillable item and keeps the order open until the rest ship or are cancelled; FillAllAvailable ships what is available."},"ship_from_country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ship From Country Code","description":"optional ISO alpha-2 origin country."},"items":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Items","description":"optional list of UpdateFulfillmentOrderItem — each {sellerFulfillmentOrderItemId (REQUIRED, maxLength 50 — identifies the item to update), quantity (REQUIRED int), optional sellerSku, giftMessage (maxLength 512), displayableComment (maxLength 250), fulfillmentNetworkSku, orderItemDisposition (whether the item is sellable or unsellable — no enum in the model; Amazon's examples use 'Sellable'), perUnitDeclaredValue / perUnitPrice / perUnitTax — each a Money {currencyCode (ISO 4217), value (decimal STRING)}}. NOTE: this shape differs from create — sellerSku is optional here and sellerFulfillmentOrderItemId is the key."},"notification_emails":{"anyOf":[{"items":{"maxLength":64,"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Notification Emails","description":"optional list of addresses to notify."},"feature_constraints":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Feature Constraints","description":"optional list of {featureName, featureFulfillmentPolicy}. featureName. Allowed: BLOCK_AMZL (block Amazon Logistics; surcharge) | BLANK_BOX (non-branded packaging) | OVERBOX | PACKING_SLIP | SIGNATURE_CONFIRMATION (US only; extra fee) | DELIVER_TOGETHER (ship all items together). featureFulfillmentPolicy Required rejects the order when the feature is unavailable."}},"required":["store","seller_fulfillment_order_id"],"title":"fbaOutbound_updateFulfillmentOrderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sellerFulfillmentOrderId":{"description":"the updated order — re-read it with fbaOutbound_getFulfillmentOrder."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_cancelFulfillmentOrder":{"post":{"operationId":"fbaOutbound_cancelFulfillmentOrder","summary":"Cancel an MCF fulfillment order.","description":"Cancel an MCF fulfillment order. IRREVERSIBLE — confirm with the human first. Amazon SP-API · cancelFulfillmentOrder · PUT /fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}/cancel Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Already-shipped orders cannot be cancelled.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_cancelFulfillmentOrder"},"tags":["amazon_sp"],"x-title":"FBA Outbound Cancel Fulfillment Order","x-access":"destructive","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.sellerFulfillmentOrderId","description":"the order whose cancellation was requested — fbaOutbound_getFulfillmentOrder shows fulfillmentOrderStatus Cancelled once Amazon applies it."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"seller_fulfillment_order_id":{"maxLength":40,"title":"Seller Fulfillment Order Id","type":"string","description":"the order to cancel."}},"required":["store","seller_fulfillment_order_id"],"title":"fbaOutbound_cancelFulfillmentOrderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sellerFulfillmentOrderId":{"description":"the order whose cancellation was requested — fbaOutbound_getFulfillmentOrder shows fulfillmentOrderStatus Cancelled once Amazon applies it."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/fbaOutbound_createFulfillmentReturn":{"post":{"operationId":"fbaOutbound_createFulfillmentReturn","summary":"Create a return for a fulfilled MCF order.","description":"Create a return for a fulfilled MCF order. Amazon SP-API · createFulfillmentReturn · PUT /fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}/return Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Call fbaOutbound_listReturnReasonCodes first to get valid returnReasonCode values.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/fbaOutbound_createFulfillmentReturn"},"tags":["amazon_sp"],"x-title":"FBA Outbound Create Fulfillment Return","x-access":"write","x-family":"sp.fulfillmentOutbound_2020-07-01","x-returns":[{"field":"data.returnItems","description":"the items Amazon accepted."},{"field":"data.invalidReturnItems","description":"the items Amazon refused, each with invalidItemReason {invalidItemReasonCode, description}."},{"field":"data.returnAuthorizations","description":"{returnAuthorizationId, amazonRmaId, rmaPageURL (return label page), returnToAddress}."},{"field":"notification.type","description":"'warning' when any item is invalid, 'error' when none were accepted — the message counts accepted items against the number requested."}],"x-notes":{"Body (Amazon schema): {items: [CreateReturnItem]}, each item":["sellerReturnItemId*: string (max 80 chars)","sellerFulfillmentOrderItemId*: string","amazonShipmentId*: string","returnReasonCode*: string","returnComment: string (max 1000 chars)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"seller_fulfillment_order_id":{"title":"Seller Fulfillment Order Id","type":"string","description":"the order being returned."},"items":{"items":{},"title":"Items","type":"array","description":"list of CreateReturnItem — each {sellerReturnItemId (your own id), sellerFulfillmentOrderItemId (the item id on the order), amazonShipmentId (fbaOutbound_getFulfillmentOrder → fulfillmentShipments[].amazonShipmentId), returnReasonCode, optional returnComment}. returnReasonCode: NOT a fixed enum — values are SKU/marketplace specific. Call fbaOutbound_listReturnReasonCodes(store, seller_sku) first and use a returnReasonCode from its data.reasonCodeDetails."}},"required":["store","seller_fulfillment_order_id","items"],"title":"fbaOutbound_createFulfillmentReturnArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"],"description":"'warning' when any item is invalid, 'error' when none were accepted — the message counts accepted items against the number requested."}}},"data":{"type":"object","properties":{"returnItems":{"description":"the items Amazon accepted."},"invalidReturnItems":{"description":"the items Amazon refused, each with invalidItemReason {invalidItemReasonCode, description}."},"returnAuthorizations":{"description":"{returnAuthorizationId, amazonRmaId, rmaPageURL (return label page), returnToAddress}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_getListingsItem":{"post":{"operationId":"listings_getListingsItem","summary":"Get the SELLER'S SUBMITTED attributes, status, and issues for a single listing SKU.","description":"Get the SELLER'S SUBMITTED attributes, status, and issues for a single listing SKU. Amazon SP-API · getListingsItem · GET /listings/2021-08-01/items/{sellerId}/{sku} Account types: Seller Central + Vendor Central (vendors pass seller_id) This returns what the seller sent to Amazon — NOT what the detail page shows. Amazon may override these values with data from other sellers or its own sources. To see whether Amazon kept your values, compare data.attributes with catalogItems_getCatalogItem's data.item.attributes for the ASIN — a difference means Amazon chose another contribution. Use to inspect a listing before making changes, or to verify that a listings_putListingsItem / listings_patchListingsItem took effect. Fix a flagged attribute with listings_patchListingsItem on the issue's attributeNames.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_getListingsItem"},"tags":["amazon_sp"],"x-title":"Listings Get Listings Item","x-access":"read","x-family":"sp.listingsItems_2021-08-01","x-returns":[{"field":"data","description":"Amazon's listing payload — the fields below."},{"field":"data.summaries[0].status","description":"'BUYABLE' (active and buyable) and/or 'DISCOVERABLE' (visible). A missing BUYABLE does not by itself mean suppressed (no stock, or a vendor listing — BUYABLE never applies to vendors)."},{"field":"data.summaries[0].asin","description":"the ASIN this SKU maps to."},{"field":"data.issues[]","description":"{code, message, severity ERROR | WARNING | INFO, attributeNames, enforcements}. The listing is suppressed when an issue's enforcements.actions[].action is Amazon's listing-suppressed action (the others suppress one attribute, remove the catalog item, or hide it from search)."},{"field":"data.attributes","description":"dict of current attribute values in SP-API format."},{"field":"data.fulfillmentAvailability[]","description":"qty by channel: - fulfillmentChannelCode 'DEFAULT' = FBM (merchant-fulfilled) - fulfillmentChannelCode 'AMAZON_NA' / 'AMAZON_EU' = FBA"}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"sku":{"title":"Sku","type":"string","description":"Merchant SKU (msku)."},"included_data":{"anyOf":[{"items":{"enum":["summaries","attributes","issues","offers","fulfillmentAvailability","procurement","relationships","productTypes"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Included Data","description":"datasets to return; default ['summaries', 'issues', 'attributes', 'fulfillmentAvailability']. procurement is for vendors only. Allowed: summaries | attributes | issues | offers | fulfillmentAvailability | procurement | relationships | productTypes."},"issue_locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issue Locale","description":"locale of Amazon's issue messages (e.g. 'en_US'); defaults to the marketplace's primary language."},"seller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Id","description":"Vendor Central accounts ONLY — pass your vendor code (e.g. 'ABCDE' from vendorOrders_getPurchaseOrders → orderDetails.sellingParty.partyId). Vendors may hold multiple codes across marketplaces/warehouses; pick the one for the marketplace you need. Do not pass this for Seller Central — the merchant token is used automatically."}},"required":["store","sku"],"title":"listings_getListingsItemArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"issues":{"description":"{code, message, severity ERROR | WARNING | INFO, attributeNames, enforcements}. The listing is suppressed when an issue's enforcements.actions[].action is Amazon's listing-suppressed action (the others suppress one attribute, remove the catalog item, or hide it from search)."},"attributes":{"description":"dict of current attribute values in SP-API format."},"fulfillmentAvailability":{"description":"qty by channel: - fulfillmentChannelCode 'DEFAULT' = FBM (merchant-fulfilled) - fulfillmentChannelCode 'AMAZON_NA' / 'AMAZON_EU' = FBA"}},"description":"Amazon's listing payload — the fields below."},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_putListingsItem":{"post":{"operationId":"listings_putListingsItem","summary":"Create a listing, or fully replace an existing one — PUT replaces every attribute, so for a targeted change use listings_patchListingsItem.","description":"Create a listing, or fully replace an existing one — PUT replaces every attribute, so for a targeted change use listings_patchListingsItem. Requires a write-enabled store. Takes the nested Amazon shape only: for Publish Queue cells (flat-file keys) use listings_submit_items, or listings_submit_feed for large batches. Amazon SP-API · putListingsItem · PUT /listings/2021-08-01/items/{sellerId}/{sku} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_putListingsItem"},"tags":["amazon_sp"],"x-title":"Listings Put Listings Item","x-access":"destructive","x-family":"sp.listingsItems_2021-08-01","x-returns":[{"field":"data.status","description":"ACCEPTED (queued) | INVALID | VALID (the preview passed)."},{"field":"data.submissionId","description":"this submission."},{"field":"data.issues","description":"when INVALID — [{code, message, severity ERROR | WARNING | INFO, categories, attributeNames}]: fix them and resubmit without mode. After ACCEPTED, listings_getListingsItem after ~30 s shows whether the listing is BUYABLE."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"sku":{"title":"Sku","type":"string","description":"the merchant SKU — a new SKU creates, an existing one replaces."},"product_type":{"title":"Product Type","type":"string","description":"the Amazon productType, e.g. 'LUGGAGE' (productTypeDefinitions_searchDefinitionsProductTypes finds it); 'PRODUCT' for LISTING_OFFER_ONLY."},"attributes":{"additionalProperties":true,"title":"Attributes","type":"object","description":"{attribute_name: [value objects]} — every value is an ARRAY of objects carrying marketplace_id, text ones language_tag too, e.g. item_name [{\"value\": \"My Product\", \"language_tag\": \"en_US\", \"marketplace_id\": \"ATVPDKIKX0DER\"}]; merchant_suggested_asin [{\"value\": \"B0XXXXXXXX\", \"marketplace_id\": …}]; purchasable_offer [{\"audience\": \"ALL\", \"currency\": \"USD\", \"our_price\": [{\"schedule\": [{\"value_with_tax\": 29.99}]}]}]; fulfillment_availability [{\"fulfillment_channel_code\": \"DEFAULT\", \"quantity\": 10}]; main_product_image_locator [{\"media_location\": \"https://…/img.jpg\", \"marketplace_id\": …}]. Shapes, enums, units and required keys are productType-specific — take them from an existing listing (listings_getListingsItem returns exactly this shape), a catalog item (catalogItems_getCatalogItem) or the authoritative schema (productTypeDefinitions_getDefinitionsProductType). The marketplace id comes from get_user_context."},"requirements":{"anyOf":[{"enum":["LISTING","LISTING_PRODUCT_ONLY","LISTING_OFFER_ONLY"],"type":"string"},{"type":"null"}],"default":null,"title":"Requirements","description":"LISTING (default — product facts + sales terms) | LISTING_OFFER_ONLY (sales terms only: condition_type, merchant_suggested_asin, purchasable_offer, fulfillment_availability, with product_type 'PRODUCT') | LISTING_PRODUCT_ONLY (product facts only; not for vendors)."},"included_data":{"anyOf":[{"items":{"enum":["identifiers","issues"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Included Data","description":"datasets to return; default ['issues']; identifiers needs mode VALIDATION_PREVIEW."},"mode":{"anyOf":[{"const":"VALIDATION_PREVIEW","type":"string"},{"type":"null"}],"default":null,"title":"Mode","description":"'VALIDATION_PREVIEW' validates without submitting (no write access needed); omit to submit."},"issue_locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issue Locale","description":"locale of Amazon's issue messages (e.g. 'en_US'); defaults to the marketplace's primary language."},"seller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Id","description":"Vendor Central only — the vendor code (sellingParty.partyId from vendorOrders_getPurchaseOrders); omit on a seller account."}},"required":["store","sku","product_type","attributes"],"title":"listings_putListingsItemArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"ACCEPTED (queued) | INVALID | VALID (the preview passed)."},"submissionId":{"description":"this submission."},"issues":{"description":"when INVALID — [{code, message, severity ERROR | WARNING | INFO, categories, attributeNames}]: fix them and resubmit without mode. After ACCEPTED, listings_getListingsItem after ~30 s shows whether the listing is BUYABLE."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_patchListingsItem":{"post":{"operationId":"listings_patchListingsItem","summary":"Patch attributes on an existing listing (JSON Patch) without replacing it — the tool for fixing a suppressed listing or changing price, inventory, title or images.","description":"Patch attributes on an existing listing (JSON Patch) without replacing it — the tool for fixing a suppressed listing or changing price, inventory, title or images. Several patches may travel in one call. Amazon SP-API · patchListingsItem · PATCH /listings/2021-08-01/items/{sellerId}/{sku} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_patchListingsItem"},"tags":["amazon_sp"],"x-title":"Listings Patch Listings Item","x-access":"destructive","x-family":"sp.listingsItems_2021-08-01","x-returns":[{"field":"data.status","description":"ACCEPTED (queued) | INVALID | VALID (the preview passed)."},{"field":"data.submissionId","description":"this submission."},{"field":"data.issues","description":"when INVALID — [{code, message, severity ERROR | WARNING | INFO, categories, attributeNames}]: fix them and resubmit without mode. After ACCEPTED, listings_getListingsItem after ~30 s shows the result."}],"x-notes":{"Body (Amazon schema)":["productType*: string","patches*: [{op*: add | replace | merge | delete, path*, value: [object]}] (min 1)"],"Gotchas":["A delete op must carry the attribute's EXACT current array as value, copied from","listings_getListingsItem — an empty, omitted or simplified value comes back INVALID.","Detach a child from its variation family: three delete ops — parentage_level,","child_parent_sku_relationship, variation_theme — each with its current array; confirm","with listings_getListingsItem.","Add a child to a family: read variation_theme[0].name on the PARENT (e.g. COLOR_NAME),","then on the CHILD replace parentage_level [{\"value\": \"child\", \"marketplace_id\": …}],","child_parent_sku_relationship [{\"child_relationship_type\": \"variation\", \"parent_sku\":","\"PARENT-SKU\", \"marketplace_id\": …}], variation_theme [{\"name\": \"COLOR_NAME\",","\"marketplace_id\": …}] and the themed attribute itself (color …); confirm on the parent","with included_data ['relationships']."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"sku":{"title":"Sku","type":"string","description":"the merchant SKU of an existing listing."},"product_type":{"title":"Product Type","type":"string","description":"the listing's productType — data.summaries[0].productType from listings_getListingsItem."},"patches":{"items":{},"title":"Patches","type":"array","description":"[{op, path, value}], at least one. op: add | replace | merge | delete (delete is not supported for vendors — Amazon returns 400). path: '/attributes/<attribute_name>'. value: the attribute's value ARRAY in exactly the shape listings_getListingsItem returns under data.attributes.<name> — read it first and patch only the paths you change; model a new attribute from catalogItems_getCatalogItem or from productTypeDefinitions_getDefinitionsProductType (the authoritative schema: enums, units, required keys). Examples — title: {\"op\": \"replace\", \"path\": \"/attributes/item_name\", \"value\": [{\"value\": \"New Title\", \"language_tag\": \"en_US\", \"marketplace_id\": \"ATVPDKIKX0DER\"}]}; price: path /attributes/purchasable_offer, value [{\"audience\": \"ALL\", \"currency\": \"USD\", \"our_price\": [{\"schedule\": [{\"value_with_tax\": 29.99}]}]}]; FBM stock: path /attributes/fulfillment_availability, value [{\"fulfillment_channel_code\": \"DEFAULT\", \"quantity\": 50}]; main image: path /attributes/main_product_image_locator, value [{\"media_location\": \"https://…/img.jpg\", \"marketplace_id\": \"ATVPDKIKX0DER\"}]."},"included_data":{"anyOf":[{"items":{"enum":["identifiers","issues"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Included Data","description":"datasets to return; default ['issues']; identifiers needs mode VALIDATION_PREVIEW."},"mode":{"anyOf":[{"const":"VALIDATION_PREVIEW","type":"string"},{"type":"null"}],"default":null,"title":"Mode","description":"'VALIDATION_PREVIEW' validates the patches without applying them (no write access needed); omit to apply."},"issue_locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issue Locale","description":"locale of Amazon's issue messages (e.g. 'en_US'); defaults to the marketplace's primary language."},"seller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Id","description":"Vendor Central only — the vendor code (sellingParty.partyId from vendorOrders_getPurchaseOrders); omit on a seller account."}},"required":["store","sku","product_type","patches"],"title":"listings_patchListingsItemArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"ACCEPTED (queued) | INVALID | VALID (the preview passed)."},"submissionId":{"description":"this submission."},"issues":{"description":"when INVALID — [{code, message, severity ERROR | WARNING | INFO, categories, attributeNames}]: fix them and resubmit without mode. After ACCEPTED, listings_getListingsItem after ~30 s shows the result."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_deleteListingsItem":{"post":{"operationId":"listings_deleteListingsItem","summary":"Delete this seller's listing for a SKU (offer and submitted attributes); the ASIN's catalog page stays.","description":"Delete this seller's listing for a SKU (offer and submitted attributes); the ASIN's catalog page stays. Amazon SP-API · deleteListingsItem · DELETE /listings/2021-08-01/items/{sellerId}/{sku} Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask. Account types: Seller Central + Vendor Central (vendors pass seller_id) Amazon queues the deletion (status ACCEPTED); it cannot be undone except by re-creating the listing with listings_putListingsItem. Verify the SKU with listings_getListingsItem first. FBA stock is untouched — remove it with a removal order.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_deleteListingsItem"},"tags":["amazon_sp"],"x-title":"Listings Delete Listings Item","x-access":"destructive","x-family":"sp.listingsItems_2021-08-01","x-returns":[{"field":"data.status","description":"ACCEPTED (queued), or INVALID with data.issues [{code, message, severity}]."},{"field":"data.submissionId","description":"this submission."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"sku":{"title":"Sku","type":"string","description":"Merchant SKU (msku) to delete."},"issue_locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issue Locale","description":"locale of Amazon's issue messages (e.g. 'en_US'); defaults to the marketplace's primary language."},"seller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Id","description":"Vendor Central accounts ONLY — pass your vendor code (e.g. 'ABCDE' from vendorOrders_getPurchaseOrders → orderDetails.sellingParty.partyId). Vendors may hold multiple codes across marketplaces/warehouses; pick the one for the marketplace you need. Do not pass this for Seller Central — the merchant token is used automatically."}},"required":["store","sku"],"title":"listings_deleteListingsItemArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"ACCEPTED (queued), or INVALID with data.issues [{code, message, severity}]."},"submissionId":{"description":"this submission."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_getListingsRestrictions":{"post":{"operationId":"listings_getListingsRestrictions","summary":"Check whether you are approved to sell an ASIN in a given condition.","description":"Check whether you are approved to sell an ASIN in a given condition. Amazon SP-API · getListingsRestrictions · GET /listings/2021-08-01/restrictions Account types: Seller Central only (Amazon rejects this endpoint for Vendor Central accounts with Unauthorized.) Returns list of restrictions with reasons and approval links. Use before attempting to create a listing for a new ASIN to verify eligibility. An empty data.restrictions means you may list the ASIN in that condition; otherwise follow reasons[].links[].resource to apply — no link means no self-service path.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_getListingsRestrictions"},"tags":["amazon_sp"],"x-title":"Listings Get Listings Restrictions","x-access":"read","x-family":"sp.listingsRestrictions_2021-08-01","x-returns":[{"field":"data.restrictions","description":"list of restriction objects, each with: - marketplaceId - conditionType (the condition the restriction applies to) - reasons[]: each has message, optional reasonCode ('APPROVAL_REQUIRED' | 'ASIN_NOT_FOUND' | 'NOT_ELIGIBLE'), and links[] (path-forward resources: resource URI, verb 'GET', title) — typically the approval/application link."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"condition_type":{"default":"new_new","enum":["new_new","new_open_box","new_oem","refurbished_refurbished","used_like_new","used_very_good","used_good","used_acceptable","collectible_like_new","collectible_very_good","collectible_good","collectible_acceptable","club_club"],"title":"Condition Type","type":"string","description":"the offer condition to check. Default: 'new_new'. Allowed: new_new | new_open_box | new_oem | refurbished_refurbished | used_like_new | used_very_good | used_good | used_acceptable | collectible_like_new | collectible_very_good | collectible_good | collectible_acceptable | club_club."},"reason_locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason Locale","description":"Locale for reason text localization (e.g. 'en_US', 'fr_CA', 'fr_FR'). Defaults to the marketplace's primary language. Falls back to 'en_US' if the requested locale is unavailable."},"product_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Product Type","description":"Amazon product type of the item, e.g. 'SHIRT'. With it Amazon also evaluates GTIN-exemption restrictions for that product type; without it only brand restrictions (this tool takes no brand argument). Get the value from productTypeDefinitions_searchDefinitionsProductTypes or catalogItems_getCatalogItem."}},"required":["store","asin"],"title":"listings_getListingsRestrictionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"restrictions":{"description":"list of restriction objects, each with: - marketplaceId - conditionType (the condition the restriction applies to) - reasons[]: each has message, optional reasonCode ('APPROVAL_REQUIRED' | 'ASIN_NOT_FOUND' | 'NOT_ELIGIBLE'), and links[] (path-forward resources: resource URI, verb 'GET', title) — typically the approval/application link."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_searchListingsItems":{"post":{"operationId":"listings_searchListingsItems","summary":"Search and filter the seller's own listings catalog — the entry point for a suppressed-listing audit (with_issue_severity ['ERROR'] and included_data ['summaries', 'issues'], then ","description":"Search and filter the seller's own listings catalog — the entry point for a suppressed-listing audit (with_issue_severity ['ERROR'] and included_data ['summaries', 'issues'], then listings_patchListingsItem), an active-listing inventory (with_status ['BUYABLE']), an identifier lookup, a variation family (variation_parent_sku) or recent changes (last_updated_after with sort_by lastUpdatedDate). Paginated. Amazon SP-API · searchListingsItems · GET /listings/2021-08-01/items/{sellerId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_searchListingsItems"},"tags":["amazon_sp"],"x-title":"Listings Search Listings Items","x-access":"read","x-family":"sp.listingsItems_2021-08-01","x-returns":[{"field":"data.items","description":"[{sku, …the requested datasets}] — a vendor PO image is summaries[0].mainImage.link with included_data ['summaries', 'procurement']."},{"field":"data.numberOfResults","description":"total matches across all pages; Amazon caps paging at 1,000 SKUs, so a larger count means the filter must be narrowed."},{"field":"data.pagination.nextToken","description":"pass as page_token; absent on the last page."}],"x-notes":{"Gotchas":["identifiers, variation_parent_sku and package_hierarchy_sku are mutually exclusive."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"included_data":{"anyOf":[{"items":{"enum":["summaries","attributes","issues","offers","fulfillmentAvailability","procurement","relationships","productTypes"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Included Data","description":"datasets per item; default ['summaries']. issues carries the suppression reasons; procurement is vendor cost data. Allowed: summaries | attributes | issues | offers | fulfillmentAvailability | procurement | relationships | productTypes."},"identifiers":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Identifiers","description":"up to 20 identifiers; requires identifiers_type."},"identifiers_type":{"anyOf":[{"enum":["ASIN","EAN","FNSKU","GTIN","ISBN","JAN","MINSAN","SKU","UPC"],"type":"string"},{"type":"null"}],"default":null,"title":"Identifiers Type","description":"the type of every value in identifiers; required with identifiers. Allowed: ASIN | EAN | FNSKU | GTIN | ISBN | JAN | MINSAN | SKU | UPC."},"variation_parent_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Variation Parent Sku","description":"every variation child of this parent SKU."},"package_hierarchy_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Package Hierarchy Sku","description":"listings that contain or are contained by this SKU."},"created_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created After","description":"ISO 8601 datetimes, e.g. '2024-01-01T00:00:00Z'."},"created_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created Before","description":"ISO 8601 datetimes, e.g. '2024-01-01T00:00:00Z'."},"last_updated_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Last Updated After","description":"ISO 8601 datetimes, e.g. '2024-01-01T00:00:00Z'."},"last_updated_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Last Updated Before","description":"ISO 8601 datetimes, e.g. '2024-01-01T00:00:00Z'."},"with_issue_severity":{"anyOf":[{"items":{"enum":["WARNING","ERROR"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"With Issue Severity","description":"keep listings with issues of these severities (ERROR = suppressed); INFO is not a filter value. Allowed: WARNING | ERROR."},"with_status":{"anyOf":[{"items":{"enum":["BUYABLE","DISCOVERABLE"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"With Status","description":"keep listings in these statuses. BUYABLE is not valid for vendor listings (400 'Unsupported Status Requested') — use DISCOVERABLE or omit it."},"without_status":{"anyOf":[{"items":{"enum":["BUYABLE","DISCOVERABLE"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Without Status","description":"exclude listings in these statuses. Allowed: BUYABLE | DISCOVERABLE."},"sort_by":{"anyOf":[{"enum":["sku","createdDate","lastUpdatedDate"],"type":"string"},{"type":"null"}],"default":null,"title":"Sort By","description":"the field the page is ordered by. Default: lastUpdatedDate. Allowed: sku | createdDate | lastUpdatedDate."},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"title":"Sort Order","description":"ASC or DESC. Default: DESC."},"page_size":{"anyOf":[{"maximum":20,"type":"integer"},{"type":"null"}],"default":null,"title":"Page Size","description":"results per page, 1–20 (default 10)."},"page_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Page Token","description":"data.pagination.nextToken from the previous page; omit for the first."},"issue_locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issue Locale","description":"locale of Amazon's issue messages (e.g. 'en_US'); defaults to the marketplace's primary language."},"seller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Id","description":"Vendor Central only — the vendor code (sellingParty.partyId from vendorOrders_getPurchaseOrders); omit on a seller account. A vendor account can hold several codes in one marketplace, each a separate catalog: group PO items by sellingParty.partyId and call once per group; a group that returns 0 items falls back to catalogItems_searchCatalogItems."}},"required":["store"],"title":"listings_searchListingsItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"items":{"description":"[{sku, …the requested datasets}] — a vendor PO image is summaries[0].mainImage.link with included_data ['summaries', 'procurement']."},"numberOfResults":{"description":"total matches across all pages; Amazon caps paging at 1,000 SKUs, so a larger count means the filter must be narrowed."},"pagination":{"properties":{"nextToken":{"description":"pass as page_token; absent on the last page."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productTypeDefinitions_searchDefinitionsProductTypes":{"post":{"operationId":"productTypeDefinitions_searchDefinitionsProductTypes","summary":"Search for Amazon product types that have definitions available.","description":"Search for Amazon product types that have definitions available. Amazon SP-API · searchDefinitionsProductTypes · GET /definitions/2020-09-01/productTypes Use this to find the correct productType string before calling listings_putListingsItem. Cannot use both keywords and item_name in the same call.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productTypeDefinitions_searchDefinitionsProductTypes"},"tags":["amazon_sp"],"x-title":"Product Type Definitions Search Definitions Product Types","x-access":"read","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.productTypes","description":"list of product type objects, each with: - name: the productType string to use in listings_putListingsItem - displayName: human-readable name - marketplaceIds: supported marketplaces"}],"x-notes":{"Workflow":["1. Search by keywords or by item_name (never both).","2. Pick the most specific data.productTypes[].name.","3. productTypeDefinitions_getDefinitionsProductType for its schema, or","   listings_prepare_publish_queue_template to build sheet columns."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"keywords":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Keywords","description":"List of keywords to search, e.g. ['luggage', 'suitcase']. Cannot combine with item_name."},"item_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Item Name","description":"Product title for recommendation. Cannot combine with keywords."},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"locale of the display names; defaults to the marketplace's primary locale."},"search_locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Search Locale","description":"language of keywords or item_name; defaults to the marketplace's primary locale."}},"required":["store"],"title":"productTypeDefinitions_searchDefinitionsProductTypesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"productTypes":{"description":"list of product type objects, each with: - name: the productType string to use in listings_putListingsItem - displayName: human-readable name - marketplaceIds: supported marketplaces"}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productTypeDefinitions_getDefinitionsProductType":{"post":{"operationId":"productTypeDefinitions_getDefinitionsProductType","summary":"Retrieve an Amazon product type's definition — its attribute groups, requirements and a link to its JSON Schema.","description":"Retrieve an Amazon product type's definition — its attribute groups, requirements and a link to its JSON Schema. Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} Use this to understand required and optional attributes before calling listings_putListingsItem. To compose listing rows, listings_prepare_publish_queue_template returns the same schema as sheet columns, required keys and enums.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productTypeDefinitions_getDefinitionsProductType"},"tags":["amazon_sp"],"x-title":"Product Type Definitions Get Definitions Product Type","x-access":"read","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.productType","description":"the product type name."},{"field":"data.definition.propertyGroups","description":"the attribute groups."},{"field":"data.definition.schema.link.resource","description":"the JSON Schema's download link."},{"field":"data.definition.schema.content","description":"(include_schema=true) the JSON Schema itself."},{"field":"data.definition.requirements / data.definition.productTypeVersion","description":"what was served."}],"x-notes":{"Workflow":["1. productTypeDefinitions_searchDefinitionsProductTypes for the productType.","2. Call with requirements LISTING (and parentage_level for a variation family).","3. Read data.definition.propertyGroups; pass include_schema=true only when you","   need the JSON Schema itself."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"product_type":{"title":"Product Type","type":"string","description":"Amazon product type string (e.g. 'LUGGAGE'). Get from productTypeDefinitions_searchDefinitionsProductTypes."},"include_schema":{"default":false,"title":"Include Schema","type":"boolean","description":"true downloads the full JSON Schema into data.definition.schema.content (large); leave it false unless you need the schema itself."},"requirements":{"anyOf":[{"enum":["LISTING","LISTING_PRODUCT_ONLY","LISTING_OFFER_ONLY"],"type":"string"},{"type":"null"}],"default":null,"title":"Requirements","description":"Which requirements set to retrieve. Default: LISTING (all attributes). Allowed: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY."},"requirements_enforced":{"anyOf":[{"enum":["ENFORCED","NOT_ENFORCED"],"type":"string"},{"type":"null"}],"default":null,"title":"Requirements Enforced","description":"ENFORCED (strict validation, the default) or NOT_ENFORCED (partial updates)."},"product_type_version":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Product Type Version","description":"Version to retrieve. Default: LATEST. Use RELEASE_CANDIDATE for preview versions."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"Locale for display labels in the response. Defaults to the default language of the first marketplace in the request. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"parentage_level":{"anyOf":[{"enum":["NONE","CHILD","PARENT"],"type":"string"},{"type":"null"}],"default":null,"title":"Parentage Level","description":"Parentage level of the listing the schema is for. Amazon then resolves all conditional logic for that level and returns a smaller schema with fewer conditions — pass it when building a variation family. Allowed: NONE | CHILD | PARENT."}},"required":["store","product_type"],"title":"productTypeDefinitions_getDefinitionsProductTypeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"productType":{"description":"the product type name."},"definition":{"properties":{"propertyGroups":{"description":"the attribute groups."},"schema":{"properties":{"link":{"properties":{"resource":{"description":"the JSON Schema's download link."}}},"content":{"description":"(include_schema=true) the JSON Schema itself."}}},"requirements":{"description":"what was served."},"productTypeVersion":{"description":"what was served."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_validate_rows":{"post":{"operationId":"listings_validate_rows","summary":"Validate rows of the LEGACY Create Listing sheet (combined headers, config in rows 1–2) with Amazon's VALIDATION_PREVIEW.","description":"Validate rows of the LEGACY Create Listing sheet (combined headers, config in rows 1–2) with Amazon's VALIDATION_PREVIEW. Publish Queue rows are validated with listings_submit_items (its default mode is VALIDATION_PREVIEW) — this tool rejects them as SplitLayoutRow. Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} Amazon SP-API · putListingsItem · PUT /listings/2021-08-01/items/{sellerId}/{sku} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Accepts flat rows in {header: value} format — same as the sheet rows. The server encodes attributes using the config dict (from rows 1-2).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_validate_rows"},"tags":["amazon_sp"],"x-title":"Listings Validate Rows","x-access":"write","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.results","description":"one entry per input row — {sku, status, issues, row_index}, plus malformed=true when the row was rejected before reaching Amazon (missing sku or productType) and partial_update=true for partial rows. Malformed rows are reported, never dropped."},{"field":"data.valid / data.invalid / data.malformed","description":"counts."},{"field":"data.notes","description":"warnings about the batch as a whole (e.g. partial rows)."},{"field":"data.submissionLog","description":"the Submission Log cells for this call — Action, Result (\"✓/⚠/✕ n of m valid\"), SKUs, Issues (\"SKU · message\"), Raw Response — append them with write_sheet when the user keeps that tab."}],"x-notes":{"Params (Amazon schema; getDefinitionsProductType)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"],"Params (Amazon schema; putListingsItem)":["sellerId*: string","sku*: string","marketplaceIds*: [string] (max 1)","includedData: identifiers | issues (list)","mode: VALIDATION_PREVIEW","issueLocale: string"],"Body (Amazon schema; putListingsItem)":["productType*: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","attributes*: object"],"Gotchas":["VALIDATE FULL PAYLOADS: VALIDATION_PREVIEW has no partial mode, so a","    PARTIAL_UPDATE / PATCH / PATCH-delete row reports every required attribute","    it omits as missing — expected, not a defect (data.notes says so).","notification.type is 'error' when every row was malformed (nothing reached","    Amazon), 'warning' when some rows have issues, else 'success'."],"Workflow":["1. read_sheet the Create Listing tab — row 0 = headers, rows 1+ = data.","2. Call this tool with the rows + config from A1:G2.","3. Fix INVALID rows in the sheet, re-read, re-validate.","4. When all are ACCEPTED, submit with listings_submit_feed_legacy."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"rows":{"items":{},"title":"Rows","type":"array","description":"2D array [[headers], [row1], ...] or list of {header: value} dicts. Each row needs: sku, operationType, productType."},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Config","description":"Dict from sheet rows 1-2 with keys: barcode_type, unit_of_length, unit_of_weight, unit_of_capacity, unit_of_unit_count, language_local. Omitted, the tool sends asin / centimeters / kilograms / liters / count / en_US — pass the sheet's own rows 1–2 on any non-US store; marketplace_id comes from the store."}},"required":["store","rows"],"title":"listings_validate_rowsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"results":{"description":"one entry per input row — {sku, status, issues, row_index}, plus malformed=true when the row was rejected before reaching Amazon (missing sku or productType) and partial_update=true for partial rows. Malformed rows are reported, never dropped."},"valid":{"description":"counts."},"invalid":{"description":"counts."},"malformed":{"description":"counts."},"notes":{"description":"warnings about the batch as a whole (e.g. partial rows)."},"submissionLog":{"description":"the Submission Log cells for this call — Action, Result (\"✓/⚠/✕ n of m valid\"), SKUs, Issues (\"SKU · message\"), Raw Response — append them with write_sheet when the user keeps that tab."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_submit_feed_legacy":{"post":{"operationId":"listings_submit_feed_legacy","summary":"Legacy Create Listing flow: submit flat Create Listing rows via JSON_LISTINGS_FEED or the Listings Items API — new work uses listings_submit_feed (Publish Queue keys).","description":"Legacy Create Listing flow: submit flat Create Listing rows via JSON_LISTINGS_FEED or the Listings Items API — new work uses listings_submit_feed (Publish Queue keys). Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} Amazon SP-API · putListingsItem · PUT /listings/2021-08-01/items/{sellerId}/{sku} Amazon SP-API · patchListingsItem · PATCH /listings/2021-08-01/items/{sellerId}/{sku} Amazon SP-API · deleteListingsItem · DELETE /listings/2021-08-01/items/{sellerId}/{sku} Amazon SP-API · createFeedDocument · POST /feeds/2021-06-30/documents Amazon SP-API · createFeed · POST /feeds/2021-06-30/feeds Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask. Accepts flat {header: value} rows — same format as the Create Listing sheet. The server encodes attributes. PATCH-delete rows always use Listings Items API.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_submit_feed_legacy"},"tags":["amazon_sp"],"x-title":"Listings Submit Feed Legacy","x-access":"destructive","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.feedId","description":"(feed mode) poll with listings_poll_feed_results."},{"field":"data.submitted / data.failed","description":"(1by1 mode) counts."},{"field":"data.submissionLog","description":"the Submission Log cells for this feed (Action, Result, SKUs in message order, Issues, Feed ID, Raw Response) — append them with write_sheet when the user keeps that tab."},{"field":"data.feedDocumentId","description":"(feed mode) feed document ID."},{"field":"data.rowCount","description":"(feed mode) rows actually written into the feed — LOWER than the rows you sent when some were excluded."},{"field":"data.results","description":"(1by1 mode) per-SKU status list."},{"field":"data.encode_errors","description":"{sku: {field: reason}} for rows that did NOT reach Amazon. A row in the split layout ('attr#n.sub' headers) is refused whole — it is not in the feed and not in rowCount, so fix it and resubmit (listings_build_payload + listings_submit_items for split rows). Other entries are per-attribute encode failures on rows that DID go."},{"field":"data.patch_results","description":"[{sku, status, issues}] for PATCH-delete rows, which always go via Listings Items PATCH rather than the feed."}],"x-notes":{"Params (Amazon schema; getDefinitionsProductType)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"],"Params (Amazon schema; putListingsItem)":["sellerId*: string","sku*: string","marketplaceIds*: [string] (max 1)","includedData: identifiers | issues (list)","mode: VALIDATION_PREVIEW","issueLocale: string"],"Params (Amazon schema; patchListingsItem)":["sellerId*: string","sku*: string","… (9 more lines; the Docs link above)"],"Body (Amazon schema; putListingsItem)":["productType*: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","attributes*: object"],"Body (Amazon schema; patchListingsItem)":["productType*: string","patches*: [{op*: add | replace | merge | delete, path*, value: [object]}] (min 1)"],"Body (Amazon schema; createFeedDocument)":["contentType*: string"],"Body (Amazon schema; createFeed)":["feedType*: string","marketplaceIds*: [string] (1–25)","inputFeedDocumentId*: string","feedOptions: object"],"Workflow":["1. read_sheet the Create Listing tab — config in rows 1–2, then the header row","   and data rows.","2. listings_validate_rows — fix all INVALID rows first.","3. Call this tool with the validated rows.","4. listings_poll_feed_results with data.feedId (and the row's SKUs) for per-SKU","   results."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"rows":{"items":{},"title":"Rows","type":"array","description":"2D array [[headers], [row1], ...] or list of {header: value} dicts."},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Config","description":"Dict from sheet rows 1-2 (keys as in listings_validate_rows); omitted → asin / centimeters / kilograms / liters / count / en_US, so pass it on any non-US store. marketplace_id comes from the store."},"mode":{"default":"feed","title":"Mode","type":"string","description":"'feed' (bulk JSON_LISTINGS_FEED, default) or '1by1' (Listings Items API per row)."},"debug":{"default":false,"title":"Debug","type":"boolean","description":"true returns the built feed as data.feed_json (with data.encode_errors, data.patch_results) without submitting (feed mode only)."}},"required":["store","rows"],"title":"listings_submit_feed_legacyArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"feedId":{"description":"(feed mode) poll with listings_poll_feed_results."},"submitted":{"description":"(1by1 mode) counts."},"failed":{"description":"(1by1 mode) counts."},"submissionLog":{"description":"the Submission Log cells for this feed (Action, Result, SKUs in message order, Issues, Feed ID, Raw Response) — append them with write_sheet when the user keeps that tab."},"feedDocumentId":{"description":"(feed mode) feed document ID."},"rowCount":{"description":"(feed mode) rows actually written into the feed — LOWER than the rows you sent when some were excluded."},"results":{"description":"(1by1 mode) per-SKU status list."},"encode_errors":{"description":"{sku: {field: reason}} for rows that did NOT reach Amazon. A row in the split layout ('attr#n.sub' headers) is refused whole — it is not in the feed and not in rowCount, so fix it and resubmit (listings_build_payload + listings_submit_items for split rows). Other entries are per-attribute encode failures on rows that DID go."},"patch_results":{"description":"[{sku, status, issues}] for PATCH-delete rows, which always go via Listings Items PATCH rather than the feed."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_poll_feed_results":{"post":{"operationId":"listings_poll_feed_results","summary":"Check the feeds behind the Submission Log's unfinished Submit Feed rows and get back the cells to write: Feed Status, Result, Issues, Raw Response.","description":"Check the feeds behind the Submission Log's unfinished Submit Feed rows and get back the cells to write: Feed Status, Result, Issues, Raw Response. Amazon SP-API · getFeed · GET /feeds/2021-06-30/feeds/{feedId} Amazon SP-API · getFeedDocument · GET /feeds/2021-06-30/documents/{feedDocumentId} The server touches no sheet. Read the Submission Log with read_sheet, take the rows whose Feed ID is set and whose Feed Status is not DONE / CANCELLED / FATAL, call this with their feed ids (and each row's SKUs cell, so a report's messageId maps to a SKU), then write the four cells back into each row with write_sheet. Feed Status takes Amazon's own value only; Result reads \"✓/⚠/✕ n of m accepted\", \"⏳ Processing\" or \"✕ Feed not found …\"; Issues is one \"SKU · message\" per line. The sidebar's Submission Log ▸ Refresh Status writes the same cells. Call this after listings_submit_feed (or listings_submit_feed_legacy) until no row is still ⏳ Processing.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_poll_feed_results"},"tags":["amazon_sp"],"x-title":"Listings Poll Feed Results","x-access":"write","x-family":"sp.feeds_2021-06-30","x-returns":[{"field":"data.results","description":"[{feedId, feedStatus, result, issues, rawResponse, terminal}] — the cells for that row; terminal=true means stop polling this feed."},{"field":"data.failed","description":"[{feedId, reason}] for feeds whose getFeed call errored (e.g. the feed belongs to another store, or Amazon 403s)."}],"x-notes":{"Params (Amazon schema; getFeed)":["feedId*: string"],"Params (Amazon schema; getFeedDocument)":["feedDocumentId*: string","enableContentEncodingUrlHeader: boolean"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"feed_ids":{"items":{},"title":"Feed Ids","type":"array","description":"Amazon feed ids to check (digits), e.g. ['474419020721']."},"skus":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Skus","description":"{feed_id: the row's SKUs cell} — one SKU per line in feed message order. Optional; without it an issue is attributed to \"Message n\"."}},"required":["store","feed_ids"],"title":"listings_poll_feed_resultsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"results":{"description":"[{feedId, feedStatus, result, issues, rawResponse, terminal}] — the cells for that row; terminal=true means stop polling this feed."},"failed":{"description":"[{feedId, reason}] for feeds whose getFeed call errored (e.g. the feed belongs to another store, or Amazon 403s)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_build_payload":{"post":{"operationId":"listings_build_payload","summary":"Build Amazon-shaped attribute JSON from a Publish Queue row's flat cells, per SKU, driven by the productType schema.","description":"Build Amazon-shaped attribute JSON from a Publish Queue row's flat cells, per SKU, driven by the productType schema. Pre-flight only — nothing is submitted; show data.warnings to the user, then listings_submit_items. Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_build_payload"},"tags":["amazon_sp"],"x-title":"Listings Build Payload","x-access":"read","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.rows","description":"[{sku, attributes, warnings, productType, requirements}] — requirements is the set carried into the PUT: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY."},{"description":"data.total_attrs, data.warnings_count: show the warnings before submitting."}],"x-notes":{"Params (Amazon schema)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"],"Gotchas":["Nothing is filled in for you: what you write is what is sent — a blank unit ships with","no unit and Amazon's issues[] names what is missing; the placeholder tokens are the only","thing resolved. Hidden fields (list_price[…]#1.currency,","child_parent_sku_relationship#1.child_relationship_type = \"variation\" on parent and","child) are ordinary keys. A filled key that does not parse, or names a field this","productType's schema lacks (a pre-v6 pseudo key such as …#1.b2b_quantity_discount),","comes back in that row's warnings as retired_column_layout, and listings_submit_items /","listings_submit_feed skip the row — re-run listings_prepare_publish_queue_template.","Dates are UTC on this path: an instant \"2026-09-19T10:00:00Z\" or \"YYYY-MM-DD\" (a sale","start = 00:00:00Z, a sale end = 23:59:59Z); never a slash date. A sheet's sale cells","are the seller's local time — convert before calling.","product_site_launch_date comes back from the fetch tools and is sent like any key; once","a product has sold, the date shoppers see cannot change — on an existing listing remove","the key or leave the fetched value."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"productType":{"title":"Producttype","type":"string","description":"the one productType whose schema shapes every row (a row's own productType is ignored — call once per productType), e.g. \"HEADPHONES\"."},"rows":{"items":{},"title":"Rows","type":"array","description":"[{sku, attributes: {key: cell_value}}]. A key is Amazon's own flat-file key, copied verbatim from a listings_prepare_publish_queue_template column — never built by hand: `<attr>[<sel>=<v>]…#<n>.<field>…`, where #n is a 1-based entry, .field an object field, and the bracket selectors are only marketplace_id / language_tag (written as the placeholder tokens marketplace_id / language_tag, filled from store and language_tag) and audience (ALL | B2B). Every other selector (currency, type, size_system, fulfillment_channel_code …) is an ordinary key with its value in the cell. `#*` is the one-cell form of a multi-value attribute (bullet_point, warranty_description): one value per line. Values: text as a string, numbers as \"1.5\" or 1.5, booleans as true/false/yes/no. Examples: \"item_name[marketplace_id=marketplace_id][language_tag=language_tag]#1.value\": \"Earbuds\" \"item_weight[marketplace_id=marketplace_id]#1.value\": \"1.5\", \"…#1.unit\": \"kilograms\" \"externally_assigned_product_identifier[marketplace_id=marketplace_id]#1.value\": \"123456789012\", \"…#1.type\": \"upc\" \"purchasable_offer[marketplace_id=marketplace_id][audience=ALL]#1.our_price#1.schedule#1.value_with_tax\": \"19.99\""},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"schema locale for localized labels (a getDefinitionsProductType locale, e.g. en_US); defaults to the marketplace's. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"fills the language_tag token; defaults to the marketplace's primary listing locale (US en_US, UK en_GB, DE de_DE, AE/SA en_AE) — pass one only to list in another language the marketplace supports."}},"required":["store","productType","rows"],"title":"listings_build_payloadArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"rows":{"description":"[{sku, attributes, warnings, productType, requirements}] — requirements is the set carried into the PUT: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_parse_payload":{"post":{"operationId":"listings_parse_payload","summary":"Turn Amazon attribute JSON you already hold (from listings_getListingsItem or catalogItems_getCatalogItem) into Publish Queue cells keyed by Amazon's flat-file keys — the inverse o","description":"Turn Amazon attribute JSON you already hold (from listings_getListingsItem or catalogItems_getCatalogItem) into Publish Queue cells keyed by Amazon's flat-file keys — the inverse of listings_build_payload. To fetch and flatten in one call use listings_fetch_attributes_by_skus or listings_fetch_attributes_by_asins. Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} Arrays become `#n` entries, object fields `.field`, the bracket selectors (marketplace_id, language_tag, audience) move into the key's brackets, and a one-field attribute with several entries folds into one `#*` cell.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_parse_payload"},"tags":["amazon_sp"],"x-title":"Listings Parse Payload","x-access":"read","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.attributes","description":"{key: cell_string} — the flat-file key grammar. A key this productType's CURRENT schema does not carry (Amazon keeps changing schemas) is just more keys here — nothing is skipped or hidden."},{"field":"data.names","description":"{key: display_name} — a NEW key's display name (for seeding row 6 when you write a key the sheet doesn't have yet)."},{"field":"data.dropped_entries","description":"{attr: sentence} — one plain-English sentence per attribute naming how many entries were skipped for a foreign marketplace or language, e.g. \"2 entries in another language (es_US) ignored — one marketplace and one language per sheet\"."},{"field":"data.notes","description":"[] normally; one sentence when the product-type schema could not be served and the cells were typed from the JSON alone (notification.type is then \"warning\"). Submit and validate still need the schema."}],"x-notes":{"Workflow":["1. catalogItems_getCatalogItem (or listings_getListingsItem) → amazon_attributes","2. listings_parse_payload → flat values","3. write_sheet → populate a review sheet for humans"],"Params (Amazon schema)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"productType":{"title":"Producttype","type":"string","description":"Amazon productType whose schema drives the inverse shaping, e.g. \"HEADPHONES\". Use productTypeDefinitions_searchDefinitionsProductTypes if unsure."},"amazon_attributes":{"additionalProperties":true,"title":"Amazon Attributes","type":"object","description":"Amazon-shaped attribute dict exactly as returned by listings_getListingsItem / catalogItems_getCatalogItem — {attr_name: [ {value:…, marketplace_id:…, …}, … ], …}."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"Schema locale for localized enumNames passed to getDefinitionsProductType. Defaults to the marketplace's default locale. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"the one language kept (e.g. en_AE, fr_FR); defaults to the marketplace's primary listing locale. An entry in another language is dropped (see data.dropped_entries) — one language per sheet."}},"required":["store","productType","amazon_attributes"],"title":"listings_parse_payloadArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"attributes":{"description":"{key: cell_string} — the flat-file key grammar. A key this productType's CURRENT schema does not carry (Amazon keeps changing schemas) is just more keys here — nothing is skipped or hidden."},"names":{"description":"{key: display_name} — a NEW key's display name (for seeding row 6 when you write a key the sheet doesn't have yet)."},"dropped_entries":{"description":"{attr: sentence} — one plain-English sentence per attribute naming how many entries were skipped for a foreign marketplace or language, e.g. \"2 entries in another language (es_US) ignored — one marketplace and one language per sheet\"."},"notes":{"description":"[] normally; one sentence when the product-type schema could not be served and the cells were typed from the JSON alone (notification.type is then \"warning\"). Submit and validate still need the schema."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_get_attribute_guide":{"post":{"operationId":"listings_get_attribute_guide","summary":"The row-4 guide (format, unit, allowed values, example) for each Publish Queue column of a productType — one per flat-file key, so item_weight has one for #1.value and one for #1.u","description":"The row-4 guide (format, unit, allowed values, example) for each Publish Queue column of a productType — one per flat-file key, so item_weight has one for #1.value and one for #1.unit. Use it to answer \"what goes in column X?\"; listings_prepare_publish_queue_template already carries the same guide per column (detail 'full'). Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_get_attribute_guide"},"tags":["amazon_sp"],"x-title":"Listings Get Attribute Guide","x-access":"read","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.guides","description":"{key: markdown_string} — keyed by the flat-file column key, e.g. `item_weight[marketplace_id=marketplace_id]#1.unit`."}],"x-notes":{"Params (Amazon schema)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"productType":{"title":"Producttype","type":"string","description":"Amazon productType, e.g. \"HEADPHONES\"."},"attributeNames":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Attributenames","description":"optional subset of ATTRIBUTE names (not column keys) — every column belonging to a listed attribute is included. None = all attributes for the productType."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"schema locale for the labels; defaults to the marketplace's. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"fills the language_tag token; defaults to the marketplace's primary listing locale."}},"required":["store","productType"],"title":"listings_get_attribute_guideArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"guides":{"description":"{key: markdown_string} — keyed by the flat-file column key, e.g. `item_weight[marketplace_id=marketplace_id]#1.unit`."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_submit_items":{"post":{"operationId":"listings_submit_items","summary":"Build Amazon-shaped payloads from Publish Queue cells AND submit them per SKU through the listings-items API in one call — the same input shape as listings_build_payload, then one ","description":"Build Amazon-shaped payloads from Publish Queue cells AND submit them per SKU through the listings-items API in one call — the same input shape as listings_build_payload, then one put, patch or delete per row by its operationType. Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} Amazon SP-API · getListingsItem · GET /listings/2021-08-01/items/{sellerId}/{sku} Amazon SP-API · putListingsItem · PUT /listings/2021-08-01/items/{sellerId}/{sku} Amazon SP-API · patchListingsItem · PATCH /listings/2021-08-01/items/{sellerId}/{sku} Amazon SP-API · deleteListingsItem · DELETE /listings/2021-08-01/items/{sellerId}/{sku} Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_submit_items"},"tags":["amazon_sp"],"x-title":"Listings Submit Items","x-access":"destructive","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.results","description":"[{sku, status, submissionId, issues: [{code, message, severity ERROR | WARNING | INFO}], warnings, reason, error}] — status is Amazon's ACCEPTED | VALID | INVALID, or SellerSheet's own SKIP (a pre-check; reason names it) and ERROR (the call failed; error says why)."},{"description":"data.submitted, data.accepted, data.failed: counts."},{"field":"data.op_counts","description":"{operationType: rows}."}],"x-notes":{"Params (Amazon schema; getDefinitionsProductType)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"],"Params (Amazon schema; getListingsItem)":["sellerId*: string","sku*: string","marketplaceIds*: [string]","issueLocale: string","includedData: summaries | attributes | issues | offers | fulfillmentAvailability | procurement | relationships | productTypes (list)"],"Params (Amazon schema; putListingsItem)":["sellerId*: string","sku*: string","… (16 more lines; the Docs link above)"],"Body (Amazon schema; putListingsItem)":["productType*: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","attributes*: object"],"Body (Amazon schema; patchListingsItem)":["productType*: string","patches*: [{op*: add | replace | merge | delete, path*, value: [object]}] (min 1)"],"Gotchas":["A row whose cells carry a BLOCKING key — one that does not parse or names a field","the row's productType schema lacks (retired_column_layout), disagrees with the","store's marketplace or the sheet's language (marketplace_mismatch,","language_mismatch), or fills the same attribute in both its #* cell and a #1 cell","(column_collision) — comes back SKIP; every other row in the call still submits.","A cell holding exactly __DELETE__ on a PATCH row deletes that attribute (JSON Patch","delete); on an UPDATE row it is ignored with a warning."],"Workflow":["1. Call with VALIDATION_PREVIEW and show the issues.","2. After the user approves and fixes, call with VALIDATION_AND_SUBMISSION.","3. Write the batch outcome to the Last Result pill (row 3, under the row-2 \"Last","   Result\" label) and each failing SKU's issues to the Submission Log."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"productType":{"title":"Producttype","type":"string","description":"the default for rows that carry no productType of their own — rows of several productTypes may go in one call, e.g. \"HEADPHONES\"."},"rows":{"items":{},"title":"Rows","type":"array","description":"[{sku, operationType, productType?, attributes: {key: cell_value}}] in the flat-file key grammar of listings_build_payload. operationType: UPDATE (full replace; PUT and CREATE are legacy aliases) | PATCH (JSON Patch on /attributes/*; PARTIAL_UPDATE is the feeds-spec alias) | PATCH-DELETE (deletes the attributes whose cells are filled; identifier attributes are never deleted) | DELETE."},"mode":{"default":"VALIDATION_PREVIEW","enum":["VALIDATION_PREVIEW","VALIDATION_AND_SUBMISSION"],"title":"Mode","type":"string","description":"'VALIDATION_PREVIEW' (default; a dry run that checks the SHAPE against the schema — Amazon may still refuse a value at submission, so always read issues) | 'VALIDATION_AND_SUBMISSION' (a real put, patch or delete). A DELETE row is not sent in a preview and comes back SKIP with the reason; only VALIDATION_AND_SUBMISSION deletes the SKU. Live submission needs SP write access; a preview works at SP read."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"schema locale for localized labels; defaults to the marketplace's. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"issueLocale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issuelocale","description":"the locale of the returned issue messages (default 'en_US')."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"fills the language_tag token; defaults to the marketplace's primary listing locale."}},"required":["store","productType","rows"],"title":"listings_submit_itemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"results":{"description":"[{sku, status, submissionId, issues: [{code, message, severity ERROR | WARNING | INFO}], warnings, reason, error}] — status is Amazon's ACCEPTED | VALID | INVALID, or SellerSheet's own SKIP (a pre-check; reason names it) and ERROR (the call failed; error says why)."},"op_counts":{"description":"{operationType: rows}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_submit_feed":{"post":{"operationId":"listings_submit_feed","summary":"Bulk publish through Amazon's Feeds API (JSON_LISTINGS_FEED) — the sidebar's \"Submit Listing\" parity, for 10+ SKUs up to ~25,000 per call; for interactive edits of ≤20 SKUs with pe","description":"Bulk publish through Amazon's Feeds API (JSON_LISTINGS_FEED) — the sidebar's \"Submit Listing\" parity, for 10+ SKUs up to ~25,000 per call; for interactive edits of ≤20 SKUs with per-SKU feedback in the same call use listings_submit_items. Same row shape as listings_submit_items: flat cell values keyed by Amazon's flat-file key grammar. Returns a feedId at once; per-SKU issues come later in the feed result — track it with listings_poll_feed_results (feed_ids [data.feedId]) every ~30 s until terminal (DONE, FATAL or CANCELLED); it reads the feed and its report for you. Requires SP write access. Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} Amazon SP-API · createFeedDocument · POST /feeds/2021-06-30/documents Amazon SP-API · createFeed · POST /feeds/2021-06-30/feeds Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_submit_feed"},"tags":["amazon_sp"],"x-title":"Listings Submit Feed","x-access":"destructive","x-family":"sp.definitionsProductTypes_2020-09-01","x-returns":[{"field":"data.feedId","description":"track it with listings_poll_feed_results. data.feedDocumentId: the uploaded document."},{"field":"data.encoded_rows","description":"how many rows made the feed. data.op_counts: {operationType as"},{"field":"data.encoded_rows.sent","description":"rows}."},{"field":"data.skipped","description":"[{sku, reason}] — missing_required_columns, invalid_operationType, unknown_product_type / schema_unavailable, no_valid_attributes_after_build, or a BLOCKING key (retired_column_layout, marketplace_mismatch, language_mismatch, column_collision, as listings_submit_items describes). When every row is skipped no feed is created and data carries no feedId."},{"field":"data.submissionLog","description":"the Submission Log row {action, result, skus, issues, feedId, rawResponse} — skus in feed message order, issues one line per skipped row."}],"x-notes":{"Params (Amazon schema; getDefinitionsProductType)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"],"Body (Amazon schema; createFeedDocument)":["contentType*: string"],"Body (Amazon schema; createFeed)":["feedType*: string","marketplaceIds*: [string] (1–25)","inputFeedDocumentId*: string","feedOptions: object"],"Gotchas":["A PARTIAL_UPDATE message carries productType + attributes only (no requirements, no","patches); a PATCH-DELETE row becomes a PATCH message whose op:delete patches remove","the filled attributes, never the identifier. A __DELETE__ cell is not honoured in a","feed (warning) — delete one attribute through listings_submit_items.","Messages keep the rows' order, minus data.skipped; pass data.submissionLog.skus as","listings_poll_feed_results' skus {feedId: one SKU per line}, or its issues read","\"Message n\". Verify a sample row's encoding with listings_build_payload before a","large feed."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"rows":{"items":{},"title":"Rows","type":"array","description":"[{sku, operationType, productType, attributes}] — operationType UPDATE, PUT or CREATE → feed UPDATE (full replace); PATCH or PARTIAL_UPDATE → feed PARTIAL_UPDATE (the listed attributes only); PATCH-DELETE → feed PATCH (op:delete of the filled attributes); DELETE → feed DELETE."},"productType":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Producttype","description":"the default productType when a row omits it."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"schema locale for localized labels; defaults to the marketplace's. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"issueLocale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Issuelocale","description":"the feed's issue locale (default 'en_US')."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"fills the language_tag token; defaults to the marketplace's primary listing locale."},"debug":{"default":false,"title":"Debug","type":"boolean","description":"true returns the built feed as data.feed_json instead of submitting — the only dry run (feeds have no preview mode)."}},"required":["store","rows"],"title":"listings_submit_feedArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"feedId":{"description":"track it with listings_poll_feed_results. data.feedDocumentId: the uploaded document."},"encoded_rows":{"description":"how many rows made the feed. data.op_counts: {operationType as","properties":{"sent":{"description":"rows}."}}},"skipped":{"description":"[{sku, reason}] — missing_required_columns, invalid_operationType, unknown_product_type / schema_unavailable, no_valid_attributes_after_build, or a BLOCKING key (retired_column_layout, marketplace_mismatch, language_mismatch, column_collision, as listings_submit_items describes). When every row is skipped no feed is created and data carries no feedId."},"submissionLog":{"description":"the Submission Log row {action, result, skus, issues, feedId, rawResponse} — skus in feed message order, issues one line per skipped row."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_parse_asin_to_cells":{"post":{"operationId":"listings_parse_asin_to_cells","summary":"Convenience: fetch an ASIN's catalog attributes from Amazon and return flat, operator-readable cell values.","description":"Convenience: fetch an ASIN's catalog attributes from Amazon and return flat, operator-readable cell values. Keys are Amazon's flat-file keys, as listings_prepare_publish_queue_template writes them. For several ASINs use listings_fetch_attributes_by_asins (one call); to edit a listing you own, fetch by SKU (listings_fetch_attributes_by_skus) — an ASIN returns Amazon's merged catalog values, not what you submitted. Amazon SP-API · getCatalogItem · GET /catalog/2022-04-01/items/{asin} Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} If productType is omitted, the catalog response's productTypes entry matching the store marketplace (else the first) is used as the inferred productType.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_parse_asin_to_cells"},"tags":["amazon_sp"],"x-title":"Listings Parse ASIN to Cells","x-access":"read","x-family":"sp.catalogItems_2022-04-01","x-returns":[{"field":"data.attributes","description":"{key: cell_string} — the flat-file key grammar."},{"field":"data.names","description":"{key: display_name} — a NEW key's display name."},{"field":"data.dropped_entries","description":"{attr: sentence} — entries skipped for a foreign marketplace/language, one plain-English sentence per attribute."},{"field":"data.productType","description":"the productType used (provided or inferred)"},{"field":"data.notes","description":"[] normally; one sentence when the product-type schema could not be served and the cells were typed from the JSON alone."}],"x-notes":{"Params (Amazon schema; getCatalogItem)":["asin*: string","marketplaceIds*: [string]","includedData: attributes | classifications | dimensions | identifiers | images | productTypes | relationships | salesRanks | summaries | vendorDetails (list)","locale: string"],"Params (Amazon schema; getDefinitionsProductType)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"productType":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Producttype","description":"Optional explicit Amazon productType. When omitted it is inferred from the catalog response's productTypes."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"Schema/catalog locale passed to getCatalogItem + getDefinitionsProductType. Defaults to the marketplace's default locale. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"the one language kept; defaults to the marketplace's primary listing locale."}},"required":["store","asin"],"title":"listings_parse_asin_to_cellsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"attributes":{"description":"{key: cell_string} — the flat-file key grammar."},"names":{"description":"{key: display_name} — a NEW key's display name."},"dropped_entries":{"description":"{attr: sentence} — entries skipped for a foreign marketplace/language, one plain-English sentence per attribute."},"productType":{"description":"the productType used (provided or inferred)"},"notes":{"description":"[] normally; one sentence when the product-type schema could not be served and the cells were typed from the JSON alone."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_prepare_publish_queue_template":{"post":{"operationId":"listings_prepare_publish_queue_template","summary":"Everything needed to seed a Publish Queue tab for N productTypes in one call: one bundle for a single productType, or ONE merged bundle keyed by the joined names (\"TOWEL,HEADPHONES","description":"Everything needed to seed a Publish Queue tab for N productTypes in one call: one bundle for a single productType, or ONE merged bundle keyed by the joined names (\"TOWEL,HEADPHONES\") whose column layout hosts rows of any productType in the set (propertyGroups, properties and required unioned across the schemas). Amazon SP-API · getCatalogItem · GET /catalog/2022-04-01/items/{asin} Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_prepare_publish_queue_template"},"tags":["amazon_sp"],"x-title":"Listings Prepare Publish Queue Template","x-access":"read","x-family":"sp.catalogItems_2022-04-01","x-returns":[{"field":"data.bundles","description":"{productType: {columns, ordered_groups, group_end_indices, required, requirements, attr_count, reference_values, source_product_types, requested_product_types}}. columns: [{key, name, required, type, enum, enum_names, several, strict, guide, group}] in sheet order — key is Amazon's own flat-file key (`<attr>[<sel>=<v>]…#<n>.<field>…`), name the display name for row 6 (never an identifier), guide the row-4 guide, type string | number | integer | boolean | date | datetime, several = one cell with one value per line (the `#*` column), strict false only for a several-value enum column. required: the keys that are required. reference_values: {key: cell} in the same grammar. ordered_groups and"},{"field":"data.bundles.group_end_indices","description":"the visual group dividers (product_identity, variations,"},{"description":"product_details, images, offer, shipping, safety_and_compliance)."},{"field":"data.errors","description":"{productType: unknown_product_type | schema_unavailable} for a schema that could not be served."}],"x-notes":{"Params (Amazon schema; getCatalogItem)":["asin*: string","marketplaceIds*: [string]","includedData: attributes | classifications | dimensions | identifiers | images | productTypes | relationships | salesRanks | summaries | vendorDetails (list)","locale: string"],"Params (Amazon schema; getDefinitionsProductType)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"],"Workflow":["Seeding a tab: row 5 (hidden) = columns[].key from column F (column E is the","attributes_json control), row 4 = columns[].guide, row 6 = columns[].name sized to","the name, rows 7+ = data (reference_values as seed), a thick right border at column F","+ each group_end_indices index. Read the tab first (read_sheet) and append only the","keys not already in row 5 at max column + 1 — existing columns are never renamed or","moved; always address a column by its row-5 key."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"productTypes":{"items":{},"title":"Producttypes","type":"array","description":"Amazon productTypes, e.g. [\"HEADPHONES\", \"SHOES\"] — one = a single bundle, several = a merged bundle."},"referenceAsins":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Referenceasins","description":"optional {productType: asin}; the bundle then carries reference_values seeded from that ASIN's catalog attributes."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"schema locale (e.g. en_AE); inferred from the store ref if omitted. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"the language the language_tag token stands for (en_AE, fr_FR, …); defaults to the marketplace's primary listing locale."},"required_first":{"default":true,"title":"Required First","type":"boolean","description":"true (default) sorts REQUIRED attributes to the front so they get the lowest column letters."},"detail":{"default":"full","title":"Detail","type":"string","description":"'full' (default) — every column carries guide; 'columns' omits guide, a lighter bundle for an AI that only needs keys, names and types to compose rows."}},"required":["store","productTypes"],"title":"listings_prepare_publish_queue_templateArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"bundles":{"description":"{productType: {columns, ordered_groups, group_end_indices, required, requirements, attr_count, reference_values, source_product_types, requested_product_types}}. columns: [{key, name, required, type, enum, enum_names, several, strict, guide, group}] in sheet order — key is Amazon's own flat-file key (`<attr>[<sel>=<v>]…#<n>.<field>…`), name the display name for row 6 (never an identifier), guide the row-4 guide, type string | number | integer | boolean | date | datetime, several = one cell with one value per line (the `#*` column), strict false only for a several-value enum column. required: the keys that are required. reference_values: {key: cell} in the same grammar. ordered_groups and","properties":{"group_end_indices":{"description":"the visual group dividers (product_identity, variations,"}}},"errors":{"description":"{productType: unknown_product_type | schema_unavailable} for a schema that could not be served."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_fetch_attributes_by_asins":{"post":{"operationId":"listings_fetch_attributes_by_asins","summary":"Bulk fetch + flatten Amazon catalog attributes for N ASINs in ONE call.","description":"Bulk fetch + flatten Amazon catalog attributes for N ASINs in ONE call. Amazon SP-API · getCatalogItem · GET /catalog/2022-04-01/items/{asin} Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} For each item, fetches the catalog item, infers productType (or uses the explicit hint), looks up the schema, and flattens the whole JSON into cells keyed by Amazon's own flat-file keys — the operator can paste them straight into a Publish Queue row. To edit a listing you own, fetch by SKU (listings_fetch_attributes_by_skus) — an ASIN returns Amazon's merged catalog values, which can include other contributors' data; a full UPDATE would submit them as yours.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_fetch_attributes_by_asins"},"tags":["amazon_sp"],"x-title":"Listings Fetch Attributes by ASINs","x-access":"read","x-family":"sp.catalogItems_2022-04-01","x-returns":[{"field":"data.rows","description":"[{asin, productType, attributes: {key: cell},"},{"field":"data.rows.names","description":"{key: display_name},"},{"field":"data.rows.data.rows.names.dropped_entries","description":"{attr: sentence}} | {asin, error}]"},{"description":"`attributes` keys are self-describing (Amazon's flat-file"},{"description":"grammar); `names` gives a NEW key's display name (for a"},{"description":"column the target sheet doesn't have yet); `dropped_entries`"},{"description":"names, per attribute, any entry skipped for a foreign"},{"description":"marketplace/language, in plain English. A row carries `note`"},{"description":"when its product-type schema could not be served and the cells"},{"description":"were typed from the JSON alone."}],"x-notes":{"Params (Amazon schema; getCatalogItem)":["asin*: string","marketplaceIds*: [string]","includedData: attributes | classifications | dimensions | identifiers | images | productTypes | relationships | salesRanks | summaries | vendorDetails (list)","locale: string"],"Params (Amazon schema; getDefinitionsProductType)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"],"Workflow":["1. Read column matching `externally_assigned_product_identifier`","   (or `merchant_suggested_asin`) for the selected rows.","2. Call this tool ONCE with all ASINs.","3. Never rename or move a template column (the template is the source","   of truth). A bare key, `#1.value`, line 1 of `#*.value` and a literal","   marketplace/language bracket equal to row 3 are the same column — the","   template's spelling wins.","4. Any other key that is not yet a column — a leaf the template's","   productType schema doesn't have (the row's productType differs","   from the template's) — is APPENDED AT THE RIGHT END, named from","   `names`, so the seller sees the whole listing. Do not write a","   special row-4 note for it: its place says it was appended. Only","   a REPEAT of a cluster the template already has (entry index >1","   whose `#1` twin is on the sheet) is inserted beside it. EVERY","   column is sent on submit — the sheet is trusted; whoever owns","   the sheet removes a column Amazon no longer takes after reading","   the result.","5. Write each row's cells back under their row-5 keys (attribute columns","   start at F; E is attributes_json) and set column D (productType) from","   the response."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"items":{"items":{},"title":"Items","type":"array","description":"List of {asin: str, productType?: str}. productType is auto-inferred from the catalog if omitted."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"schema locale for the labels; defaults to the marketplace's. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"which language's entries to keep; defaults to the marketplace's primary listing locale."}},"required":["store","items"],"title":"listings_fetch_attributes_by_asinsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"rows":{"description":"[{asin, productType, attributes: {key: cell},","properties":{"names":{"description":"{key: display_name},"},"data":{"properties":{"rows":{"properties":{"names":{"properties":{"dropped_entries":{"description":"{attr: sentence}} | {asin, error}]"}}}}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/listings_fetch_attributes_by_skus":{"post":{"operationId":"listings_fetch_attributes_by_skus","summary":"Bulk fetch + flatten Amazon listings attributes for N OWNED SKUs in ONE call.","description":"Bulk fetch + flatten Amazon listings attributes for N OWNED SKUs in ONE call. Amazon SP-API · getListingsItem · GET /listings/2021-08-01/items/{sellerId}/{sku} Amazon SP-API · getDefinitionsProductType · GET /definitions/2020-09-01/productTypes/{productType} Same shape as `listings_fetch_attributes_by_asins`, but reads your own submitted listing (listings_getListingsItem) instead of Amazon's merged catalog. productType comes from summaries[].productType.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/listings_fetch_attributes_by_skus"},"tags":["amazon_sp"],"x-title":"Listings Fetch Attributes by SKUs","x-access":"read","x-family":"sp.listingsItems_2021-08-01","x-returns":[{"field":"data.rows","description":"[{sku, productType, attributes: {key: cell},"},{"field":"data.rows.names","description":"{key: display_name},"},{"field":"data.rows.data.rows.names.dropped_entries","description":"{attr: sentence}, note?} | {sku, error}]"},{"description":"`note` is present when the row's product-type schema could not"},{"description":"be served and the cells were typed from the JSON alone."}],"x-notes":{"Params (Amazon schema; getListingsItem)":["sellerId*: string","sku*: string","marketplaceIds*: [string]","issueLocale: string","includedData: summaries | attributes | issues | offers | fulfillmentAvailability | procurement | relationships | productTypes (list)"],"Params (Amazon schema; getDefinitionsProductType)":["productType*: string","sellerId: string","marketplaceIds*: [string]","productTypeVersion: string","requirements: LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY","requirementsEnforced: ENFORCED | NOT_ENFORCED","locale: DEFAULT | ar | ar_AE | de | … | zh_TW (38 values)","parentageLevel: NONE | CHILD | PARENT"],"Workflow":["1. Read column B (sku) for the selected rows.","2. Call this tool ONCE with all SKUs.","3. Place the returned keys by the template-is-truth recipe in","   `listings_fetch_attributes_by_asins` (steps 3–4): never rename a","   template column; a key outside the template's productType","   schema goes at the right end, named from `names`.","4. Write each row's flat attributes back + col D productType.","5. `product_site_launch_date` comes back with the rest. Nothing","   drops it for you: before you update this listing, remove the key","   or leave the fetched value — see listings_build_payload's note on","   it."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"skus":{"items":{},"title":"Skus","type":"array","description":"List of SKUs from the configured store."},"locale":{"anyOf":[{"enum":["DEFAULT","ar","ar_AE","de","de_DE","en","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es","es_ES","es_MX","es_US","fr","fr_CA","fr_FR","it","it_IT","ja","ja_JP","nl","nl_NL","pl","pl_PL","pt","pt_BR","pt_PT","sv","sv_SE","tr","tr_TR","zh","zh_CN","zh_TW"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"schema locale for the labels; defaults to the marketplace's. Allowed: DEFAULT | ar | ar_AE | de | de_DE | en | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es | es_ES | es_MX | es_US | fr | fr_CA | fr_FR | it | it_IT | ja | ja_JP | nl | nl_NL | pl | pl_PL | pt | pt_BR | pt_PT | sv | sv_SE | tr | tr_TR | zh | zh_CN | zh_TW."},"language_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Language Tag","description":"which language's entries to keep; defaults to the marketplace's primary listing locale."}},"required":["store","skus"],"title":"listings_fetch_attributes_by_skusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"rows":{"description":"[{sku, productType, attributes: {key: cell},","properties":{"names":{"description":"{key: display_name},"},"data":{"properties":{"rows":{"properties":{"names":{"properties":{"dropped_entries":{"description":"{attr: sentence}, note?} | {sku, error}]"}}}}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/feeds_createFeed":{"post":{"operationId":"feeds_createFeed","summary":"Submit a feed to Amazon (createFeedDocument upload + createFeed); returns feedId at once.","description":"Submit a feed to Amazon (createFeedDocument upload + createFeed); returns feedId at once. The marketplace comes from the store ref. Poll feeds_getFeed until processingStatus is DONE, FATAL or CANCELLED (FATAL/CANCELLED never becomes DONE — stop and report). Amazon SP-API · createFeedDocument · POST /feeds/2021-06-30/documents Amazon SP-API · createFeed · POST /feeds/2021-06-30/feeds Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/feeds_createFeed"},"tags":["amazon_sp"],"x-title":"Feeds Create Feed","x-access":"destructive","x-family":"sp.feeds_2021-06-30","x-returns":[{"field":"data.feedId","description":"poll it with feeds_getFeed."},{"field":"data.feedDocumentId","description":"the uploaded document."},{"field":"data.processingStatus","description":"always 'IN_QUEUE' here — Amazon's createFeed carries only feedId."},{"field":"data.feedType","description":"as submitted."}],"x-notes":{"Body (Amazon schema; createFeedDocument)":["contentType*: string"],"Body (Amazon schema; createFeed)":["feedType*: string","marketplaceIds*: [string] (1–25)","inputFeedDocumentId*: string","feedOptions: object"],"Gotchas":["A seller with a GTIN exemption can get a NEW ASIN spun off even on a PARTIAL_UPDATE:","always send externally_assigned_product_identifier [{type: \"asin\", value: <the ASIN>,","marketplace_id}] to keep the SKU bound to its ASIN (Amazon accepts type \"asin\" although","the schema lists ean|gtin|upc).","For Publish Queue rows use listings_submit_feed (it builds this feed from the sheet's keys)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"feedType":{"title":"Feedtype","type":"string","description":"Amazon's feed type string (100+ values; the exact string, see https://developer-docs.amazon.com/sp-api/docs/feed-type-values). Common: JSON_LISTINGS_FEED (listings — the XML/flat-file product feeds are deprecated), POST_INVENTORY_AVAILABILITY_DATA, POST_PRODUCT_PRICING_DATA, POST_PRODUCT_IMAGE_DATA, POST_ORDER_FULFILLMENT_DATA, POST_ORDER_ACKNOWLEDGEMENT_DATA, UPLOAD_VAT_INVOICE, POST_FBA_INBOUND_CARTON_CONTENTS, POST_EASYSHIP_DOCUMENTS."},"feedData":{"title":"Feeddata","type":"string","description":"the feed body, base64-encoded; decoded it must match feedType and contentType (JSON for JSON_LISTINGS_FEED, XML for POST_* feeds, PDF bytes for UPLOAD_VAT_INVOICE). A JSON_LISTINGS_FEED body is {header, messages}: header = {sellerId (the store's seller id from get_user_context), version \"2.0\", issueLocale, report: {includedData: [\"issues\", …], apiVersion \"2021-08-01\"}} — always include \"issues\" so feeds_getFeed carries per-SKU issues; add \"relationships\" when touching a variation group. Each message = {messageId (unique int), sku, operationType, …} with ONE of four shapes: UPDATE → productType + attributes (the full set; optional requirements LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY) — creates or fully republishes a listing; PARTIAL_UPDATE → productType + attributes (only those sent are merged; no patches); PATCH → productType + patches (JSON-Patch op replace|merge|delete on /attributes/<name>; no attributes); DELETE → sku only. attributes and patches are never interchangeable (a PARTIAL_UPDATE with patches 400s). Attribute values have exactly the shape listings_getListingsItem returns (e.g. item_thickness → [{decimal_value: 3.6, unit: \"millimeters\", marketplace_id}]): read the current ones with listings_getListingsItem(included_data=['attributes', 'productTypes']), model a new ASIN from catalogItems_getCatalogItem, or validate against productTypeDefinitions_getDefinitionsProductType."},"contentType":{"title":"Contenttype","type":"string","description":"MIME type of feedData: 'application/json; charset=UTF-8' (JSON_LISTINGS_FEED), 'text/xml; charset=UTF-8' (XML feeds), 'application/pdf' (UPLOAD_VAT_INVOICE)."},"feedOptions":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Feedoptions","description":"feed-specific metadata; for UPLOAD_VAT_INVOICE {'metadata:orderid': '<amazonOrderId>', 'metadata:invoicenumber': '<invoiceNumber>'}."}},"required":["store","feedType","feedData","contentType"],"title":"feeds_createFeedArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"feedId":{"description":"poll it with feeds_getFeed."},"feedDocumentId":{"description":"the uploaded document."},"processingStatus":{"description":"always 'IN_QUEUE' here — Amazon's createFeed carries only feedId."},"feedType":{"description":"as submitted."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/feeds_getFeed":{"post":{"operationId":"feeds_getFeed","summary":"Get Amazon feed processing status (getFeed).","description":"Get Amazon feed processing status (getFeed). Whenever Amazon has a result document for the feed, it is auto-fetched + decoded (getFeedDocument is folded in — the server resolves resultFeedDocumentId, downloads the presigned URL, gunzips, and decodes to text). Amazon attaches a result document to FATAL feeds too, not only DONE ones. Amazon SP-API · getFeed · GET /feeds/2021-06-30/feeds/{feedId} Amazon SP-API · getFeedDocument · GET /feeds/2021-06-30/documents/{feedDocumentId} Call this repeatedly to poll until processingStatus is terminal. Feeds typically complete within 1–5 minutes. Terminal vs retryable: 'DONE', 'FATAL' and 'CANCELLED' are terminal — polling again can never change them. Only 'IN_QUEUE' / 'IN_PROGRESS' are worth another call.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/feeds_getFeed"},"tags":["amazon_sp"],"x-title":"Feeds Get Feed","x-access":"read","x-family":"sp.feeds_2021-06-30","x-returns":[{"field":"data.feedId","description":"same as input."},{"field":"data.processingStatus","description":"Amazon enum 'IN_QUEUE' | 'IN_PROGRESS' | 'DONE' | 'CANCELLED' | 'FATAL', plus the SellerSheet-synthetic 'NOT_FOUND' (returned as a warning when Amazon has no such feed for this store)."},{"field":"data.resultFeedDocumentId","description":"Amazon's result-document id, whenever Amazon returned one (DONE and FATAL feeds both carry one)."},{"field":"data.document","description":"(whenever Amazon has a result document — DONE or FATAL) Decoded string content of the feed processing report. For a JSON listings feed a JSON report {header, summary {messagesProcessed, messagesAccepted, messagesInvalid, errors, warnings}, issues [{messageId, code, severity, message, attributeName}]} — messageId n is the n-th message sent. For XML feeds an XML summary with counts of messages processed, warnings, and errors. On FATAL it says why Amazon aborted."}],"x-notes":{"Workflow":["1. Read data.processingStatus.","2. DONE: read data.document (the processing report) and report each message's issues.","3. IN_QUEUE or IN_PROGRESS: wait 2–5 minutes, then call again.","4. CANCELLED or FATAL: relay the reason; the feed was not applied.","5. NOT_FOUND: the feedId is invalid or was submitted to a different store."],"Params (Amazon schema; getFeed)":["feedId*: string"],"Params (Amazon schema; getFeedDocument)":["feedDocumentId*: string","enableContentEncodingUrlHeader: boolean"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"feedId":{"title":"Feedid","type":"string","description":"Amazon feed ID returned by feeds_createFeed."}},"required":["store","feedId"],"title":"feeds_getFeedArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"feedId":{"description":"same as input."},"processingStatus":{"description":"Amazon enum 'IN_QUEUE' | 'IN_PROGRESS' | 'DONE' | 'CANCELLED' | 'FATAL', plus the SellerSheet-synthetic 'NOT_FOUND' (returned as a warning when Amazon has no such feed for this store)."},"resultFeedDocumentId":{"description":"Amazon's result-document id, whenever Amazon returned one (DONE and FATAL feeds both carry one)."},"document":{"description":"(whenever Amazon has a result document — DONE or FATAL) Decoded string content of the feed processing report. For a JSON listings feed a JSON report {header, summary {messagesProcessed, messagesAccepted, messagesInvalid, errors, warnings}, issues [{messageId, code, severity, message, attributeName}]} — messageId n is the n-th message sent. For XML feeds an XML summary with counts of messages processed, warnings, and errors. On FATAL it says why Amazon aborted."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/feeds_getFeeds":{"post":{"operationId":"feeds_getFeeds","summary":"List/filter your recent feeds (getFeeds).","description":"List/filter your recent feeds (getFeeds). Read-only. Amazon SP-API · getFeeds · GET /feeds/2021-06-30/feeds Use this to find feedIds you didn't record, or to audit recent submissions and their statuses. Marketplace is derived server-side from the store — you do NOT pass a marketplace. Feeds are retained for 90 days.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/feeds_getFeeds"},"tags":["amazon_sp"],"x-title":"Feeds Get Feeds","x-access":"read","x-family":"sp.feeds_2021-06-30","x-returns":[{"field":"data.feeds","description":"list of {feedId, feedType, marketplaceIds, createdTime, processingStatus, processingStartTime, processingEndTime, resultFeedDocumentId}."},{"field":"data.count","description":"number of feeds in this page."},{"field":"data.nextToken","description":"cursor — if present, call feeds_getFeeds again with ONLY this."}],"x-notes":{"Workflow":["1. First call: pass your filters (feedTypes / processingStatuses / dates).","2. If data.nextToken is set, call again with ONLY nextToken and NOTHING","   else — Amazon REJECTS nextToken combined with any other filter.","3. Repeat until data.nextToken is null."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"feedTypes":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Feedtypes","description":"required unless paginating with nextToken — 1–10 Amazon feed-type strings, e.g. ['JSON_LISTINGS_FEED']. Amazon REJECTS a getFeeds call with neither feedTypes nor nextToken (\"required parameters missing: feedTypes\"). Full list: https://developer-docs.amazon.com/sp-api/docs/feed-type-values"},"processingStatuses":{"anyOf":[{"items":{"enum":["CANCELLED","DONE","FATAL","IN_PROGRESS","IN_QUEUE"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Processingstatuses","description":"optional list of statuses to filter by. Allowed: CANCELLED | DONE | FATAL | IN_PROGRESS | IN_QUEUE."},"pageSize":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Pagesize","description":"max feeds to return, 1–100 (Amazon default 10)."},"createdSince":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Createdsince","description":"ISO-8601 lower bound on feed creation. Default 90 days ago (feeds older than 90 days are purged)."},"createdUntil":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Createduntil","description":"ISO-8601 upper bound. Default now."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"feeds_getFeedsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"feeds":{"description":"list of {feedId, feedType, marketplaceIds, createdTime, processingStatus, processingStartTime, processingEndTime, resultFeedDocumentId}."},"count":{"description":"number of feeds in this page."},"nextToken":{"description":"cursor — if present, call feeds_getFeeds again with ONLY this."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/feeds_cancelFeed":{"post":{"operationId":"feeds_cancelFeed","summary":"Cancel a queued feed (cancelFeed).","description":"Cancel a queued feed (cancelFeed). Amazon write. Amazon SP-API · cancelFeed · DELETE /feeds/2021-06-30/feeds/{feedId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Only feeds with processingStatus == 'IN_QUEUE' can be cancelled — once a feed is IN_PROGRESS/DONE it is too late. A cancelled feed still appears in feeds_getFeed / feeds_getFeeds with processingStatus == 'CANCELLED'. Requires SP write access.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/feeds_cancelFeed"},"tags":["amazon_sp"],"x-title":"Feeds Cancel Feed","x-access":"destructive","x-family":"sp.feeds_2021-06-30","x-returns":[{"field":"data.feedId","description":"same as input."},{"field":"data.cancelled","description":"True on success; False with a 'warning' notification when Amazon has no such feed for this store."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"feedId":{"title":"Feedid","type":"string","description":"Amazon feed ID to cancel (from feeds_createFeed or feeds_getFeeds)."}},"required":["store","feedId"],"title":"feeds_cancelFeedArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"feedId":{"description":"same as input."},"cancelled":{"description":"True on success; False with a 'warning' notification when Amazon has no such feed for this store."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_searchContentDocuments":{"post":{"operationId":"aplusContent_searchContentDocuments","summary":"Fetch one metadata page of A+ Content documents — lightweight, no enrichment.","description":"Fetch one metadata page of A+ Content documents — lightweight, no enrichment. Amazon decides the page size: a whole library can come back in one page. Amazon SP-API · searchContentDocuments · GET /aplus/2020-11-01/contentDocuments Use this first to discover how many A+ documents exist and get their contentReferenceKeys. Does NOT fetch full contentDocument or linked ASINs — returns metadata only. For sheet-ready rows with full content, use ``aplusContent_list_documents_detailed`` instead.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_searchContentDocuments"},"tags":["amazon_sp"],"x-title":"A+ Content Search Content Documents","x-access":"read","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.count","description":"records on this page."},{"field":"data.contentMetadataRecords","description":"list of ContentMetadataRecord dicts. A record has exactly TWO fields — contentReferenceKey, and contentMetadata (which holds everything else): - contentReferenceKey: unique document key (pass to aplusContent_getContentDocument or aplusContent_list_documents_detailed) - contentMetadata.name: A+ content name (e.g. \"MY-SKU-001 - V5\"; maxLength 100) - contentMetadata.status: 'DRAFT' | 'SUBMITTED' | 'APPROVED' | 'REJECTED' (the only SP-API status values; suspended content reverts to 'DRAFT') - contentMetadata.badgeSet: badges — 'BULK'|'GENERATED'|'LAUNCHPAD'|'PREMIUM'|'STANDARD' - contentMetadata.marketplaceId: marketplace ID - contentMetadata.updateTime: ISO-8601 timestamp This operation returns NO linked ASINs — call ``aplusContent_listContentDocumentAsinRelations`` with a contentReferenceKey for those."},{"field":"data.nextPageToken","description":"(only when more pages exist) pass to next call."}],"x-notes":{"Workflow":["1. Call without pageToken, then with data.nextPageToken until it is absent.","2. For sheet rows with the full document use aplusContent_list_documents_detailed;","   for one document aplusContent_getContentDocument."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"pageToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Pagetoken","description":"the previous call's data.nextPageToken; omit for the first page."}},"required":["store"],"title":"aplusContent_searchContentDocumentsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"count":{"description":"records on this page."},"contentMetadataRecords":{"description":"list of ContentMetadataRecord dicts. A record has exactly TWO fields — contentReferenceKey, and contentMetadata (which holds everything else): - contentReferenceKey: unique document key (pass to aplusContent_getContentDocument or aplusContent_list_documents_detailed) - contentMetadata.name: A+ content name (e.g. \"MY-SKU-001 - V5\"; maxLength 100) - contentMetadata.status: 'DRAFT' | 'SUBMITTED' | 'APPROVED' | 'REJECTED' (the only SP-API status values; suspended content reverts to 'DRAFT') - contentMetadata.badgeSet: badges — 'BULK'|'GENERATED'|'LAUNCHPAD'|'PREMIUM'|'STANDARD' - contentMetadata.marketplaceId: marketplace ID - contentMetadata.updateTime: ISO-8601 timestamp This operation returns NO linked ASINs — call ``aplusContent_listContentDocumentAsinRelations`` with a contentReferenceKey for those."},"nextPageToken":{"description":"(only when more pages exist) pass to next call."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_list_documents_detailed":{"post":{"operationId":"aplusContent_list_documents_detailed","summary":"Up to 50 A+ Content documents per call (5 pages × 10 records), each enriched with its full contentDocument JSON and linked ASINs — sheet-ready rows for the \"List A+\" tab.","description":"Up to 50 A+ Content documents per call (5 pages × 10 records), each enriched with its full contentDocument JSON and linked ASINs — sheet-ready rows for the \"List A+\" tab. Each record costs two enrichment calls (aplusContent_getContentDocument and the ASIN relations), ~100 per batch, on purpose. aplusContent_searchContentDocuments first says how many documents exist; then call without pageToken, write data.rows, and repeat with data.nextPageToken until it is absent. Amazon SP-API · searchContentDocuments · GET /aplus/2020-11-01/contentDocuments Amazon SP-API · getContentDocument · GET /aplus/2020-11-01/contentDocuments/{contentReferenceKey} Amazon SP-API · listContentDocumentAsinRelations · GET /aplus/2020-11-01/contentDocuments/{contentReferenceKey}/asins","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_list_documents_detailed"},"tags":["amazon_sp"],"x-title":"List A+ Content Rows","x-access":"read","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.count","description":"rows in this batch."},{"field":"data.unenriched_keys","description":"the page's remaining contentReferenceKeys when Amazon's page was larger than the batch — fetch each with aplusContent_getContentDocument."},{"field":"data.rows","description":"one per document — {name, status DRAFT | SUBMITTED | APPROVED | REJECTED (suspended content reverts to DRAFT), updateTime ('YYYY-MM-DD HH:MM:SS'), badgeSet (comma-separated: BULK, GENERATED, LAUNCHPAD, PREMIUM, STANDARD), marketplaceId, contentReferenceKey, contentDocument (JSON string of the document itself — parse it and pass it to aplusContent_updateContentDocument; \"error: <reason>\" when that fetch failed), contentDocumentAsinRelations (every linked ASIN, newline-separated; \"error: <reason>\" when the enrichment failed)}."},{"field":"data.nextPageToken","description":"only when more batches exist."}],"x-notes":{"Params (Amazon schema; searchContentDocuments)":["marketplaceId*: string","pageToken: string"],"Params (Amazon schema; getContentDocument)":["contentReferenceKey*: string","marketplaceId*: string","includedDataSet*: CONTENTS | METADATA (list)"],"Params (Amazon schema; listContentDocumentAsinRelations)":["contentReferenceKey*: string","marketplaceId*: string","includedDataSet: METADATA (list)","asinSet: [string]","pageToken: string"],"Workflow":["1. Write data.rows from row 5 of the \"List A+\" tab: row 1 = the key headers (name |","   status | updateTime | badgeSet | marketplaceId | contentReferenceKey |","   contentDocument | contentDocumentAsinRelations), row 2 = the \"Store\" label (do","   not overwrite), row 3 = the store value, row 4 = the display headers (A+ Name |","   Status | Update Time | Badge Set | Marketplace ID | Content Reference Key |","   Content Document | ASINs)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"pageToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Pagetoken","description":"the previous call's data.nextPageToken; omit for the first page."},"maxPages":{"default":5,"title":"Maxpages","type":"integer","description":"the batch size in tens, 1–10 (default 5 → at most 50 records enriched); Amazon decides a page's size, so the records beyond maxPages×10 come back as data.unenriched_keys. Lower it for a smaller batch."}},"required":["store"],"title":"aplusContent_list_documents_detailedArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"count":{"description":"rows in this batch."},"unenriched_keys":{"description":"the page's remaining contentReferenceKeys when Amazon's page was larger than the batch — fetch each with aplusContent_getContentDocument."},"rows":{"description":"one per document — {name, status DRAFT | SUBMITTED | APPROVED | REJECTED (suspended content reverts to DRAFT), updateTime ('YYYY-MM-DD HH:MM:SS'), badgeSet (comma-separated: BULK, GENERATED, LAUNCHPAD, PREMIUM, STANDARD), marketplaceId, contentReferenceKey, contentDocument (JSON string of the document itself — parse it and pass it to aplusContent_updateContentDocument; \"error: <reason>\" when that fetch failed), contentDocumentAsinRelations (every linked ASIN, newline-separated; \"error: <reason>\" when the enrichment failed)}."},"nextPageToken":{"description":"only when more batches exist."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_getContentDocument":{"post":{"operationId":"aplusContent_getContentDocument","summary":"Get an A+ Content document.","description":"Get an A+ Content document. ``includedDataSet`` selects which data types Amazon returns (full contents and/or just metadata). Amazon SP-API · getContentDocument · GET /aplus/2020-11-01/contentDocuments/{contentReferenceKey} Use this to inspect an existing document before updating or to audit content.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_getContentDocument"},"tags":["amazon_sp"],"x-title":"A+ Content Get Content Document","x-access":"read","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.contentReferenceKey","description":"same as input."},{"field":"data.contentDocument","description":"the contentDocument itself — the server unwraps Amazon's GET envelope, so this dict can be passed straight back into ``aplusContent_updateContentDocument``. Present when CONTENTS was requested (None for a METADATA-only fetch). Fields: - name: content name (maxLength 100) - contentType: 'EBC' (Seller Central A+ — what seller accounts get) or 'EMC' (Vendor Central A+) - contentSubType: optional special-purpose subtype string (often absent) - locale: IETF language tag, HYPHENATED — pattern ^[a-z]{2,}-[A-Z0-9]{2,}$ (e.g. 'en-US', 'en-GB', 'de-DE', 'zh-CN'). Underscores are rejected. - contentModuleList: 1–100 module dicts, each with: - contentModuleType: module type string (e.g. 'STANDARD_HEADER_IMAGE_TEXT') - [module-specific key]: module data with images and text"},{"field":"data.contentMetadata","description":"(if present, i.e. when METADATA was requested) name/status/badgeSet/marketplaceId/updateTime."},{"field":"data.warnings","description":"(if present) Amazon advisory messages ({code, message, details})."}],"x-notes":{"Gotchas":["A PREMIUM A+ document can fail with 400 \"Unsupported content module type\" — read","its metadata from aplusContent_searchContentDocuments instead."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"contentReferenceKey":{"title":"Contentreferencekey","type":"string","description":"the A+ content document key (from aplusContent_searchContentDocuments)."},"includedDataSet":{"anyOf":[{"items":{"enum":["CONTENTS","METADATA"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Includeddataset","description":"which A+ data types to return, any subset: CONTENTS is the full content document (modules + text + images), METADATA the document's metadata only (name/status/badges/updateTime). Amazon requires this query param; the server sends ['CONTENTS'] when omitted. Pass ['CONTENTS','METADATA'] for both, or ['METADATA'] for a lightweight metadata-only fetch."}},"required":["store","contentReferenceKey"],"title":"aplusContent_getContentDocumentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"contentReferenceKey":{"description":"same as input."},"contentDocument":{"description":"the contentDocument itself — the server unwraps Amazon's GET envelope, so this dict can be passed straight back into ``aplusContent_updateContentDocument``. Present when CONTENTS was requested (None for a METADATA-only fetch). Fields: - name: content name (maxLength 100) - contentType: 'EBC' (Seller Central A+ — what seller accounts get) or 'EMC' (Vendor Central A+) - contentSubType: optional special-purpose subtype string (often absent) - locale: IETF language tag, HYPHENATED — pattern ^[a-z]{2,}-[A-Z0-9]{2,}$ (e.g. 'en-US', 'en-GB', 'de-DE', 'zh-CN'). Underscores are rejected. - contentModuleList: 1–100 module dicts, each with: - contentModuleType: module type string (e.g. 'STANDARD_HEADER_IMAGE_TEXT') - [module-specific key]: module data with images and text"},"contentMetadata":{"description":"(if present, i.e. when METADATA was requested) name/status/badgeSet/marketplaceId/updateTime."},"warnings":{"description":"(if present) Amazon advisory messages ({code, message, details})."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_create_and_publish":{"post":{"operationId":"aplusContent_create_and_publish","summary":"Full A+ pipeline in one call: upload the images → create the content document → link the ASINs → submit for approval.","description":"Full A+ pipeline in one call: upload the images → create the content document → link the ASINs → submit for approval. Every step's result is returned whichever step failed. Amazon SP-API · createUploadDestinationForResource · POST /uploads/2020-11-01/uploadDestinations/{resource} Amazon SP-API · createContentDocument · POST /aplus/2020-11-01/contentDocuments Amazon SP-API · postContentDocumentAsinRelations · POST /aplus/2020-11-01/contentDocuments/{contentReferenceKey}/asins Amazon SP-API · postContentDocumentApprovalSubmission · POST /aplus/2020-11-01/contentDocuments/{contentReferenceKey}/approvalSubmissions Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_create_and_publish"},"tags":["amazon_sp"],"x-title":"Create and Publish A+ Content","x-access":"destructive","x-family":"sp.uploads_2020-11-01","x-returns":[{"field":"data.contentReferenceKey","description":"the created document (null when create failed)."},{"field":"data.steps","description":"{step: record} in run order — upload_images {status, count, uploads: [{driveUrl, uploadDestinationId | error, status} | {status 'reused', url}]} (only when a slot held a URL); create {status, contentReferenceKey | error}; link_asins {status, asinCount | error}; submit {status | error | status 'skipped', reason} (only when submitForApproval)."},{"field":"data.allSucceeded","description":"true only when every attempted step succeeded — otherwise data.steps names the failing one."}],"x-notes":{"Params (Amazon schema; createUploadDestinationForResource)":["marketplaceIds*: [string] (max 1)","contentMD5*: string","resource*: string","contentType: string"],"Params (Amazon schema; createContentDocument)":["marketplaceId*: string"],"Params (Amazon schema; postContentDocumentAsinRelations)":["contentReferenceKey*: string","marketplaceId*: string"],"Params (Amazon schema; postContentDocumentApprovalSubmission)":["contentReferenceKey*: string","marketplaceId*: string"],"Body (Amazon schema; createContentDocument)":["contentDocument*: {name* (max 100 chars), contentType*: EBC | EMC, contentSubType, locale* (min 5 chars),","  contentModuleList*: [{contentModuleType*, standardCompanyLogo, standardComparisonTable,","    standardFourImageText, standardFourImageTextQuadrant, standardHeaderImageText, standardImageSidebar,","    standardImageTextOverlay, standardMultipleImageText, standardProductDescription,","    standardSingleImageHighlights, standardSingleImageSpecsDetail, standardSingleSideImage,","    standardTechSpecs, standardText, standardThreeImageText}] (1–100)}","  contentDocument.contentModuleList.contentModuleType: STANDARD_COMPANY_LOGO | STANDARD_COMPARISON_TABLE |","    STANDARD_FOUR_IMAGE_TEXT | STANDARD_FOUR_IMAGE_TEXT_QUADRANT | STANDARD_HEADER_IMAGE_TEXT |","    STANDARD_IMAGE_SIDEBAR | STANDARD_IMAGE_TEXT_OVERLAY | STANDARD_MULTIPLE_IMAGE_TEXT |","    STANDARD_PRODUCT_DESCRIPTION | STANDARD_SINGLE_IMAGE_HIGHLIGHTS | STANDARD_SINGLE_IMAGE_SPECS_DETAIL |","    STANDARD_SINGLE_SIDE_IMAGE | STANDARD_TECH_SPECS | STANDARD_TEXT | STANDARD_THREE_IMAGE_TEXT","  contentDocument.contentModuleList.standardImageTextOverlay.overlayColorType: DARK | LIGHT","  contentDocument.contentModuleList.standardSingleSideImage.imagePositionType: LEFT | RIGHT"],"Body (Amazon schema; postContentDocumentAsinRelations)":["asinSet*: [string] (min 10 chars)"],"Gotchas":["A failed image upload stops the pipeline before create; a failed create skips linking","and submit; a failed link skips submit. Check aplusContent_searchContentPublishRecords","per ASIN first so you do not create a second document for content that already exists."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"contentDocument":{"additionalProperties":true,"title":"Contentdocument","type":"object","description":"the A+ document — required fields name (≤100 chars), contentType, locale, contentModuleList (1–100 modules). contentType: EBC (Seller Central A+) | EMC (Vendor Central). locale: a HYPHENATED IETF tag ('en-US', 'de-DE', 'zh-CN'). A module is {contentModuleType, <camelCase type name>: {…}}, e.g. {\"contentModuleType\": \"STANDARD_HEADER_IMAGE_TEXT\", \"standardHeaderImageText\": {\"headline\": {\"value\": \"…\"}, \"block\": {\"image\": {\"uploadDestinationId\": \"https://…/hero.jpg\", \"altText\": \"…\"}, \"headline\": {\"value\": \"…\"}, \"body\": {\"textList\": [{\"value\": \"…\"}]}}}} (contentModuleType values: the Body block). Rich text (headline, body) ≤10,000 chars; positional labels (specs, highlights) ≤250; every image needs uploadDestinationId + altText (≤100). Optional enums: decoratorSet[].type STYLE_BOLD | STYLE_ITALIC | STYLE_UNDERLINE | STYLE_LINEBREAK | STYLE_PARAGRAPH | LIST_ORDERED | LIST_UNORDERED | LIST_ITEM (each with offset, length; depth for lists); imagePositionType LEFT | RIGHT (STANDARD_SINGLE_SIDE_IMAGE); overlayColorType DARK | LIGHT (STANDARD_IMAGE_TEXT_OVERLAY). Images: put a URL straight into uploadDestinationId — an Amazon A+ CDN URL (https://m.media-amazon.com/images/S/<id>) is reused as is; any other http(s) URL (cdn.sellersheetai.com, a public Drive link, any host) is downloaded and uploaded to the A+ media library; a raw uploadDestinationId is kept. A missing imageCropSpecification is filled with the full image size."},"asinSet":{"items":{"minLength":10,"type":"string"},"title":"Asinset","type":"array","description":"the ASINs to link, all in the store's marketplace."},"submitForApproval":{"default":true,"title":"Submitforapproval","type":"boolean","description":"true (default) submits after linking; false leaves a DRAFT to review first."}},"required":["store","contentDocument","asinSet"],"title":"aplusContent_create_and_publishArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"contentReferenceKey":{"description":"the created document (null when create failed)."},"steps":{"description":"{step: record} in run order — upload_images {status, count, uploads: [{driveUrl, uploadDestinationId | error, status} | {status 'reused', url}]} (only when a slot held a URL); create {status, contentReferenceKey | error}; link_asins {status, asinCount | error}; submit {status | error | status 'skipped', reason} (only when submitForApproval)."},"allSucceeded":{"description":"true only when every attempted step succeeded — otherwise data.steps names the failing one."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_listContentDocumentAsinRelations":{"post":{"operationId":"aplusContent_listContentDocumentAsinRelations","summary":"List the ASINs currently linked to a specific A+ Content document.","description":"List the ASINs currently linked to a specific A+ Content document. Amazon SP-API · listContentDocumentAsinRelations · GET /aplus/2020-11-01/contentDocuments/{contentReferenceKey}/asins Use this to audit or verify which ASINs will display the content before or after calling ``aplusContent_create_and_publish``. Returns one Amazon page. If ``data.nextPageToken`` is present, call again with ``pageToken`` set to it (and the same other args) to get the next page.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_listContentDocumentAsinRelations"},"tags":["amazon_sp"],"x-title":"A+ Content List Content Document ASIN Relations","x-access":"read","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.contentReferenceKey","description":"same as input."},{"field":"data.asinCount","description":"number of linked ASINs on this page."},{"field":"data.asinMetadataSet","description":"list of ASIN objects (per the A+ AsinMetadata model), each with: - asin: the ASIN string - badgeSet: (if present, when METADATA requested) ASIN-relationship state badges — these are AsinBadge values (NOT the content badges): 'BRAND_NOT_ELIGIBLE' | 'CATALOG_NOT_FOUND' | 'CONTENT_NOT_PUBLISHED' | 'CONTENT_PUBLISHED' - parent: (if present) parent ASIN of a variation family - title: (if present) the ASIN's catalog title - imageUrl: (if present) the ASIN's catalog image URL - contentReferenceKeySet: (if present) keys of content documents linked to this ASIN"},{"field":"data.warnings","description":"(if present) list of Amazon advisory messages ({code, message, details})."},{"field":"data.nextPageToken","description":"(only when more pages exist) pass as pageToken to the next call."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"contentReferenceKey":{"title":"Contentreferencekey","type":"string","description":"the A+ content document key (from aplusContent_searchContentDocuments)."},"includedDataSet":{"anyOf":[{"items":{"const":"METADATA","type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Includeddataset","description":"optional list selecting ASIN metadata to include. Pass ['METADATA'] to enrich each ASIN with parent/title/imageUrl/badgeSet. Omit to return the related ASINs without metadata."},"asinSet":{"anyOf":[{"items":{"minLength":10,"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Asinset","description":"optional list of ASIN strings to filter to (each at least 10 chars). Omit to return ALL ASINs linked to the document."},"pageToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Pagetoken","description":"the previous call's data.nextPageToken; omit for the first page."}},"required":["store","contentReferenceKey"],"title":"aplusContent_listContentDocumentAsinRelationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"contentReferenceKey":{"description":"same as input."},"asinCount":{"description":"number of linked ASINs on this page."},"asinMetadataSet":{"description":"list of ASIN objects (per the A+ AsinMetadata model), each with: - asin: the ASIN string - badgeSet: (if present, when METADATA requested) ASIN-relationship state badges — these are AsinBadge values (NOT the content badges): 'BRAND_NOT_ELIGIBLE' | 'CATALOG_NOT_FOUND' | 'CONTENT_NOT_PUBLISHED' | 'CONTENT_PUBLISHED' - parent: (if present) parent ASIN of a variation family - title: (if present) the ASIN's catalog title - imageUrl: (if present) the ASIN's catalog image URL - contentReferenceKeySet: (if present) keys of content documents linked to this ASIN"},"warnings":{"description":"(if present) list of Amazon advisory messages ({code, message, details})."},"nextPageToken":{"description":"(only when more pages exist) pass as pageToken to the next call."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_validateContentDocumentAsinRelations":{"post":{"operationId":"aplusContent_validateContentDocumentAsinRelations","summary":"Validate ASINs against an A+ content document before linking — no changes made (read-only).","description":"Validate ASINs against an A+ content document before linking — no changes made (read-only). Amazon SP-API · validateContentDocumentAsinRelations · POST /aplus/2020-11-01/contentAsinValidations Non-mutating: requires only read access (a read-only user can validate eligibility before asking someone with write access to link). Call this before ``aplusContent_postContentDocumentAsinRelations`` when you're unsure about ASIN eligibility, or to diagnose why the link_asins step failed inside ``aplusContent_create_and_publish``. Returns Amazon's per-ASIN error objects — an empty list means all ASINs are valid. The SP-API validates against the full ``contentDocument`` you pass; the wire request carries only marketplaceId + asinSet + contentDocument. There is NO contentReferenceKey on this Amazon operation, so none is accepted here — pass the document you intend to create, or the existing document retrieved via ``aplusContent_getContentDocument``.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_validateContentDocumentAsinRelations"},"tags":["amazon_sp"],"x-title":"A+ Content Validate Content Document ASIN Relations","x-access":"read","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.asinCount","description":"number of ASINs validated."},{"field":"data.errors","description":"Amazon's validation findings, each {code, message, details} (this operation reports findings under `errors`, not `issues`). Empty list means all ASINs are eligible for this content document."},{"field":"data.warnings","description":"(if present) Amazon advisory messages, same {code, message, details} shape. Not returned when Amazon reported errors — the SDK surfaces that response as an error list only."}],"x-notes":{"Body (Amazon schema)":["contentDocument*: {name* (max 100 chars), contentType*: EBC | EMC, contentSubType, locale* (min 5 chars),","  contentModuleList*: [{contentModuleType*, standardCompanyLogo, standardComparisonTable,","    standardFourImageText, standardFourImageTextQuadrant, standardHeaderImageText, standardImageSidebar,","    standardImageTextOverlay, standardMultipleImageText, standardProductDescription,","    standardSingleImageHighlights, standardSingleImageSpecsDetail, standardSingleSideImage,","    standardTechSpecs, standardText, standardThreeImageText}] (1–100)}","  contentDocument.contentModuleList.contentModuleType: STANDARD_COMPANY_LOGO | STANDARD_COMPARISON_TABLE |","    STANDARD_FOUR_IMAGE_TEXT | STANDARD_FOUR_IMAGE_TEXT_QUADRANT | STANDARD_HEADER_IMAGE_TEXT |","    STANDARD_IMAGE_SIDEBAR | STANDARD_IMAGE_TEXT_OVERLAY | STANDARD_MULTIPLE_IMAGE_TEXT |","    STANDARD_PRODUCT_DESCRIPTION | STANDARD_SINGLE_IMAGE_HIGHLIGHTS | STANDARD_SINGLE_IMAGE_SPECS_DETAIL |","    STANDARD_SINGLE_SIDE_IMAGE | STANDARD_TECH_SPECS | STANDARD_TEXT | STANDARD_THREE_IMAGE_TEXT","  contentDocument.contentModuleList.standardImageTextOverlay.overlayColorType: DARK | LIGHT","  contentDocument.contentModuleList.standardSingleSideImage.imagePositionType: LEFT | RIGHT"],"Workflow":["1. Call with your intended asinSet and contentDocument.","2. data.errors empty → link with aplusContent_postContentDocumentAsinRelations or","   create with aplusContent_create_and_publish.","3. data.errors not empty → show them to the user; fix eligibility before retrying."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asinSet":{"items":{"minLength":10,"type":"string"},"title":"Asinset","type":"array","description":"List of ASIN strings to validate (e.g. ['B0XXXXXXXX']). Each ASIN is at least 10 chars."},"contentDocument":{"additionalProperties":true,"title":"Contentdocument","type":"object","description":"Full content document dict (same structure as aplusContent_create_and_publish). This is what the SP-API actually validates the ASINs against."}},"required":["store","asinSet","contentDocument"],"title":"aplusContent_validateContentDocumentAsinRelationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"asinCount":{"description":"number of ASINs validated."},"errors":{"description":"Amazon's validation findings, each {code, message, details} (this operation reports findings under `errors`, not `issues`). Empty list means all ASINs are eligible for this content document."},"warnings":{"description":"(if present) Amazon advisory messages, same {code, message, details} shape. Not returned when Amazon reported errors — the SDK surfaces that response as an error list only."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_postContentDocumentAsinRelations":{"post":{"operationId":"aplusContent_postContentDocumentAsinRelations","summary":"Replace all ASINs linked to an existing A+ content document.","description":"Replace all ASINs linked to an existing A+ content document. Amazon SP-API · postContentDocumentAsinRelations · POST /aplus/2020-11-01/contentDocuments/{contentReferenceKey}/asins Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. This is a FULL replacement — the new asinSet becomes the complete set of linked ASINs. Any ASIN omitted from asinSet will have A+ content suspended on its listing. Always include ALL ASINs you want linked, not just the new ones.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_postContentDocumentAsinRelations"},"tags":["amazon_sp"],"x-title":"A+ Content Post Content Document ASIN Relations","x-access":"destructive","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.contentReferenceKey","description":"same as input."},{"field":"data.asinCount","description":"number of ASINs sent."},{"field":"data.warnings","description":"(only when present) Amazon accepted the call but did not apply all of it — the notification is then a warning."}],"x-notes":{"Workflow":["1. aplusContent_listContentDocumentAsinRelations for the current set of linked ASINs.","2. Merge existing ASINs with new ones (or remove specific ones).","3. Optionally aplusContent_validateContentDocumentAsinRelations to check eligibility.","4. Call this tool with the complete new asinSet.","5. If the document is DRAFT, submit it with","   aplusContent_postContentDocumentApprovalSubmission.","6. Write the updated ASIN list to your tracking sheet."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"contentReferenceKey":{"title":"Contentreferencekey","type":"string","description":"the A+ content document key (from aplusContent_searchContentDocuments)."},"asinSet":{"items":{"minLength":10,"type":"string"},"title":"Asinset","type":"array","description":"New complete set of ASIN strings. All previously linked ASINs not in this list will be suspended."}},"required":["store","contentReferenceKey","asinSet"],"title":"aplusContent_postContentDocumentAsinRelationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"contentReferenceKey":{"description":"same as input."},"asinCount":{"description":"number of ASINs sent."},"warnings":{"description":"(only when present) Amazon accepted the call but did not apply all of it — the notification is then a warning."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_postContentDocumentApprovalSubmission":{"post":{"operationId":"aplusContent_postContentDocumentApprovalSubmission","summary":"Submit an A+ document for Amazon review and publication — after aplusContent_create_and_publish ran with submitForApproval false, or to retry its failed submit step.","description":"Submit an A+ document for Amazon review and publication — after aplusContent_create_and_publish ran with submitForApproval false, or to retry its failed submit step. Amazon SP-API · postContentDocumentApprovalSubmission · POST /aplus/2020-11-01/contentDocuments/{contentReferenceKey}/approvalSubmissions Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Link its ASINs first (aplusContent_postContentDocumentAsinRelations). Review typically takes 1–7 business days; once approved the content shows on every linked ASIN.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_postContentDocumentApprovalSubmission"},"tags":["amazon_sp"],"x-title":"A+ Content Post Content Document Approval Submission","x-access":"destructive","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.contentReferenceKey","description":"same as input."},{"field":"data.warnings","description":"(only when present) Amazon's warnings — the notification is then a warning."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"contentReferenceKey":{"title":"Contentreferencekey","type":"string","description":"the A+ content document key (from aplusContent_searchContentDocuments)."}},"required":["store","contentReferenceKey"],"title":"aplusContent_postContentDocumentApprovalSubmissionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"contentReferenceKey":{"description":"same as input."},"warnings":{"description":"(only when present) Amazon's warnings — the notification is then a warning."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_postContentDocumentSuspendSubmission":{"post":{"operationId":"aplusContent_postContentDocumentSuspendSubmission","summary":"Suspend live (APPROVED) A+ content: it leaves every linked ASIN's detail page while the document and its ASIN links stay.","description":"Suspend live (APPROVED) A+ content: it leaves every linked ASIN's detail page while the document and its ASIN links stay. Amazon SP-API · postContentDocumentSuspendSubmission · POST /aplus/2020-11-01/contentDocuments/{contentReferenceKey}/suspendSubmissions Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Use it to hide content during a product refresh or compliance review, or before changing ASIN assignments. The document then reads DRAFT in aplusContent_searchContentDocuments (the SP-API has no separate published or suspended status). To bring it back, fix it if needed (aplusContent_updateContentDocument) and resubmit with aplusContent_postContentDocumentApprovalSubmission.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_postContentDocumentSuspendSubmission"},"tags":["amazon_sp"],"x-title":"A+ Content Post Content Document Suspend Submission","x-access":"destructive","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.contentReferenceKey","description":"same as input."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"contentReferenceKey":{"title":"Contentreferencekey","type":"string","description":"the A+ content document key (from aplusContent_searchContentDocuments)."}},"required":["store","contentReferenceKey"],"title":"aplusContent_postContentDocumentSuspendSubmissionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"contentReferenceKey":{"description":"same as input."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_searchContentPublishRecords":{"post":{"operationId":"aplusContent_searchContentPublishRecords","summary":"Check if an ASIN already has published (live) A+ Content on Amazon.","description":"Check if an ASIN already has published (live) A+ Content on Amazon. Amazon SP-API · searchContentPublishRecords · GET /aplus/2020-11-01/contentPublishRecords Call this BEFORE creating new A+ content for an ASIN to avoid duplicates or conflicts with existing live content. No records means no live A+ on this ASIN — safe to create; otherwise review the existing content first. Returns one Amazon page. If ``data.nextPageToken`` is present, call again with ``pageToken`` set to it (and the same asin) to get the next page.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_searchContentPublishRecords"},"tags":["amazon_sp"],"x-title":"A+ Content Search Content Publish Records","x-access":"read","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.asin","description":"same as input."},{"field":"data.count","description":"number of publish records on this page."},{"field":"data.publishRecordList","description":"list of published content records, each with exactly these fields (per the A+ PublishRecord model — no badgeSet): - contentReferenceKey: the content document behind this published record - asin: the ASIN - contentType: 'EBC' (Seller Central A+) or 'EMC' (Vendor Central A+) - contentSubType: optional subtype string (often absent) - locale: IETF language tag, hyphenated (e.g. 'en-US') - marketplaceId: marketplace the record applies to"},{"field":"data.nextPageToken","description":"(only when more pages exist) pass as pageToken to the next call."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"minLength":10,"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"pageToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Pagetoken","description":"the previous call's data.nextPageToken; omit for the first page."}},"required":["store","asin"],"title":"aplusContent_searchContentPublishRecordsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"asin":{"description":"same as input."},"count":{"description":"number of publish records on this page."},"publishRecordList":{"description":"list of published content records, each with exactly these fields (per the A+ PublishRecord model — no badgeSet): - contentReferenceKey: the content document behind this published record - asin: the ASIN - contentType: 'EBC' (Seller Central A+) or 'EMC' (Vendor Central A+) - contentSubType: optional subtype string (often absent) - locale: IETF language tag, hyphenated (e.g. 'en-US') - marketplaceId: marketplace the record applies to"},"nextPageToken":{"description":"(only when more pages exist) pass as pageToken to the next call."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/aplusContent_updateContentDocument":{"post":{"operationId":"aplusContent_updateContentDocument","summary":"Replace the content of an existing A+ document, keeping its key and ASIN links — to revise copy, module order or images without creating a new document.","description":"Replace the content of an existing A+ document, keeping its key and ASIN links — to revise copy, module order or images without creating a new document. ASIN links change through aplusContent_postContentDocumentAsinRelations. Amazon SP-API · updateContentDocument · POST /aplus/2020-11-01/contentDocuments/{contentReferenceKey} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/aplusContent_updateContentDocument"},"tags":["amazon_sp"],"x-title":"A+ Content Update Content Document","x-access":"destructive","x-family":"sp.aplusContent_2020-11-01","x-returns":[{"field":"data.contentReferenceKey","description":"same as input."},{"field":"data.warnings","description":"(only when present) Amazon's warnings — the notification is then a warning."}],"x-notes":{"Body (Amazon schema)":["contentDocument*: {name* (max 100 chars), contentType*: EBC | EMC, contentSubType, locale* (min 5 chars),","  contentModuleList*: [{contentModuleType*, standardCompanyLogo, standardComparisonTable,","    standardFourImageText, standardFourImageTextQuadrant, standardHeaderImageText, standardImageSidebar,","    standardImageTextOverlay, standardMultipleImageText, standardProductDescription,","    standardSingleImageHighlights, standardSingleImageSpecsDetail, standardSingleSideImage,","    standardTechSpecs, standardText, standardThreeImageText}] (1–100)}","  contentDocument.contentModuleList.contentModuleType: STANDARD_COMPANY_LOGO | STANDARD_COMPARISON_TABLE |","    STANDARD_FOUR_IMAGE_TEXT | STANDARD_FOUR_IMAGE_TEXT_QUADRANT | STANDARD_HEADER_IMAGE_TEXT |","    STANDARD_IMAGE_SIDEBAR | STANDARD_IMAGE_TEXT_OVERLAY | STANDARD_MULTIPLE_IMAGE_TEXT |","    STANDARD_PRODUCT_DESCRIPTION | STANDARD_SINGLE_IMAGE_HIGHLIGHTS | STANDARD_SINGLE_IMAGE_SPECS_DETAIL |","    STANDARD_SINGLE_SIDE_IMAGE | STANDARD_TECH_SPECS | STANDARD_TEXT | STANDARD_THREE_IMAGE_TEXT","  contentDocument.contentModuleList.standardImageTextOverlay.overlayColorType: DARK | LIGHT","  contentDocument.contentModuleList.standardSingleSideImage.imagePositionType: LEFT | RIGHT"],"Gotchas":["SUBMITTED or APPROVED content: suspend it first","(aplusContent_postContentDocumentSuspendSubmission), update, then resubmit."],"Workflow":["1. aplusContent_getContentDocument for the current contentDocument.","2. Change it (e.g. a STANDARD_HEADER_IMAGE_TEXT module's headline) and call this","   tool with the whole document.","3. aplusContent_postContentDocumentApprovalSubmission to publish the new version."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"contentReferenceKey":{"title":"Contentreferencekey","type":"string","description":"the A+ content document key (from aplusContent_searchContentDocuments)."},"contentDocument":{"additionalProperties":true,"title":"Contentdocument","type":"object","description":"The full new document body — same shape as create. Required: name (maxLength 100), contentType (Allowed: EBC = Seller Central A+, use this for seller accounts | EMC = Vendor Central A+), locale (IETF tag, HYPHENATED — pattern ^[a-z]{2,}-[A-Z0-9]{2,}$, e.g. 'en-US'), contentModuleList (1–100 modules). Optional: contentSubType. See aplusContent_create_and_publish for the module shape and text limits (contentModuleType values: the Body block)."}},"required":["store","contentReferenceKey","contentDocument"],"title":"aplusContent_updateContentDocumentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"contentReferenceKey":{"description":"same as input."},"warnings":{"description":"(only when present) Amazon's warnings — the notification is then a warning."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/catalogItems_searchCatalogItems":{"post":{"operationId":"catalogItems_searchCatalogItems","summary":"Search Amazon's live catalog by keywords or by identifiers — what shoppers see, not one seller's submission.","description":"Search Amazon's live catalog by keywords or by identifiers — what shoppers see, not one seller's submission. For a known list of ASINs this is the bulk fetch: up to 20 identifiers in one call return the same per-item shape as catalogItems_getCatalogItem (the catalog limit is 2 req/s, so looping the single-item tool over 20 ASINs costs ~10 s against ~1 s here). Use catalogItems_getCatalogItem only for one ASIN. Amazon SP-API · searchCatalogItems · GET /catalog/2022-04-01/items","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/catalogItems_searchCatalogItems"},"tags":["amazon_sp"],"x-title":"Catalog Items Search Catalog Items","x-access":"read","x-family":"sp.catalogItems_2022-04-01","x-returns":[{"field":"data.numberOfResults","description":"total matches."},{"field":"data.items","description":"[{asin, summaries, attributes, images, dimensions, identifiers, productTypes, relationships, salesRanks, classifications, vendorDetails}] — a dataset is present only when requested."},{"field":"data.nextToken","description":"pass it back as pageToken; null on the last page."},{"field":"data.refinements","description":"keyword searches only — {brands: [{brandName, numberOfResults}],"},{"field":"data.refinements.classifications","description":"[{classificationId, displayName, numberOfResults}]} to narrow the"},{"description":"same search through brandNames / classificationIds."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"keywords":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Keywords","description":"up to 20 keywords, e.g. ['wireless', 'mouse'] — this OR identifiers."},"identifiers":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Identifiers","description":"up to 20 product identifiers — this OR keywords."},"identifiersType":{"anyOf":[{"enum":["ASIN","EAN","GTIN","ISBN","JAN","MINSAN","SKU","UPC"],"type":"string"},{"type":"null"}],"default":null,"title":"Identifierstype","description":"the type of every value in identifiers; required with identifiers. Allowed: ASIN | EAN | GTIN | ISBN | JAN | MINSAN | SKU | UPC."},"includedData":{"anyOf":[{"items":{"enum":["attributes","classifications","dimensions","identifiers","images","productTypes","relationships","salesRanks","summaries","vendorDetails"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Includeddata","description":"datasets per item; default ['summaries']. Not here: customerReviews (the customerFeedback tools) and offers (productPricing_getItemOffersBatch). Allowed: attributes | classifications | dimensions | identifiers | images | productTypes | relationships | salesRanks | summaries | vendorDetails."},"brandNames":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Brandnames","description":"keyword searches only — brandName values from data.refinements.brands of a previous search (with identifiers Amazon returns 400)."},"classificationIds":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Classificationids","description":"keyword searches only — browse-node ids from data.refinements.classifications, or a classificationId read from catalogItems_getCatalogItem (includedData=['classifications'])."},"pageSize":{"default":10,"maximum":20,"title":"Pagesize","type":"integer","description":"items per page, 1–20 (default 10)."},"pageToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Pagetoken","description":"the cursor from the previous call's data.nextToken; omit for the first page."},"sellerId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sellerid","description":"required by Amazon when identifiersType is SKU — defaulted to the store's seller id on a seller account; a vendor passes its vendor code (orderDetails.sellingParty.partyId from vendorOrders_getPurchaseOrders)."},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"locale for localized content (e.g. 'en_US', 'fr_CA')."},"keywordsLocale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Keywordslocale","description":"keyword searches only — the keywords' locale; defaults to the marketplace's."}},"required":["store"],"title":"catalogItems_searchCatalogItemsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"numberOfResults":{"description":"total matches."},"items":{"description":"[{asin, summaries, attributes, images, dimensions, identifiers, productTypes, relationships, salesRanks, classifications, vendorDetails}] — a dataset is present only when requested."},"nextToken":{"description":"pass it back as pageToken; null on the last page."},"refinements":{"description":"keyword searches only — {brands: [{brandName, numberOfResults}],","properties":{"classifications":{"description":"[{classificationId, displayName, numberOfResults}]} to narrow the"}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/catalogItems_getCatalogItem":{"post":{"operationId":"catalogItems_getCatalogItem","summary":"Get Amazon's LIVE catalog data for a single ASIN — the reconciled version that shoppers see on the detail page.","description":"Get Amazon's LIVE catalog data for a single ASIN — the reconciled version that shoppers see on the detail page. Amazon SP-API · getCatalogItem · GET /catalog/2022-04-01/items/{asin} This returns what Amazon ACTUALLY DISPLAYS, not what the seller submitted. Amazon merges data from all sellers and its own sources, then picks the winning value for each attribute (title, images, bullets, brand, etc.). To check whether Amazon kept a seller's submission, compare data.item.attributes with listings_getListingsItem's data.attributes.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/catalogItems_getCatalogItem"},"tags":["amazon_sp"],"x-title":"Catalog Items Get Catalog Item","x-access":"read","x-family":"sp.catalogItems_2022-04-01","x-returns":[{"field":"data.asin","description":"the requested ASIN."},{"field":"data.item","description":"catalog item object with: - asin: Amazon Standard Identification Number - summaries: basic info (title, brand, manufacturer, etc) if includedData includes 'summaries' - attributes: detailed attributes (color, size, material, etc) if includedData includes 'attributes' - images: product images with URLs if includedData includes 'images' - dimensions: package dimensions (weight, height, width, length) if includedData includes 'dimensions' - identifiers: all product identifiers (EAN, UPC, ISBN, etc) if includedData includes 'identifiers' - productTypes: product type info if includedData includes 'productTypes' - relationships: parent/child relationships (variations) if includedData includes 'relationships' - salesRanks: sales rank by category if includedData includes 'salesRanks' - classifications: the browse-node hierarchy per marketplace if includedData includes 'classifications' — [{marketplaceId, classifications: [{displayName, classificationId, parent: {displayName, classificationId, parent: …}}]}]. Amazon retired the v0 categories operation on 2026-03-31; this is the category hierarchy (a classificationId is a browse node id). - vendorDetails: vendor-only data if includedData includes 'vendorDetails' (vendors only)"}],"x-notes":{"Workflow":["1. Use catalogItems_searchCatalogItems to find ASINs of interest.","2. For up to 20 ASINs at once use catalogItems_searchCatalogItems with identifiers +","   identifiersType ASIN (same per-item shape); call this tool for a single ASIN."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"includedData":{"anyOf":[{"items":{"enum":["attributes","classifications","dimensions","identifiers","images","productTypes","relationships","salesRanks","summaries","vendorDetails"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Includeddata","description":"List of additional data to include in response. Default: ['summaries'] (basic info only). NOT supported here: 'customerReviews' (use customerFeedback_getItemReviewTopics), 'offers' (use Product Pricing API → productPricing_getItemOffersBatch). Recommended: ['attributes', 'images', 'dimensions', 'salesRanks'] for full details. Allowed: attributes | classifications | dimensions | identifiers | images | productTypes | relationships | salesRanks | summaries | vendorDetails."},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"Locale for localized content (e.g. 'en_US', 'fr_CA')."}},"required":["store","asin"],"title":"catalogItems_getCatalogItemArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"asin":{"description":"the requested ASIN."},"item":{"description":"catalog item object with: - asin: Amazon Standard Identification Number - summaries: basic info (title, brand, manufacturer, etc) if includedData includes 'summaries' - attributes: detailed attributes (color, size, material, etc) if includedData includes 'attributes' - images: product images with URLs if includedData includes 'images' - dimensions: package dimensions (weight, height, width, length) if includedData includes 'dimensions' - identifiers: all product identifiers (EAN, UPC, ISBN, etc) if includedData includes 'identifiers' - productTypes: product type info if includedData includes 'productTypes' - relationships: parent/child relationships (variations) if includedData includes 'relationships' - salesRanks: sales rank by category if includedData includes 'salesRanks' - classifications: the browse-node hierarchy per marketplace if includedData includes 'classifications' — [{marketplaceId, classifications: [{displayName, classificationId, parent: {displayName, classificationId, parent: …}}]}]. Amazon retired the v0 categories operation on 2026-03-31; this is the category hierarchy (a classificationId is a browse node id). - vendorDetails: vendor-only data if includedData includes 'vendorDetails' (vendors only)"}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productFees_getMyFeesEstimateForASIN":{"post":{"operationId":"productFees_getMyFeesEstimateForASIN","summary":"Estimate Amazon fees (referral fee + FBA/MFN fees) for a single ASIN at a given price.","description":"Estimate Amazon fees (referral fee + FBA/MFN fees) for a single ASIN at a given price. Amazon SP-API · getMyFeesEstimateForASIN · POST /products/fees/v0/items/{Asin}/feesEstimate Uses Product Fees v0 API. Note: ASIN-based estimates use catalog size, which may differ from actual item dimensions. For accurate FBA estimates after sending inventory, use productFees_getMyFeesEstimateForSKU instead. Net margin = price − data.totalFeesEstimate.Amount − COGS; never compute it when data.error is set.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productFees_getMyFeesEstimateForASIN"},"tags":["amazon_sp"],"x-title":"Product Fees Get My Fees Estimate for ASIN","x-access":"read","x-family":"sp.productFeesV0","x-returns":[{"field":"data.asin","description":"the queried ASIN."},{"field":"data.price","description":"the price used for estimation."},{"field":"data.isFba","description":"whether FBA or MFN fees were estimated."},{"field":"data.status","description":"'Success' or error status from Amazon."},{"field":"data.totalFeesEstimate","description":"{Amount, CurrencyCode} — total estimated fees."},{"field":"data.error","description":"null on success; on failure Amazon's {Type, Code, Message} saying WHY there is no estimate, and the Message is in notification.message too. A refused estimate is not zero fees — never write a blank or 0 fee to your sheet when data.error is set, because any margin computed from it is wrong."},{"field":"data.feeDetail","description":"list of per-fee breakdown objects, each with: - FeeType: e.g. 'ReferralFee', 'FBAFees', 'VariableClosingFee' - FeeAmount: {Amount, CurrencyCode} - FinalFee: {Amount, CurrencyCode}"}],"x-notes":{"Body (Amazon schema)":["FeesEstimateRequest: {MarketplaceId*, IsAmazonFulfilled, PriceToEstimateFees*: {ListingPrice*, Shipping, Points}, Identifier*, OptionalFulfillmentProgram: FBA_CORE | FBA_SNL | FBA_EFN}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"price":{"title":"Price","type":"number","description":"Listing price to estimate fees for (e.g. 29.99)."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Currency","description":"ISO 4217 currency code for `price`. Omit to use the store marketplace's own currency (AE→AED, GB→GBP, JP→JPY, US→USD, …) — only pass this to override."},"shippingPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Shippingprice","description":"Shipping price included in the estimate (MFN only). Default None."},"isFba":{"default":false,"title":"Isfba","type":"boolean","description":"True for FBA fee estimate, False for MFN (merchant fulfilled). Default False."},"points":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Points","description":"Amazon Points offered with the purchase — Japan only. Shape {PointsNumber: int, PointsMonetaryValue: {Amount: float, CurrencyCode: str}}. Points reduce the price basis the referral fee is computed on."},"optionalFulfillmentProgram":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Optionalfulfillmentprogram","description":"FBA program override, only used when isFba=True; FBA_CORE is the default and FBA_SNL (Small and Light) is sunset — do not pass it."}},"required":["store","asin","price"],"title":"productFees_getMyFeesEstimateForASINArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"asin":{"description":"the queried ASIN."},"price":{"description":"the price used for estimation."},"isFba":{"description":"whether FBA or MFN fees were estimated."},"status":{"description":"'Success' or error status from Amazon."},"totalFeesEstimate":{"description":"{Amount, CurrencyCode} — total estimated fees."},"error":{"description":"null on success; on failure Amazon's {Type, Code, Message} saying WHY there is no estimate, and the Message is in notification.message too. A refused estimate is not zero fees — never write a blank or 0 fee to your sheet when data.error is set, because any margin computed from it is wrong."},"feeDetail":{"description":"list of per-fee breakdown objects, each with: - FeeType: e.g. 'ReferralFee', 'FBAFees', 'VariableClosingFee' - FeeAmount: {Amount, CurrencyCode} - FinalFee: {Amount, CurrencyCode}"}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productFees_getMyFeesEstimateForSKU":{"post":{"operationId":"productFees_getMyFeesEstimateForSKU","summary":"Estimate Amazon fees (referral fee + FBA/MFN fees) for a seller SKU at a given price.","description":"Estimate Amazon fees (referral fee + FBA/MFN fees) for a seller SKU at a given price. Amazon SP-API · getMyFeesEstimateForSKU · POST /products/fees/v0/listings/{SellerSKU}/feesEstimate Uses Product Fees v0 API. SKU-based estimates use actual item measurements after the item has been sent to Amazon — more accurate than ASIN-based estimates for FBA sellers. Pass isFba=True for FBA items. Net margin = price − data.totalFeesEstimate.Amount − COGS; never compute it when data.error is set.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productFees_getMyFeesEstimateForSKU"},"tags":["amazon_sp"],"x-title":"Product Fees Get My Fees Estimate for SKU","x-access":"read","x-family":"sp.productFeesV0","x-returns":[{"field":"data.sellerSku","description":"the queried SKU."},{"field":"data.price","description":"the price used for estimation."},{"field":"data.isFba","description":"whether FBA or MFN fees were estimated."},{"field":"data.status","description":"'Success' or error status from Amazon."},{"field":"data.totalFeesEstimate","description":"{Amount, CurrencyCode} — total estimated fees."},{"field":"data.error","description":"null on success; on failure Amazon's {Type, Code, Message} saying WHY there is no estimate, and the Message is in notification.message too. A refused estimate is not zero fees — never write a blank or 0 fee to your sheet when data.error is set, because any margin computed from it is wrong."},{"field":"data.feeDetail","description":"list of per-fee breakdown objects, each with: - FeeType: e.g. 'ReferralFee', 'FBAFees', 'VariableClosingFee' - FeeAmount: {Amount, CurrencyCode} - FinalFee: {Amount, CurrencyCode}"}],"x-notes":{"Body (Amazon schema)":["FeesEstimateRequest: {MarketplaceId*, IsAmazonFulfilled, PriceToEstimateFees*: {ListingPrice*, Shipping, Points}, Identifier*, OptionalFulfillmentProgram: FBA_CORE | FBA_SNL | FBA_EFN}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"sellerSku":{"title":"Sellersku","type":"string","description":"Seller's SKU for the item (URL encoding handled automatically)."},"price":{"title":"Price","type":"number","description":"Listing price to estimate fees for (e.g. 29.99)."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Currency","description":"ISO 4217 currency code for `price`. Omit to use the store marketplace's own currency (AE→AED, GB→GBP, JP→JPY, US→USD, …) — only pass this to override."},"shippingPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Shippingprice","description":"Shipping price included in the estimate (MFN only). Default None."},"isFba":{"default":false,"title":"Isfba","type":"boolean","description":"True for FBA fee estimate, False for MFN (merchant fulfilled). Default False."},"points":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Points","description":"Amazon Points offered with the purchase — Japan only. Shape {PointsNumber: int, PointsMonetaryValue: {Amount: float, CurrencyCode: str}}. Points reduce the price basis the referral fee is computed on."},"optionalFulfillmentProgram":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Optionalfulfillmentprogram","description":"FBA program override, only used when isFba=True; FBA_CORE is the default and FBA_SNL (Small and Light) is sunset — do not pass it."}},"required":["store","sellerSku","price"],"title":"productFees_getMyFeesEstimateForSKUArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"sellerSku":{"description":"the queried SKU."},"price":{"description":"the price used for estimation."},"isFba":{"description":"whether FBA or MFN fees were estimated."},"status":{"description":"'Success' or error status from Amazon."},"totalFeesEstimate":{"description":"{Amount, CurrencyCode} — total estimated fees."},"error":{"description":"null on success; on failure Amazon's {Type, Code, Message} saying WHY there is no estimate, and the Message is in notification.message too. A refused estimate is not zero fees — never write a blank or 0 fee to your sheet when data.error is set, because any margin computed from it is wrong."},"feeDetail":{"description":"list of per-fee breakdown objects, each with: - FeeType: e.g. 'ReferralFee', 'FBAFees', 'VariableClosingFee' - FeeAmount: {Amount, CurrencyCode} - FinalFee: {Amount, CurrencyCode}"}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productPricing_getCompetitiveSummary":{"post":{"operationId":"productPricing_getCompetitiveSummary","summary":"Competitive summary for 1–20 ASINs (Product Pricing v2022-05-01): featured buying options (who wins the featured offer, at what price), lowest-priced offers, reference prices and s","description":"Competitive summary for 1–20 ASINs (Product Pricing v2022-05-01): featured buying options (who wins the featured offer, at what price), lowest-priced offers, reference prices and similar items, per includedData. The server fills the batch uri, method and marketplaceId — pass only asin and includedData per request. Prefer it over productPricing_getItemOffersBatch when you need who holds the featured offer per segment or reference prices (WasPrice, CompetitivePriceThreshold); getItemOffersBatch returns the v0 offer list with Buy Box prices. Amazon SP-API · getCompetitiveSummary · POST /batches/products/pricing/2022-05-01/items/competitiveSummary","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productPricing_getCompetitiveSummary"},"tags":["amazon_sp"],"x-title":"Product Pricing Get Competitive Summary","x-access":"read","x-family":"sp.productPricing_2022-05-01","x-returns":[{"field":"data.ok","description":"the ASINs Amazon accepted (statusCode 200, no errors)."},{"field":"data.failed","description":"[{identifier, status, reason}] for every ASIN that failed at the transport level — statusCode not 200, a body.errors list, or no response envelope (status 'NoResponse'); notification.type is 'warning' whenever it is non-empty."},{"field":"data.responses","description":"per ASIN, in request order — {status: {statusCode, reasonPhrase},"},{"field":"data.responses.body","description":"{asin, marketplaceId (which request this answers — competitiveSummary does"},{"description":"not echo a request object), featuredBuyingOptions: [{buyingOptionType 'New',"},{"description":"segmentedFeaturedOffers}], lowestPricedOffers, referencePrices: [{name, price}]"},{"description":"(CompetitivePriceThreshold, WasPrice …), similarItems, errors}}."}],"x-notes":{"Body (Amazon schema): {requests: [CompetitiveSummaryRequest]} (1–20), each item":["asin*: string","marketplaceId*: string","includedData*: [featuredBuyingOptions | referencePrices | lowestPricedOffers | similarItems] (min 1)","lowestPricedOffersInputs: [{itemCondition*, offerType*: Consumer}] (max 5)","lowestPricedOffersInputs.itemCondition: New | Used | Collectible | Refurbished | Club","method*: GET | PUT | PATCH | DELETE | POST","uri*: string (6–512 chars)"],"Gotchas":["This endpoint cannot confirm an ASIN exists: an unknown ASIN returns 200 with","featuredBuyingOptions [] — byte-identical to a valid ASIN with no featured offer — so","an empty list proves nothing and data.ok is not proof of validity. When identifier","validity matters, productPricing_getPricing's data.failed says."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"requests_":{"items":{},"title":"Requests","type":"array","description":"1–20 of {asin (required), includedData (required, non-empty; Allowed: featuredBuyingOptions | referencePrices | lowestPricedOffers | similarItems), marketplaceId (optional; defaults to the store's), lowestPricedOffersInputs (optional, max 5, with lowestPricedOffers only: [{itemCondition New | Used | Collectible | Refurbished | Club, offerType 'Consumer'}])}, e.g. [{\"asin\": \"B0XXXXXXXX\", \"includedData\": [\"featuredBuyingOptions\"]}]."}},"required":["store","requests_"],"title":"productPricing_getCompetitiveSummaryArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"ok":{"description":"the ASINs Amazon accepted (statusCode 200, no errors)."},"failed":{"description":"[{identifier, status, reason}] for every ASIN that failed at the transport level — statusCode not 200, a body.errors list, or no response envelope (status 'NoResponse'); notification.type is 'warning' whenever it is non-empty."},"responses":{"description":"per ASIN, in request order — {status: {statusCode, reasonPhrase},","properties":{"body":{"description":"{asin, marketplaceId (which request this answers — competitiveSummary does"}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productPricing_getFeaturedOfferExpectedPriceBatch":{"post":{"operationId":"productPricing_getFeaturedOfferExpectedPriceBatch","summary":"Featured offer expected price (FOEP) for 1–20 seller SKUs (Product Pricing v2022-05-01) — the price at or below which each SKU is expected to win the featured offer, an input for r","description":"Featured offer expected price (FOEP) for 1–20 seller SKUs (Product Pricing v2022-05-01) — the price at or below which each SKU is expected to win the featured offer, an input for repricing (listings_patchListingsItem), not a guarantee. The server fills the batch uri, method and marketplaceId — pass only sku (and an optional segment) per request. Amazon SP-API · getFeaturedOfferExpectedPriceBatch · POST /batches/products/pricing/2022-05-01/offer/featuredOfferExpectedPrice","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productPricing_getFeaturedOfferExpectedPriceBatch"},"tags":["amazon_sp"],"x-title":"Product Pricing Get Featured Offer Expected Price Batch","x-access":"read","x-family":"sp.productPricing_2022-05-01","x-returns":[{"field":"data.ok","description":"the SKUs Amazon accepted (statusCode 200, no errors)."},{"field":"data.failed","description":"[{identifier, status, reason}] for transport failures — statusCode not 200 (a bogus SKU lands here: 400 with body.errors code InvalidInput), a body.errors list, or no response envelope (status 'NoResponse'); notification.type is 'warning' whenever it is non-empty."},{"field":"data.result_statuses","description":"[{sku, resultStatus, has_price}], one per featuredOfferExpectedPriceResults entry. featuredOfferExpectedPrice is present ONLY when resultStatus is VALID_FOEP. NO_COMPETING_OFFER is a legitimate success with no price — you hold the featured offer unopposed, and currentFeaturedOffer shows at what price; the other statuses are OFFER_NOT_ELIGIBLE, OFFER_NOT_FOUND and ASIN_NOT_ELIGIBLE. Never read a blank price as \"no repricing needed\" — this list says WHY there is none."},{"field":"data.responses","description":"per SKU — {request: {marketplaceId, sku, segment} (echoed, to map a response to its SKU), status: {statusCode, reasonPhrase}, body: {offerIdentifier: {marketplaceId, sku, asin}, featuredOfferExpectedPriceResults: [{resultStatus,"},{"field":"data.responses.featuredOfferExpectedPrice","description":"{listingPrice: {amount, currencyCode}},"},{"description":"currentFeaturedOffer, competingFeaturedOffer}], errors}}."}],"x-notes":{"Body (Amazon schema): {requests: [FeaturedOfferExpectedPriceRequest]} (min 1), each item":["uri*: string","method*: GET | PUT | PATCH | DELETE | POST","body: object","headers: object","marketplaceId*: string","sku*: string","segment: {segmentDetails: {glanceViewWeightPercentage, sampleLocation}}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"requests_":{"items":{},"title":"Requests","type":"array","description":"1–20 of {sku (required), marketplaceId (optional; defaults to the store's), segment (optional location scope: {segmentDetails: {sampleLocation: {postalCode: {countryCode, value}}}})}, e.g. [{\"sku\": \"MY-SKU-001\"}]."}},"required":["store","requests_"],"title":"productPricing_getFeaturedOfferExpectedPriceBatchArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"ok":{"description":"the SKUs Amazon accepted (statusCode 200, no errors)."},"failed":{"description":"[{identifier, status, reason}] for transport failures — statusCode not 200 (a bogus SKU lands here: 400 with body.errors code InvalidInput), a body.errors list, or no response envelope (status 'NoResponse'); notification.type is 'warning' whenever it is non-empty."},"result_statuses":{"description":"[{sku, resultStatus, has_price}], one per featuredOfferExpectedPriceResults entry. featuredOfferExpectedPrice is present ONLY when resultStatus is VALID_FOEP. NO_COMPETING_OFFER is a legitimate success with no price — you hold the featured offer unopposed, and currentFeaturedOffer shows at what price; the other statuses are OFFER_NOT_ELIGIBLE, OFFER_NOT_FOUND and ASIN_NOT_ELIGIBLE. Never read a blank price as \"no repricing needed\" — this list says WHY there is none."},"responses":{"description":"per SKU — {request: {marketplaceId, sku, segment} (echoed, to map a response to its SKU), status: {statusCode, reasonPhrase}, body: {offerIdentifier: {marketplaceId, sku, asin}, featuredOfferExpectedPriceResults: [{resultStatus,","properties":{"featuredOfferExpectedPrice":{"description":"{listingPrice: {amount, currencyCode}},"}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productFees_getMyFeesEstimates":{"post":{"operationId":"productFees_getMyFeesEstimates","summary":"Amazon fee estimates for a batch of items in one request (Product Fees v0) — the batch form of productFees_getMyFeesEstimateForASIN and productFees_getMyFeesEstimateForSKU.","description":"Amazon fee estimates for a batch of items in one request (Product Fees v0) — the batch form of productFees_getMyFeesEstimateForASIN and productFees_getMyFeesEstimateForSKU. Amazon SP-API · getMyFeesEstimates · POST /products/fees/v0/feesEstimate","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productFees_getMyFeesEstimates"},"tags":["amazon_sp"],"x-title":"Product Fees Get My Fees Estimates","x-access":"read","x-family":"sp.productFeesV0","x-returns":[{"field":"data.ok","description":"the identifiers Amazon estimated."},{"field":"data.failed","description":"[{identifier, status, reason}] for every identifier without a usable estimate — Status not 'Success' (reason carries Amazon's Error.Code and Error.Message) or no result at all (status 'NoResponse'; an empty result list puts EVERY identifier here); notification.type is 'warning' whenever it is non-empty. Never read a missing fee as zero — a margin computed from a blank estimate is wrong."},{"field":"data.results","description":"[{FeesEstimateIdentifier, FeesEstimateResult: {Status, FeesEstimate: {TotalFeesEstimate: {Amount, CurrencyCode}, FeeDetailList}}}] — write TotalFeesEstimate.Amount per identifier."}],"x-notes":{"Body (Amazon schema): [FeesEstimateByIdRequest], each item":["FeesEstimateRequest: {MarketplaceId*, IsAmazonFulfilled, PriceToEstimateFees*: {ListingPrice*, Shipping, Points}, Identifier*, OptionalFulfillmentProgram: FBA_CORE | FBA_SNL | FBA_EFN}","IdType*: ASIN | SellerSKU","IdValue*: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"estimates":{"items":{},"title":"Estimates","type":"array","description":"[{identifier (required: an ASIN or a SKU, auto-detected — an ASIN matches ^B[0-9A-Z]{9}$ — and echoed as FeesEstimateIdentifier), price (required listing price), currency (ISO 4217; defaults to the marketplace's), is_fba (true for FBA, false for MFN), shipping_price (MFN only), points (Japan only: {PointsNumber, PointsMonetaryValue: {Amount, CurrencyCode}}), marketplace_id (defaults to the store's), optional_fulfillment_program (FBA only; FBA_SNL is sunset)}], e.g. [{\"identifier\": \"B0XXXXXXXX\", \"price\": 29.99, \"is_fba\": true}]. The camelCase spellings (isFba, shippingPrice, marketplaceId, optionalFulfillmentProgram) work too; any other key is dropped. A 10-digit ISBN ASIN does not match the pattern and is sent as a SellerSKU — estimate it with productFees_getMyFeesEstimateForASIN."}},"required":["store","estimates"],"title":"productFees_getMyFeesEstimatesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"ok":{"description":"the identifiers Amazon estimated."},"failed":{"description":"[{identifier, status, reason}] for every identifier without a usable estimate — Status not 'Success' (reason carries Amazon's Error.Code and Error.Message) or no result at all (status 'NoResponse'; an empty result list puts EVERY identifier here); notification.type is 'warning' whenever it is non-empty. Never read a missing fee as zero — a margin computed from a blank estimate is wrong."},"results":{"description":"[{FeesEstimateIdentifier, FeesEstimateResult: {Status, FeesEstimate: {TotalFeesEstimate: {Amount, CurrencyCode}, FeeDetailList}}}] — write TotalFeesEstimate.Amount per identifier."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productPricing_getPricing":{"post":{"operationId":"productPricing_getPricing","summary":"Get pricing information for up to 20 ASINs or SKUs (Product Pricing v0).","description":"Get pricing information for up to 20 ASINs or SKUs (Product Pricing v0). Amazon SP-API · getPricing · GET /products/pricing/v0/price Returns the seller's own listing prices. Use productPricing_getCompetitivePricing to see competitor prices, or productPricing_getItemOffers / productPricing_getListingOffers for all seller offers.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productPricing_getPricing"},"tags":["amazon_sp"],"x-title":"Product Pricing Get Pricing","x-access":"read","x-family":"sp.productPricingV0","x-returns":[{"field":"data.pricing","description":"list of pricing objects, each with: - ASIN or SellerSKU - Product.Offers: list of offer details with BuyingPrice, RegularPrice, FulfillmentChannel"},{"field":"data.ok","description":"identifiers Amazon returned a product for."},{"field":"data.failed","description":"[{identifier, status, reason}] for identifiers Amazon did NOT resolve. Amazon answers HTTP 200 even for a bad ASIN — it comes back as status='ClientError', as a \"successful\" item with no Product body, or with no envelope at all (status='NoResponse'; an empty payload puts EVERY requested identifier here). Either way it lands here and notification.type is 'warning', not 'success'. Never read a missing price as \"no offers\" without checking data.failed first."},{"field":"data.no_offers","description":"identifiers Amazon resolved (status Success, with a Product) but returned NO Offers for. getPricing does NOT validate ASIN existence — a bogus ASIN and a real ASIN you simply don't list look identical here, so these are reported rather than failed. Cross-check doubtful ASINs via productPricing_getCompetitivePricing, which rejects invalid ones as ClientError."}],"x-notes":{"Params (Amazon schema)":["MarketplaceId*: string","Asins: [string] (max 20)","Skus: [string] (max 20)","ItemType*: Asin | Sku","ItemCondition: New | Used | Collectible | Refurbished | Club","OfferType: B2C | B2B"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asins":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Asins","description":"List of up to 20 ASINs. Use this OR skus, not both."},"skus":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Skus","description":"List of up to 20 seller SKUs. Use this OR asins, not both."},"itemCondition":{"anyOf":[{"enum":["New","Used","Collectible","Refurbished","Club"],"type":"string"},{"type":"null"}],"default":null,"title":"Itemcondition","description":"filters the offers by condition. Allowed: New | Used | Collectible | Refurbished | Club."},"offerType":{"anyOf":[{"enum":["B2C","B2B"],"type":"string"},{"type":"null"}],"default":null,"title":"Offertype","description":"the seller's consumer or business offer. Omit for Amazon's default (B2C). Allowed: B2C | B2B."}},"required":["store"],"title":"productPricing_getPricingArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"pricing":{"description":"list of pricing objects, each with: - ASIN or SellerSKU - Product.Offers: list of offer details with BuyingPrice, RegularPrice, FulfillmentChannel"},"ok":{"description":"identifiers Amazon returned a product for."},"failed":{"description":"[{identifier, status, reason}] for identifiers Amazon did NOT resolve. Amazon answers HTTP 200 even for a bad ASIN — it comes back as status='ClientError', as a \"successful\" item with no Product body, or with no envelope at all (status='NoResponse'; an empty payload puts EVERY requested identifier here). Either way it lands here and notification.type is 'warning', not 'success'. Never read a missing price as \"no offers\" without checking data.failed first."},"no_offers":{"description":"identifiers Amazon resolved (status Success, with a Product) but returned NO Offers for. getPricing does NOT validate ASIN existence — a bogus ASIN and a real ASIN you simply don't list look identical here, so these are reported rather than failed. Cross-check doubtful ASINs via productPricing_getCompetitivePricing, which rejects invalid ones as ClientError."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productPricing_getCompetitivePricing":{"post":{"operationId":"productPricing_getCompetitivePricing","summary":"Get competitive pricing for up to 20 ASINs or SKUs (Product Pricing v0).","description":"Get competitive pricing for up to 20 ASINs or SKUs (Product Pricing v0). Amazon SP-API · getCompetitivePricing · GET /products/pricing/v0/competitivePrice Returns the competitive price (Buy Box price) and number of competing offers. More useful than productPricing_getPricing for understanding market position.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productPricing_getCompetitivePricing"},"tags":["amazon_sp"],"x-title":"Product Pricing Get Competitive Pricing","x-access":"read","x-family":"sp.productPricingV0","x-returns":[{"field":"notification.type","description":"'warning' when data.failed is non-empty, else 'success'."},{"field":"data.pricing","description":"list of pricing objects, each with: - ASIN or SellerSKU - Product.CompetitivePricing.CompetitivePrices: list of competitive prices - Product.CompetitivePricing.NumberOfOfferListings: offer count by condition - Product.CompetitivePricing.TradeInValue (if applicable)"},{"field":"data.ok","description":"identifiers Amazon returned a product for."},{"field":"data.failed","description":"[{identifier, status, reason}] for identifiers Amazon did NOT resolve. Amazon answers HTTP 200 even for a bad ASIN — it comes back as status='ClientError', as a \"successful\" item with no Product body, or with no envelope at all (status='NoResponse'). Either way it lands here and notification.type is 'warning', not 'success'. Never read a missing competitive price as \"no competitors\" without checking data.failed first."}],"x-notes":{"Workflow":["1. Call productPricing_getCompetitivePricing in batches of up to 20.","2. Compare against your current prices to identify repricing opportunities."],"Params (Amazon schema)":["MarketplaceId*: string","Asins: [string] (max 20)","Skus: [string] (max 20)","ItemType*: Asin | Sku","CustomerType: Consumer | Business"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asins":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Asins","description":"List of up to 20 ASINs. Use this OR skus, not both."},"skus":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Skus","description":"List of up to 20 seller SKUs. Use this OR asins, not both."},"customerType":{"anyOf":[{"enum":["Consumer","Business"],"type":"string"},{"type":"null"}],"default":null,"title":"Customertype","description":"whose point of view the prices are from — consumer or business buyers. Omit for Amazon's default (Consumer). Allowed: Consumer | Business."}},"required":["store"],"title":"productPricing_getCompetitivePricingArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"],"description":"'warning' when data.failed is non-empty, else 'success'."}}},"data":{"type":"object","properties":{"pricing":{"description":"list of pricing objects, each with: - ASIN or SellerSKU - Product.CompetitivePricing.CompetitivePrices: list of competitive prices - Product.CompetitivePricing.NumberOfOfferListings: offer count by condition - Product.CompetitivePricing.TradeInValue (if applicable)"},"ok":{"description":"identifiers Amazon returned a product for."},"failed":{"description":"[{identifier, status, reason}] for identifiers Amazon did NOT resolve. Amazon answers HTTP 200 even for a bad ASIN — it comes back as status='ClientError', as a \"successful\" item with no Product body, or with no envelope at all (status='NoResponse'). Either way it lands here and notification.type is 'warning', not 'success'. Never read a missing competitive price as \"no competitors\" without checking data.failed first."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productPricing_getListingOffers":{"post":{"operationId":"productPricing_getListingOffers","summary":"Get lowest-priced offers for a single seller SKU listing (Product Pricing v0).","description":"Get lowest-priced offers for a single seller SKU listing (Product Pricing v0). Amazon SP-API · getListingOffers · GET /products/pricing/v0/listings/{SellerSKU}/offers Returns the lowest-priced offers from every seller on the ASIN this SKU is listed against (data.summary.TotalOfferCount is the full count), plus Buy Box prices. For an ASIN you do not list use productPricing_getItemOffers.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productPricing_getListingOffers"},"tags":["amazon_sp"],"x-title":"Product Pricing Get Listing Offers","x-access":"read","x-family":"sp.productPricingV0","x-returns":[{"field":"notification.type","description":"'warning' when data.found is false, else 'success'."},{"field":"data.found","description":"false when Amazon resolved NOTHING for this SKU (empty payload or a ClientError envelope — a typo, or a SKU absent from this marketplace). This is NOT the same as a live listing with zero active offers, which returns found=true with an empty data.offers list and a real data.summary. When found is false, do not write a blank or a zero price to your sheet — check the SKU first."},{"field":"data.sellerSku","description":"the queried SKU."},{"field":"data.summary","description":"offer summary including: - TotalOfferCount: total number of offers - NumberOfOffers: offer count by condition and fulfillment channel - LowestPrices: lowest prices by condition/channel - BuyBoxPrices: current Buy Box prices - BuyBoxEligibleOffers: offers eligible for Buy Box"},{"field":"data.offers","description":"list of individual offers with price, condition, shipping, seller info."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"sellerSku":{"title":"Sellersku","type":"string","description":"Seller's SKU for the listing."},"itemCondition":{"enum":["New","Used","Collectible","Refurbished","Club"],"title":"Itemcondition","type":"string","description":"the condition of the offers returned. Allowed: New | Used | Collectible | Refurbished | Club."},"customerType":{"anyOf":[{"enum":["Consumer","Business"],"type":"string"},{"type":"null"}],"default":null,"title":"Customertype","description":"consumer or business offers. Omit for Amazon's default (Consumer). Allowed: Consumer | Business."}},"required":["store","sellerSku","itemCondition"],"title":"productPricing_getListingOffersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"],"description":"'warning' when data.found is false, else 'success'."}}},"data":{"type":"object","properties":{"found":{"description":"false when Amazon resolved NOTHING for this SKU (empty payload or a ClientError envelope — a typo, or a SKU absent from this marketplace). This is NOT the same as a live listing with zero active offers, which returns found=true with an empty data.offers list and a real data.summary. When found is false, do not write a blank or a zero price to your sheet — check the SKU first."},"sellerSku":{"description":"the queried SKU."},"summary":{"description":"offer summary including: - TotalOfferCount: total number of offers - NumberOfOffers: offer count by condition and fulfillment channel - LowestPrices: lowest prices by condition/channel - BuyBoxPrices: current Buy Box prices - BuyBoxEligibleOffers: offers eligible for Buy Box"},"offers":{"description":"list of individual offers with price, condition, shipping, seller info."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productPricing_getItemOffers":{"post":{"operationId":"productPricing_getItemOffers","summary":"Get lowest-priced offers for a single ASIN (Product Pricing v0).","description":"Get lowest-priced offers for a single ASIN (Product Pricing v0). Amazon SP-API · getItemOffers · GET /products/pricing/v0/items/{Asin}/offers Returns the lowest-priced offers on this ASIN (data.summary.TotalOfferCount is the full count) with Buy Box prices — use it for competitive analysis across all sellers on a product; check whether you are in data.offers and how your price compares.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productPricing_getItemOffers"},"tags":["amazon_sp"],"x-title":"Product Pricing Get Item Offers","x-access":"read","x-family":"sp.productPricingV0","x-returns":[{"field":"notification.type","description":"'warning' when data.found is false, else 'success'."},{"field":"data.found","description":"false when Amazon resolved NOTHING for this ASIN (empty payload or a ClientError envelope — a typo, or an ASIN absent from this marketplace). This is NOT the same as a live ASIN with zero active offers, which returns found=true with an empty data.offers list and a real data.summary. When found is false, do not write a blank or a zero price to your sheet — check the ASIN first."},{"field":"data.asin","description":"the queried ASIN."},{"field":"data.summary","description":"offer summary including: - TotalOfferCount: total number of offers - NumberOfOffers: offer count by condition and fulfillment channel - LowestPrices: lowest prices by condition/channel - BuyBoxPrices: current Buy Box prices - BuyBoxEligibleOffers: offers eligible for Buy Box"},{"field":"data.offers","description":"list of individual offers with price, condition, shipping, IsFeaturedMerchant."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"itemCondition":{"enum":["New","Used","Collectible","Refurbished","Club"],"title":"Itemcondition","type":"string","description":"the condition of the offers returned. Allowed: New | Used | Collectible | Refurbished | Club."},"customerType":{"anyOf":[{"enum":["Consumer","Business"],"type":"string"},{"type":"null"}],"default":null,"title":"Customertype","description":"consumer or business offers. Omit for Amazon's default (Consumer). Allowed: Consumer | Business."}},"required":["store","asin","itemCondition"],"title":"productPricing_getItemOffersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"],"description":"'warning' when data.found is false, else 'success'."}}},"data":{"type":"object","properties":{"found":{"description":"false when Amazon resolved NOTHING for this ASIN (empty payload or a ClientError envelope — a typo, or an ASIN absent from this marketplace). This is NOT the same as a live ASIN with zero active offers, which returns found=true with an empty data.offers list and a real data.summary. When found is false, do not write a blank or a zero price to your sheet — check the ASIN first."},"asin":{"description":"the queried ASIN."},"summary":{"description":"offer summary including: - TotalOfferCount: total number of offers - NumberOfOffers: offer count by condition and fulfillment channel - LowestPrices: lowest prices by condition/channel - BuyBoxPrices: current Buy Box prices - BuyBoxEligibleOffers: offers eligible for Buy Box"},"offers":{"description":"list of individual offers with price, condition, shipping, IsFeaturedMerchant."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productPricing_getItemOffersBatch":{"post":{"operationId":"productPricing_getItemOffersBatch","summary":"Get lowest-priced offers for a batch of ASINs in a single request (Product Pricing v0).","description":"Get lowest-priced offers for a batch of ASINs in a single request (Product Pricing v0). Amazon SP-API · getItemOffersBatch · POST /batches/products/pricing/v0/itemOffers More efficient than calling productPricing_getItemOffers repeatedly. Batch up to 20 ASINs.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productPricing_getItemOffersBatch"},"tags":["amazon_sp"],"x-title":"Product Pricing Get Item Offers Batch","x-access":"read","x-family":"sp.productPricingV0","x-returns":[{"field":"notification.type","description":"'warning' whenever data.failed is non-empty, else 'success'."},{"field":"data.ok","description":"ASINs whose request Amazon accepted (statusCode 200, no errors)."},{"field":"data.failed","description":"[{identifier, status, reason}] for every ASIN that failed at the TRANSPORT level — statusCode != 200 (a bogus ASIN 400s here with body.errors [{code: 'InvalidInput', ...}]), a body.errors list, or no response envelope at all (status='NoResponse', including when the whole payload came back empty). Body CONTENT is never judged: a listing with a real Summary and an empty Offers list is a genuine zero-offer answer, not a failure. Note the success body nests the real payload under body.payload. Never read a missing Buy Box price as \"no Buy Box\" without checking data.failed first."},{"field":"data.responses","description":"list of per-ASIN responses, each with: - request.Asin / request.ItemCondition: the request this entry answers - status.statusCode: 200 means success - body.payload.Summary.BuyBoxPrices: current Buy Box prices - body.payload.Summary.LowestPrices: lowest prices by channel/condition - body.payload.Offers: individual offer details - body.errors: Amazon's error list when this entry failed NOTE the body.payload nesting — reading body.Summary directly is undefined."}],"x-notes":{"Workflow":["1. Build requests_ list (up to 20 ASINs per call).","2. Call productPricing_getItemOffersBatch."],"Body (Amazon schema): {requests: [ItemOffersRequest]} (1–20), each item":["uri*: string","method*: GET | PUT | PATCH | DELETE | POST","headers: object","MarketplaceId*: string","ItemCondition*: New | Used | Collectible | Refurbished | Club","CustomerType: Consumer | Business"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"requests_":{"items":{},"title":"Requests","type":"array","description":"List of up to 20 batch request dicts. Each must include: - uri: str — '/products/pricing/v0/items/{asin}/offers' (fill in ASIN) - method: str — 'GET' - ItemCondition: str — Allowed: New | Used | Collectible | Refurbished | Club - MarketplaceId: str (optional) — defaults to the store's marketplace; pass only to override. - CustomerType: str (optional) — Allowed: Consumer | Business"}},"required":["store","requests_"],"title":"productPricing_getItemOffersBatchArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"],"description":"'warning' whenever data.failed is non-empty, else 'success'."}}},"data":{"type":"object","properties":{"ok":{"description":"ASINs whose request Amazon accepted (statusCode 200, no errors)."},"failed":{"description":"[{identifier, status, reason}] for every ASIN that failed at the TRANSPORT level — statusCode != 200 (a bogus ASIN 400s here with body.errors [{code: 'InvalidInput', ...}]), a body.errors list, or no response envelope at all (status='NoResponse', including when the whole payload came back empty). Body CONTENT is never judged: a listing with a real Summary and an empty Offers list is a genuine zero-offer answer, not a failure. Note the success body nests the real payload under body.payload. Never read a missing Buy Box price as \"no Buy Box\" without checking data.failed first."},"responses":{"description":"list of per-ASIN responses, each with: - request.Asin / request.ItemCondition: the request this entry answers - status.statusCode: 200 means success - body.payload.Summary.BuyBoxPrices: current Buy Box prices - body.payload.Summary.LowestPrices: lowest prices by channel/condition - body.payload.Offers: individual offer details - body.errors: Amazon's error list when this entry failed NOTE the body.payload nesting — reading body.Summary directly is undefined."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/productPricing_getListingOffersBatch":{"post":{"operationId":"productPricing_getListingOffersBatch","summary":"Get lowest-priced offers for a batch of SKU listings in a single request (Product Pricing v0).","description":"Get lowest-priced offers for a batch of SKU listings in a single request (Product Pricing v0). Amazon SP-API · getListingOffersBatch · POST /batches/products/pricing/v0/listingOffers More efficient than calling productPricing_getListingOffers repeatedly. Batch up to 20 SKUs.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/productPricing_getListingOffersBatch"},"tags":["amazon_sp"],"x-title":"Product Pricing Get Listing Offers Batch","x-access":"read","x-family":"sp.productPricingV0","x-returns":[{"field":"notification.type","description":"'warning' whenever data.failed is non-empty, else 'success'."},{"field":"data.ok","description":"SKUs whose request Amazon accepted (statusCode 200, no errors)."},{"field":"data.failed","description":"[{identifier, status, reason}] for every SKU that failed at the TRANSPORT level — statusCode != 200, a body.errors list, or no response envelope at all (status='NoResponse', including when the whole payload came back empty). Body CONTENT is never judged: a listing with a real Summary and an empty Offers list is a genuine zero-offer answer, not a failure. Note the success body nests the real payload under body.payload. Never read a missing Buy Box price as \"no Buy Box\" without checking data.failed first."},{"field":"data.responses","description":"list of per-SKU responses, each with: - request.SellerSKU / request.ItemCondition: the request this entry answers - status.statusCode: 200 means success - body.payload.Summary.BuyBoxPrices: current Buy Box prices - body.payload.Summary.LowestPrices: lowest prices by channel/condition - body.payload.Offers: individual offer details - body.errors: Amazon's error list when this entry failed NOTE the body.payload nesting — reading body.Summary directly is undefined."}],"x-notes":{"Workflow":["1. Build requests_ list (up to 20 SKUs per call).","2. Call productPricing_getListingOffersBatch."],"Body (Amazon schema): {requests: [ListingOffersRequest]} (1–20), each item":["uri*: string","method*: GET | PUT | PATCH | DELETE | POST","headers: object","MarketplaceId*: string","ItemCondition*: New | Used | Collectible | Refurbished | Club","CustomerType: Consumer | Business"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"requests_":{"items":{},"title":"Requests","type":"array","description":"List of up to 20 batch request dicts. Each must include: - uri: str — '/products/pricing/v0/listings/{sellerSku}/offers' (fill in SKU, URL-encode the SKU if it contains special characters) - method: str — 'GET' - ItemCondition: str — Allowed: New | Used | Collectible | Refurbished | Club - MarketplaceId: str (optional) — defaults to the store's marketplace; pass only to override. - CustomerType: str (optional) — Allowed: Consumer | Business"}},"required":["store","requests_"],"title":"productPricing_getListingOffersBatchArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"],"description":"'warning' whenever data.failed is non-empty, else 'success'."}}},"data":{"type":"object","properties":{"ok":{"description":"SKUs whose request Amazon accepted (statusCode 200, no errors)."},"failed":{"description":"[{identifier, status, reason}] for every SKU that failed at the TRANSPORT level — statusCode != 200, a body.errors list, or no response envelope at all (status='NoResponse', including when the whole payload came back empty). Body CONTENT is never judged: a listing with a real Summary and an empty Offers list is a genuine zero-offer answer, not a failure. Note the success body nests the real payload under body.payload. Never read a missing Buy Box price as \"no Buy Box\" without checking data.failed first."},"responses":{"description":"list of per-SKU responses, each with: - request.SellerSKU / request.ItemCondition: the request this entry answers - status.statusCode: 200 means success - body.payload.Summary.BuyBoxPrices: current Buy Box prices - body.payload.Summary.LowestPrices: lowest prices by channel/condition - body.payload.Offers: individual offer details - body.errors: Amazon's error list when this entry failed NOTE the body.payload nesting — reading body.Summary directly is undefined."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_async_report":{"post":{"operationId":"ads_create_async_report","summary":"Request an Amazon Advertising performance report (async — not immediately available; poll with ads_get_async_report until status=COMPLETED, then read data.report rows).","description":"Request an Amazon Advertising performance report (async — not immediately available; poll with ads_get_async_report until status=COMPLETED, then read data.report rows). Amazon Ads API · createAsyncReport · POST /reporting/reports Docs: https://advertising.amazon.com/API/docs/en-us/offline-report-prod-3p#tag/Asynchronous-Reports/operation/createAsyncReport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_async_report"},"tags":["amazon_ads"],"x-title":"Ads Create Async Report","x-access":"read","x-family":"ads.reporting","x-returns":[{"field":"data.reportId","description":"pass to ads_get_async_report."},{"field":"data.status","description":"the status at creation."}],"x-notes":{"Gotchas":["- configuration.adProduct must match the reportTypeId's family:","  an sp* type needs SPONSORED_PRODUCTS, sb* needs SPONSORED_BRANDS,","  sd* needs SPONSORED_DISPLAY — a mismatched pair is rejected.","- A DSP report's filters need a real advertiserId","  ({\"field\": \"advertiserId\", \"values\": [\"<id>\"]}) — get one from","  ads_dsp_advertisers first.","- Commonly used report types: spCampaigns (groupBy campaign,","  SUMMARY, campaign totals; or campaign+campaignPlacement; or","  campaign+adGroup DAILY for a daily trend), spTargeting (groupBy","  targeting, SUMMARY), spSearchTerm (groupBy searchTerm, SUMMARY),","  spAdvertisedProduct / spPurchasedProduct (DAILY, ASIN-level),","  spGrossAndInvalids (groupBy campaign, DAILY), sbCampaigns /","  sdCampaigns (groupBy campaign, SUMMARY, adProduct SPONSORED_BRANDS","  / SPONSORED_DISPLAY respectively).","- Reports take minutes and can take up to 3 hours — poll every","  5-10 minutes, never in a tight loop."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"configuration":{"additionalProperties":true,"properties":{"adProduct":{"enum":["ALL","DEMAND_SIDE_PLATFORM","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"columns":{"items":{"type":"string"},"type":"array"},"filters":{"items":{"additionalProperties":true,"properties":{"field":{"type":"string"},"values":{"items":{"type":"string"},"type":"array"}},"type":"object"},"type":"array"},"format":{"enum":["GZIP_JSON"],"type":"string"},"groupBy":{"items":{"type":"string"},"type":"array"},"reportTypeId":{"type":"string"},"timeUnit":{"enum":["DAILY","SUMMARY"],"type":"string"}},"required":["adProduct","columns","format","groupBy","reportTypeId","timeUnit"],"type":"object"},"endDate":{"type":"string"},"name":{"type":"string"},"startDate":{"type":"string"}},"required":["configuration","endDate","startDate"],"title":"Body","type":"object","description":"{name, startDate, endDate, configuration: {adProduct, reportTypeId, format: 'GZIP_JSON', groupBy: [...], columns: [...], timeUnit: 'SUMMARY'|'DAILY', filters?}}. startDate / endDate: 'YYYY-MM-DD'; most report types look back at most 95 days."}},"required":["store","countryCode","body"],"title":"ads_create_async_reportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reportId":{"description":"pass to ads_get_async_report."},"status":{"description":"the status at creation."},"result":{"properties":{"configuration":{"properties":{"adProduct":{},"columns":{"items":{}},"filters":{"items":{"properties":{"field":{},"values":{"items":{}}}}},"format":{},"groupBy":{"items":{}},"reportTypeId":{},"timeUnit":{}}},"createdAt":{},"endDate":{},"failureReason":{},"fileSize":{},"generatedAt":{},"name":{},"reportId":{},"startDate":{},"status":{},"updatedAt":{},"url":{},"urlExpiresAt":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_async_report":{"post":{"operationId":"ads_get_async_report","summary":"Poll an Amazon Advertising report's status; auto-downloads and returns the rows in data.report once status=COMPLETED.","description":"Poll an Amazon Advertising report's status; auto-downloads and returns the rows in data.report once status=COMPLETED. Amazon Ads API · getAsyncReport · GET /reporting/reports/{reportId} Docs: https://advertising.amazon.com/API/docs/en-us/offline-report-prod-3p#tag/Asynchronous-Reports/operation/getAsyncReport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_async_report"},"tags":["amazon_ads"],"x-title":"Ads Get Async Report","x-access":"read","x-family":"ads.reporting","x-returns":[{"field":"data.status","description":"PENDING | PROCESSING | COMPLETED | FAILED."},{"field":"data.report","description":"the rows (a list of dicts, one per groupBy dimension, e.g. campaign/ad group/keyword) once COMPLETED, else null."}],"x-notes":{"Gotchas":["- On FAILED (Amazon's failureReason is in notification.message),","  create a new report with corrected params rather than retrying","  the same reportId."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"reportId":{"title":"Reportid","type":"string","description":"data.reportId from ads_create_async_report."}},"required":["store","countryCode","reportId"],"title":"ads_get_async_reportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"PENDING | PROCESSING | COMPLETED | FAILED."},"report":{"description":"the rows (a list of dicts, one per groupBy dimension, e.g. campaign/ad group/keyword) once COMPLETED, else null."},"result":{"properties":{"configuration":{"properties":{"adProduct":{},"columns":{"items":{}},"filters":{"items":{"properties":{"field":{},"values":{"items":{}}}}},"format":{},"groupBy":{"items":{}},"reportTypeId":{},"timeUnit":{}}},"createdAt":{},"endDate":{},"failureReason":{},"fileSize":{},"generatedAt":{},"name":{},"reportId":{},"startDate":{},"status":{},"updatedAt":{},"url":{},"urlExpiresAt":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_portfolios":{"post":{"operationId":"ads_list_portfolios","summary":"List portfolios (group campaigns across Sponsored Products, Brands and Display for shared budget caps and reporting).","description":"List portfolios (group campaigns across Sponsored Products, Brands and Display for shared budget caps and reporting). To create or change one use ads_create_portfolio / ads_update_portfolio. Amazon Ads API · ListPortfolios · POST /portfolios/list Docs: https://advertising.amazon.com/API/docs/en-us/reference/portfolios#tag/Portfolios/operation/ListPortfolios","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_portfolios"},"tags":["amazon_ads"],"x-title":"Ads List Portfolios","x-access":"read","x-family":"ads.portfolios","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.portfolios","description":"[{portfolioId, name, state, budget, inBudget}]."},{"field":"data.result.nextToken","description":"present when more remain — call again with the same filters plus {\"nextToken\": \"<that token>\"}; one call returns one page."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"includeExtendedDataFields":{"type":"boolean"},"nameFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":1000,"minItems":1,"type":"array"},"queryTermMatchType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"}},"type":"object"},"nextToken":{"type":"string"},"portfolioIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":1000,"minItems":1,"type":"array"}},"type":"object"},"stateFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["ENABLED"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"type":"object"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"dict of filters or omit for all. Filters use {\"include\": [...]} form, e.g.: {\"stateFilter\": {\"include\": [\"ENABLED\"]}, \"portfolioIdFilter\": {\"include\": [\"123\", \"456\"]}, \"nameFilter\": {\"include\": [\"My Portfolio\"]}}"}},"required":["store","countryCode"],"title":"ads_list_portfoliosArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"nextToken":{"description":"present when more remain — call again with the same filters plus {\"nextToken\": \"<that token>\"}; one call returns one page."},"portfolios":{"items":{"properties":{"budget":{"properties":{"amount":{},"currencyCode":{},"endDate":{},"policy":{},"startDate":{}}},"budgetControls":{"properties":{"campaignUnspentBudgetSharing":{"properties":{"featureState":{}}}}},"extendedData":{"properties":{"creationDateTime":{},"lastUpdateDateTime":{},"servingStatus":{},"statusReasons":{"items":{}}}},"inBudget":{},"name":{},"portfolioId":{},"state":{}}},"description":"[{portfolioId, name, state, budget, inBudget}]."},"totalResults":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_portfolio":{"post":{"operationId":"ads_create_portfolio","summary":"Create portfolios (cross-product: Sponsored Products, Brands and Display).","description":"Create portfolios (cross-product: Sponsored Products, Brands and Display). Amazon Ads API · CreatePortfolios · POST /portfolios Docs: https://advertising.amazon.com/API/docs/en-us/reference/portfolios#tag/Portfolios/operation/CreatePortfolios Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_portfolio"},"tags":["amazon_ads"],"x-title":"Ads Create Portfolio","x-access":"write","x-family":"ads.portfolios","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.portfolios.success","description":"[{index, portfolioId, portfolio}] — each created portfolio and its id; index is its position in your list."},{"field":"data.result.portfolios.error","description":"[{index, errors}] — items Amazon refused (notification.type is 'warning' when some items failed, 'error' when none succeeded)."}],"x-notes":{"Gotchas":["- A portfolio's state can only be ENABLED — the one value in Amazon's portfolio","  API (create, update and list); a portfolio cannot be paused, archived or","  deleted through the API — do that in the Amazon Ads console.","- Check existing names with ads_list_portfolios first; put campaigns in the","  new portfolio by setting portfolioId with ads_create_campaign or","  ads_update_campaign."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"items":{"additionalProperties":true,"properties":{"budget":{"additionalProperties":true,"properties":{"amount":{"format":"double","type":"number"},"currencyCode":{"enum":["AED","AUD","BRL","CAD","CLP","CNY","COP","EGP","EUR","GBP","INR","JPY","MXN","NGN","PLN","SAR","SEK","SGD","TRY","USD","ZAR"],"type":"string"},"endDate":{"format":"date","type":"string"},"policy":{"enum":["DATE_RANGE","MONTHLY_RECURRING","NO_CAP","OTHER"],"type":"string"},"startDate":{"format":"date","type":"string"}},"type":"object"},"budgetControls":{"additionalProperties":true,"properties":{"campaignUnspentBudgetSharing":{"additionalProperties":true,"properties":{"featureState":{"enum":["DISABLED","ENABLED"],"type":"string"}},"required":["featureState"],"type":"object"}},"type":"object"},"name":{"type":"string"},"state":{"enum":["ENABLED"],"type":"string"}},"required":["name","state"],"type":"object"},"maxItems":100,"minItems":1,"title":"Body","type":"array","description":"a bare list of portfolio objects (1–100) — the server wraps it in {portfolios: [...]}, so never send that envelope. name* and state* ('ENABLED') are required; budget is optional ({amount, currencyCode, policy, startDate, endDate}; dates YYYY-MM-DD)."}},"required":["store","countryCode","body"],"title":"ads_create_portfolioArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"portfolios":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"properties":{"errorType":{},"errorValue":{"description":"10 fields (billingError, budgetError, dateError, duplicateValueError, entityNotFoundError, entityQuotaError, …) — see the Docs link"}}}},"index":{}}},"description":"[{index, errors}] — items Amazon refused (notification.type is 'warning' when some items failed, 'error' when none succeeded)."},"success":{"items":{"properties":{"index":{},"portfolio":{"properties":{"budget":{"description":"5 fields (amount, currencyCode, endDate, policy, startDate) — see the Docs link"},"budgetControls":{"description":"1 fields (campaignUnspentBudgetSharing) — see the Docs link"},"extendedData":{"description":"4 fields (creationDateTime, lastUpdateDateTime, servingStatus, statusReasons) — see the Docs link"},"inBudget":{},"name":{},"portfolioId":{},"state":{}}},"portfolioId":{}}},"description":"[{index, portfolioId, portfolio}] — each created portfolio and its id; index is its position in your list."}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_portfolio":{"post":{"operationId":"ads_update_portfolio","summary":"Update portfolios (cross-product: Sponsored Products, Brands and Display).","description":"Update portfolios (cross-product: Sponsored Products, Brands and Display). Amazon Ads API · UpdatePortfolios · PUT /portfolios Docs: https://advertising.amazon.com/API/docs/en-us/reference/portfolios#tag/Portfolios/operation/UpdatePortfolios Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_portfolio"},"tags":["amazon_ads"],"x-title":"Ads Update Portfolio","x-access":"destructive","x-family":"ads.portfolios","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.portfolios.success","description":"[{index, portfolioId, portfolio}] — each updated portfolio and its id; index is its position in your list."},{"field":"data.result.portfolios.error","description":"[{index, errors}] — items Amazon refused (notification.type is 'warning' when some items failed, 'error' when none succeeded)."}],"x-notes":{"Gotchas":["- A portfolio's state can only be ENABLED — the one value in Amazon's portfolio","  API (create, update and list); a portfolio cannot be paused, archived or","  deleted through the API — do that in the Amazon Ads console."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"items":{"additionalProperties":true,"properties":{"budget":{"additionalProperties":true,"properties":{"amount":{"format":"double","type":"number"},"currencyCode":{"enum":["AED","AUD","BRL","CAD","CLP","CNY","COP","EGP","EUR","GBP","INR","JPY","MXN","NGN","PLN","SAR","SEK","SGD","TRY","USD","ZAR"],"type":"string"},"endDate":{"format":"date","type":"string"},"policy":{"enum":["DATE_RANGE","MONTHLY_RECURRING","NO_CAP","OTHER"],"type":"string"},"startDate":{"format":"date","type":"string"}},"type":"object"},"budgetControls":{"additionalProperties":true,"properties":{"campaignUnspentBudgetSharing":{"additionalProperties":true,"properties":{"featureState":{"enum":["DISABLED","ENABLED"],"type":"string"}},"required":["featureState"],"type":"object"}},"type":"object"},"name":{"type":"string"},"portfolioId":{"type":"string"},"state":{"enum":["ENABLED"],"type":"string"}},"required":["portfolioId"],"type":"object"},"maxItems":100,"minItems":1,"title":"Body","type":"array","description":"a bare list of {portfolioId*, ...fields to change} (1–100) — the server wraps it in {portfolios: [...]}; never send that envelope."}},"required":["store","countryCode","body"],"title":"ads_update_portfolioArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"portfolios":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"properties":{"errorType":{},"errorValue":{"description":"10 fields (billingError, budgetError, dateError, duplicateValueError, entityNotFoundError, entityQuotaError, …) — see the Docs link"}}}},"index":{}}},"description":"[{index, errors}] — items Amazon refused (notification.type is 'warning' when some items failed, 'error' when none succeeded)."},"success":{"items":{"properties":{"index":{},"portfolio":{"properties":{"budget":{"description":"5 fields (amount, currencyCode, endDate, policy, startDate) — see the Docs link"},"budgetControls":{"description":"1 fields (campaignUnspentBudgetSharing) — see the Docs link"},"extendedData":{"description":"4 fields (creationDateTime, lastUpdateDateTime, servingStatus, statusReasons) — see the Docs link"},"inBudget":{},"name":{},"portfolioId":{},"state":{}}},"portfolioId":{}}},"description":"[{index, portfolioId, portfolio}] — each updated portfolio and its id; index is its position in your list."}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_ranked_keyword_recommendation":{"post":{"operationId":"ads_get_ranked_keyword_recommendation","summary":"Sponsored Products: ranked keyword recommendations with per-match-type suggested bids, from either an ad group or a list of ASINs.","description":"Sponsored Products: ranked keyword recommendations with per-match-type suggested bids, from either an ad group or a list of ASINs. Amazon Ads API · getRankedKeywordRecommendation · POST /sp/targets/keywords/recommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Keyword-Targets/operation/getRankedKeywordRecommendation","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_ranked_keyword_recommendation"},"tags":["amazon_ads"],"x-title":"Ads Get Ranked Keyword Recommendation","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.keywordTargetList","description":"[{keyword, bidInfo}] — one bidInfo entry per match type with its suggested bid, rank and theme."}],"x-notes":{"Gotchas":["- The server calls Amazon's v5 media type and automatically","  falls back to v4 if the marketplace refuses v5. v5 adds a","  `theme` and `rank` per bidInfo entry and returns a suggested","  bid for EVERY match type, where v4 left EXACT/PHRASE bids null","  in ASIN mode.","- Bids here are INTEGER MINOR UNITS (94 = 0.94 AED). The theme-","  based ads_get_theme_based_bid_recommendation_for_ad_group_v1","  tool returns DECIMAL currency (2.09 = 2.09 AED). Convert to a","  single consistent unit before comparing or combining the two.","- Create the picked keywords as KEYWORD targets with","  ads_create_target."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"anyOf":[{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"campaignId":{"type":"string"},"locale":{"enum":["ar_EG","de_DE","en_AE","en_AU","en_CA","en_GB","en_IN","en_SA","en_SG","en_US","es_ES","es_MX","fr_FR","it_IT","ja_JP","nl_NL","pl_PL","pt_BR","sv_SE","tr_TR","zh_CN"],"type":"string"},"maxRecommendations":{"default":200.0,"maximum":200,"minimum":0,"type":"number"},"recommendationType":{"enum":["KEYWORDS_FOR_ADGROUP"],"type":"string"},"sortDimension":{"enum":["CLICKS","CONVERSIONS","DEFAULT"],"type":"string"},"targets":{"items":{"additionalProperties":true,"properties":{"bid":{"format":"double","type":"number"},"keyword":{"type":"string"},"matchType":{"enum":["BROAD","EXACT","PHRASE"],"type":"string"},"userSelectedKeyword":{"type":"boolean"}},"type":"object"},"maxItems":100,"minItems":0,"type":"array"}},"required":["adGroupId","campaignId","recommendationType"],"title":"AdGroupKeywordTargetRankRecommendationRequest","type":"object"},{"additionalProperties":true,"properties":{"asins":{"items":{"type":"string"},"maxItems":50,"minItems":0,"type":"array"},"locale":{"enum":["ar_EG","de_DE","en_AE","en_AU","en_CA","en_GB","en_IN","en_SA","en_SG","en_US","es_ES","es_MX","fr_FR","it_IT","ja_JP","nl_NL","pl_PL","pt_BR","sv_SE","tr_TR","zh_CN"],"type":"string"},"maxRecommendations":{"default":200.0,"maximum":200,"minimum":0,"type":"number"},"recommendationType":{"enum":["KEYWORDS_FOR_ASINS"],"type":"string"},"sortDimension":{"enum":["CLICKS","CONVERSIONS","DEFAULT"],"type":"string"},"targets":{"items":{"additionalProperties":true,"properties":{"bid":{"format":"double","type":"number"},"keyword":{"type":"string"},"matchType":{"enum":["BROAD","EXACT","PHRASE"],"type":"string"},"userSelectedKeyword":{"type":"boolean"}},"type":"object"},"maxItems":100,"minItems":0,"type":"array"}},"required":["asins","recommendationType"],"title":"AsinsKeywordTargetRankRecommendationRequest","type":"object"}],"title":"Body","type":"object","description":"ONE of: - ASIN-based:    {\"asins\": [\"B0...\"], \"maxRecommendations\": 100} - ad-group-based:{\"adGroupId\": \"...\", \"campaignId\": \"...\", \"maxRecommendations\": 100, \"sortDimension\": \"CLICKS\"} recommendationType (KEYWORDS_FOR_ASINS vs KEYWORDS_FOR_ADGROUP) is auto-inferred from whether you pass asins or adGroupId. maxRecommendations 0–200 (default 200; 0 ranks only the keywords you pass in targets); asins ≤ 50; targets ≤ 100."}},"required":["store","countryCode","body"],"title":"ads_get_ranked_keyword_recommendationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"bid":{},"keyword":{},"matchType":{},"rank":{},"suggestedBid":{"properties":{"bidRecId":{},"rangeEnd":{},"rangeStart":{},"suggested":{}}},"translation":{},"userSelectedKeyword":{},"keywordTargetList":{"description":"[{keyword, bidInfo}] — one bidInfo entry per match type with its suggested bid, rank and theme."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_theme_based_bid_recommendation_for_ad_group_v1":{"post":{"operationId":"ads_get_theme_based_bid_recommendation_for_ad_group_v1","summary":"Sponsored Products: suggested bid amounts for keywords or targeting expressions, for an existing ad group or a new one.","description":"Sponsored Products: suggested bid amounts for keywords or targeting expressions, for an existing ad group or a new one. Use before creating or updating keywords/targets to set competitive bids. Amazon Ads API · GetThemeBasedBidRecommendationForAdGroup_v1 · POST /sp/targets/bid/recommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Theme-based-bid-recommendations/operation/GetThemeBasedBidRecommendationForAdGroup_v1","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_theme_based_bid_recommendation_for_ad_group_v1"},"tags":["amazon_ads"],"x-title":"Ads Get Theme Based Bid Recommendation for Ad Group V1","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Body (Amazon schema; application/vnd.spthemebasedbidrecommendation.v3+json), one of":["AdGroupThemeBasedBidRecommendationRequest","adGroupId*: string","campaignId*: string","recommendationType*: BIDS_FOR_EXISTING_AD_GROUP","targetingExpressions*: [{type*, value}] (max 100) (max 100 per request, use pagination for more if needed)","  targetingExpressions.type: CLOSE_MATCH | COMPLEMENTS | KEYWORD_BROAD_MATCH | KEYWORD_EXACT_MATCH | KEYWORD_PHRASE_MATCH | LOOSE_MATCH | SUBSTITUTES","AsinsThemeBasedBidRecommendationRequest","asins*: [string] (max 50)","bidding*: {adjustments: [{percentage, predicate}] (max 3), strategy*}","  bidding.adjustments.predicate: PLACEMENT_PRODUCT_PAGE | PLACEMENT_REST_OF_SEARCH | PLACEMENT_TOP","  bidding.strategy: AUTO_FOR_SALES | LEGACY_FOR_SALES | MANUAL | RULE_BASED","recommendationType*: BIDS_FOR_NEW_AD_GROUP","targetingExpressions*: [{type*, value}] (max 100) (max 100 per request, use pagination for more if needed)","  targetingExpressions.type: CLOSE_MATCH | COMPLEMENTS | KEYWORD_BROAD_MATCH | KEYWORD_EXACT_MATCH | KEYWORD_PHRASE_MATCH | LOOSE_MATCH | SUBSTITUTES"],"Gotchas":["- The AUTO types (CLOSE_MATCH/LOOSE_MATCH/SUBSTITUTES/","  COMPLEMENTS) and the KEYWORD_* types are TYPE-ONLY — do NOT","  add a `value` with keyword text (that is only required by the","  separate ads_get_ranked_keyword_recommendation endpoint). The","  PAT_* types are the exception: each takes a `value` (target","  ASIN, category id, or category refinement id).","- The response keys each suggested bid back to the expression's","  `value` when it has one, else to its `type`."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"title":"Body","type":"object","description":"pick the shape that matches your case: - Auto targeting on an EXISTING ad group: targetingExpressions [{\"type\": \"CLOSE_MATCH\"|\"LOOSE_MATCH\"|\"SUBSTITUTES\"| \"COMPLEMENTS\"}], campaignId, adGroupId, recommendationType: \"BIDS_FOR_EXISTING_AD_GROUP\". - Keyword/PAT targeting for a NEW ad group: asins, targetingExpressions, bidding.strategy, recommendationType: \"BIDS_FOR_NEW_AD_GROUP\"."}},"required":["store","countryCode","body"],"title":"ads_get_theme_based_bid_recommendation_for_ad_group_v1Arguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"bidRecommendations":{"items":{"properties":{"bidRecommendationsForTargetingExpressions":{"items":{"properties":{"bidValues":{"items":{"properties":{"suggestedBid":{}}}},"targetingExpression":{"properties":{"type":{},"value":{}}}}}},"impactMetrics":{"properties":{"clicks":{"properties":{"values":{"items":{"properties":{"lower":{},"upper":{}}}}}},"orders":{"properties":{"values":{"items":{"properties":{"lower":{},"upper":{}}}}}}}},"theme":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_sp_bulk_create":{"post":{"operationId":"ads_sp_bulk_create","summary":"Create complete Sponsored Products campaign structures in one call (Amazon Ads API v1) — campaign → ad groups → product ads → targets, with the created ids chained server-side.","description":"Create complete Sponsored Products campaign structures in one call (Amazon Ads API v1) — campaign → ad groups → product ads → targets, with the created ids chained server-side. The whole request is validated and preflighted first, so a malformed spec, a duplicate campaign name or an ASIN you do not own creates nothing. Amazon Ads API · QueryCampaign · POST /adsApi/v1/query/campaigns Amazon Ads API · ProductMetadata · POST /product/metadata Amazon Ads API · CreateCampaign · POST /adsApi/v1/create/campaigns Amazon Ads API · CreateAdGroup · POST /adsApi/v1/create/adGroups Amazon Ads API · CreateAd · POST /adsApi/v1/create/ads Amazon Ads API · CreateTarget · POST /adsApi/v1/create/targets Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-campaigns#tag/Campaigns/operation/QueryCampaign Docs: https://advertising.amazon.com/API/docs/en-us/product-metadata#tag/Product-Selector/operation/ProductMetadata Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-campaigns#tag/Campaigns/operation/CreateCampaign Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adgroups#tag/AdGroups/operation/CreateAdGroup Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-ads#tag/Ads/operation/CreateAd Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-targets#tag/Targets/operation/CreateTarget Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_sp_bulk_create"},"tags":["amazon_ads"],"x-title":"Ads SP Bulk Create","x-access":"write","x-family":"ads.v1","x-returns":[{"description":"the orchestrated result described below."},{"field":"data.results","description":"per campaign {campaignName, status SUCCESS | PARTIAL | ERROR, campaignId, adGroupIds {name: id}, steps: [{action, status, id | error}], message} — inspect every step; PARTIAL means some children failed."}],"x-notes":{"Gotchas":["- A rejected request names the field path of each problem. After the preflight","    only Amazon-side state (an ineligible product) fails, per step: that campaign","    becomes PARTIAL and every other step proceeds.","- A seller account advertises by SKU (one SKU = one ASIN, so it names the offer).","    An asin is resolved to your SKU, but when it maps to several SKUs the whole","    request is rejected with the SKUs listed — prefer sku when you list a product","    more than once. A Vendor Central account has no SKUs and passes asin.","- To resume a PARTIAL campaign re-call with the row's campaignId and each created","    adGroupId (with its defaultBid), OMITTING every child (product ad, target,","    negative) whose step shows SUCCESS — only the campaign and ad groups are skipped","    by id; children are re-sent verbatim and an existing one returns a per-index","    duplicate error.","- Idea sources: ads_get_ranked_keyword_recommendation,","    ads_sp_get_product_recommendations, ads_get_category_recommendations_for_asins,","    ads_get_budget_recommendation, ads_get_theme_based_bid_recommendation_for_ad_group_v1."],"Example":["one manual campaign with a product-targeting ad group — [{\"campaign\": {\"name\":","\"AE_Widget_SP_PT\", \"state\": \"PAUSED\", \"dailyBudget\": 10, \"startDate\":","\"20261201\"}, \"adGroups\": [{\"adGroup\": {\"name\": \"AE_Widget_SP_PT_Main\",","\"defaultBid\": 0.4}, \"productAds\": [{\"sku\": \"MY-SKU-001\"}], \"targets\": [{\"targetType\":","\"PRODUCT\", \"bid\": 0.4, \"targetDetails\": {\"productTarget\": {\"matchType\":","\"PRODUCT_EXACT\", \"product\": {\"productId\": \"B0XXXXXXXX\"}, \"productIdType\": \"ASIN\"}}}],","\"negativeTargets\": [{\"targetType\": \"KEYWORD\", \"targetDetails\": {\"keywordTarget\":","{\"keyword\": \"cheap\", \"matchType\": \"EXACT\"}}}]}]}]"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaign_spec":{"items":{},"title":"Campaign Spec","type":"array","description":"[{campaign, negativeTargets, adGroups}] — campaign: {name*, state PAUSED (default — a bulk never launches spend by accident) | ENABLED, dailyBudget*, startDate* 'YYYYMMDD', endDate, targetingType MANUAL (default) | AUTO, bidStrategy SALES_DOWN_ONLY (default) | SALES_UP_AND_DOWN | MANUAL, portfolioId, campaignId (resume only)}; negativeTargets: campaign-level blocks [{targetType KEYWORD | PRODUCT, targetDetails, state}]; adGroups: [{adGroup: {name*, defaultBid*, state, adGroupId (resume only)}, productAds: [{sku OR asin, state}], targets: [{targetType*, targetDetails*, bid, state}], negativeTargets: [{targetType* KEYWORD | PRODUCT, targetDetails*, state}]}]. A biddable target's targetType is KEYWORD | PRODUCT | PRODUCT_CATEGORY | THEME, with targetDetails exactly as ads_create_target takes them (the amazon-ads skill lists the catalog); one ad group is single-targeting-type — keyword targets and product/category/theme targets need separate ad groups. At most 10 campaigns per call, 20 ad groups per campaign and 100 productAds / targets / negativeTargets per ad group — split larger launches."}},"required":["store","countryCode","campaign_spec"],"title":"ads_sp_bulk_createArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"results":{"description":"per campaign {campaignName, status SUCCESS | PARTIAL | ERROR, campaignId, adGroupIds {name: id}, steps: [{action, status, id | error}], message} — inspect every step; PARTIAL means some children failed."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_sp_get_product_recommendations":{"post":{"operationId":"ads_sp_get_product_recommendations","summary":"Sponsored Products: suggested target ASINs (product targets) for your advertised ASINs — competitor / complementary ASINs Amazon considers relevant, each with the themes that produ","description":"Sponsored Products: suggested target ASINs (product targets) for your advertised ASINs — competitor / complementary ASINs Amazon considers relevant, each with the themes that produced it (e.g. \"Similar items (frequently viewed together)\"). Amazon Ads API · getProductRecommendations · POST /sp/targets/products/recommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Product-Recommendation-Service/operation/getProductRecommendations","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_sp_get_product_recommendations"},"tags":["amazon_ads"],"x-title":"Ads SP Get Product Recommendations","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- Best practice: get bids for the picked ASINs with","  ads_get_theme_based_bid_recommendation_for_ad_group_v1","  (targetingExpressions [{\"type\": \"PAT_ASIN\", \"value\": \"<asin>\"}]),","  then create them as PRODUCT targets with ads_create_target","  (targetDetails.productTarget, matchType PRODUCT_EXACT)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adAsins":{"items":{"maxLength":10,"minLength":10,"type":"string"},"type":"array"},"count":{"description":"the API will return a max `10` themes irrespective of how large the count is set","minimum":1,"type":"integer"},"cursor":{"type":"string"},"locale":{"type":"string"}},"required":["adAsins"],"title":"Body","type":"object","description":"{\"adAsins\": [\"B0XXXXXXXX\", ...], \"count\": 25, \"cursor\": \"...\"} — adAsins is the ASINs you advertise; count is optional (default 5); cursor pages from the previous data.nextCursor (send the same count with it)."}},"required":["store","countryCode","body"],"title":"ads_sp_get_product_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"nextCursor":{},"previousCursor":{},"recommendations":{"items":{"properties":{"recommendedAsin":{},"themes":{"items":{}}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_category_recommendations_for_asins":{"post":{"operationId":"ads_get_category_recommendations_for_asins","summary":"Sponsored Products: category targets recommended for a list of ASINs — the coarse half of SP product targeting; narrow one further with ads_get_refinements_for_category.","description":"Sponsored Products: category targets recommended for a list of ASINs — the coarse half of SP product targeting; narrow one further with ads_get_refinements_for_category. Amazon Ads API · getCategoryRecommendationsForASINs · POST /sp/targets/categories/recommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Product-Targeting/operation/getCategoryRecommendationsForASINs","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_category_recommendations_for_asins"},"tags":["amazon_ads"],"x-title":"Ads Get Category Recommendations for ASINs","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- Amazon 500s (\"Failed to get category recommendations\") for","  some ASIN/marketplace combinations — relayed as an Amazon","  error, not a SellerSheet bug. Do not retry-loop; try other","  ASINs or use ads_sp_get_product_recommendations instead.","- Only entries with canBeTargeted=true can be used as targets.","- Best practice: call ads_get_refinements_for_category on a chosen","  category id to get the brand / age-range / genre facets, then create","  the target with ads_create_target, targetType='PRODUCT_CATEGORY' and","  targetDetails={\"productCategoryTarget\": {\"productCategoryRefinement\": {","  \"productCategoryRefinement\": {\"productCategoryId\": \"<id>\"}}}}","  (productCategoryRefinement is nested TWICE — the outer key is the","  wrapper, the inner one holds the fields)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"asins":{"items":{"type":"string"},"maxItems":10000,"type":"array"},"includeAncestor":{"type":"boolean"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"{\"asins\": [\"B0XXXXXXXX\", ...], \"includeAncestor\": false} — includeAncestor optionally also returns ancestor categories (more results, less relevant)."},"locale":{"anyOf":[{"enum":["ar_AE","de_DE","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es_ES","es_MX","fr_CA","fr_FR","hi_IN","it_IT","ja_JP","ko_KR","nl_NL","pl_PL","pt_BR","sv_SE","ta_IN","th_TH","tr_TR","vi_VN","zh_CN"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"the language of the returned category names; omit for the marketplace's default language. Allowed: ar_AE | de_DE | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es_ES | es_MX | fr_CA | fr_FR | hi_IN | it_IT | ja_JP | ko_KR | nl_NL | pl_PL | pt_BR | sv_SE | ta_IN | th_TH | tr_TR | vi_VN | zh_CN."}},"required":["store","countryCode"],"title":"ads_get_category_recommendations_for_asinsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"categories":{"items":{"properties":{"canBeTargeted":{},"id":{},"name":{},"parent":{},"path":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_refinements_for_category":{"post":{"operationId":"ads_get_refinements_for_category","summary":"Sponsored Products: the refinements (brand / age-range / genre facets) targetable WITHIN a category — e.g.","description":"Sponsored Products: the refinements (brand / age-range / genre facets) targetable WITHIN a category — e.g. \"Toys > Building Sets\" refined to brand=LEGO. Amazon Ads API · getRefinementsForCategory · GET /sp/targets/category/{categoryId}/refinements Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Product-Targeting/operation/getRefinementsForCategory","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_refinements_for_category"},"tags":["amazon_ads"],"x-title":"Ads Get Refinements for Category","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- data.result.brands / ageRanges / genres are the facet ids to","  build the target with (ageRanges / genres may be null).","- Best practice: build the target with ads_create_target,","  targetType='PRODUCT_CATEGORY', targetDetails=","  {\"productCategoryTarget\": {\"productCategoryRefinement\": {","  \"productCategoryRefinement\": {\"productCategoryId\": \"<this","  categoryId>\", \"productBrandId\"?, \"productAgeRangeId\"?,","  \"productGenreId\"?}}}} — keep only the facets you actually want to","  narrow by (productCategoryRefinement is nested TWICE — the outer key","  is the wrapper, the inner one holds the fields)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"categoryId":{"title":"Categoryid","type":"string","description":"from ads_get_category_recommendations_for_asins (or the catalog browse node)."},"locale":{"anyOf":[{"enum":["ar_AE","de_DE","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es_ES","es_MX","fr_CA","fr_FR","hi_IN","it_IT","ja_JP","ko_KR","nl_NL","pl_PL","pt_BR","sv_SE","ta_IN","th_TH","tr_TR","vi_VN","zh_CN"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"the language of the returned facet names; omit for the marketplace's default language. Allowed: ar_AE | de_DE | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es_ES | es_MX | fr_CA | fr_FR | hi_IN | it_IT | ja_JP | ko_KR | nl_NL | pl_PL | pt_BR | sv_SE | ta_IN | th_TH | tr_TR | vi_VN | zh_CN."}},"required":["store","countryCode","categoryId"],"title":"ads_get_refinements_for_categoryArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"ageRanges":{"items":{"properties":{"id":{},"name":{}}}},"brands":{"items":{"properties":{"id":{},"name":{}}}},"genres":{"items":{"properties":{"id":{},"name":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_negative_brands":{"post":{"operationId":"ads_get_negative_brands","summary":"Sponsored Products: brands Amazon recommends excluding from targeting (no input needed).","description":"Sponsored Products: brands Amazon recommends excluding from targeting (no input needed). To search for a named competitor brand instead, use ads_search_brands. Amazon Ads API · getNegativeBrands · GET /sp/negativeTargets/brands/recommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Product-Targeting/operation/getNegativeBrands","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_negative_brands"},"tags":["amazon_ads"],"x-title":"Ads Get Negative Brands","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- There is NO negative-KEYWORD suggestion endpoint in the Amazon","  Ads API. To find wasteful search terms, query the SP","  search-term report (query_report_data on rpt_sp_search_terms —","  high spend, zero orders), not this tool.","- Amazon returns a bare array of {id, name} objects, not an","  envelope.","- To exclude a brand, create a negative target with","  ads_create_target: targetType PRODUCT_CATEGORY, negative true,","  targetDetails {productCategoryTarget: {productCategoryRefinement: {","  productCategoryRefinement: {productBrandId: <id>}}}} (the","  wrapper key is nested twice)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."}},"required":["store","countryCode"],"title":"ads_get_negative_brandsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"items":{"properties":{"id":{},"name":{}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_search_brands":{"post":{"operationId":"ads_search_brands","summary":"Sponsored Products: search for a brand by name, to exclude it from targeting (negative brand target) — use this to find a specific named competitor.","description":"Sponsored Products: search for a brand by name, to exclude it from targeting (negative brand target) — use this to find a specific named competitor. For Amazon's own suggestions with no input, use ads_get_negative_brands. Amazon Ads API · searchBrands · POST /sp/negativeTargets/brands/search Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Product-Targeting/operation/searchBrands","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_search_brands"},"tags":["amazon_ads"],"x-title":"Ads Search Brands","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- Amazon returns a bare array of {id, name} objects, not an","  envelope.","- To exclude a found brand, create the negative brand target","  ads_get_negative_brands describes (ads_create_target with","  productBrandId = the brand's id)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"keyword":{"title":"Keyword","type":"string","description":"the brand-name query (e.g. 'lego')."}},"required":["store","countryCode","keyword"],"title":"ads_search_brandsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"items":{"properties":{"id":{},"name":{}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_sp_get_budget_recommendations":{"post":{"operationId":"ads_sp_get_budget_recommendations","summary":"Sponsored Products: the recommended daily budget and missed opportunities for existing campaigns — campaigns that are budget-capped, losing impressions/clicks/sales because they ru","description":"Sponsored Products: the recommended daily budget and missed opportunities for existing campaigns — campaigns that are budget-capped, losing impressions/clicks/sales because they run out of budget. (Distinct from ads_get_budget_recommendation, which covers a new campaign, before it exists.) Amazon Ads API · getBudgetRecommendations · POST /sp/campaigns/budgetRecommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Budget-recommendations-and-missed-opportunities/operation/getBudgetRecommendations","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_sp_get_budget_recommendations"},"tags":["amazon_ads"],"x-title":"Ads SP Get Budget Recommendations","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.budgetRecommendationsSuccessResults","description":"[{index, campaignId, suggestedBudget, sevenDaysMissedOpportunities {startDate, endDate, percentTimeInBudget, estimatedMissed*Lower/Upper}}]."},{"field":"data.result.budgetRecommendationsErrorResults","description":"per-campaign failures {index, campaignId, code, details}."}],"x-notes":{"Gotchas":["- sevenDaysMissedOpportunities reflects the campaign's last","  ACTIVE period. For a long-paused campaign that window can be","  YEARS old — always show startDate/endDate next to the numbers.","- percentTimeInBudget = -1.0 with null dates is the \"no data\"","  sentinel (never served / long paused) — it is NOT 0%, never","  render it as a percent.","- Apply a raise with ads_update_campaign_budget."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaignIds":{"items":{"type":"string"},"maxItems":100,"title":"Campaignids","type":"array","description":"1-100 campaign id strings, from ads_query_campaign."}},"required":["store","countryCode","campaignIds"],"title":"ads_sp_get_budget_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"budgetRecommendationsErrorResults":{"items":{"properties":{"Error":{"properties":{"code":{},"details":{}}},"campaignId":{},"index":{}}},"description":"per-campaign failures {index, campaignId, code, details}."},"budgetRecommendationsSuccessResults":{"items":{"properties":{"budgetRuleRecommendation":{"properties":{"ruleId":{},"ruleName":{},"suggestedBudgetIncreasePercent":{}}},"campaignId":{},"index":{},"sevenDaysMissedOpportunities":{"properties":{"endDate":{},"estimatedMissedClicksLower":{},"estimatedMissedClicksUpper":{},"estimatedMissedImpressionsLower":{},"estimatedMissedImpressionsUpper":{},"estimatedMissedSalesLower":{},"estimatedMissedSalesUpper":{},"percentTimeInBudget":{},"startDate":{}}},"suggestedBudget":{}}},"description":"[{index, campaignId, suggestedBudget, sevenDaysMissedOpportunities {startDate, endDate, percentTimeInBudget, estimatedMissed*Lower/Upper}}]."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_generate_brand_metrics_report":{"post":{"operationId":"ads_generate_brand_metrics_report","summary":"Request a Brand Metrics report — your brand's shopper-funnel metrics in a category against category peers (engaged-shopper rate, customer conversion rate, new-to-brand customer rat","description":"Request a Brand Metrics report — your brand's shopper-funnel metrics in a category against category peers (engaged-shopper rate, customer conversion rate, new-to-brand customer rate, branded searches, detail-page views). It is brand-level, not per ad product or campaign. Poll and download it with ads_get_brand_metrics_report. Amazon Ads API · generateBrandMetricsReport · POST /insights/brandMetrics/report Docs: https://advertising.amazon.com/API/docs/en-us/brand-metrics-openapi#tag/Report/operation/generateBrandMetricsReport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_generate_brand_metrics_report"},"tags":["amazon_ads"],"x-title":"Ads Generate Brand Metrics Report","x-access":"read","x-family":"ads.brand-metrics","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.reportId","description":"pass to ads_get_brand_metrics_report."},{"field":"data.result.status","description":"IN_PROGRESS, SUCCESSFUL or FAILED."}],"x-notes":{"Gotchas":["- Brand metrics may not be supported in all marketplaces (e.g. AE)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"brandName":{"type":"string"},"categoryPath":{"items":{"type":"string"},"maxItems":20,"minItems":0,"type":"array"},"categoryTreeName":{"type":"string"},"format":{"default":"JSON","enum":["CSV","JSON"],"type":"string"},"lookBackPeriod":{"default":"1W","enum":["1CM","1M","1W"],"type":"string"},"metrics":{"items":{"type":"string"},"maxItems":20,"minItems":0,"type":"array"},"reportEndDate":{"format":"date","type":"string"},"reportStartDate":{"format":"date","type":"string"}},"title":"Body","type":"object","description":"every field optional — brandName, categoryTreeName, categoryPath, reportStartDate / reportEndDate (YYYY-MM-DD, at most 3 months apart; omit both for the latest computation), lookBackPeriod (default 1W), metrics (omit for all), format (default JSON). {} reports every brand."}},"required":["store","countryCode","body"],"title":"ads_generate_brand_metrics_reportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"expiration":{},"format":{},"location":{},"reportId":{"description":"pass to ads_get_brand_metrics_report."},"status":{"description":"IN_PROGRESS, SUCCESSFUL or FAILED."},"statusDetails":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_brand_metrics_report":{"post":{"operationId":"ads_get_brand_metrics_report","summary":"Poll a Brand Metrics report; when the server sees it finished, the same call also downloads the file, so there is no separate download step.","description":"Poll a Brand Metrics report; when the server sees it finished, the same call also downloads the file, so there is no separate download step. Poll every ~30 s. Amazon Ads API · getBrandMetricsReport · GET /insights/brandMetrics/report/{reportId} Docs: https://advertising.amazon.com/API/docs/en-us/brand-metrics-openapi#tag/Report/operation/getBrandMetricsReport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_brand_metrics_report"},"tags":["amazon_ads"],"x-title":"Ads Get Brand Metrics Report","x-access":"read","x-family":"ads.brand-metrics","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.status","description":"IN_PROGRESS, SUCCESSFUL or FAILED (statusDetails says why; a FAILED report answers with a warning)."},{"field":"data.result.reportData","description":"the parsed rows once SUCCESSFUL, capped at 20,000 (reportDataTruncated / reportDataTotalRecords when larger)."}],"x-notes":{"Gotchas":["- The file is parsed server-side when it is JSON (the default","  format); a CSV file comes back base64 with reportDataParsed","  false. data.result.location is the file's presigned URL (valid","  for data.result.expiration ms)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"reportId":{"title":"Reportid","type":"string","description":"data.result.reportId from ads_generate_brand_metrics_report."}},"required":["store","countryCode","reportId"],"title":"ads_get_brand_metrics_reportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"brandsInfo":{"items":{"properties":{"id":{},"name":{}}}},"expiration":{},"format":{},"location":{},"reportId":{},"status":{"description":"IN_PROGRESS, SUCCESSFUL or FAILED (statusDetails says why; a FAILED report answers with a warning)."},"statusDetails":{},"reportData":{"description":"the parsed rows once SUCCESSFUL, capped at 20,000 (reportDataTruncated / reportDataTotalRecords when larger)."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_campaign_export":{"post":{"operationId":"ads_campaign_export","summary":"Submit a bulk export of every campaign across Sponsored Products, Brands and Display — an asynchronous full snapshot in one file.","description":"Submit a bulk export of every campaign across Sponsored Products, Brands and Display — an asynchronous full snapshot in one file. For a filtered, paged read use ads_query_campaign. Amazon Ads API · CampaignExport · POST /campaigns/export Docs: https://advertising.amazon.com/API/docs/en-us/exports#tag/Exports/operation/CampaignExport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_campaign_export"},"tags":["amazon_ads"],"x-title":"Ads Campaign Export","x-access":"read","x-family":"ads.exports","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.exportId","description":"poll it with ads_get_export, typeExport='campaigns', until data.result.status is COMPLETED (or FAILED)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"adProductFilter":{"items":{"enum":["SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"},"stateFilter":{"items":{"enum":["ARCHIVED","ENABLED","PAUSED"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional filters — adProductFilter (default: all three ad products) and stateFilter (default ENABLED + PAUSED; ARCHIVED only when asked for)."}},"required":["store","countryCode"],"title":"ads_campaign_exportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"createdAt":{},"error":{"properties":{"errorCode":{},"message":{}}},"exportId":{"description":"poll it with ads_get_export, typeExport='campaigns', until data.result.status is COMPLETED (or FAILED)."},"fileSize":{},"generatedAt":{},"status":{},"url":{},"urlExpiresAt":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_ad_group_export":{"post":{"operationId":"ads_ad_group_export","summary":"Submit a bulk export of every ad group across Sponsored Products, Brands and Display — an asynchronous full snapshot in one file.","description":"Submit a bulk export of every ad group across Sponsored Products, Brands and Display — an asynchronous full snapshot in one file. For a filtered, paged read use ads_query_ad_group. Amazon Ads API · AdGroupExport · POST /adGroups/export Docs: https://advertising.amazon.com/API/docs/en-us/exports#tag/Exports/operation/AdGroupExport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_ad_group_export"},"tags":["amazon_ads"],"x-title":"Ads Ad Group Export","x-access":"read","x-family":"ads.exports","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.exportId","description":"poll it with ads_get_export, typeExport='adGroups', until data.result.status is COMPLETED (or FAILED)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"adProductFilter":{"items":{"enum":["SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"},"stateFilter":{"items":{"enum":["ARCHIVED","ENABLED","PAUSED"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional filters — adProductFilter (default: all three ad products) and stateFilter (default ENABLED + PAUSED; ARCHIVED only when asked for)."}},"required":["store","countryCode"],"title":"ads_ad_group_exportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"createdAt":{},"error":{"properties":{"errorCode":{},"message":{}}},"exportId":{"description":"poll it with ads_get_export, typeExport='adGroups', until data.result.status is COMPLETED (or FAILED)."},"fileSize":{},"generatedAt":{},"status":{},"url":{},"urlExpiresAt":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_target_export":{"post":{"operationId":"ads_target_export","summary":"Submit a bulk export of every targeting clause (keywords, product targets and all negatives) across Sponsored Products, Brands and Display — an asynchronous full snapshot in one fi","description":"Submit a bulk export of every targeting clause (keywords, product targets and all negatives) across Sponsored Products, Brands and Display — an asynchronous full snapshot in one file. For a filtered, paged read use ads_query_target. Amazon Ads API · TargetExport · POST /targets/export Docs: https://advertising.amazon.com/API/docs/en-us/exports#tag/Exports/operation/TargetExport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_target_export"},"tags":["amazon_ads"],"x-title":"Ads Target Export","x-access":"read","x-family":"ads.exports","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.exportId","description":"poll it with ads_get_export, typeExport='targets', until data.result.status is COMPLETED (or FAILED)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"adProductFilter":{"items":{"enum":["SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"},"negativeFilter":{"items":{"type":"boolean"},"maxItems":2,"minItems":1,"type":"array"},"stateFilter":{"items":{"enum":["ARCHIVED","ENABLED","PAUSED"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"},"targetLevelFilter":{"items":{"enum":["AD_GROUP","CAMPAIGN"],"type":"string"},"maxItems":2,"minItems":1,"type":"array"},"targetTypeFilter":{"items":{"enum":["AUDIENCE","AUTO","CONTENT_CATEGORY","KEYWORD","PRODUCT","PRODUCT_AUDIENCE","PRODUCT_CATEGORY","PRODUCT_CATEGORY_AUDIENCE","THEME"],"type":"string"},"maxItems":9,"minItems":1,"type":"array"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional filters — adProductFilter (default: all three ad products) and stateFilter (default ENABLED + PAUSED; ARCHIVED only when asked for). Targets also take negativeFilter, targetLevelFilter and targetTypeFilter (see Body)."}},"required":["store","countryCode"],"title":"ads_target_exportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"createdAt":{},"error":{"properties":{"errorCode":{},"message":{}}},"exportId":{"description":"poll it with ads_get_export, typeExport='targets', until data.result.status is COMPLETED (or FAILED)."},"fileSize":{},"generatedAt":{},"status":{},"url":{},"urlExpiresAt":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_ad_export":{"post":{"operationId":"ads_ad_export","summary":"Submit a bulk export of every product ad across Sponsored Products, Brands and Display — an asynchronous full snapshot in one file.","description":"Submit a bulk export of every product ad across Sponsored Products, Brands and Display — an asynchronous full snapshot in one file. For a filtered, paged read use ads_query_ad. Amazon Ads API · AdExport · POST /ads/export Docs: https://advertising.amazon.com/API/docs/en-us/exports#tag/Exports/operation/AdExport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_ad_export"},"tags":["amazon_ads"],"x-title":"Ads Ad Export","x-access":"read","x-family":"ads.exports","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.exportId","description":"poll it with ads_get_export, typeExport='ads', until data.result.status is COMPLETED (or FAILED)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"adProductFilter":{"items":{"enum":["SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"},"stateFilter":{"items":{"enum":["ARCHIVED","ENABLED","PAUSED"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional filters — adProductFilter (default: all three ad products) and stateFilter (default ENABLED + PAUSED; ARCHIVED only when asked for)."}},"required":["store","countryCode"],"title":"ads_ad_exportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"createdAt":{},"error":{"properties":{"errorCode":{},"message":{}}},"exportId":{"description":"poll it with ads_get_export, typeExport='ads', until data.result.status is COMPLETED (or FAILED)."},"fileSize":{},"generatedAt":{},"status":{},"url":{},"urlExpiresAt":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_export":{"post":{"operationId":"ads_get_export","summary":"Poll a bulk export submitted with ads_campaign_export / ads_ad_group_export / ads_target_export / ads_ad_export; downloads the file once status=COMPLETED.","description":"Poll a bulk export submitted with ads_campaign_export / ads_ad_group_export / ads_target_export / ads_ad_export; downloads the file once status=COMPLETED. Amazon Ads API · GetExport · GET /exports/{exportId} Docs: https://advertising.amazon.com/API/docs/en-us/exports#tag/Exports/operation/GetExport","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_export"},"tags":["amazon_ads"],"x-title":"Ads Get Export","x-access":"read","x-family":"ads.exports","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.status","description":"PROCESSING, COMPLETED or FAILED (data.result.error {errorCode, message} on FAILED)."},{"field":"data.result.exportData","description":"the parsed records once COMPLETED (see Gotchas)."}],"x-notes":{"Gotchas":["- The download is gunzipped and parsed server-side into","  data.result.exportData (a list of dicts), capped at 20,000","  records. When the export is larger, exportDataTruncated=true","  and exportDataTotalRecords gives the real count — fetch","  data.result.url (short-lived) for the rest. If Amazon ever","  serves a non-JSON format, exportDataParsed=false and","  exportData is a base64 slice with exportDataError explaining","  why."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"exportId":{"title":"Exportid","type":"string","description":"from the submit call."},"typeExport":{"title":"Typeexport","type":"string","description":"'campaigns' | 'adGroups' | 'targets' | 'ads' — MUST match the export you submitted (selects the download's Accept header); no default, an unknown/missing value is refused."}},"required":["store","countryCode","exportId","typeExport"],"title":"ads_get_exportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"createdAt":{},"error":{"properties":{"errorCode":{},"message":{}}},"exportId":{},"fileSize":{},"generatedAt":{},"status":{"description":"PROCESSING, COMPLETED or FAILED (data.result.error {errorCode, message} on FAILED)."},"url":{},"urlExpiresAt":{},"exportData":{"description":"the parsed records once COMPLETED (see Gotchas)."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_history":{"post":{"operationId":"ads_get_history","summary":"Get the entity change history — an audit log of edits to campaigns, ad groups, keywords, targets and product ads.","description":"Get the entity change history — an audit log of edits to campaigns, ad groups, keywords, targets and product ads. Sponsored Products and Sponsored Brands only: Sponsored Display changes are not returned, and no event says who made the change. Amazon Ads API · getHistory · POST /history Docs: https://advertising.amazon.com/API/docs/en-us/change-history#operation/getHistory","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_history"},"tags":["amazon_ads"],"x-title":"Ads Get History","x-access":"read","x-family":"ads.change-history","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- eventTypes is an object keyed by event type, NOT an array (an array","  400s), and every entry needs eventTypeIds: Amazon answers 0 events, not","  an error, for an entry without them, so the server refuses such a call","  (400) before Amazon — an empty page is never mistaken for 'no changes'.","  THEME is sent with Amazon's v1.1 Accept header, which it requires.","- Date range must be within the last 90 days."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"count":{"type":"integer"},"eventTypes":{"additionalProperties":true,"properties":{"AD":{"additionalProperties":true,"properties":{"eventTypeIds":{"items":{"type":"string"},"type":"array"},"filters":{"items":{"enum":["BID_AMOUNT","BUDGET_AMOUNT","END_DATE","IN_BUDGET","NAME","PLACEMENT_GROUP","SMART_BIDDING_STRATEGY","START_DATE","STATUS"],"type":"string"},"type":"array"},"parents":{"description":"max 10 parents","items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"campaignId":{"type":"string"},"useProfileIdAdvertiser":{"type":"boolean"}},"type":"object"},"type":"array"}},"type":"object"},"AD_GROUP":{"additionalProperties":true,"properties":{"eventTypeIds":{"items":{"type":"string"},"type":"array"},"filters":{"items":{"enum":["BID_AMOUNT","BUDGET_AMOUNT","END_DATE","IN_BUDGET","NAME","PLACEMENT_GROUP","SMART_BIDDING_STRATEGY","START_DATE","STATUS"],"type":"string"},"type":"array"},"parents":{"description":"max 10 parents","items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"campaignId":{"type":"string"},"useProfileIdAdvertiser":{"type":"boolean"}},"type":"object"},"type":"array"}},"type":"object"},"CAMPAIGN":{"additionalProperties":true,"properties":{"eventTypeIds":{"items":{"type":"string"},"type":"array"},"filters":{"items":{"enum":["BID_AMOUNT","BUDGET_AMOUNT","END_DATE","IN_BUDGET","NAME","PLACEMENT_GROUP","SMART_BIDDING_STRATEGY","START_DATE","STATUS"],"type":"string"},"type":"array"},"parents":{"description":"max 10 parents","items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"campaignId":{"type":"string"},"useProfileIdAdvertiser":{"type":"boolean"}},"type":"object"},"type":"array"}},"type":"object"},"KEYWORD":{"additionalProperties":true,"properties":{"eventTypeIds":{"items":{"type":"string"},"type":"array"},"filters":{"items":{"enum":["BID_AMOUNT","BUDGET_AMOUNT","END_DATE","IN_BUDGET","NAME","PLACEMENT_GROUP","SMART_BIDDING_STRATEGY","START_DATE","STATUS"],"type":"string"},"type":"array"},"parents":{"description":"max 10 parents","items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"campaignId":{"type":"string"},"useProfileIdAdvertiser":{"type":"boolean"}},"type":"object"},"type":"array"}},"type":"object"},"NEGATIVE_KEYWORD":{"additionalProperties":true,"properties":{"eventTypeIds":{"items":{"type":"string"},"type":"array"},"filters":{"items":{"enum":["BID_AMOUNT","BUDGET_AMOUNT","END_DATE","IN_BUDGET","NAME","PLACEMENT_GROUP","SMART_BIDDING_STRATEGY","START_DATE","STATUS"],"type":"string"},"type":"array"},"parents":{"description":"max 10 parents","items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"campaignId":{"type":"string"},"useProfileIdAdvertiser":{"type":"boolean"}},"type":"object"},"type":"array"}},"type":"object"},"PRODUCT_TARGETING":{"additionalProperties":true,"properties":{"eventTypeIds":{"items":{"type":"string"},"type":"array"},"filters":{"items":{"enum":["BID_AMOUNT","BUDGET_AMOUNT","END_DATE","IN_BUDGET","NAME","PLACEMENT_GROUP","SMART_BIDDING_STRATEGY","START_DATE","STATUS"],"type":"string"},"type":"array"},"parents":{"description":"max 10 parents","items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"campaignId":{"type":"string"},"useProfileIdAdvertiser":{"type":"boolean"}},"type":"object"},"type":"array"}},"type":"object"},"THEME":{"additionalProperties":true,"properties":{"eventTypeIds":{"items":{"type":"string"},"type":"array"},"filters":{"items":{"enum":["BID_AMOUNT","BUDGET_AMOUNT","END_DATE","IN_BUDGET","NAME","PLACEMENT_GROUP","SMART_BIDDING_STRATEGY","START_DATE","STATUS"],"type":"string"},"type":"array"},"parents":{"description":"max 10 parents","items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"campaignId":{"type":"string"},"useProfileIdAdvertiser":{"type":"boolean"}},"type":"object"},"type":"array"}},"type":"object"}},"type":"object"},"fromDate":{"type":"integer"},"nextToken":{"type":"string"},"pageOffset":{"type":"integer"},"sort":{"additionalProperties":true,"properties":{"direction":{"default":"DESC","enum":["ASC","DESC"],"type":"string"},"key":{"enum":["DATE"],"type":"string"}},"type":"object"},"toDate":{"type":"integer"}},"required":["eventTypes","fromDate","toDate"],"title":"Body","type":"object","description":"{fromDate, toDate (millisecond Unix timestamps, 13 digits, within the last 90 days), eventTypes (below), count (page size, 50–200, default 100), pageOffset (0-based page index — the result carries pageOffset, maxPageNumber and totalRecords; there is no nextToken), sort ({key: 'DATE', direction: 'ASC' | 'DESC'})}. eventTypes is an object keyed by entity type — CAMPAIGN | AD_GROUP | AD | KEYWORD | NEGATIVE_KEYWORD | PRODUCT_TARGETING | NEGATIVE_PRODUCT_TARGETING | THEME — each value {eventTypeIds: [the ids of the entities to audit — required, an entry without them matches nothing], filters: [change types, e.g. NAME | STATUS | BUDGET_AMOUNT | BID_AMOUNT | START_DATE | END_DATE], parents: [parent ids, e.g. the campaignId of an ad group]}. List the ids first (ads_query_campaign, ads_query_ad_group, ads_query_target, ads_query_ad) and pass them."}},"required":["store","countryCode","body"],"title":"ads_get_historyArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"events":{"items":{"properties":{"changeType":{},"entityId":{},"entityType":{},"metadata":{"properties":{"adGroupId":{},"campaignBudgetType":{},"campaignId":{},"keyword":{},"keywordType":{},"negativeTargetingType":{},"placementGroupPosition":{},"predefinedTarget":{},"productTargetingType":{},"targetingExpression":{},"targetingType":{},"theme":{}}},"newValue":{},"previousValue":{},"timestamp":{}}}},"nextToken":{},"totalResults":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_insights_get_audiences_overlapping_audiences":{"post":{"operationId":"ads_insights_get_audiences_overlapping_audiences","summary":"Get the audiences that OVERLAP one given audience segment — audience-overlap insights for a single audienceId, not a catalog of audiences.","description":"Get the audiences that OVERLAP one given audience segment — audience-overlap insights for a single audienceId, not a catalog of audiences. Amazon Ads API · insightsGetAudiencesOverlappingAudiences · GET /insights/audiences/{audienceId}/overlappingAudiences Docs: https://advertising.amazon.com/API/docs/en-us/overlapping-audiences#tag/Audience-insights/operation/insightsGetAudiencesOverlappingAudiences","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_insights_get_audiences_overlapping_audiences"},"tags":["amazon_ads"],"x-title":"Ads Insights Get Audiences Overlapping Audiences","x-access":"read","x-family":"ads.insights","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Params (Amazon schema)":["audienceId*: string","adType*: DSP | SD","advertiserId: string","minimumOverlapAffinity: number (min 0)","maximumOverlapAffinity: number (min 0) — if specified, the affinities of all returned overlapping audiences will be at most the provided affinity","audienceCategory: [string] (max 20)","maxResults: integer (1–500)","nextToken: string"],"Gotchas":["- For standard SP brand performance use","  ads_generate_brand_metrics_report / ads_get_brand_metrics_report","  instead."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"audienceId":{"title":"Audienceid","type":"string","description":"the one audience segment to fetch overlap insights for — there is no list-all mode; sent inside the request body as body.audienceId."},"ad_type":{"enum":["DSP","SD"],"title":"Ad Type","type":"string","description":"Amazon's adType — the ad program whose audiences are compared; DSP also needs body.advertiserId. Allowed: DSP | SD."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"adType":{"enum":["DSP","SD"],"type":"string"},"advertiserId":{"type":"string"},"audienceCategory":{"items":{"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"maxResults":{"default":30,"maximum":500,"minimum":1,"type":"integer"},"maximumOverlapAffinity":{"description":"if specified, the affinities of all returned overlapping audiences will be at most the provided affinity","minimum":0,"type":"number"},"minimumOverlapAffinity":{"minimum":0,"type":"number"},"nextToken":{"type":"string"}},"required":["adType"],"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional query parameters — adType comes from ad_type; advertiserId (required for DSP, from ads_dsp_advertisers), minimumOverlapAffinity / maximumOverlapAffinity (≥ 0), audienceCategory (list, 1–20), maxResults (1–500, default 30), nextToken."}},"required":["store","countryCode","audienceId","ad_type"],"title":"ads_insights_get_audiences_overlapping_audiencesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"marketplace":{},"nextToken":{},"overlappingAudiences":{"items":{"properties":{"affinity":{},"audienceMetadata":{"properties":{"audienceForecast":{"properties":{"dailyImpressions":{"properties":{"lowerBound":{},"upperBound":{}}},"dailyReach":{"properties":{"lowerBound":{},"upperBound":{}}}}},"audienceId":{},"category":{},"name":{}}}}}},"requestedAudienceMetadata":{"properties":{"audienceForecast":{"properties":{"dailyImpressions":{"properties":{"lowerBound":{},"upperBound":{}}},"dailyReach":{"properties":{"lowerBound":{},"upperBound":{}}}}},"audienceId":{},"category":{},"name":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_sp_get_all_rule_events":{"post":{"operationId":"ads_sp_get_all_rule_events","summary":"Sponsored Products: list the special shopping events (Prime Day, Black Friday, …) with Amazon's suggested date range in this profile's marketplace.","description":"Sponsored Products: list the special shopping events (Prime Day, Black Friday, …) with Amazon's suggested date range in this profile's marketplace. An eventId scopes an SP budget rule (duration.eventTypeRuleDuration.eventId on ads_create_budget_rules_for_campaigns) or a bid rule (recurrence.duration.eventId). Amazon Ads API · SPGetAllRuleEvents · POST /sp/v1/events Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRulesRecommendation/operation/SPGetAllRuleEvents","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_sp_get_all_rule_events"},"tags":["amazon_ads"],"x-title":"Ads SP Get All Rule Events","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.events[]","description":"{eventId, eventName, startDate, endDate}."},{"field":"data.result.groupedEvents[]","description":"{groupedEventId, groupedEventName, startDate, endDate}."}],"x-notes":{"Gotchas":["- Pass an eventId as recurrence.duration.eventId (with","  eventName) on ads_sp_create_optimization_rules to bound a rule","  to the event instead of hardcoding dates. Rule changes take up","  to 24h to take effect, so create event rules well before the","  event starts."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."}},"required":["store","countryCode"],"title":"ads_sp_get_all_rule_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"events":{"items":{"properties":{"endDate":{},"eventId":{},"eventName":{},"startDate":{}}},"description":"{eventId, eventName, startDate, endDate}."},"groupedEvents":{"items":{"properties":{"endDate":{},"groupedEventId":{},"groupedEventName":{},"startDate":{}}},"description":"{groupedEventId, groupedEventName, startDate, endDate}."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_search_optimization_rules":{"post":{"operationId":"ads_search_optimization_rules","summary":"Search Sponsored Products bid optimization rules — rules that raise bids on a SCHEDULE or, with apiVersion='v2', while a PERFORMANCE condition holds (ROAS, CVR, CTR, …).","description":"Search Sponsored Products bid optimization rules — rules that raise bids on a SCHEDULE or, with apiVersion='v2', while a PERFORMANCE condition holds (ROAS, CVR, CTR, …). Rules only ever INCREMENT by a PERCENT; to \"lower\" bids at night, set a lower base bid and add a rule that raises it during the hours you want. Amazon Ads API · SearchOptimizationRules · POST /sp/rules/optimization/search Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Optimization-Rules/operation/SearchOptimizationRules","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_search_optimization_rules"},"tags":["amazon_ads"],"x-title":"Ads Search Optimization Rules","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.optimizationRules[]","description":"each with optimizationRuleId, status, ruleCategory, ruleSubCategory."},{"field":"data.nextToken","description":"pass back as body.nextToken with the SAME filters; the page size is pageSize on v1 (≤ 100 rules) or maxResults on v2 (1–300)."}],"x-notes":{"Gotchas":["- v2's ruleName filter is unreliable — a name-filtered query can","  return 0 rows against many a name-less query returns. Filter","  by id or by campaign+category+subcategory and match names","  client-side."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"campaignFilter":{"additionalProperties":true,"properties":{"campaignId":{"additionalProperties":true,"properties":{"filterType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"},"values":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"type":"object"}},"type":"object"},"nextToken":{"type":"string"},"optimizationRuleFilter":{"additionalProperties":true,"properties":{"optimizationRuleId":{"additionalProperties":true,"properties":{"filterType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"},"values":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"type":"object"},"ruleCategory":{"additionalProperties":true,"properties":{"filterType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"},"values":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"type":"object"},"ruleSubCategory":{"additionalProperties":true,"properties":{"filterType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"},"values":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"type":"object"}},"type":"object"},"pageSize":{"type":"number"}},"title":"Body","type":"object","description":"REQUIRED — Amazon 400s on an empty body. Exactly one of: a rule id filter ALONE (optimizationRuleFilter. optimizationRuleId), or campaignId + ruleCategory + ruleSubCategory together (campaignId lives in its OWN top-level campaignFilter object)."},"apiVersion":{"default":"v1","title":"Apiversion","type":"string","description":"v1 (default — BID+SCHEDULE only) | v2 (adds PERFORMANCE rules, the condition metrics, targeting[], and the ruleName/ruleStatus search filters)."}},"required":["store","countryCode","body"],"title":"ads_search_optimization_rulesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"code":{},"nextToken":{},"optimizationRules":{"items":{"properties":{"action":{"properties":{"actionDetails":{"properties":{"actionOperator":{},"actionUnit":{},"value":{}}},"actionType":{}}},"conditions":{"items":{"properties":{"attributeName":{},"criteria":{"anyOf":[{"properties":{"maxValue":{},"minValue":{}},"title":"OptimizationRulesAPISwaggerRangeTypeRuleCriteria"},{"properties":{"comparisonOperator":{},"value":{}},"title":"OptimizationRulesAPISwaggerValueTypeRuleCriteria"}]}}}},"optimizationRuleId":{},"recurrence":{"properties":{"daysOfWeek":{"items":{}},"duration":{"properties":{"endTime":{},"eventId":{},"eventName":{},"startTime":{}}},"timesOfDay":{"items":{"properties":{"endTime":{},"startTime":{}}}},"type":{}}},"ruleCategory":{},"ruleName":{},"ruleSubCategory":{},"status":{}}},"description":"each with optimizationRuleId, status, ruleCategory, ruleSubCategory."}}},"nextToken":{"description":"pass back as body.nextToken with the SAME filters; the page size is pageSize on v1 (≤ 100 rules) or maxResults on v2 (1–300)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_sp_create_optimization_rules":{"post":{"operationId":"ads_sp_create_optimization_rules","summary":"Create a Sponsored Products bid optimization rule — schedule or performance bid rules that raise bids automatically.","description":"Create a Sponsored Products bid optimization rule — schedule or performance bid rules that raise bids automatically. List existing rules first with ads_search_optimization_rules; a new rule changes nothing until it is associated with ads_associate_optimization_rules_to_campaign. Amazon Ads API · CreateOptimizationRules · POST /sp/rules/optimization Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Optimization-Rules/operation/CreateOptimizationRules Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_sp_create_optimization_rules"},"tags":["amazon_ads"],"x-title":"Ads SP Create Optimization Rules","x-access":"write","x-family":"ads.sp","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.failed","description":"[{index, optimizationRuleId, code, details}] for every item Amazon did not confirm. ALWAYS relay this verbatim."},{"field":"data.result.responses","description":"per rule, optimizationRule.optimizationRuleId — pass it to ads_associate_optimization_rules_to_campaign."}],"x-notes":{"Body (Amazon schema; application/vnd.spoptimizationrules.v1+json): {optimizationRules":["[OptimizationRulesAPISwaggerOptimizationRuleWithoutRuleId]} (exactly 1), each item:","  action*: {actionDetails*: {actionOperator*, actionUnit*, value*}, actionType*: ADOPT}","action.actionDetails.actionOperator: INCREMENT","action.actionDetails.actionUnit: PERCENT","conditions: [{attributeName: ROAS, criteria: {maxValue*, minValue*} | {comparisonOperator*, value*}}] (max 1)","conditions.criteria.comparisonOperator: EQUAL_TO | GREATER_THAN | GREATER_THAN_OR_EQUAL_TO | LESS_THAN | LESS_THAN_OR_EQUAL_TO","recurrence*: {daysOfWeek, duration*: {endTime, eventId, eventName, startTime}, timesOfDay: [{endTime*, startTime*}] (max 1), type*: DAILY | WEEKLY}","recurrence.daysOfWeek: [FRIDAY | MONDAY | SATURDAY | SUNDAY | THURSDAY | TUESDAY | WEDNESDAY]","ruleCategory*: BID","ruleName: string","ruleSubCategory*: SCHEDULE","status: ENABLED | ENDED | PAUSED | SCHEDULED"],"Gotchas":["- Rules only ever INCREMENT by a PERCENT — there is no decrease","  action.","- Changes take up to 24 HOURS to take effect. Max 20 schedule","  rules per campaign.","- Rules active together STACK ADDITIVELY (a 10% daily + 20%","  event rule = +30%), on top of placement adjustments and","  bidding strategies.","- The response echoes status 'SCHEDULED' even when you sent","  'ENABLED' — that is normal, not a failure.","- ruleCategory BID pins ruleSubCategory to SCHEDULE;","  ruleCategory TARGETING pins it to PERFORMANCE — any other","  pairing 400s, so a performance condition only ever adjusts","  TARGETING, never a plain BID rule. BUDGET appears in the","  spec's ruleCategory enum but Amazon rejects it — budget","  automation lives in ads_create_budget_rules_for_campaigns.","- A TARGETING/PERFORMANCE rule must NOT carry recurrence (Amazon","  rejects it — the start time is the creation time) and MUST","  carry targeting[]. ACOS is in the spec's condition","  attributeName enum but Amazon rejects it here — for","  ACOS-gated automation use","  ads_create_budget_rules_for_campaigns instead (it acts on","  budget, not bids).","- Mutually exclusive with ads_create_optimization_rule (the","  DIFFERENT campaign-optimization / rule-based-bidding API) on","  the same campaign — associating this kind of rule fails","  \"Campaign has performance based rule enabled…\" if the other","  kind is already attached. Pick ONE automation model per","  campaign."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{},"type":"array"},{"additionalProperties":true,"type":"object"}],"title":"Body","description":"one rule object, a list, or Amazon's {optimizationRules: [...]} envelope (all accepted) — v1 takes exactly ONE rule per call, v2 1–300."},"apiVersion":{"default":"v1","title":"Apiversion","type":"string","description":"v1 (default — BID+SCHEDULE only) | v2 (adds PERFORMANCE rules — ruleCategory TARGETING — and targeting[])."}},"required":["store","countryCode","body"],"title":"ads_sp_create_optimization_rulesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"failed":{"description":"[{index, optimizationRuleId, code, details}] for every item Amazon did not confirm. ALWAYS relay this verbatim."},"result":{"properties":{"code":{},"responses":{"items":{"properties":{"code":{},"details":{},"optimizationRule":{"properties":{"action":{"properties":{"actionDetails":{"properties":{"actionOperator":{},"actionUnit":{},"value":{}}},"actionType":{}}},"conditions":{"items":{"properties":{"attributeName":{},"criteria":{"anyOf":[{"properties":{"maxValue":{},"minValue":{}},"title":"OptimizationRulesAPISwaggerRangeTypeRuleCriteria"},{"properties":{"comparisonOperator":{},"value":{}},"title":"OptimizationRulesAPISwaggerValueTypeRuleCriteria"}]}}}},"optimizationRuleId":{},"recurrence":{"properties":{"daysOfWeek":{"items":{}},"duration":{"properties":{"endTime":{},"eventId":{},"eventName":{},"startTime":{}}},"timesOfDay":{"items":{"properties":{"endTime":{},"startTime":{}}}},"type":{}}},"ruleCategory":{},"ruleName":{},"ruleSubCategory":{},"status":{}}}}},"description":"per rule, optimizationRule.optimizationRuleId — pass it to ads_associate_optimization_rules_to_campaign."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_sp_update_optimization_rules":{"post":{"operationId":"ads_sp_update_optimization_rules","summary":"Update a Sponsored Products bid optimization rule — Amazon replaces the rule, it does not merge, so send the FULL rule object(s) including optimizationRuleId.","description":"Update a Sponsored Products bid optimization rule — Amazon replaces the rule, it does not merge, so send the FULL rule object(s) including optimizationRuleId. Read the current rule first with ads_search_optimization_rules. Amazon Ads API · UpdateOptimizationRules · PUT /sp/rules/optimization Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Optimization-Rules/operation/UpdateOptimizationRules Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_sp_update_optimization_rules"},"tags":["amazon_ads"],"x-title":"Ads SP Update Optimization Rules","x-access":"destructive","x-family":"ads.sp","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.failed","description":"[{index, optimizationRuleId, code, details}] for every item Amazon did not confirm. ALWAYS relay this verbatim."}],"x-notes":{"Body (Amazon schema; application/vnd.spoptimizationrules.v1+json): {optimizationRules":["[OptimizationRulesAPISwaggerOptimizationRule]} (1–25), each item:","  action*: {actionDetails*: {actionOperator*, actionUnit*, value*}, actionType*: ADOPT}","action.actionDetails.actionOperator: INCREMENT","action.actionDetails.actionUnit: PERCENT","conditions: [{attributeName: ROAS, criteria: {maxValue*, minValue*} | {comparisonOperator*, value*}}] (max 1)","conditions.criteria.comparisonOperator: EQUAL_TO | GREATER_THAN | GREATER_THAN_OR_EQUAL_TO | LESS_THAN | LESS_THAN_OR_EQUAL_TO","recurrence*: {daysOfWeek, duration*: {endTime, eventId, eventName, startTime}, timesOfDay: [{endTime*, startTime*}] (max 1), type*: DAILY | WEEKLY}","recurrence.daysOfWeek: [FRIDAY | MONDAY | SATURDAY | SUNDAY | THURSDAY | TUESDAY | WEDNESDAY]","ruleCategory*: BID","ruleName: string","ruleSubCategory*: SCHEDULE","status: ENABLED | ENDED | PAUSED | SCHEDULED","optimizationRuleId: string"],"Gotchas":["- To stop a rule, send status: PAUSED yourself — it is the only","  status Amazon honours as an off-switch. ARCHIVED and ENDED are","  refused before the call reaches Amazon (Amazon itself 400s","  ARCHIVED and silently reverts ENDED to SCHEDULED).","- A rule read back from ads_search_optimization_rules may carry","  a `recurrence` (on a TARGETING rule, which rejects it on","  write) or an empty v2 `targeting: []` (which 400s as \"size","  must be between 1 and 1\") — both are stripped automatically","  before the write, so a naive list -> edit -> update round","  trip does not fail.","- Changes take up to 24 hours to take effect; rules stack","  additively."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{},"type":"array"},{"additionalProperties":true,"type":"object"}],"title":"Body","description":"the FULL rule object(s) including optimizationRuleId — v1 1–25 rules per call, v2 1–300."},"apiVersion":{"default":"v1","title":"Apiversion","type":"string","description":"v1 (default) | v2 — must match the rule's own kind."}},"required":["store","countryCode","body"],"title":"ads_sp_update_optimization_rulesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"failed":{"description":"[{index, optimizationRuleId, code, details}] for every item Amazon did not confirm. ALWAYS relay this verbatim."},"result":{"properties":{"code":{},"responses":{"items":{"properties":{"code":{},"details":{},"optimizationRule":{"properties":{"action":{"properties":{"actionDetails":{"properties":{"actionOperator":{},"actionUnit":{},"value":{}}},"actionType":{}}},"conditions":{"items":{"properties":{"attributeName":{},"criteria":{"anyOf":[{"properties":{"maxValue":{},"minValue":{}},"title":"OptimizationRulesAPISwaggerRangeTypeRuleCriteria"},{"properties":{"comparisonOperator":{},"value":{}},"title":"OptimizationRulesAPISwaggerValueTypeRuleCriteria"}]}}}},"optimizationRuleId":{},"recurrence":{"properties":{"daysOfWeek":{"items":{}},"duration":{"properties":{"endTime":{},"eventId":{},"eventName":{},"startTime":{}}},"timesOfDay":{"items":{"properties":{"endTime":{},"startTime":{}}}},"type":{}}},"ruleCategory":{},"ruleName":{},"ruleSubCategory":{},"status":{}}}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_associate_optimization_rules_to_campaign":{"post":{"operationId":"ads_associate_optimization_rules_to_campaign","summary":"Attach Sponsored Products bid optimization rules to a campaign — a rule changes nothing until it is associated.","description":"Attach Sponsored Products bid optimization rules to a campaign — a rule changes nothing until it is associated. Amazon Ads API · AssociateOptimizationRulesToCampaign · POST /sp/campaigns/{campaignId}/optimizationRules Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Optimization-Rules/operation/AssociateOptimizationRulesToCampaign Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_associate_optimization_rules_to_campaign"},"tags":["amazon_ads"],"x-title":"Ads Associate Optimization Rules to Campaign","x-access":"destructive","x-family":"ads.sp","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.failed","description":"[{index, optimizationRuleId, code, details}] for every item Amazon did not confirm. ALWAYS relay this verbatim."}],"x-notes":{"Gotchas":["- A campaign that already carries a rule from","  ads_create_optimization_rule (the campaign-optimization /","  rule-based-bidding API) REFUSES association: \"Campaign has","  performance based rule enabled and therefore cannot associate","  an Intraday bidding rule or performance based rule.\" The two","  automation models are mutually exclusive per campaign — pick","  one and say which.","- Changes take up to 24 hours to take effect."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaignId":{"title":"Campaignid","type":"string","description":"the SP campaign the rules attach to."},"body":{"additionalProperties":true,"properties":{"optimizationRuleIds":{"items":{"type":"string"},"maxItems":25,"minItems":1,"type":"array"}},"required":["optimizationRuleIds"],"title":"Body","type":"object","description":"{optimizationRuleIds: [\"amzn1.ads-rule.m.xxx\"]}."},"apiVersion":{"default":"v1","title":"Apiversion","type":"string","description":"v1 (default) | v2."}},"required":["store","countryCode","campaignId","body"],"title":"ads_associate_optimization_rules_to_campaignArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"failed":{"description":"[{index, optimizationRuleId, code, details}] for every item Amazon did not confirm. ALWAYS relay this verbatim."},"result":{"properties":{"code":{},"responses":{"items":{"properties":{"code":{},"details":{},"optimizationRuleId":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_optimization_rule_eligibility":{"post":{"operationId":"ads_get_optimization_rule_eligibility","summary":"Sponsored Products: check which campaigns are eligible for rule-based bidding (a ROAS guardrail Amazon manages itself) before creating a rule with ads_create_optimization_rule — Am","description":"Sponsored Products: check which campaigns are eligible for rule-based bidding (a ROAS guardrail Amazon manages itself) before creating a rule with ads_create_optimization_rule — Amazon rejects ineligible campaigns. Amazon Ads API · GetOptimizationRuleEligibility · POST /sp/rules/campaignOptimization/eligibility Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Campaign-Optimization-Rules/operation/GetOptimizationRuleEligibility","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_optimization_rule_eligibility"},"tags":["amazon_ads"],"x-title":"Ads Get Optimization Rule Eligibility","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- Eligibility needs the campaign running >=10 DAYS, >=10","  CONVERSIONS in the last 30 days, and the marketplace's minimum","  daily budget. Use the returned roas as the create threshold","  rather than inventing one — it is derived from this","  campaign's own history.","- Response keys are lowerCamelCase, not the PascalCase Amazon's","  guide shows: campaignOptimizationRecommendations[{campaignId,","  performanceMetrics: {roas}}]. Per-campaign failures (e.g.","  LOW_BUDGET, NO_CONVERSIONS — one campaign can produce several","  at once) land in data.failed; an empty recommendations list","  with errors present means NOT eligible, whatever the HTTP","  status says."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"campaignIds":{"items":{"type":"string"},"maxItems":100,"type":"array"},"requirePerformanceMetrics":{"default":true,"type":"boolean"}},"required":["campaignIds"],"title":"Body","type":"object","description":"{campaignIds: [...] (max 100), requirePerformanceMetrics (default true — false also lists eligible campaigns with no roas yet; read performanceMetricsExists)}."}},"required":["store","countryCode","body"],"title":"ads_get_optimization_rule_eligibilityArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"CampaignOptimizationRecommendations":{"items":{"properties":{"campaignId":{},"performanceMetrics":{"properties":{"roas":{}}},"performanceMetricsExists":{}}}},"CampaignOptimizationRecommendationsError":{"items":{"properties":{"Error":{"properties":{"code":{},"details":{}}},"campaignId":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_rule_notification":{"post":{"operationId":"ads_get_rule_notification","summary":"Sponsored Products: the daily health-check for a rule-based-bidding rule — whether Amazon has silently disabled it.","description":"Sponsored Products: the daily health-check for a rule-based-bidding rule — whether Amazon has silently disabled it. Amazon Ads API · GetRuleNotification · POST /sp/rules/campaignOptimization/state Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Campaign-Optimization-Rules/operation/GetRuleNotification","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_rule_notification"},"tags":["amazon_ads"],"x-title":"Ads Get Rule Notification","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.campaignOptimizationNotifications[]","description":"{campaignId, campaignOptimizationId, ruleState (ENABLED or DISABLED), notificationString}."},{"field":"data.failed","description":"per-campaign errors."}],"x-notes":{"Gotchas":["- Amazon can disable the rule on its own: if the campaign's ROAS","  over the last 20 days falls below 30% of its ROAS over the","  20-to-40-day window, Amazon switches the rule off, restores","  the previous bidding strategy and target-level bids, and only","  notifies inside the Seller Central bell drawer — nothing is","  pushed to the API. Poll this at least once a day and tell the","  user when ruleState changes, or a dead rule looks alive.","- The guardrail is evaluated over the PREVIOUS 21 DAYS at","  campaign level — it is not an intraday control."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"campaignIds":{"items":{"type":"string"},"maxItems":100,"type":"array"}},"required":["campaignIds"],"title":"Body","type":"object","description":"{campaignIds: [...]} (max 100)."}},"required":["store","countryCode","body"],"title":"ads_get_rule_notificationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"CampaignOptimizationNotifications":{"items":{"properties":{"campaignId":{},"campaignOptimizationId":{},"notificationString":{},"ruleState":{}}}},"CampaignOptimizationRecommendationsError":{"items":{"properties":{"Error":{"properties":{"code":{},"details":{}}},"campaignId":{}}}},"campaignOptimizationNotifications":{"description":"{campaignId, campaignOptimizationId, ruleState (ENABLED or DISABLED), notificationString}."}}},"failed":{"description":"per-campaign errors."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_campaign_optimization_rule":{"post":{"operationId":"ads_get_campaign_optimization_rule","summary":"Sponsored Products: get one rule-based-bidding rule by its id.","description":"Sponsored Products: get one rule-based-bidding rule by its id. Amazon Ads API · GetCampaignOptimizationRule · GET /sp/rules/campaignOptimization/{campaignOptimizationId} Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Campaign-Optimization-Rules/operation/GetCampaignOptimizationRule","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_campaign_optimization_rule"},"tags":["amazon_ads"],"x-title":"Ads Get Campaign Optimization Rule","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaignOptimizationId":{"title":"Campaignoptimizationid","type":"string","description":"from ads_create_optimization_rule (data.result.campaignOptimizationId) or ads_get_rule_notification."}},"required":["store","countryCode","campaignOptimizationId"],"title":"ads_get_campaign_optimization_ruleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"CampaignOptimizationRule":{"properties":{"campaignIds":{"items":{}},"campaignOptimizationId":{},"createdDate":{},"recurrence":{},"ruleAction":{},"ruleCondition":{"items":{"properties":{"comparisonOperator":{},"metricName":{},"threshold":{}}}},"ruleName":{},"ruleStatus":{},"ruleType":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_optimization_rule":{"post":{"operationId":"ads_create_optimization_rule","summary":"Sponsored Products rule-based bidding — hand bid control to Amazon under a ROAS guardrail you declare; Amazon raises and lowers the campaign's base bids itself to increase conversi","description":"Sponsored Products rule-based bidding — hand bid control to Amazon under a ROAS guardrail you declare; Amazon raises and lowers the campaign's base bids itself to increase conversions while trying to hold it. This is NOT the same API as ads_sp_create_optimization_rules (which only applies fixed percentage increases on a schedule). Amazon Ads API · CreateOptimizationRule · POST /sp/rules/campaignOptimization Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Campaign-Optimization-Rules/operation/CreateOptimizationRule Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_optimization_rule"},"tags":["amazon_ads"],"x-title":"Ads Create Optimization Rule","x-access":"destructive","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.campaignOptimizationId","description":"the rule id that ads_get_campaign_optimization_rule, ads_update_optimization_rule and ads_delete_campaign_optimization_rule take."},{"field":"data.result.code / data.result.details","description":"whether Amazon created it."}],"x-notes":{"Gotchas":["- ALWAYS call ads_get_optimization_rule_eligibility first —","  Amazon rejects ineligible campaigns.","- ruleType only supports BID today: KEYWORD and PRODUCT are in","  the spec enum but Amazon answers \"Rule type is invalid. Only","  support BID as of now.\"","- A ROAS condition is MANDATORY — AVERAGE_BID is in the spec","  enum but Amazon answers \"Condition on ROAS is required, and","  AVERAGE_BID is not allowed.\"","- When metricName=ROAS, Amazon only actually supports","  GREATER_THAN and EQUAL_TO, despite the fuller comparisonOperator","  enum in the spec.","- Mutually exclusive with","  ads_associate_optimization_rules_to_campaign on the same","  campaign — associating a schedule/intraday bid rule fails once","  this kind is attached. Pick ONE automation model and say which","  one you picked."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"campaignIds":{"items":{"type":"string"},"maxItems":20,"type":"array"},"recurrence":{"enum":["DAILY"],"type":"string"},"ruleAction":{"enum":["ADOPT"],"type":"string"},"ruleCondition":{"items":{"additionalProperties":true,"properties":{"comparisonOperator":{"enum":["EQUAL_TO","GREATER_THAN","GREATER_THAN_OR_EQUAL_TO","LESS_THAN","LESS_THAN_OR_EQUAL_TO"],"type":"string"},"metricName":{"enum":["AVERAGE_BID","ROAS"],"type":"string"},"threshold":{"format":"double","type":"number"}},"required":["comparisonOperator","metricName","threshold"],"type":"object"},"maxItems":3,"type":"array"},"ruleName":{"maxLength":355,"type":"string"},"ruleType":{"enum":["BID","KEYWORD","PRODUCT"],"type":"string"}},"required":["campaignIds","recurrence","ruleAction","ruleType"],"title":"Body","type":"object","description":"{campaignIds (max 20, fewer than eligibility's 100 — split larger sets), ruleType: BID, ruleAction: ADOPT, recurrence: DAILY, ruleCondition: [{metricName, ...}]}. Use the roas returned by ads_get_optimization_rule_eligibility as the threshold rather than inventing one."}},"required":["store","countryCode","body"],"title":"ads_create_optimization_ruleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"campaignOptimizationId":{"description":"the rule id that ads_get_campaign_optimization_rule, ads_update_optimization_rule and ads_delete_campaign_optimization_rule take."},"code":{"description":"whether Amazon created it."},"details":{"description":"whether Amazon created it."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_optimization_rule":{"post":{"operationId":"ads_update_optimization_rule","summary":"Sponsored Products: update a rule-based-bidding rule — same shape as ads_create_optimization_rule plus campaignOptimizationId.","description":"Sponsored Products: update a rule-based-bidding rule — same shape as ads_create_optimization_rule plus campaignOptimizationId. Amazon Ads API · UpdateOptimizationRule · PUT /sp/rules/campaignOptimization Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Campaign-Optimization-Rules/operation/UpdateOptimizationRule Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_optimization_rule"},"tags":["amazon_ads"],"x-title":"Ads Update Optimization Rule","x-access":"destructive","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- Same field-enum quirks as ads_create_optimization_rule","  (ruleType only BID; ROAS condition mandatory; comparisonOperator","  effectively GREATER_THAN | EQUAL_TO for ROAS)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"campaignIds":{"items":{"type":"string"},"maxItems":20,"type":"array"},"campaignOptimizationId":{"maxLength":355,"type":"string"},"recurrence":{"enum":["DAILY"],"type":"string"},"ruleAction":{"enum":["ADOPT"],"type":"string"},"ruleCondition":{"items":{"additionalProperties":true,"properties":{"comparisonOperator":{"enum":["EQUAL_TO","GREATER_THAN","GREATER_THAN_OR_EQUAL_TO","LESS_THAN","LESS_THAN_OR_EQUAL_TO"],"type":"string"},"metricName":{"enum":["AVERAGE_BID","ROAS"],"type":"string"},"threshold":{"format":"double","type":"number"}},"required":["comparisonOperator","metricName","threshold"],"type":"object"},"maxItems":3,"type":"array"},"ruleName":{"maxLength":355,"type":"string"},"ruleType":{"enum":["BID","KEYWORD","PRODUCT"],"type":"string"}},"required":["campaignIds","campaignOptimizationId","recurrence","ruleAction","ruleType"],"title":"Body","type":"object","description":"the rule shape from ads_create_optimization_rule plus campaignOptimizationId."}},"required":["store","countryCode","body"],"title":"ads_update_optimization_ruleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"campaignOptimizationId":{},"code":{},"details":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_campaign_optimization_rule":{"post":{"operationId":"ads_delete_campaign_optimization_rule","summary":"Sponsored Products: delete a rule-based-bidding rule — unlike ads_sp_update_optimization_rules's API (which has no delete), this one really does support delete; the campaign return","description":"Sponsored Products: delete a rule-based-bidding rule — unlike ads_sp_update_optimization_rules's API (which has no delete), this one really does support delete; the campaign returns to its previous bidding. Amazon Ads API · DeleteCampaignOptimizationRule · DELETE /sp/rules/campaignOptimization/{campaignOptimizationId} Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Campaign-Optimization-Rules/operation/DeleteCampaignOptimizationRule Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_campaign_optimization_rule"},"tags":["amazon_ads"],"x-title":"Ads Delete Campaign Optimization Rule","x-access":"destructive","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaignOptimizationId":{"title":"Campaignoptimizationid","type":"string","description":"the rule to delete."}},"required":["store","countryCode","campaignOptimizationId"],"title":"ads_delete_campaign_optimization_ruleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"campaignOptimizationId":{},"code":{},"details":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_recommendations":{"post":{"operationId":"ads_list_recommendations","summary":"List Amazon-generated recommendations for SP, SB, SD and ST campaigns (budget, bid, bidding strategy, new keywords, new campaigns, …) — filter by AD_PRODUCT.","description":"List Amazon-generated recommendations for SP, SB, SD and ST campaigns (budget, bid, bidding strategy, new keywords, new campaigns, …) — filter by AD_PRODUCT. To accept some use ads_apply_recommendations; to modify one before accepting use ads_update_recommendation. Amazon Ads API · ListRecommendations · POST /recommendations/list","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_recommendations"},"tags":["amazon_ads"],"x-title":"Ads List Recommendations","x-access":"read","x-family":"ads.recommendations","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.recommendations[]","description":"max 500 per page, each with recommendationId, recommendationType, status, recommendedValue."},{"field":"data.result.nextToken / data.result.totalResults","description":"pass nextToken back as body.nextToken for the next page."}],"x-notes":{"Gotchas":["- This is NOT keyword suggestions — use","  ads_get_ranked_keyword_recommendation for those. Amazon","  generates these from campaign performance signals (e.g.","  \"increase budget\", \"enable suggested bid\", \"add suggested","  keywords\")."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"filters":{"items":{"additionalProperties":true,"properties":{"field":{"enum":["AD_PRODUCT","CAMPAIGN_ID","GROUPING_TYPE","RECOMMENDATION_ID","RECOMMENDATION_TYPE","STATUS"],"type":"string"},"include":{"default":true,"type":"boolean"},"operator":{"enum":["EXACT"],"type":"string"},"values":{"items":{"type":"string"},"maxItems":500,"minItems":1,"type":"array"}},"required":["field","operator","values"],"type":"object"},"maxItems":10,"minItems":1,"type":"array"},"locale":{"enum":["ar_AE","cs_CZ","de_DE","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es_CO","es_ES","es_MX","es_US","fr_CA","fr_FR","he_IL","hi_IN","it_IT","ja_JP","ko_KR","nl_NL","pl_PL","pt_BR","sv_SE","ta_IN","th_TH","tr_TR","vi_VN","zh_CN","zh_TW"],"type":"string"},"maxResults":{"default":500,"maximum":500,"minimum":1,"type":"integer"},"nextToken":{"type":"string"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional {filters: [{field, operator: EXACT, values}], maxResults, nextToken, locale} — e.g. {filters: [{field: 'AD_PRODUCT', operator: 'EXACT', values: ['SP']}]}."}},"required":["store","countryCode"],"title":"ads_list_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"nextToken":{"description":"pass nextToken back as body.nextToken for the next page."},"recommendations":{"items":{"description":"28 fields (adGroupId, adId, adProduct, applyFailureReason, asin, asinGroupTemplateId, …) — see the Docs link"},"description":"max 500 per page, each with recommendationId, recommendationType, status, recommendedValue."},"totalResults":{"description":"pass nextToken back as body.nextToken for the next page."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_apply_recommendations":{"post":{"operationId":"ads_apply_recommendations","summary":"Accept Amazon-generated Sponsored Products campaign recommendations — Amazon applies the proposed change to the campaign.","description":"Accept Amazon-generated Sponsored Products campaign recommendations — Amazon applies the proposed change to the campaign. Confirm with the user which ones to accept first. Amazon Ads API · ApplyRecommendations · POST /recommendations/apply Gate: approve, choice — interactive: show the change and the option (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change, within named rule (one option, no tie); otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_apply_recommendations"},"tags":["amazon_ads"],"x-title":"Ads Apply Recommendations","x-access":"destructive","x-family":"ads.recommendations","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.successes[] / data.result.failures[]","description":"one entry per id sent; read each failure's details."}],"x-notes":{"Gotchas":["- NEW_CAMPAIGN / NEW_VIDEO_CAMPAIGN recommendations are accepted","  asynchronously — confirm with ads_list_recommendations (STATUS","  APPLY_SUCCESS or APPLY_FAILED)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"recommendationIds":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["recommendationIds"],"title":"Body","type":"object","description":"{recommendationIds: [recommendationId, ...]} (1–100) — the recommendationIds from ads_list_recommendations."}},"required":["store","countryCode","body"],"title":"ads_apply_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"failures":{"items":{"properties":{"error":{"description":"2 fields (code, message) — see the Docs link"},"index":{},"recommendationId":{}}},"description":"one entry per id sent; read each failure's details."},"successes":{"items":{"properties":{"index":{},"recommendation":{"description":"28 fields (adGroupId, adId, adProduct, applyFailureReason, asin, asinGroupTemplateId, …) — see the Docs link"},"recommendationId":{},"success":{"description":"2 fields (code, message) — see the Docs link"}}},"description":"one entry per id sent; read each failure's details."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_recommendation":{"post":{"operationId":"ads_update_recommendation","summary":"Modify one Amazon-generated Sponsored Products campaign recommendation before accepting it.","description":"Modify one Amazon-generated Sponsored Products campaign recommendation before accepting it. Amazon Ads API · UpdateRecommendation · PUT /recommendations/{recommendationId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_recommendation"},"tags":["amazon_ads"],"x-title":"Ads Update Recommendation","x-access":"destructive","x-family":"ads.recommendations","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"recommendationId":{"title":"Recommendationid","type":"string","description":"the recommendation to modify — carried inside the request body as body.recommendationId."},"body":{"additionalProperties":true,"properties":{"budgetRule":{"additionalProperties":true,"properties":{"ruleDetails":{"additionalProperties":true,"properties":{"budgetIncreaseBy":{"additionalProperties":true,"properties":{"value":{"type":"number"}},"required":["value"],"type":"object"},"duration":{"additionalProperties":true,"properties":{"dateRangeTypeDuration":{"additionalProperties":true,"properties":{"endDate":{"format":"date","type":"string"}},"type":"object"}},"type":"object"},"performanceMeasureCondition":{"additionalProperties":true,"properties":{"threshold":{"type":"number"}},"required":["threshold"],"type":"object"},"ruleName":{"maxLength":355,"type":"string"}},"type":"object"}},"required":["ruleDetails"],"type":"object"},"recommendedValue":{"type":"string"},"ruleBasedBidding":{"additionalProperties":true,"properties":{"recommendedRuleRoas":{"type":"number"}},"required":["recommendedRuleRoas"],"type":"object"}},"title":"Body","type":"object","description":"one of recommendedValue (a string: a number for budgets and bids, YYYY-MM-DD for CAMPAIGN_END_DATE, ENABLED / PAUSED / ARCHIVED for the *_STATE types, a strategy name for CAMPAIGN_BIDDING_STRATEGY), budgetRule.ruleDetails, or ruleBasedBidding.recommendedRuleRoas — matching the recommendation's type."}},"required":["store","countryCode","recommendationId","body"],"title":"ads_update_recommendationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"adGroupId":{},"adId":{},"adProduct":{},"applyFailureReason":{},"asin":{},"asinGroupTemplateId":{},"budgetRecommendation":{"description":"1 fields (sevenDaysMissedOpportunities) — see the Docs link"},"budgetRule":{"description":"2 fields (ruleDetails, ruleId) — see the Docs link"},"campaignId":{},"campaignTemplateId":{},"consolidatedRecommendation":{"description":"2 fields (recommendationReasons, sevenDaysEstimatedOpportunities) — see the Docs link"},"currentValue":{},"estimatedImpact":{"description":"1 fields (campaign) — see the Docs link"},"groupingType":{},"keywordSortingDimension":{},"keywordSortingRank":{},"publishMetadata":{"description":"2 fields (publishedBy, publishedToAmazonAdConsole) — see the Docs link"},"recommendationContext":{"description":"2 fields (asinContext, diagnosticContext) — see the Docs link"},"recommendationId":{},"recommendationType":{},"recommendedValue":{},"resolvedTargeting":{},"ruleBasedBidding":{"description":"5 fields (campaignOptimizationId, currentBiddingStrategy, currentRuleRoas, recommendedBiddingStrategy, recommendedRuleRoas) — see the Docs link"},"sku":{},"status":{},"targetId":{},"targeting":{},"targetingMatchType":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_brands":{"post":{"operationId":"ads_get_brands","summary":"Sponsored Brands: list the brands registered under this advertiser profile — brandId, brandRegistryName and (sellers only) the brandEntityId the Store insights tools take (ads_get_","description":"Sponsored Brands: list the brands registered under this advertiser profile — brandId, brandRegistryName and (sellers only) the brandEntityId the Store insights tools take (ads_get_asin_engagement_for_store, ads_get_insights_for_store_api). Amazon Ads API · getBrands · GET /brands Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi#tag/Brands/operation/getBrands","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_brands"},"tags":["amazon_ads"],"x-title":"Ads Get Brands","x-access":"read","x-family":"ads.sb3","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result","description":"a list of {brandId, brandEntityId, brandRegistryName}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"brand_type_filter":{"anyOf":[{"enum":["brandRegistry","bookAuthor"],"type":"string"},{"type":"null"}],"default":null,"title":"Brand Type Filter","description":"keep one brand type; omit for every brand. Allowed: brandRegistry | bookAuthor."}},"required":["store","countryCode"],"title":"ads_get_brandsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"items":{"properties":{"brandEntityId":{},"brandId":{},"brandRegistryName":{}}},"description":"a list of {brandId, brandEntityId, brandRegistryName}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_dsp_advertisers":{"post":{"operationId":"ads_dsp_advertisers","summary":"List Amazon DSP advertisers accessible to this profile — the `advertiserId` a DSP report needs in its `filters` (e.g.","description":"List Amazon DSP advertisers accessible to this profile — the `advertiserId` a DSP report needs in its `filters` (e.g. {\"field\": \"advertiserId\", \"values\": [\"<id>\"]}). Amazon Ads API · GET /dsp/advertisers","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_dsp_advertisers"},"tags":["amazon_ads"],"x-title":"Ads DSP Advertisers","x-access":"read","x-family":"ads.dsp-advertiser","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Params (Amazon schema)":["startIndex: integer (max 29900)","count: integer (1–100) — max 100 advertisers per call","advertiserIdFilter: string"],"Gotchas":["- Requires an AGENCY-type ad profile. Seller/vendor profiles return","  400 \"Selected profile type is not agency\" — those accounts have","  no DSP advertiser seat, so DSP offline reports can't run for them."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"advertiserIdFilter":{"type":"string"},"count":{"default":100,"description":"max 100 advertisers per call","format":"int32","maximum":100,"minimum":1,"type":"integer"},"startIndex":{"default":0,"format":"int32","maximum":29900,"type":"integer"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional query params dict: {\"startIndex\": 0, \"count\": 100, \"advertiserIdFilter\": \"<id1>,<id2>\"}."}},"required":["store","countryCode"],"title":"ads_dsp_advertisersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"response":{"items":{"properties":{"advertiserId":{},"country":{},"currency":{},"isRegional":{},"name":{},"timezone":{},"url":{}}}},"totalResults":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_invoices":{"post":{"operationId":"ads_list_invoices","summary":"List Amazon Ads billing invoices — billing period (fromDate/toDate), amount due, status and the document types available in the advertising console (INVOICE, CREDIT_NOTE), per invo","description":"List Amazon Ads billing invoices — billing period (fromDate/toDate), amount due, status and the document types available in the advertising console (INVOICE, CREDIT_NOTE), per invoice. There is no download URL in the list. Amazon Ads API · getAdvertiserInvoices · GET /invoices Docs: https://advertising.amazon.com/API/docs/en-us/billing#tag/invoice/operation/getAdvertiserInvoices","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_invoices"},"tags":["amazon_ads"],"x-title":"Ads List Invoices","x-access":"read","x-family":"ads.billing","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.payload.invoiceSummaries[]","description":"{id, status, fromDate, toDate, amountDue, ...} — id goes to ads_get_invoice (Amazon wraps this answer in `payload`)."},{"field":"data.result.payload.nextCursor","description":"pass back as body.cursor."}],"x-notes":{"Params (Amazon schema)":["invoiceStatuses: ISSUED | PAID_IN_FULL | PAID_IN_PART | WRITTEN_OFF (list)","startDate: string","endDate: string","count: integer (0–100)","cursor: string"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"count":{"maximum":100,"minimum":0,"type":"integer"},"cursor":{"type":"string"},"endDate":{},"invoiceStatuses":{"items":{"enum":["ISSUED","PAID_IN_FULL","PAID_IN_PART","WRITTEN_OFF"],"type":"string"},"type":"array"},"startDate":{}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional query params — invoiceStatuses (a list of ISSUED, PAID_IN_PART, PAID_IN_FULL, WRITTEN_OFF), startDate / endDate (inclusive dates as YYYYMMDD — Amazon refuses dashes), count (max 100, default 10; not with cursor), cursor (the previous page's data.result.payload.nextCursor)."}},"required":["store","countryCode"],"title":"ads_list_invoicesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"invoiceSummaries":{"items":{"properties":{"amountDue":{"properties":{"amount":{},"currencyCode":{}}},"billingAggregation":{"properties":{"billingAggregationId":{},"billingAggregationResourcePath":{},"billingLevel":{}}},"downloadableDocuments":{"items":{}},"dueDate":{},"fees":{"items":{"properties":{"cost":{"properties":{"amount":{},"currencyCode":{}}},"feeIdentifiers":{"properties":{"countryCode":{}}},"feeType":{}}}},"fromDate":{},"id":{},"invoiceDate":{},"paymentMethod":{},"paymentTermsDays":{},"paymentTermsType":{},"purchaseOrderNumber":{},"remainingAmountDue":{"properties":{"amount":{},"currencyCode":{}}},"remainingFees":{"items":{"properties":{"cost":{"properties":{"amount":{},"currencyCode":{}}},"feeIdentifiers":{"properties":{"countryCode":{}}},"feeType":{}}}},"remainingTaxAmountDue":{"properties":{"amount":{},"currencyCode":{}}},"status":{},"taxAmountDue":{"properties":{"amount":{},"currencyCode":{}}},"taxRate":{},"toDate":{}}}},"nextCursor":{},"previousCursor":{},"payload":{"properties":{"invoiceSummaries":{"description":"{id, status, fromDate, toDate, amountDue, ...} — id goes to ads_get_invoice (Amazon wraps this answer in `payload`)."},"nextCursor":{"description":"pass back as body.cursor."}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_invoice":{"post":{"operationId":"ads_get_invoice","summary":"Get one Amazon Ads invoice by id — invoice lines, payments, adjustments and tax detail.","description":"Get one Amazon Ads invoice by id — invoice lines, payments, adjustments and tax detail. A presigned PDF/XML link exists only on a government invoice (governmentInvoiceInformation.governmentDocumentS3Link). Amazon Ads API · getInvoice · GET /invoices/{invoiceId} Docs: https://advertising.amazon.com/API/docs/en-us/billing#tag/invoice/operation/getInvoice","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_invoice"},"tags":["amazon_ads"],"x-title":"Ads Get Invoice","x-access":"read","x-family":"ads.billing","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"invoiceId":{"title":"Invoiceid","type":"string","description":"data.result.payload.invoiceSummaries[].id from ads_list_invoices."}},"required":["store","countryCode","invoiceId"],"title":"ads_get_invoiceArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"adjustments":{"items":{"description":"5 fields (accountingDate, amount, comments, fees, portfolioId) — see the Docs link"}},"governmentInvoiceInformation":{"description":"5 fields (countryCode, governmentDocumentS3Link, governmentInvoiceId, governmentXmlDocumentS3Link, transactionType) — see the Docs link"},"invoiceLines":{"items":{"description":"18 fields (campaignId, campaignName, campaignTags, commissionAmount, commissionRate, cost, …) — see the Docs link"}},"invoiceSummary":{"description":"19 fields (amountDue, billingAggregation, downloadableDocuments, dueDate, fees, fromDate, …) — see the Docs link"},"issuerContactInfo":{"description":"2 fields (address, email) — see the Docs link"},"payerContactInfo":{"description":"2 fields (address, email) — see the Docs link"},"payments":{"items":{"description":"9 fields (amount, currentPaymentAttemptDate, id, lastPaymentAttemptDate, nextPaymentAttemptDate, paymentMethod, …) — see the Docs link"}},"portfolios":{"items":{"description":"4 fields (feeAmount, id, name, totalAmount) — see the Docs link"}},"promotions":{"items":{"description":"3 fields (amount, description, lastConsumedDate) — see the Docs link"}},"taxDetail":{"description":"3 fields (permanentAccountNumber, taxBreakups, taxCalculationDate) — see the Docs link"},"thirdPartyContactInfo":{"items":{"description":"2 fields (address, email) — see the Docs link"}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_localized_currencies":{"post":{"operationId":"ads_get_localized_currencies","summary":"Convert amounts to a target marketplace's local currency — use before creating campaigns in a different marketplace than the store's primary one.","description":"Convert amounts to a target marketplace's local currency — use before creating campaigns in a different marketplace than the store's primary one. Amazon Ads API · getLocalizedCurrencies · POST /currencies/localize Docs: https://advertising.amazon.com/API/docs/en-us/localization#tag/Currency-Localization/operation/getLocalizedCurrencies","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_localized_currencies"},"tags":["amazon_ads"],"x-title":"Ads Get Localized Currencies","x-access":"read","x-family":"ads.localization","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"localizeCurrencyRequests":{"items":{"additionalProperties":true,"properties":{"currency":{"additionalProperties":true,"properties":{"amount":{"type":"number"}},"required":["amount"],"type":"object"},"currencyCode":{"enum":["USD"],"type":"string"}},"required":["currency"],"type":"object"},"maxItems":1000,"minItems":1,"type":"array"},"sourceCountryCode":{"type":"string"},"sourceMarketplaceId":{"type":"string"},"targetCountryCodes":{"items":{"type":"string"},"maxItems":10,"minItems":0,"type":"array"},"targetMarketplaces":{"items":{"type":"string"},"maxItems":10,"minItems":0,"type":"array"}},"required":["localizeCurrencyRequests"],"title":"Body","type":"object","description":"{localizeCurrencyRequests: [{currency: {amount}}], sourceCountryCode, sourceMarketplaceId, targetCountryCodes: [...]}."}},"required":["store","countryCode","body"],"title":"ads_get_localized_currenciesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"localizedCurrencyResponses":{"items":{"properties":{"errorCode":{},"localizedCurrencies":{},"status":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_localized_products":{"post":{"operationId":"ads_get_localized_products","summary":"Map products (ASIN or SKU) from the source marketplace to their equivalents in up to 10 target marketplaces — Sponsored Products only.","description":"Map products (ASIN or SKU) from the source marketplace to their equivalents in up to 10 target marketplaces — Sponsored Products only. A target fails when no matching product exists there or the advertiser cannot advertise it. Amazon Ads API · getLocalizedProducts · POST /products/localize Docs: https://advertising.amazon.com/API/docs/en-us/localization#tag/Product-Localization/operation/getLocalizedProducts","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_localized_products"},"tags":["amazon_ads"],"x-title":"Ads Get Localized Products","x-access":"read","x-family":"ads.localization","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adType":{"enum":["SPONSORED_PRODUCTS"],"type":"string"},"entityType":{"enum":["KDP_AUTHOR","SELLER","VENDOR"],"type":"string"},"localizeProductRequests":{"items":{"additionalProperties":true,"properties":{"product":{"additionalProperties":true,"properties":{"asin":{"type":"string"},"sku":{"type":"string"}},"type":"object"}},"required":["product"],"type":"object"},"maxItems":1000,"minItems":1,"type":"array"},"sourceAdvertiserId":{"type":"string"},"sourceCountryCode":{"type":"string"},"sourceMarketplaceId":{"type":"string"},"targetDetails":{"items":{"additionalProperties":true,"properties":{"advertiserId":{"type":"string"},"countryCode":{"type":"string"},"marketplaceId":{"type":"string"}},"required":["advertiserId"],"type":"object"},"maxItems":10,"minItems":1,"type":"array"}},"required":["adType","entityType","localizeProductRequests","sourceAdvertiserId","targetDetails"],"title":"Body","type":"object","description":"{adType, entityType, sourceAdvertiserId, sourceCountryCode, targetDetails: [{countryCode, marketplaceId, advertiserId}] (advertiserId required on each), localizeProductRequests: [{product: {asin | sku}}]}."}},"required":["store","countryCode","body"],"title":"ads_get_localized_productsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"localizedProductResponses":{"items":{"properties":{"errorCode":{},"localizedProducts":{},"status":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_localized_keywords":{"post":{"operationId":"ads_get_localized_keywords","summary":"Translate keyword targeting between marketplaces.","description":"Translate keyword targeting between marketplaces. Amazon Ads API · getLocalizedKeywords · POST /keywords/localize Docs: https://advertising.amazon.com/API/docs/en-us/localization#tag/Keyword-Localization/operation/getLocalizedKeywords","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_localized_keywords"},"tags":["amazon_ads"],"x-title":"Ads Get Localized Keywords","x-access":"read","x-family":"ads.localization","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"localizeKeywordRequests":{"items":{"additionalProperties":true,"properties":{"localizationKeyword":{"additionalProperties":true,"type":"object"}},"required":["localizationKeyword"],"type":"object"},"maxItems":1000,"minItems":1,"type":"array"},"sourceDetails":{"additionalProperties":true,"properties":{"countryCode":{"type":"string"},"locale":{"type":"string"},"marketplaceId":{"type":"string"}},"type":"object"},"targetDetails":{"additionalProperties":true,"properties":{"countryCodes":{"items":{"type":"string"},"maxItems":10,"minItems":0,"type":"array"},"locales":{"items":{"type":"string"},"maxItems":10,"minItems":0,"type":"array"},"marketplaceIds":{"items":{"type":"string"},"maxItems":10,"minItems":0,"type":"array"}},"type":"object"}},"required":["localizeKeywordRequests","targetDetails"],"title":"Body","type":"object","description":"{localizeKeywordRequests: [{localizationKeyword: {keyword}}], sourceDetails: {countryCode | marketplaceId | locale}, targetDetails: {countryCodes | marketplaceIds | locales: [...]}} — targetDetails is ONE object of lists, not a list of objects."}},"required":["store","countryCode","body"],"title":"ads_get_localized_keywordsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"localizedKeywordResponses":{"items":{"properties":{"errorCode":{},"localizedKeywords":{},"status":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_localized_targeting_expression":{"post":{"operationId":"ads_get_localized_targeting_expression","summary":"Translate targeting expressions between marketplaces.","description":"Translate targeting expressions between marketplaces. Amazon Ads API · getLocalizedTargetingExpression · POST /targetingExpression/localize Docs: https://advertising.amazon.com/API/docs/en-us/localization#tag/Targeting-Expression-Localization/operation/getLocalizedTargetingExpression","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_localized_targeting_expression"},"tags":["amazon_ads"],"x-title":"Ads Get Localized Targeting Expression","x-access":"read","x-family":"ads.localization","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"requests":{"items":{"additionalProperties":true,"properties":{"targetingExpression":{"additionalProperties":true,"properties":{"expression":{"items":{"additionalProperties":true,"properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"],"type":"object"},"maxItems":100,"minItems":1,"type":"array"},"isForNegativeTargeting":{"type":"boolean"}},"required":["expression","isForNegativeTargeting"],"type":"object"}},"required":["targetingExpression"],"type":"object"},"maxItems":100,"minItems":1,"type":"array"},"sourceDetails":{"additionalProperties":true,"properties":{"countryCode":{"type":"string"},"marketplaceId":{"type":"string"}},"type":"object"},"sourceResolvedTargetingExpressionLocales":{"items":{"type":"string"},"maxItems":10,"minItems":0,"type":"array"},"targetDetailsList":{"items":{"additionalProperties":true,"properties":{"countryCode":{"type":"string"},"marketplaceId":{"type":"string"}},"type":"object"},"maxItems":10,"minItems":1,"type":"array"},"targetResolvedTargetingExpressionLocale":{"type":"string"}},"required":["requests","sourceDetails","targetDetailsList"],"title":"Body","type":"object","description":"{requests: [{targetingExpression: {expression: [{type, value}], isForNegativeTargeting: true|false}}], sourceDetails: {countryCode | marketplaceId}, targetDetailsList: [{countryCode | marketplaceId}]}."}},"required":["store","countryCode","body"],"title":"ads_get_localized_targeting_expressionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"responses":{"items":{"properties":{"localizedTargetingExpressionResults":{},"localizedTargetingExpressions":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_product_metadata":{"post":{"operationId":"ads_product_metadata","summary":"Get SP product metadata for ASINs or SKUs — title, brand, category, image and advertising eligibility, to check before creating product ads.","description":"Get SP product metadata for ASINs or SKUs — title, brand, category, image and advertising eligibility, to check before creating product ads. Amazon Ads API · ProductMetadata · POST /product/metadata Docs: https://advertising.amazon.com/API/docs/en-us/product-metadata#tag/Product-Selector/operation/ProductMetadata","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_product_metadata"},"tags":["amazon_ads"],"x-title":"Ads Product Metadata","x-access":"read","x-family":"ads.product-selector","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- data.result is an OBJECT, not a list — rows are under","  data.result.ProductMetadataList."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"adType":{"enum":["SB","SD","SP"],"type":"string"},"asins":{"items":{"maxLength":10,"minLength":10,"type":"string"},"maxItems":300,"minItems":0,"type":"array"},"checkEligibility":{"default":false,"type":"boolean"},"checkItemDetails":{"default":false,"type":"boolean"},"cursorToken":{"type":"string"},"isGlobalStoreSelection":{"default":false,"type":"boolean"},"locale":{"type":"string"},"pageIndex":{"format":"int32","minimum":0,"type":"integer"},"pageSize":{"format":"int32","maximum":300,"minimum":1,"type":"integer"},"searchStr":{"maxLength":200,"type":"string"},"skus":{"items":{"type":"string"},"maxItems":300,"minItems":0,"type":"array"},"sortBy":{"enum":["CREATED_DATE","SUGGESTED"],"type":"string"},"sortOrder":{"default":"DESC","enum":["ASC","DESC"],"type":"string"}},"required":["pageIndex","pageSize"],"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"ONE of asins / skus / searchStr (max 300 ids; skus work for SP sellers only), adType (required when checkEligibility is true), checkItemDetails / checkEligibility optional bools. Amazon requires pageIndex and pageSize; the server fills 0 and 100 when omitted — pass pageSize up to 300, or page with pageIndex, for more than 100 items."}},"required":["store","countryCode"],"title":"ads_product_metadataArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"ProductMetadataList":{"items":{"properties":{"asin":{},"availability":{},"basisPrice":{"properties":{"amount":{},"currency":{}}},"bestSellerRank":{},"brand":{},"category":{},"createdDate":{},"eligibilityStatus":{},"globalStoreSetting":{"properties":{"catalogSourceCountryCode":{}}},"imageUrl":{},"ineligibilityCodes":{"items":{}},"ineligibilityReasons":{"items":{}},"priceToPay":{"properties":{"amount":{},"currency":{}}},"sku":{},"title":{},"variationList":{"items":{}}}}},"cursorToken":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_asin_engagement_for_store":{"post":{"operationId":"ads_get_asin_engagement_for_store","summary":"Per-ASIN engagement on a brand's Store pages (renders, views, clicks, add-to-carts, orders, in-stock rate), or a store-level TOTAL_VIEWS / TOTAL_CLICKS row.","description":"Per-ASIN engagement on a brand's Store pages (renders, views, clicks, add-to-carts, orders, in-stock rate), or a store-level TOTAL_VIEWS / TOTAL_CLICKS row. For page / date / traffic-source traffic and sales use ads_get_insights_for_store_api. Amazon Ads API · getAsinEngagementForStore · POST /stores/{brandEntityId}/asinMetrics Docs: https://advertising.amazon.com/API/docs/en-us/stores/open-api#tag/Stores-Analytics/operation/getAsinEngagementForStore","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_asin_engagement_for_store"},"tags":["amazon_ads"],"x-title":"Ads Get ASIN Engagement for Store","x-access":"read","x-family":"ads.stores","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.metricsDetails[]","description":"one map per ASIN (max 1500), keyed by the requested metrics."}],"x-notes":{"Gotchas":["- A store-aggregate call (dimension omitted) accepts ONLY","  TOTAL_VIEWS and TOTAL_CLICKS — every other metric needs","  dimension='ASIN'. sortBy is valid only when dimension='ASIN'.","- Amazon returns 400 \"Invalid request body\" when the brand has no","  published Store page."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"brandEntityId":{"title":"Brandentityid","type":"string","description":"from ads_get_brands."},"body":{"additionalProperties":true,"properties":{"dimension":{"enum":["ASIN"],"type":"string"},"endDate":{"format":"date","type":"string"},"metrics":{"items":{"enum":["ADD_TO_CARTS","AVERAGE_IN_STOCK_PRICE","AVERAGE_SALE_PRICE","CLICKS","CLICK_RATE","CONVERSION_RATE","IN_STOCK_RATE","IN_STOCK_VIEWS","ORDERS","RENDERS","TOTAL_CLICKS","TOTAL_VIEWS","UNITS","VIEWS"],"type":"string"},"maxItems":12,"minItems":0,"type":"array"},"orderBy":{"enum":["ASC","DESC"],"type":"string"},"sortBy":{},"startDate":{"format":"date","type":"string"}},"required":["endDate","metrics","startDate"],"title":"Body","type":"object","description":"{startDate, endDate, metrics: [...]}; dimension='ASIN' for per-ASIN rows, omitted for a store-aggregate row; optional orderBy / sortBy."}},"required":["store","countryCode","brandEntityId","body"],"title":"ads_get_asin_engagement_for_storeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"dimension":{},"metricsDetails":{"items":{},"description":"one map per ASIN (max 1500), keyed by the requested metrics."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_insights_for_store_api":{"post":{"operationId":"ads_get_insights_for_store_api","summary":"Store traffic / sales / dwell / bounce insights for a brand's Store page.","description":"Store traffic / sales / dwell / bounce insights for a brand's Store page. Amazon Ads API · getInsightsForStoreAPI · POST /stores/{brandEntityId}/insights Docs: https://advertising.amazon.com/API/docs/en-us/stores/open-api#tag/Stores-Analytics/operation/getInsightsForStoreAPI","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_insights_for_store_api"},"tags":["amazon_ads"],"x-title":"Ads Get Insights for Store API","x-access":"read","x-family":"ads.stores","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.metricsDetails[]","description":"one map per dimension value (max 1500)."},{"field":"data.result.paginationToken","description":"pass back as body.paginationToken with the SAME request body, within 24 h."}],"x-notes":{"Gotchas":["- The metric allowlist depends on dimension: DATE/PAGE/SOURCE/TAG","  take the traffic metrics (VIEWS, ORDERS, UNITS, SALES, VISITS,","  DWELL_TIME, BOUNCE_RATE, ...); STORE takes only DWELL_TIME,","  BOUNCE_RATE, NEW_TO_STORE. Non-SQS metrics: exactly ONE per call;","  SQS (Store-Quality) metrics may be combined freely.","- filter accepts pageIds, sources, tags, but sources+tags together","  are not supported.","- language is SQS-only (default 'en'), e.g. 'fr-FR', 'de-DE',","  'ja-JP', 'zh-CN', 'ar-AE', 'en-GB'."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"brandEntityId":{"title":"Brandentityid","type":"string","description":"from ads_get_brands."},"body":{"additionalProperties":true,"properties":{"dimension":{"enum":["DATE","PAGE","SOURCE","STORE","TAG"],"type":"string"},"endDate":{"format":"date","type":"string"},"filter":{"additionalProperties":true,"properties":{"pageIds":{"items":{"type":"string"},"maxItems":200,"minItems":0,"type":"array"},"sources":{"items":{"enum":["ADS","ORGANIC","OTHER"],"type":"string"},"maxItems":200,"minItems":0,"type":"array"},"tags":{"items":{"type":"string"},"maxItems":200,"minItems":0,"type":"array"}},"type":"object"},"language":{"type":"string"},"maxResult":{"maximum":1500,"minimum":1,"type":"integer"},"metrics":{"items":{"enum":["ACTIONS_TAKEN_BY_PEERS","BOUNCE_RATE","COMPLETED_RECOMMENDATIONS","CONTRIBUTORS","DWELL","DWELL_TIME","NEW_TO_STORE","ORDERS","PEER_DWELL","PEER_SALES_LAST_60_DAYS","RECOMMENDATIONS","SALES","SALES_LAST_60_DAYS","SCORE_LEVEL","UNITS","VIDEO_10S_PLAYED","VIDEO_25P_PLAYED","VIDEO_50P_PLAYED","VIDEO_75P_PLAYED","VIDEO_COMPLETED","VIDEO_STARTED","VIEWS","VISITORS","VISITS"],"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"paginationToken":{"type":"string"},"startDate":{"format":"date","type":"string"}},"required":["dimension","endDate","metrics","startDate"],"title":"Body","type":"object","description":"{dimension: DATE|PAGE|SOURCE|TAG|STORE, startDate, endDate, metrics: [...]}; optional filter {pageIds, sources, tags}, maxResult (1-1500), paginationToken, language."}},"required":["store","countryCode","brandEntityId","body"],"title":"ads_get_insights_for_store_apiArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"dimension":{},"filter":{"properties":{"pageIds":{"items":{}},"sources":{"items":{}},"tags":{"items":{}}}},"metricsDetails":{"items":{},"description":"one map per dimension value (max 1500)."},"paginationToken":{"description":"pass back as body.paginationToken with the SAME request body, within 24 h."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_assets":{"post":{"operationId":"ads_list_assets","summary":"Sponsored Brands: list a brand's Stores asset library — logos, images, lifestyle imagery, video — every asset tied to the supplied entity id.","description":"Sponsored Brands: list a brand's Stores asset library — logos, images, lifestyle imagery, video — every asset tied to the supplied entity id. Amazon Ads API · listAssets · GET /stores/assets Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi#tag/Stores/operation/listAssets","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_assets"},"tags":["amazon_ads"],"x-title":"Ads List Assets","x-access":"read","x-family":"ads.sb3","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"brandEntityId":{"title":"Brandentityid","type":"string","description":"the entityId from ads_list_ads_accounts (data.result.adsAccounts[].alternateIds[].entityId for this country) — NOT the brandEntityId from ads_get_brands, which typically returns empty here although Amazon's spec names it."},"mediaType":{"anyOf":[{"enum":["brandLogo","image"],"type":"string"},{"type":"null"}],"default":null,"title":"Mediatype","description":"optional filter; in practice Amazon only accepts 'brandLogo' (every other value, including 'image' from its own schema, 400s \"MediaType X is not supported\"). Omit it and filter client-side for the complete asset list."}},"required":["store","countryCode","brandEntityId"],"title":"ads_list_assetsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"items":{"properties":{"assetID":{},"mediaType":{},"name":{},"url":{}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_stream_subscriptions":{"post":{"operationId":"ads_list_stream_subscriptions","summary":"List Amazon Ads event stream subscriptions — real-time notifications of campaign state changes, budget events, etc.","description":"List Amazon Ads event stream subscriptions — real-time notifications of campaign state changes, budget events, etc. Most accounts have an empty list; this is normal unless streaming was explicitly configured. Amazon Ads API · ListStreamSubscriptions · GET /streams/subscriptions Docs: https://advertising.amazon.com/API/docs/en-us/amazon-marketing-stream/openapi#tag/Stream-Subscription/operation/ListStreamSubscriptions","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_stream_subscriptions"},"tags":["amazon_ads"],"x-title":"Ads List Stream Subscriptions","x-access":"read","x-family":"ads.marketing-stream","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.subscriptions","description":"the page."},{"field":"data.result.nextToken","description":"present when more remain — pass it as starting_token."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"max_results":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Results","description":"subscriptions per page; omit for Amazon's default."},"starting_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Starting Token","description":"the cursor from the previous call's data.result.nextToken; omit for the first page."}},"required":["store","countryCode"],"title":"ads_list_stream_subscriptionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"nextToken":{"description":"present when more remain — pass it as starting_token."},"subscriptions":{"items":{"properties":{"createdDate":{},"dataSetId":{},"destination":{"properties":{"firehoseDestination":{"properties":{"deliveryStreamArn":{},"subscriberRoleArn":{},"subscriptionRoleArn":{}}},"sqsDestination":{"properties":{"queueArn":{}}}}},"destinationArn":{},"notes":{},"status":{},"subscriptionId":{},"updatedDate":{}}},"description":"the page."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_stream_subscription":{"post":{"operationId":"ads_get_stream_subscription","summary":"Get one Amazon Ads event stream subscription by id.","description":"Get one Amazon Ads event stream subscription by id. Amazon Ads API · GetStreamSubscription · GET /streams/subscriptions/{subscriptionId} Docs: https://advertising.amazon.com/API/docs/en-us/amazon-marketing-stream/openapi#tag/Stream-Subscription/operation/GetStreamSubscription","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_stream_subscription"},"tags":["amazon_ads"],"x-title":"Ads Get Stream Subscription","x-access":"read","x-family":"ads.marketing-stream","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"subscriptionId":{"maxLength":255,"title":"Subscriptionid","type":"string","description":"from ads_list_stream_subscriptions."}},"required":["store","countryCode","subscriptionId"],"title":"ads_get_stream_subscriptionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"subscription":{"properties":{"createdDate":{},"dataSetId":{},"destination":{"properties":{"firehoseDestination":{"properties":{"deliveryStreamArn":{},"subscriberRoleArn":{},"subscriptionRoleArn":{}}},"sqsDestination":{"properties":{"queueArn":{}}}}},"destinationArn":{},"notes":{},"status":{},"subscriptionId":{},"updatedDate":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_stream_subscription":{"post":{"operationId":"ads_create_stream_subscription","summary":"Create an Amazon Marketing Stream subscription: Amazon pushes one dataset (dataSetId, from Amazon's Marketing Stream data guide) to an AWS SQS queue or Firehose stream the seller o","description":"Create an Amazon Marketing Stream subscription: Amazon pushes one dataset (dataSetId, from Amazon's Marketing Stream data guide) to an AWS SQS queue or Firehose stream the seller owns (destination ARN). Only for a seller who already runs that AWS endpoint; read the new subscription's status with ads_get_stream_subscription. Amazon Ads API · CreateStreamSubscription · POST /streams/subscriptions Docs: https://advertising.amazon.com/API/docs/en-us/amazon-marketing-stream/openapi#tag/Stream-Subscription/operation/CreateStreamSubscription Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_stream_subscription"},"tags":["amazon_ads"],"x-title":"Ads Create Stream Subscription","x-access":"write","x-family":"ads.marketing-stream","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.subscriptionId","description":"for ads_get_stream_subscription / ads_update_stream_subscription."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"clientRequestToken":{"maxLength":36,"minLength":22,"type":"string"},"dataSetId":{"type":"string"},"destination":{"additionalProperties":true,"properties":{"firehoseDestination":{"additionalProperties":true,"properties":{"deliveryStreamArn":{"maxLength":255,"type":"string"},"subscriberRoleArn":{"maxLength":255,"type":"string"},"subscriptionRoleArn":{"maxLength":255,"type":"string"}},"required":["deliveryStreamArn","subscriberRoleArn","subscriptionRoleArn"],"type":"object"},"sqsDestination":{"additionalProperties":true,"properties":{"queueArn":{"maxLength":255,"type":"string"}},"required":["queueArn"],"type":"object"}},"type":"object"},"destinationArn":{"maxLength":2048,"minLength":20,"type":"string"},"notes":{"maxLength":128,"type":"string"}},"required":["clientRequestToken","dataSetId"],"title":"Body","type":"object","description":"the request body — its fields, enums and required marks are in this parameter's schema."}},"required":["store","countryCode","body"],"title":"ads_create_stream_subscriptionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"clientRequestToken":{},"subscriptionId":{"description":"for ads_get_stream_subscription / ads_update_stream_subscription."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_stream_subscription":{"post":{"operationId":"ads_update_stream_subscription","summary":"Archive an Amazon Ads event stream subscription — Amazon has no enable/disable for this resource, only ARCHIVED.","description":"Archive an Amazon Ads event stream subscription — Amazon has no enable/disable for this resource, only ARCHIVED. Amazon Ads API · UpdateStreamSubscription · PUT /streams/subscriptions/{subscriptionId} Docs: https://advertising.amazon.com/API/docs/en-us/amazon-marketing-stream/openapi#tag/Stream-Subscription/operation/UpdateStreamSubscription Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_stream_subscription"},"tags":["amazon_ads"],"x-title":"Ads Update Stream Subscription","x-access":"destructive","x-family":"ads.marketing-stream","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"subscriptionId":{"maxLength":255,"title":"Subscriptionid","type":"string","description":"the subscription to archive."},"body":{"additionalProperties":true,"properties":{"notes":{"maxLength":128,"type":"string"},"status":{"enum":["ARCHIVED"],"type":"string"}},"title":"Body","type":"object","description":"the request body — its fields, enums and required marks are in this parameter's schema."}},"required":["store","countryCode","subscriptionId","body"],"title":"ads_update_stream_subscriptionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_campaigns_validation_configs":{"post":{"operationId":"ads_get_campaigns_validation_configs","summary":"Validation rules Amazon enforces on campaign create/update — allowed values, ranges, and required fields, before building a payload.","description":"Validation rules Amazon enforces on campaign create/update — allowed values, ranges, and required fields, before building a payload. Amazon Ads API · getCampaignsValidationConfigs · POST /validationConfigurations/campaigns Docs: https://advertising.amazon.com/API/docs/en-us/validation-configuration#tag/Validation-Configurations-Retrieval/operation/getCampaignsValidationConfigs","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_campaigns_validation_configs"},"tags":["amazon_ads"],"x-title":"Ads Get Campaigns Validation Configs","x-access":"read","x-family":"ads.validation-configurations","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- The payload is large (~200KB+) — filter to the relevant section","  before writing it anywhere."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"countryCodesList":{"items":{"enum":["AE","AU","BE","BR","CA","CN","DE","EG","ES","FR","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","UK","US","ZA"],"type":"string"},"maxItems":5,"minItems":1,"type":"array"},"entityTypesList":{"items":{"enum":["SELLER","VENDOR"],"type":"string"},"maxItems":2,"minItems":1,"type":"array"},"programTypesList":{"items":{"enum":["SB","SD","SP"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional context — countryCodesList (Amazon's codes: 'UK', not 'GB'), entityTypesList, programTypesList (see Body). Pass all three to get one context instead of the whole set; the answer is under data.result.campaignValidationConfigs."}},"required":["store","countryCode"],"title":"ads_get_campaigns_validation_configsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"campaignValidationConfigs":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_targeting_clauses_validation_configs":{"post":{"operationId":"ads_get_targeting_clauses_validation_configs","summary":"Validation rules Amazon enforces on targeting-clause create — allowed expression types, ASIN/category id formats, bid constraints.","description":"Validation rules Amazon enforces on targeting-clause create — allowed expression types, ASIN/category id formats, bid constraints. Amazon Ads API · getTargetingClausesValidationConfigs · POST /validationConfigurations/targetingClauses Docs: https://advertising.amazon.com/API/docs/en-us/validation-configuration#tag/Validation-Configurations-Retrieval/operation/getTargetingClausesValidationConfigs","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_targeting_clauses_validation_configs"},"tags":["amazon_ads"],"x-title":"Ads Get Targeting Clauses Validation Configs","x-access":"read","x-family":"ads.validation-configurations","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- The payload is large (~200KB+) — filter to the relevant section","  before writing it anywhere."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"countryCodesList":{"items":{"enum":["AE","AU","BE","BR","CA","CN","DE","EG","ES","FR","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","UK","US","ZA"],"type":"string"},"maxItems":5,"minItems":1,"type":"array"},"entityTypesList":{"items":{"enum":["SELLER","VENDOR"],"type":"string"},"maxItems":2,"minItems":1,"type":"array"},"programTypesList":{"items":{"enum":["SB","SD","SP"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional context — countryCodesList (Amazon's codes: 'UK', not 'GB'), entityTypesList, programTypesList (see Body). Pass all three to get one context instead of the whole set; the answer is under data.result.targetingClausesValidationConfigs."}},"required":["store","countryCode"],"title":"ads_get_targeting_clauses_validation_configsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"targetingClausesValidationConfigs":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_ads_accounts":{"post":{"operationId":"ads_list_ads_accounts","summary":"List the Amazon Ads accounts linked to this store's Ads credentials, each with its per-country profileId and entityId.","description":"List the Amazon Ads accounts linked to this store's Ads credentials, each with its per-country profileId and entityId. Amazon Ads API · ListAdsAccounts · POST /adsAccounts/list Docs: https://advertising.amazon.com/API/docs/en-us/account-management#tag/Account/operation/ListAdsAccounts","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_ads_accounts"},"tags":["amazon_ads"],"x-title":"Ads List Ads Accounts","x-access":"read","x-family":"ads.accounts","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.adsAccounts[]","description":"{adsAccountId, accountName, status, countryCodes, alternateIds[{countryCode, entityId, profileId}]}."},{"field":"data.result.nextToken","description":"pass back as body.nextToken."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"maxResults":{"default":100.0,"maximum":100,"minimum":1,"type":"number"},"nextToken":{"type":"string"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"optional {maxResults, nextToken} — paging only; Amazon has no filters here."}},"required":["store","countryCode"],"title":"ads_list_ads_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"adsAccounts":{"items":{"properties":{"accountName":{},"adsAccountId":{},"alternateIds":{"items":{"properties":{"countryCode":{},"entityId":{},"profileId":{}}}},"countryCodes":{"items":{}},"errors":{},"status":{}}},"description":"{adsAccountId, accountName, status, countryCodes, alternateIds[{countryCode, entityId, profileId}]}."},"nextToken":{"description":"pass back as body.nextToken."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_ads_account":{"post":{"operationId":"ads_get_ads_account","summary":"Get one Amazon Ads account by id.","description":"Get one Amazon Ads account by id. Amazon Ads API · GetAccount · GET /adsAccounts/{advertisingAccountId} Docs: https://advertising.amazon.com/API/docs/en-us/account-management#tag/Account/operation/GetAccount","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_ads_account"},"tags":["amazon_ads"],"x-title":"Ads Get Ads Account","x-access":"read","x-family":"ads.accounts","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"advertisingAccountId":{"title":"Advertisingaccountid","type":"string","description":"data.result.adsAccounts[].adsAccountId from ads_list_ads_accounts."}},"required":["store","countryCode","advertisingAccountId"],"title":"ads_get_ads_accountArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"adsAccount":{"properties":{"accountName":{},"adsAccountId":{},"alternateIds":{"items":{"properties":{"countryCode":{},"entityId":{},"profileId":{}}}},"countryCodes":{"items":{}},"errors":{},"status":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_ads_account":{"post":{"operationId":"ads_create_ads_account","summary":"Register a new Amazon Ads account.","description":"Register a new Amazon Ads account. List existing accounts first with ads_list_ads_accounts so you do not create a duplicate. Amazon Ads API · RegisterAdsAccount · POST /adsAccounts Docs: https://advertising.amazon.com/API/docs/en-us/account-management#tag/Account/operation/RegisterAdsAccount Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_ads_account"},"tags":["amazon_ads"],"x-title":"Ads Create Ads Account","x-access":"write","x-family":"ads.accounts","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.adsAccount","description":"{adsAccountId, accountName, status} — status CREATED, PENDING, PARTIALLY_CREATED or DISABLED."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"accountName":{"type":"string"},"associations":{"items":{"additionalProperties":true,"properties":{"amazonAuthor":{"additionalProperties":true,"properties":{"email":{"type":"string"}},"type":"object"},"amazonSeller":{"additionalProperties":true,"properties":{"sellerCentralAccount":{"type":"string"}},"type":"object"},"amazonVendor":{"additionalProperties":true,"properties":{"vendorGroup":{"type":"string"}},"type":"object"},"business":{"additionalProperties":true,"properties":{"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"countryCode":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"state":{"type":"string"},"websiteUrl":{"type":"string"},"zipCode":{"type":"string"}},"type":"object"}},"type":"object"},"maxItems":1,"minItems":0,"type":"array"},"countryCodes":{"items":{"type":"string"},"maxItems":1,"minItems":0,"type":"array"},"termsToken":{"type":"string"}},"title":"Body","type":"object","description":"the request body — its fields, enums and required marks are in this parameter's schema."}},"required":["store","countryCode","body"],"title":"ads_create_ads_accountArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"adsAccount":{"properties":{"accountName":{},"adsAccountId":{},"status":{}},"description":"{adsAccountId, accountName, status} — status CREATED, PENDING, PARTIALLY_CREATED or DISABLED."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_manager_accounts":{"post":{"operationId":"ads_get_manager_accounts","summary":"List Amazon Ads manager accounts — an agency or brand's umbrella over several advertiser accounts.","description":"List Amazon Ads manager accounts — an agency or brand's umbrella over several advertiser accounts. Most sellers get an empty list; this is normal. Amazon Ads API · getManagerAccountsForUser · GET /managerAccounts Docs: https://advertising.amazon.com/API/docs/en-us/reference/1-0/managerAccount#tag/Manager-Accounts/operation/getManagerAccountsForUser","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_manager_accounts"},"tags":["amazon_ads"],"x-title":"Ads Get Manager Accounts","x-access":"read","x-family":"ads.manager-accounts","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.managerAccounts[]","description":"{managerAccountId, managerAccountName, linkedAccounts[{accountId, accountName, accountType, profileId, dspAdvertiserId}]} — at most 50 linked accounts shown per manager."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."}},"required":["store","countryCode"],"title":"ads_get_manager_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"managerAccounts":{"items":{"properties":{"linkedAccounts":{"items":{"properties":{"accountId":{},"accountName":{},"accountType":{},"dspAdvertiserId":{},"marketplaceId":{},"profileId":{}}}},"managerAccountId":{},"managerAccountName":{}}},"description":"{managerAccountId, managerAccountName, linkedAccounts[{accountId, accountName, accountType, profileId, dspAdvertiserId}]} — at most 50 linked accounts shown per manager."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_manager_account":{"post":{"operationId":"ads_create_manager_account","summary":"Create an Amazon Ads manager account.","description":"Create an Amazon Ads manager account. List existing ones first with ads_get_manager_accounts. Amazon Ads API · createManagerAccount · POST /managerAccounts Docs: https://advertising.amazon.com/API/docs/en-us/reference/1-0/managerAccount#tag/Manager-Accounts/operation/createManagerAccount Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_manager_account"},"tags":["amazon_ads"],"x-title":"Ads Create Manager Account","x-access":"write","x-family":"ads.manager-accounts","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"managerAccountName":{"type":"string"},"managerAccountType":{"enum":["Advertiser","Agency"],"type":"string"}},"title":"Body","type":"object","description":"the request body — its fields, enums and required marks are in this parameter's schema."}},"required":["store","countryCode","body"],"title":"ads_create_manager_accountArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"linkedAccounts":{"items":{"properties":{"accountId":{},"accountName":{},"accountType":{},"dspAdvertiserId":{},"marketplaceId":{},"profileId":{}}}},"managerAccountId":{},"managerAccountName":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_associate_accounts":{"post":{"operationId":"ads_associate_accounts","summary":"Link an advertising account to an Amazon Ads manager account.","description":"Link an advertising account to an Amazon Ads manager account. Amazon Ads API · LinkAdvertisingAccountsToManagerAccountPublicAPI · POST /managerAccounts/{managerAccountId}/associate Docs: https://advertising.amazon.com/API/docs/en-us/reference/1-0/managerAccount#tag/Manager-Accounts/operation/LinkAdvertisingAccountsToManagerAccountPublicAPI Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_associate_accounts"},"tags":["amazon_ads"],"x-title":"Ads Associate Accounts","x-access":"write","x-family":"ads.manager-accounts","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.succeedAccounts / data.result.failedAccounts[]","description":"{account, error} — any failedAccounts entry was not linked."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"managerAccountId":{"title":"Manageraccountid","type":"string","description":"data.result.managerAccounts[].managerAccountId from ads_get_manager_accounts."},"body":{"additionalProperties":true,"properties":{"accounts":{"description":"user can pass a list with a max 20 accounts/advertisers using any mix of identifiers","items":{"additionalProperties":true,"properties":{"id":{"type":"string"},"roles":{"items":{"enum":["ENTITY_OWNER","ENTITY_USER","ENTITY_VIEWER","SELLER_USER"],"type":"string"},"type":"array"},"type":{"enum":["ACCOUNT_ID","DSP_ADVERTISER_ID"],"type":"string"}},"type":"object"},"type":"array"}},"title":"Body","type":"object","description":"{accounts: [{id, type, roles: [ONE role]}]} (max 20) — for type ACCOUNT_ID the id is the profile's accountInfo.id (may begin with 'ENTITY'); a DSP_ADVERTISER_ID comes from ads_dsp_advertisers."}},"required":["store","countryCode","managerAccountId","body"],"title":"ads_associate_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"failedAccounts":{"items":{"properties":{"account":{"properties":{"id":{},"roles":{"items":{}},"type":{}}},"error":{"properties":{"code":{},"message":{}}}}},"description":"{account, error} — any failedAccounts entry was not linked."},"succeedAccounts":{"items":{"properties":{"id":{},"roles":{"items":{}},"type":{}}},"description":"{account, error} — any failedAccounts entry was not linked."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_disassociate_accounts":{"post":{"operationId":"ads_disassociate_accounts","summary":"Unlink an advertising account from an Amazon Ads manager account — the manager loses access to that account.","description":"Unlink an advertising account from an Amazon Ads manager account — the manager loses access to that account. Amazon Ads API · UnlinkAdvertisingAccountsToManagerAccountPublicAPI · POST /managerAccounts/{managerAccountId}/disassociate Docs: https://advertising.amazon.com/API/docs/en-us/reference/1-0/managerAccount#tag/Manager-Accounts/operation/UnlinkAdvertisingAccountsToManagerAccountPublicAPI Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_disassociate_accounts"},"tags":["amazon_ads"],"x-title":"Ads Disassociate Accounts","x-access":"destructive","x-family":"ads.manager-accounts","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.succeedAccounts / data.result.failedAccounts[]","description":"{account, error} — any failedAccounts entry is still linked."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"managerAccountId":{"title":"Manageraccountid","type":"string","description":"data.result.managerAccounts[].managerAccountId from ads_get_manager_accounts."},"body":{"additionalProperties":true,"properties":{"accounts":{"description":"user can pass a list with a max 20 accounts/advertisers using any mix of identifiers","items":{"additionalProperties":true,"properties":{"id":{"type":"string"},"roles":{"items":{"enum":["ENTITY_OWNER","ENTITY_USER","ENTITY_VIEWER","SELLER_USER"],"type":"string"},"type":"array"},"type":{"enum":["ACCOUNT_ID","DSP_ADVERTISER_ID"],"type":"string"}},"type":"object"},"type":"array"}},"title":"Body","type":"object","description":"{accounts: [{id, type}]} (max 20) — id is that manager's linkedAccounts[].accountId (or its dspAdvertiserId) from ads_get_manager_accounts."}},"required":["store","countryCode","managerAccountId","body"],"title":"ads_disassociate_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"failedAccounts":{"items":{"properties":{"account":{"properties":{"id":{},"roles":{"items":{}},"type":{}}},"error":{"properties":{"code":{},"message":{}}}}},"description":"{account, error} — any failedAccounts entry is still linked."},"succeedAccounts":{"items":{"properties":{"id":{},"roles":{"items":{}},"type":{}}},"description":"{account, error} — any failedAccounts entry is still linked."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_bids_recommendations":{"post":{"operationId":"ads_get_bids_recommendations","summary":"Sponsored Brands: suggested bids for keywords, product targets or themes.","description":"Sponsored Brands: suggested bids for keywords, product targets or themes. Use the returned amounts as the `bid` when creating SB targets with ads_create_target. Amazon Ads API · getBidsRecommendations · POST /sb/recommendations/bids Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi#tag/Bid-recommendations/operation/getBidsRecommendations","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_bids_recommendations"},"tags":["amazon_ads"],"x-title":"Ads Get Bids Recommendations","x-access":"read","x-family":"ads.sb3","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.keywordsBidsRecommendationSuccessResults","description":"[{keywordIndex, keyword, recommendedBid {rangeStart, recommended, rangeEnd}}]; product targets and themes come back in the matching targets… and themes… lists, failures in the …ErrorResults lists."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adFormat":{"enum":["productCollection","video"],"type":"string"},"campaignId":{"format":"int64","type":"integer"},"costType":{"type":"string"},"goal":{"type":"string"},"keywords":{"description":"sum of the sizes of (targets + keywords + themeTypes) arrays should be ≤ 100","items":{"additionalProperties":true,"properties":{"keywordText":{"description":"max 10 words","type":"string"},"matchType":{"enum":["broad","exact","phrase"],"type":"string"}},"type":"object"},"maxItems":100,"type":"array"},"targets":{"description":"sum of the sizes of (targets + keywords + themeTypes) arrays should be ≤ 100","items":{"items":{"additionalProperties":true,"properties":{"type":{"enum":["asinCategorySameAs","asinBrandSameAs","asinPriceLessThan","asinPriceBetween","asinPriceGreaterThan","asinReviewRatingLessThan","asinReviewRatingBetween","asinReviewRatingGreaterThan","asinSameAs"],"type":"string"},"value":{"type":"string"}},"type":"object"},"type":"array"},"maxItems":100,"type":"array"},"themeTypes":{"description":"sum of the sizes of (targets + keywords + themeTypes) arrays should be ≤ 100","items":{"type":"string"},"maxItems":100,"minItems":0,"type":"array"}},"title":"Body","type":"object","description":"{campaignId, adFormat: 'productCollection'|'video', keywords: [{keywordText, matchType}] (max 100), targets: [[{type, value}]] (max 100 — each target is a LIST of expressions), themeTypes: [...] (max 100)}; sum of (targets + keywords + themeTypes) ≤ 100. costType (CPC | VCPM) needs a matching goal — costType without goal is refused; omit both for CPC bids at the default page-visit goal."}},"required":["store","countryCode","body"],"title":"ads_get_bids_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"keywordsBidsRecommendationErrorResults":{"items":{"properties":{"code":{},"details":{},"keyword":{"properties":{"type":{},"value":{"description":"max 10 words"}}},"keywordIndex":{}}}},"keywordsBidsRecommendationSuccessResults":{"items":{"properties":{"keyword":{"properties":{"keywordText":{},"matchType":{}}},"keywordIndex":{},"recommendationId":{},"recommendedBid":{"properties":{"rangeEnd":{},"rangeStart":{},"recommended":{}}}}},"description":"[{keywordIndex, keyword, recommendedBid {rangeStart, recommended, rangeEnd}}]; product targets and themes come back in the matching targets… and themes… lists, failures in the …ErrorResults lists."},"targetsBidsRecommendationErrorResults":{"items":{"properties":{"code":{},"details":{},"targets":{"items":{"properties":{"type":{},"value":{}}}},"targetsIndex":{}}}},"targetsBidsRecommendationSuccessResults":{"items":{"properties":{"recommendationId":{},"recommendedBid":{"properties":{"rangeEnd":{},"rangeStart":{},"recommended":{}}},"targets":{"items":{"properties":{"type":{},"value":{}}}},"targetsIndex":{}}}},"themesRecommendationErrorResults":{"items":{"properties":{"code":{},"details":{},"themeIndex":{},"themeType":{}}}},"themesRecommendationSuccessResults":{"items":{"properties":{"recommendationId":{},"recommendedBid":{"properties":{"rangeEnd":{},"rangeStart":{},"recommended":{}}},"themeIndex":{},"themeType":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_keyword_recommendations":{"post":{"operationId":"ads_get_keyword_recommendations","summary":"Sponsored Brands: suggested keywords, from ASINs or a landing page URL.","description":"Sponsored Brands: suggested keywords, from ASINs or a landing page URL. Create the picked ones as KEYWORD targets with ads_create_target. Amazon Ads API · getKeywordRecommendations · POST /sb/recommendations/keyword Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi#tag/Keyword-Recommendations/operation/getKeywordRecommendations","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_keyword_recommendations"},"tags":["amazon_ads"],"x-title":"Ads Get Keyword Recommendations","x-access":"read","x-family":"ads.sb3","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result","description":"[{value, matchType, recommendationId, searchTermImpressionShare, searchTermImpressionRank, translation}] — a bare list, one entry per suggested keyword."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"anyOf":[{"additionalProperties":true,"properties":{"asins":{"items":{"maximum":100,"minimum":1,"type":"string"},"type":"array"},"creativeAsins":{"items":{"maximum":3,"minimum":0,"type":"string"},"type":"array"},"creativeType":{"enum":["PRODUCT_COLLECTION","AUTHOR_COLLECTION","STORE_SPOTLIGHT","VIDEO","BRAND_VIDEO"],"type":"string"},"goal":{"default":"PAGE_VISIT","enum":["PAGE_VISIT","BRAND_IMPRESSION_SHARE","ACQUIRE_NEW_CUSTOMERS","AD_VIEWS"],"type":"string"},"locale":{"type":"string"},"maxNumSuggestions":{"format":"int64","type":"integer"}},"required":["asins"],"title":"SBKeywordRecommendationRequestAsin","type":"object"},{"additionalProperties":true,"properties":{"creativeAsins":{"items":{"maximum":3,"minimum":0,"type":"string"},"type":"array"},"creativeType":{"enum":["PRODUCT_COLLECTION","AUTHOR_COLLECTION","STORE_SPOTLIGHT","VIDEO","BRAND_VIDEO"],"type":"string"},"goal":{"default":"PAGE_VISIT","enum":["PAGE_VISIT","BRAND_IMPRESSION_SHARE","ACQUIRE_NEW_CUSTOMERS","AD_VIEWS"],"type":"string"},"locale":{"type":"string"},"maxNumSuggestions":{"format":"int64","type":"integer"},"url":{"type":"string"}},"required":["url"],"title":"SBKeywordRecommendationRequestUrl","type":"object"}],"title":"Body","type":"object","description":"one of {asins*: [...], goal?, creativeType?, maxNumSuggestions?, creativeAsins?, locale?} or {url*, goal?, creativeType?, maxNumSuggestions?, creativeAsins?, locale?}. maxNumSuggestions defaults to 100, at most 1000; locale adds a translation per keyword — zh_CN in US, UK and CA, en_GB in DE, FR, IT and ES; any other locale returns none."}},"required":["store","countryCode","body"],"title":"ads_get_keyword_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"items":{"properties":{"matchType":{},"recommendationId":{},"searchTermImpressionRank":{},"searchTermImpressionShare":{},"translation":{},"type":{},"value":{}}},"description":"[{value, matchType, recommendationId, searchTermImpressionShare, searchTermImpressionRank, translation}] — a bare list, one entry per suggested keyword."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_target_bid_recommendations":{"post":{"operationId":"ads_get_target_bid_recommendations","summary":"Sponsored Display: bid recommendations for up to 100 targeting clauses, derived from the last 7 days of winning auction bids for each one.","description":"Sponsored Display: bid recommendations for up to 100 targeting clauses, derived from the last 7 days of winning auction bids for each one. Only meaningful when product ads use asin (vendors) or sku (sellers). Amazon Ads API · getTargetBidRecommendations · POST /sd/targets/bid/recommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Bid-Recommendations/operation/getTargetBidRecommendations","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_target_bid_recommendations"},"tags":["amazon_ads"],"x-title":"Ads Get Target Bid Recommendations","x-access":"read","x-family":"ads.sd","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."}],"x-notes":{"Gotchas":["- products accepts sku as well as asin (Amazon's schema documents","  only asin, but a seller may pass sku instead) — required for","  similarProduct, exactProduct and relatedProduct targets.","- Use recommended bids as the `bid` when creating targets with","  ads_create_target."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"bidOptimization":{"enum":["reach","clicks","conversions"],"type":"string"},"costType":{"enum":["cpc","vcpm"],"type":"string"},"creativeType":{"enum":["IMAGE","VIDEO"],"type":"string"},"products":{"items":{"additionalProperties":true,"properties":{"asin":{"type":"string"}},"required":["asin"],"type":"object"},"maxItems":10000,"minItems":0,"type":"array"},"targetingClauses":{"items":{"additionalProperties":true,"properties":{"targetingClause":{"additionalProperties":true,"properties":{"expression":{"items":{"anyOf":[{"additionalProperties":true,"description":"* Review predicates accept numbers between 0 and 5 and are inclusive","properties":{"type":{"enum":["asinSameAs","asinCategorySameAs","asinBrandSameAs","asinPriceBetween","asinPriceGreaterThan","asinPriceLessThan","asinReviewRatingLessThan","asinReviewRatingGreaterThan","asinReviewRatingBetween","asinIsPrimeShippingEligible","asinAgeRangeSameAs","asinGenreSameAs"],"type":"string"},"value":{"type":"string"}},"required":["type"],"title":"SDTargetingPredicateV31","type":"object"},{"additionalProperties":true,"properties":{"type":{"enum":["views","audience","purchases"],"type":"string"},"value":{"items":{"additionalProperties":true,"description":"* Review predicates accept numbers between 0 and 5 and are inclusive","properties":{"type":{"enum":["asinCategorySameAs","asinBrandSameAs","asinPriceBetween","asinPriceGreaterThan","asinPriceLessThan","asinReviewRatingLessThan","asinReviewRatingGreaterThan","asinReviewRatingBetween","similarProduct","relatedProduct","exactProduct","asinIsPrimeShippingEligible","asinAgeRangeSameAs","asinGenreSameAs","audienceSameAs","lookback"],"type":"string"},"value":{"type":"string"}},"required":["type"],"type":"object"},"type":"array"}},"required":["type","value"],"title":"SDTargetingPredicateNestedV31","type":"object"},{"additionalProperties":true,"properties":{"type":{"enum":["contentCategorySameAs"],"type":"string"},"value":{"type":"string"}},"required":["type","value"],"title":"SDContentTargetingPredicateV31","type":"object"}]},"minItems":1,"type":"array"},"expressionType":{"enum":["manual","auto"],"type":"string"}},"required":["expressionType","expression"],"type":"object"}},"required":["targetingClause"],"type":"object"},"maxItems":100,"minItems":1,"type":"array"}},"required":["bidOptimization","costType","targetingClauses"],"title":"Body","type":"object","description":"{bidOptimization*: 'clicks'|'reach'|'conversions', costType*: 'cpc'|'vcpm', targetingClauses*: [{targetingClause: {expressionType, expression}}] (1-100), products: [{asin}] (max 10000), creativeType?}."}},"required":["store","countryCode","body"],"title":"ads_get_target_bid_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"bidOptimization":{},"bidRecommendations":{"items":{"anyOf":[{"properties":{"code":{},"rangeLower":{},"rangeUpper":{},"recommended":{}},"title":"SDTargetingBidRecommendationsResponseItemSuccessV31"},{"properties":{"code":{},"details":{}},"title":"SDTargetingBidRecommendationsResponseItemFailureV31"}]}},"costType":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_sd_budget_recommendations":{"post":{"operationId":"ads_get_sd_budget_recommendations","summary":"Budget recommendations and missed-opportunity metrics for up to 100 Sponsored Display campaigns — suggestedBudget, and under sevenDaysMissedOpportunities the percentTimeInBudget (s","description":"Budget recommendations and missed-opportunity metrics for up to 100 Sponsored Display campaigns — suggestedBudget, and under sevenDaysMissedOpportunities the percentTimeInBudget (share of the past 7 days in budget) and estimated missed impressions/clicks/sales. Amazon Ads API · getSDBudgetRecommendations · POST /sd/campaigns/budgetRecommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Recommendations/operation/getSDBudgetRecommendations","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_sd_budget_recommendations"},"tags":["amazon_ads"],"x-title":"Ads Get SD Budget Recommendations","x-access":"read","x-family":"ads.sd","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.budgetRecommendationsSuccessResults","description":"[{index, campaignId, suggestedBudget, sevenDaysMissedOpportunities}]."},{"field":"data.result.budgetRecommendationsErrorResults","description":"[{index, campaignId, code, details}] — campaigns that got no recommendation."}],"x-notes":{"Gotchas":["- Metrics are based on historical performance — not a guarantee","  of future results. Sort by","  sevenDaysMissedOpportunities.estimatedMissedSalesUpper descending","  to prioritize which campaigns to raise, then raise them with","  ads_update_campaign_budget."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaignIds":{"items":{"type":"string"},"maxItems":100,"title":"Campaignids","type":"array","description":"SD campaign ids, as strings (max 100), from ads_query_campaign (adProductFilter SPONSORED_DISPLAY)."}},"required":["store","countryCode","campaignIds"],"title":"ads_get_sd_budget_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"budgetRecommendationsErrorResults":{"items":{"properties":{"campaignId":{},"code":{},"details":{},"index":{}}},"description":"[{index, campaignId, code, details}] — campaigns that got no recommendation."},"budgetRecommendationsSuccessResults":{"items":{"properties":{"campaignId":{},"index":{},"sevenDaysMissedOpportunities":{"properties":{"endDate":{},"estimatedMissedClicksLower":{},"estimatedMissedClicksUpper":{},"estimatedMissedImpressionsLower":{},"estimatedMissedImpressionsUpper":{},"estimatedMissedSalesLower":{},"estimatedMissedSalesUpper":{},"estimatedMissedViewableImpressionsLower":{},"estimatedMissedViewableImpressionsUpper":{},"percentTimeInBudget":{},"startDate":{}}},"suggestedBudget":{}}},"description":"[{index, campaignId, suggestedBudget, sevenDaysMissedOpportunities}]."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_target_recommendations":{"post":{"operationId":"ads_get_target_recommendations","summary":"Sponsored Display: up to 100 recommended product, category, audience or content-category targets (whichever typeFilter asks for), based on the ASINs/SKUs you advertise.","description":"Sponsored Display: up to 100 recommended product, category, audience or content-category targets (whichever typeFilter asks for), based on the ASINs/SKUs you advertise. Amazon Ads API · getTargetRecommendations · POST /sd/targets/recommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Targeting-Recommendations/operation/getTargetRecommendations","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_target_recommendations"},"tags":["amazon_ads"],"x-title":"Ads Get Target Recommendations","x-access":"read","x-family":"ads.sd","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{"Gotchas":["- products accepts sku as well as asin (Amazon's schema documents","  only asin, but a seller may pass sku instead).","- Allow about a week for Amazon to have data on a newly listed ASIN.","- The response uses the legacy SD expression form","  ({type: 'asinSameAs', value: '<ASIN>'}) —","  ads_create_target does NOT accept that shape; translate before","  creating (adProduct SPONSORED_DISPLAY):","  asinSameAs -> targetType PRODUCT, targetDetails","  {productTarget: {matchType: PRODUCT_EXACT, product: {productId},","  productIdType: ASIN}}; asinCategorySameAs -> targetType","  PRODUCT_CATEGORY, targetDetails {productCategoryTarget:","  {productCategoryRefinement: {productCategoryRefinement:","  {productCategoryId}}}} (the wrapper key is nested TWICE)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"categoryType":{"enum":["views","purchases"],"type":"string"},"locationExpression":{"items":{"additionalProperties":true,"properties":{"type":{"enum":["location"],"type":"string"},"value":{"type":"string"}},"type":"object"},"maxItems":20,"minItems":1,"type":"array"},"products":{"items":{"additionalProperties":true,"properties":{"asin":{"type":"string"},"landingPageType":{"enum":["OFF_AMAZON_LINK"],"type":"string"},"landingPageURL":{"type":"string"}},"type":"object"},"maxItems":10000,"minItems":1,"type":"array"},"tactic":{"enum":["T00020","T00030"],"type":"string"},"themes":{"additionalProperties":true,"properties":{"product":{"items":{"additionalProperties":true,"properties":{"expression":{"items":{"additionalProperties":true,"properties":{"type":{"enum":["asinPriceGreaterThan","asinBrandSameAs","asinReviewRatingLessThan","asinGlanceViewsGreaterThan"],"type":"string"}},"required":["type"],"type":"object"},"maxItems":1,"minItems":1,"type":"array"},"name":{"maxLength":100,"type":"string"}},"required":["name","expression"],"type":"object"},"maxItems":5,"minItems":0,"type":"array"}},"type":"object"},"typeFilter":{"items":{"enum":["PRODUCT","CATEGORY","AUDIENCE","CONTENT_CATEGORY"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"required":["tactic","products","typeFilter"],"title":"Body","type":"object","description":"{tactic*: 'T00020'|'T00030', products*: [{asin}] (1-10000), typeFilter*: ['PRODUCT'|'CATEGORY'|'AUDIENCE'| 'CONTENT_CATEGORY'] (1-3)}. tactic T00020 is contextual targeting (products); T00030 is audiences or contextual (products, categories, refined categories, audiences)."},"locale":{"anyOf":[{"enum":["ar_AE","de_DE","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","es_ES","es_MX","fr_CA","fr_FR","hi_IN","it_IT","ja_JP","ko_KR","nl_NL","pl_PL","pt_BR","sv_SE","ta_IN","th_TH","tr_TR","vi_VN","zh_CN"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"the language of the returned names; omit for the profile's own. Allowed: ar_AE | de_DE | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | es_ES | es_MX | fr_CA | fr_FR | hi_IN | it_IT | ja_JP | ko_KR | nl_NL | pl_PL | pt_BR | sv_SE | ta_IN | th_TH | tr_TR | vi_VN | zh_CN."}},"required":["store","countryCode","body"],"title":"ads_get_target_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"recommendations":{"properties":{"audiences":{"items":{"properties":{"audiences":{"items":{"properties":{"audience":{},"name":{},"rank":{}}}},"category":{}}}},"categories":{"items":{"properties":{"category":{},"name":{},"path":{"items":{}},"rank":{},"targetableAsinCountRange":{"properties":{"rangeLower":{},"rangeUpper":{}}},"translatedName":{},"translatedPath":{"items":{}}}}},"contentCategories":{"items":{"properties":{"contentCategory":{},"name":{},"rank":{}}}},"products":{"items":{"properties":{"products":{"items":{"properties":{"advertisedAsins":{"items":{}},"asin":{},"rank":{}}}}}}},"themes":{"properties":{"themes":{"properties":{"products":{"items":{"properties":{"code":{},"expression":{"items":{"description":"1 fields (type) — see the Docs link"}},"name":{},"recommendations":{"items":{"description":"3 fields (asin, rank, advertisedAsins) — see the Docs link"}}}}}}}}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_campaigns_budget_usage":{"post":{"operationId":"ads_campaigns_budget_usage","summary":"Real-time budget consumption for campaigns — how much of today's budget is already spent, so you can see which campaigns are about to stop serving.","description":"Real-time budget consumption for campaigns — how much of today's budget is already spent, so you can see which campaigns are about to stop serving. This is live intraday data the synced report warehouse cannot provide. Amazon Ads API · spCampaignsBudgetUsage · POST /sp/campaigns/budget/usage Amazon Ads API · sbCampaignsBudgetUsage · POST /sb/campaigns/budget/usage Amazon Ads API · sdCampaignsBudgetUsage · POST /sd/campaigns/budget/usage Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Budget-Usage/operation/spCampaignsBudgetUsage Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-usage/operation/sbCampaignsBudgetUsage Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Usage/operation/sdCampaignsBudgetUsage","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_campaigns_budget_usage"},"tags":["amazon_ads"],"x-title":"Ads Campaigns Budget Usage","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."}],"x-notes":{"Body (Amazon schema)":["campaignIds: [string] (1–100)"],"Gotchas":["- A partial result is still HTTP-success — always inspect","  data.result.error[] (per-id failures: unknown id, no active","  budget) alongside success[]; index matches the position in","  your ids list.","- budgetUsagePercent is spend / available budget under the","  current budget policy; usageUpdatedTimestamp is when Amazon","  last evaluated usage — always relay it, the figure is not","  instantaneous.","- Campaigns near 100% are about to stop serving; for","  SPONSORED_PRODUCTS, ads_sp_get_budget_recommendations suggests a","  raise."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"ids":{"items":{},"title":"Ids","type":"array","description":"1-100 campaign ids, as strings, from ads_query_campaign. Amazon rejects >100 per call — chunk larger sets."}},"required":["store","countryCode","adProduct","ids"],"title":"ads_campaigns_budget_usageArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"campaignId":{},"code":{},"details":{},"index":{}}}},"success":{"items":{"properties":{"budget":{},"budgetUsagePercent":{},"campaignId":{},"index":{},"usageUpdatedTimestamp":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_portfolio_budget_usage":{"post":{"operationId":"ads_portfolio_budget_usage","summary":"Real-time budget consumption for portfolios — how much of the portfolio's current budget cap (its date-range or monthly policy) is already spent; a portfolio with no budget cap com","description":"Real-time budget consumption for portfolios — how much of the portfolio's current budget cap (its date-range or monthly policy) is already spent; a portfolio with no budget cap comes back in data.result.error[]. Amazon Ads API · portfolioBudgetUsage · POST /portfolios/budget/usage Docs: https://advertising.amazon.com/API/docs/en-us/reference/portfolios#tag/Budget-Usage/operation/portfolioBudgetUsage","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_portfolio_budget_usage"},"tags":["amazon_ads"],"x-title":"Ads Portfolio Budget Usage","x-access":"read","x-family":"ads.portfolios","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."}],"x-notes":{"Body (Amazon schema)":["portfolioIds: [string] (1–100)"],"Gotchas":["- Same envelope as ads_campaigns_budget_usage: a partial result","  is still HTTP-success — always inspect data.result.error[]."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"ids":{"items":{},"title":"Ids","type":"array","description":"1-100 portfolio ids, as strings, from ads_list_portfolios. Amazon rejects >100 per call — chunk larger sets."}},"required":["store","countryCode","ids"],"title":"ads_portfolio_budget_usageArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"code":{},"details":{},"index":{},"portfolioId":{}}}},"success":{"items":{"properties":{"budget":{},"budgetUsagePercent":{},"index":{},"portfolioId":{},"usageUpdatedTimestamp":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_budget_rules_for_advertiser":{"post":{"operationId":"ads_get_budget_rules_for_advertiser","summary":"Page all of the advertiser's budget rules for one ad product.","description":"Page all of the advertiser's budget rules for one ad product. Amazon Ads API · GetSPBudgetRulesForAdvertiser · GET /sp/budgetRules Amazon Ads API · GetSBBudgetRulesForAdvertiser · GET /sb/budgetRules Amazon Ads API · GetSDBudgetRulesForAdvertiser · GET /sd/budgetRules Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRules/operation/GetSPBudgetRulesForAdvertiser Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-rules/operation/GetSBBudgetRulesForAdvertiser Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Rules/operation/GetSDBudgetRulesForAdvertiser","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_budget_rules_for_advertiser"},"tags":["amazon_ads"],"x-title":"Ads Get Budget Rules for Advertiser","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.budgetRulesForAdvertiserResponse[]","description":"{ruleId, ruleState, ruleStatus, ruleDetails}."},{"field":"data.nextToken","description":"the cursor for the next page (absent on the last page)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"pageSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pagesize","description":"rules per page, 1–30 (default 30)."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","countryCode","adProduct"],"title":"ads_get_budget_rules_for_advertiserArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"budgetRulesForAdvertiserResponse":{"items":{"properties":{"createdDate":{},"lastUpdatedDate":{},"ruleDetails":{"properties":{"budgetIncreaseBy":{"properties":{"type":{},"value":{}}},"duration":{"properties":{"dateRangeTypeRuleDuration":{"properties":{"endDate":{},"startDate":{}}},"eventTypeRuleDuration":{"properties":{"endDate":{},"eventId":{},"eventName":{},"startDate":{}}}}},"name":{},"performanceMeasureCondition":{"properties":{"comparisonOperator":{"description":"values differ by ad product"},"metricName":{"description":"values differ by ad product"},"threshold":{}}},"recurrence":{"properties":{"daysOfWeek":{"items":{}},"intraDaySchedule":{"items":{"properties":{"endTime":{},"startTime":{}}}},"type":{"description":"values differ by ad product"}}},"ruleType":{}}},"ruleId":{},"ruleState":{},"ruleStatus":{}}},"description":"{ruleId, ruleState, ruleStatus, ruleDetails}."},"nextToken":{}}},"nextToken":{"description":"the cursor for the next page (absent on the last page)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_budget_rule_by_rule_id_for_campaigns":{"post":{"operationId":"ads_get_budget_rule_by_rule_id_for_campaigns","summary":"Get one budget rule by id.","description":"Get one budget rule by id. Amazon Ads API · GetBudgetRuleByRuleIdForSPCampaigns · GET /sp/budgetRules/{budgetRuleId} Amazon Ads API · GetBudgetRuleByRuleIdForSBCampaigns · GET /sb/budgetRules/{budgetRuleId} Amazon Ads API · GetBudgetRuleByRuleIdForSDCampaigns · GET /sd/budgetRules/{budgetRuleId} Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRules/operation/GetBudgetRuleByRuleIdForSPCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-rules/operation/GetBudgetRuleByRuleIdForSBCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Rules/operation/GetBudgetRuleByRuleIdForSDCampaigns","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_budget_rule_by_rule_id_for_campaigns"},"tags":["amazon_ads"],"x-title":"Ads Get Budget Rule by Rule ID for Campaigns","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"budgetRuleId":{"title":"Budgetruleid","type":"string","description":"from ads_get_budget_rules_for_advertiser."}},"required":["store","countryCode","adProduct","budgetRuleId"],"title":"ads_get_budget_rule_by_rule_id_for_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"budgetRule":{"properties":{"createdDate":{},"lastUpdatedDate":{},"ruleDetails":{"properties":{"budgetIncreaseBy":{"properties":{"type":{},"value":{}}},"duration":{"properties":{"dateRangeTypeRuleDuration":{"properties":{"endDate":{},"startDate":{}}},"eventTypeRuleDuration":{"properties":{"endDate":{},"eventId":{},"eventName":{},"startDate":{}}}}},"name":{},"performanceMeasureCondition":{"properties":{"comparisonOperator":{"description":"values differ by ad product"},"metricName":{"description":"values differ by ad product"},"threshold":{}}},"recurrence":{"properties":{"daysOfWeek":{"items":{}},"intraDaySchedule":{"items":{"properties":{"endTime":{},"startTime":{}}}},"type":{"description":"values differ by ad product"}}},"ruleType":{}}},"ruleId":{},"ruleState":{},"ruleStatus":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_campaigns_associated_with_budget_rule":{"post":{"operationId":"ads_get_campaigns_associated_with_budget_rule","summary":"List the campaigns a budget rule is attached to.","description":"List the campaigns a budget rule is attached to. Amazon Ads API · GetCampaignsAssociatedWithSPBudgetRule · GET /sp/budgetRules/{budgetRuleId}/campaigns Amazon Ads API · GetCampaignsAssociatedWithSBBudgetRule · GET /sb/budgetRules/{budgetRuleId}/campaigns Amazon Ads API · GetCampaignsAssociatedWithSDBudgetRule · GET /sd/budgetRules/{budgetRuleId}/campaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRules/operation/GetCampaignsAssociatedWithSPBudgetRule Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-rules/operation/GetCampaignsAssociatedWithSBBudgetRule Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Rules/operation/GetCampaignsAssociatedWithSDBudgetRule","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_campaigns_associated_with_budget_rule"},"tags":["amazon_ads"],"x-title":"Ads Get Campaigns Associated with Budget Rule","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.associatedCampaigns[]","description":"{campaignId, campaignName, ruleStatus}."},{"field":"data.nextToken","description":"the cursor for the next page (absent on the last page)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"budgetRuleId":{"title":"Budgetruleid","type":"string","description":"from ads_get_budget_rules_for_advertiser."},"pageSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pagesize","description":"campaigns per page, 1–30 (default 30)."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","countryCode","adProduct","budgetRuleId"],"title":"ads_get_campaigns_associated_with_budget_ruleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"associatedCampaigns":{"items":{"properties":{"campaignId":{},"campaignName":{},"ruleStatus":{}}},"description":"{campaignId, campaignName, ruleStatus}."},"nextToken":{}}},"nextToken":{"description":"the cursor for the next page (absent on the last page)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_associated_budget_rules_for_campaigns":{"post":{"operationId":"ads_list_associated_budget_rules_for_campaigns","summary":"List the budget rules applied to one campaign.","description":"List the budget rules applied to one campaign. Amazon Ads API · ListAssociatedBudgetRulesForSPCampaigns · GET /sp/campaigns/{campaignId}/budgetRules Amazon Ads API · ListAssociatedBudgetRulesForSBCampaigns · GET /sb/campaigns/{campaignId}/budgetRules Amazon Ads API · ListAssociatedBudgetRulesForSDCampaigns · GET /sd/campaigns/{campaignId}/budgetRules Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRules/operation/ListAssociatedBudgetRulesForSPCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-rules/operation/ListAssociatedBudgetRulesForSBCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Rules/operation/ListAssociatedBudgetRulesForSDCampaigns","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_associated_budget_rules_for_campaigns"},"tags":["amazon_ads"],"x-title":"Ads List Associated Budget Rules for Campaigns","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.associatedRules[]","description":"{ruleId, ruleState, ruleStatus, ruleDetails}."}],"x-notes":{"Gotchas":["- A rule can be ACTIVE and still be doing NOTHING. ruleState is","  what you set (ACTIVE | PAUSED); ruleStatus is Amazon's own","  evaluation status, with ruleStatusDetails {status, reasonCode}","  beside it — read them here after associating; it is the only","  signal that the rule is really in effect. A correctly","  created + associated PERFORMANCE rule was seen sitting at","  ruleStatus ON_HOLD, reasonCode INELIGIBLE_PERFORMANCE_METRIC —","  the campaign had no usable ACOS yet, so the rule never","  evaluated (identical at threshold 30 and 1000: it reflects the","  campaign's data sufficiency, not the threshold). Never report","  \"rule created\" as \"rule working\"."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"campaignId":{"title":"Campaignid","type":"string","description":"from ads_query_campaign. Amazon returns every associated rule in one response."}},"required":["store","countryCode","adProduct","campaignId"],"title":"ads_list_associated_budget_rules_for_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"associatedRules":{"items":{"properties":{"createdDate":{},"lastUpdatedDate":{},"ruleDetails":{"properties":{"budgetIncreaseBy":{"properties":{"type":{},"value":{}}},"duration":{"properties":{"dateRangeTypeRuleDuration":{"properties":{"endDate":{},"startDate":{}}},"eventTypeRuleDuration":{"properties":{"endDate":{},"eventId":{},"eventName":{},"startDate":{}}}}},"name":{},"performanceMeasureCondition":{"properties":{"comparisonOperator":{"description":"values differ by ad product"},"metricName":{"description":"values differ by ad product"},"threshold":{}}},"recurrence":{"properties":{"daysOfWeek":{"items":{}},"intraDaySchedule":{"items":{"properties":{"endTime":{},"startTime":{}}}},"type":{"description":"values differ by ad product"}}},"ruleType":{}}},"ruleId":{},"ruleState":{},"ruleStatus":{}}},"description":"{ruleId, ruleState, ruleStatus, ruleDetails}."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_budget_rules_for_campaigns":{"post":{"operationId":"ads_create_budget_rules_for_campaigns","summary":"Create budget rules — automatic, time- or performance-based daily-budget increases.","description":"Create budget rules — automatic, time- or performance-based daily-budget increases. A rule does nothing until it is attached with ads_create_associated_budget_rules_for_campaigns. Amazon Ads API · CreateBudgetRulesForSPCampaigns · POST /sp/budgetRules Amazon Ads API · CreateBudgetRulesForSBCampaigns · POST /sb/budgetRules Amazon Ads API · CreateBudgetRulesForSDCampaigns · POST /sd/budgetRules Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRules/operation/CreateBudgetRulesForSPCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-rules/operation/CreateBudgetRulesForSBCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Rules/operation/CreateBudgetRulesForSDCampaigns Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_budget_rules_for_campaigns"},"tags":["amazon_ads"],"x-title":"Ads Create Budget Rules for Campaigns","x-access":"write","x-family":"ads.sp","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.responses","description":"per rule {ruleId, code, details} — ruleId goes to ads_create_associated_budget_rules_for_campaigns; a code other than Ok means that rule failed."}],"x-notes":{"Body (Amazon schema): {budgetRulesDetails: [BudgetRuleDetails]} (max 25), each item":["budgetIncreaseBy: {type*: PERCENT, value*}","duration: {dateRangeTypeRuleDuration: {endDate, startDate*}, eventTypeRuleDuration: {endDate, eventId*, eventName, startDate}}","name: string (max 355 chars)","performanceMeasureCondition: {comparisonOperator*, metricName*, threshold*}","recurrence: {daysOfWeek, intraDaySchedule: [{endTime, startTime}] (max 1), type}","recurrence.daysOfWeek: [FRIDAY | MONDAY | SATURDAY | SUNDAY | THURSDAY | TUESDAY | WEDNESDAY]","ruleType: PERFORMANCE | SCHEDULE","By product:           SPONSORED_PRODUCTS  SPONSORED_BRANDS  SPONSORED_DISPLAY","  comparisonOperator  EQUAL_TO + shared   shared            shared","    shared: GREATER_THAN GREATER_THAN_OR_EQUAL_TO LESS_THAN LESS_THAN_OR_EQUAL_TO","  metricName          ACOS CTR CVR ROAS   IS NTB ROAS       ACOS CTR CVR ROAS","  recurrence.type     DAILY               DAILY WEEKLY      DAILY WEEKLY"],"Gotchas":["- Rules only ever RAISE a budget. For a lower overnight budget,","  set the base budget low and raise it inside daytime windows","  (recurrence.intraDaySchedule: max 1 window per rule - a","  morning/afternoon/evening ramp needs three rules). The time","  format (\"HH:MM:SS\") differs from","  ads_search_optimization_rules' recurrence.timesOfDay","  (\"HH:MM\") - two different APIs.","- recurrence appears in CREATE bodies only, never in an update.","- Rules active together stack additively (+5% and +10% -> +15%).","- eventId (for an eventTypeRuleDuration) comes from","  ads_get_budget_rules_recommendation.","- Verify the live effect with ads_campaigns_budget_usage during","  the rule window, not from the rule definition — an ACTIVE rule","  can still be ON_HOLD (see","  ads_list_associated_budget_rules_for_campaigns).","- duration.dateRangeTypeRuleDuration dates are YYYYMMDD (no","  dashes); startDate must be today or later."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"body":{"items":{"additionalProperties":true,"properties":{"budgetIncreaseBy":{"additionalProperties":true,"properties":{"type":{"enum":["PERCENT"],"type":"string"},"value":{"format":"double","type":"number"}},"required":["type","value"],"type":"object"},"duration":{"additionalProperties":true,"properties":{"dateRangeTypeRuleDuration":{"additionalProperties":true,"properties":{"endDate":{"type":"string"},"startDate":{"type":"string"}},"required":["startDate"],"type":"object"},"eventTypeRuleDuration":{"additionalProperties":true,"properties":{"endDate":{"type":"string"},"eventId":{"type":"string"},"eventName":{"type":"string"},"startDate":{"type":"string"}},"required":["eventId"],"type":"object"}},"type":"object"},"name":{"maxLength":355,"type":"string"},"performanceMeasureCondition":{"additionalProperties":true,"properties":{"comparisonOperator":{"description":"values differ by ad product","enum":["EQUAL_TO","GREATER_THAN","GREATER_THAN_OR_EQUAL_TO","LESS_THAN","LESS_THAN_OR_EQUAL_TO"],"type":"string"},"metricName":{"description":"values differ by ad product","enum":["ACOS","CTR","CVR","ROAS","IS","NTB"],"type":"string"},"threshold":{"format":"double","type":"number"}},"required":["comparisonOperator","metricName","threshold"],"type":"object"},"recurrence":{"additionalProperties":true,"properties":{"daysOfWeek":{"items":{"enum":["FRIDAY","MONDAY","SATURDAY","SUNDAY","THURSDAY","TUESDAY","WEDNESDAY"],"type":"string"},"type":"array"},"intraDaySchedule":{"items":{"additionalProperties":true,"properties":{"endTime":{"type":"string"},"startTime":{"type":"string"}},"type":"object"},"maxItems":1,"type":"array"},"type":{"description":"values differ by ad product","enum":["DAILY","WEEKLY"],"type":"string"}},"type":"object"},"ruleType":{"enum":["PERFORMANCE","SCHEDULE"],"type":"string"}},"type":"object"},"maxItems":25,"title":"Body","type":"array","description":"list of 1-25 FLAT rule details (max 25)."}},"required":["store","countryCode","adProduct","body"],"title":"ads_create_budget_rules_for_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"responses":{"items":{"properties":{"associatedCampaignIds":{"items":{}},"code":{},"details":{},"ruleId":{}}},"description":"per rule {ruleId, code, details} — ruleId goes to ads_create_associated_budget_rules_for_campaigns; a code other than Ok means that rule failed."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_budget_rules_for_campaigns":{"post":{"operationId":"ads_update_budget_rules_for_campaigns","summary":"Update existing budget rules — rename, change the increase, threshold or duration, or set ruleState PAUSED to stop one.","description":"Update existing budget rules — rename, change the increase, threshold or duration, or set ruleState PAUSED to stop one. Budget rules have no delete; ads_disassociate_associated_budget_rule_for_campaigns detaches one from a campaign. Amazon Ads API · UpdateBudgetRulesForSPCampaigns · PUT /sp/budgetRules Amazon Ads API · UpdateBudgetRulesForSBCampaigns · PUT /sb/budgetRules Amazon Ads API · UpdateBudgetRulesForSDCampaigns · PUT /sd/budgetRules Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRules/operation/UpdateBudgetRulesForSPCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-rules/operation/UpdateBudgetRulesForSBCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Rules/operation/UpdateBudgetRulesForSDCampaigns Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_budget_rules_for_campaigns"},"tags":["amazon_ads"],"x-title":"Ads Update Budget Rules for Campaigns","x-access":"destructive","x-family":"ads.sp","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."}],"x-notes":{"Body (Amazon schema): {budgetRulesDetails: [BudgetRule]} (max 25), each item":["createdDate: number","lastUpdatedDate: number","ruleDetails: {budgetIncreaseBy: {type*, value*}, duration: {dateRangeTypeRuleDuration, eventTypeRuleDuration}, name (max 355 chars), performanceMeasureCondition: {comparisonOperator*, metricName*, threshold*}, recurrence: {daysOfWeek, intraDaySchedule, type}, ruleType: PERFORMANCE | SCHEDULE}","ruleDetails.budgetIncreaseBy.type: PERCENT","ruleDetails.recurrence.daysOfWeek: [FRIDAY | MONDAY | SATURDAY | SUNDAY | THURSDAY | TUESDAY | WEDNESDAY]","ruleId*: string","ruleState: ACTIVE | PAUSED","ruleStatus: string","By product:           SPONSORED_PRODUCTS  SPONSORED_BRANDS  SPONSORED_DISPLAY","  comparisonOperator  EQUAL_TO + shared   shared            shared","    shared: GREATER_THAN GREATER_THAN_OR_EQUAL_TO LESS_THAN LESS_THAN_OR_EQUAL_TO","  metricName          ACOS CTR CVR ROAS   IS NTB ROAS       ACOS CTR CVR ROAS","  recurrence.type     DAILY               DAILY WEEKLY      DAILY WEEKLY"],"Gotchas":["- ruleDetails accepts ONLY mutable fields: name, duration,","  budgetIncreaseBy, performanceMeasureCondition. Amazon's schema","  also lists ruleType and recurrence, but an update carrying","  either is rejected (400 'Expected null')."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"body":{"items":{"additionalProperties":true,"properties":{"createdDate":{"format":"int64","type":"number"},"lastUpdatedDate":{"format":"int64","type":"number"},"ruleDetails":{"additionalProperties":true,"properties":{"budgetIncreaseBy":{"additionalProperties":true,"properties":{"type":{"enum":["PERCENT"],"type":"string"},"value":{"format":"double","type":"number"}},"required":["type","value"],"type":"object"},"duration":{"additionalProperties":true,"properties":{"dateRangeTypeRuleDuration":{"additionalProperties":true,"properties":{"endDate":{"type":"string"},"startDate":{"type":"string"}},"required":["startDate"],"type":"object"},"eventTypeRuleDuration":{"additionalProperties":true,"properties":{"endDate":{"type":"string"},"eventId":{"type":"string"},"eventName":{"type":"string"},"startDate":{"type":"string"}},"required":["eventId"],"type":"object"}},"type":"object"},"name":{"maxLength":355,"type":"string"},"performanceMeasureCondition":{"additionalProperties":true,"properties":{"comparisonOperator":{"description":"values differ by ad product","enum":["EQUAL_TO","GREATER_THAN","GREATER_THAN_OR_EQUAL_TO","LESS_THAN","LESS_THAN_OR_EQUAL_TO"],"type":"string"},"metricName":{"description":"values differ by ad product","enum":["ACOS","CTR","CVR","ROAS","IS","NTB"],"type":"string"},"threshold":{"format":"double","type":"number"}},"required":["comparisonOperator","metricName","threshold"],"type":"object"},"recurrence":{"additionalProperties":true,"properties":{"daysOfWeek":{"items":{"enum":["FRIDAY","MONDAY","SATURDAY","SUNDAY","THURSDAY","TUESDAY","WEDNESDAY"],"type":"string"},"type":"array"},"intraDaySchedule":{"items":{"additionalProperties":true,"properties":{"endTime":{"type":"string"},"startTime":{"type":"string"}},"type":"object"},"maxItems":1,"type":"array"},"type":{"description":"values differ by ad product","enum":["DAILY","WEEKLY"],"type":"string"}},"type":"object"},"ruleType":{"enum":["PERFORMANCE","SCHEDULE"],"type":"string"}},"type":"object"},"ruleId":{"type":"string"},"ruleState":{"enum":["ACTIVE","PAUSED"],"type":"string"},"ruleStatus":{"type":"string"}},"required":["ruleId"],"type":"object"},"maxItems":25,"title":"Body","type":"array","description":"list of 1-25 {ruleId*, ruleDetails, ruleState} wrappers (NOT flat like create)."}},"required":["store","countryCode","adProduct","body"],"title":"ads_update_budget_rules_for_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"responses":{"items":{"properties":{"associatedCampaignIds":{"items":{}},"code":{},"details":{},"ruleId":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_associated_budget_rules_for_campaigns":{"post":{"operationId":"ads_create_associated_budget_rules_for_campaigns","summary":"Attach budget rules to one campaign.","description":"Attach budget rules to one campaign. Afterwards verify with ads_list_associated_budget_rules_for_campaigns. Amazon Ads API · CreateAssociatedBudgetRulesForSPCampaigns · POST /sp/campaigns/{campaignId}/budgetRules Amazon Ads API · CreateAssociatedBudgetRulesForSBCampaigns · POST /sb/campaigns/{campaignId}/budgetRules Amazon Ads API · CreateAssociatedBudgetRulesForSDCampaigns · POST /sd/campaigns/{campaignId}/budgetRules Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRules/operation/CreateAssociatedBudgetRulesForSPCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-rules/operation/CreateAssociatedBudgetRulesForSBCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Rules/operation/CreateAssociatedBudgetRulesForSDCampaigns Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_associated_budget_rules_for_campaigns"},"tags":["amazon_ads"],"x-title":"Ads Create Associated Budget Rules for Campaigns","x-access":"destructive","x-family":"ads.sp","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.responses","description":"per id sent, {ruleId, code, details}."}],"x-notes":{"Gotchas":["- A campaign holds at most 250 rules, and every rule attached to","  one campaign must have a unique name."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"body":{"additionalProperties":true,"properties":{"budgetRuleIds":{"items":{"type":"string"},"maxItems":25,"type":"array"}},"title":"Body","type":"object","description":"{budgetRuleIds: [...]} (max 25)."},"campaignId":{"title":"Campaignid","type":"string","description":"the campaign to attach rules to."}},"required":["store","countryCode","adProduct","body","campaignId"],"title":"ads_create_associated_budget_rules_for_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"responses":{"items":{"properties":{"code":{},"details":{},"ruleId":{}}},"description":"per id sent, {ruleId, code, details}."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_disassociate_associated_budget_rule_for_campaigns":{"post":{"operationId":"ads_disassociate_associated_budget_rule_for_campaigns","summary":"Detach one budget rule from one campaign.","description":"Detach one budget rule from one campaign. Confirm the association first with ads_list_associated_budget_rules_for_campaigns. Amazon Ads API · DisassociateAssociatedBudgetRuleForSPCampaigns · DELETE /sp/campaigns/{campaignId}/budgetRules/{budgetRuleId} Amazon Ads API · DisassociateAssociatedBudgetRuleForSBCampaigns · DELETE /sb/campaigns/{campaignId}/budgetRules/{budgetRuleId} Amazon Ads API · DisassociateAssociatedBudgetRuleForSDCampaigns · DELETE /sd/campaigns/{campaignId}/budgetRules/{budgetRuleId} Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRules/operation/DisassociateAssociatedBudgetRuleForSPCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Budget-rules/operation/DisassociateAssociatedBudgetRuleForSBCampaigns Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-display/3-0/openapi#tag/Budget-Rules/operation/DisassociateAssociatedBudgetRuleForSDCampaigns Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_disassociate_associated_budget_rule_for_campaigns"},"tags":["amazon_ads"],"x-title":"Ads Disassociate Associated Budget Rule for Campaigns","x-access":"destructive","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS | SPONSORED_DISPLAY."},"campaignId":{"title":"Campaignid","type":"string","description":"the campaign to detach the rule from."},"budgetRuleId":{"title":"Budgetruleid","type":"string","description":"from ads_list_associated_budget_rules_for_campaigns."}},"required":["store","countryCode","adProduct","campaignId","budgetRuleId"],"title":"ads_disassociate_associated_budget_rule_for_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_budget_rules_recommendation":{"post":{"operationId":"ads_get_budget_rules_recommendation","summary":"Special-event budget-rule recommendations for one EXISTING campaign — Amazon's list of upcoming shopping events (Prime Day etc.) with a suggested budget-increase percent for this c","description":"Special-event budget-rule recommendations for one EXISTING campaign — Amazon's list of upcoming shopping events (Prime Day etc.) with a suggested budget-increase percent for this campaign. For the marketplace's event calendar without a campaign or a suggested percent, use ads_sp_get_all_rule_events. Amazon Ads API · SPGetBudgetRulesRecommendation · POST /sp/campaigns/budgetRules/recommendations Amazon Ads API · SBGetBudgetRulesRecommendation · POST /sb/campaigns/budgetRules/recommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/BudgetRulesRecommendation/operation/SPGetBudgetRulesRecommendation Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi#tag/Budget-Rules-Recommendations/operation/SBGetBudgetRulesRecommendation","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_budget_rules_recommendation"},"tags":["amazon_ads"],"x-title":"Ads Get Budget Rules Recommendation","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.recommendedBudgetRuleEvents[]","description":"{eventId, eventName, startDate, endDate (YYYYMMDD), suggestedBudgetIncreasePercent}."}],"x-notes":{"Gotchas":["- To act on an event, call ads_create_budget_rules_for_campaigns","  with ruleType SCHEDULE and eventTypeRuleDuration {eventId},","  budgetIncreaseBy {type: PERCENT, value: suggested percent}, then","  attach it with ads_create_associated_budget_rules_for_campaigns."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"adProduct":{"title":"Adproduct","type":"string","description":"SPONSORED_PRODUCTS | SPONSORED_BRANDS (Sponsored Display has no rules-recommendation endpoint)."},"campaignId":{"title":"Campaignid","type":"string","description":"ONE campaign id (Amazon takes a single id here) — from ads_query_campaign."}},"required":["store","countryCode","adProduct","campaignId"],"title":"ads_get_budget_rules_recommendationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"recommendedBudgetRuleEvents":{"items":{"properties":{"endDate":{},"eventId":{},"eventName":{},"startDate":{},"suggestedBudgetIncreasePercent":{}}},"description":"{eventId, eventName, startDate, endDate (YYYYMMDD), suggestedBudgetIncreasePercent}."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_sb_get_budget_recommendations":{"post":{"operationId":"ads_sb_get_budget_recommendations","summary":"Daily-budget recommendations and missed-opportunity estimates for EXISTING Sponsored Brands campaigns (SP: ads_sp_get_budget_recommendations; a not-yet-created SP campaign: ads_get","description":"Daily-budget recommendations and missed-opportunity estimates for EXISTING Sponsored Brands campaigns (SP: ads_sp_get_budget_recommendations; a not-yet-created SP campaign: ads_get_budget_recommendation). Amazon Ads API · GetBudgetRecommendations · POST /sb/campaigns/budgetRecommendations Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#tag/Recommendations/operation/GetBudgetRecommendations","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_sb_get_budget_recommendations"},"tags":["amazon_ads"],"x-title":"Ads SB Get Budget Recommendations","x-access":"read","x-family":"ads.sb4","x-returns":[{"description":"207, one result per item; an item whose code is not \"Ok\" (or that is listed under error / failures) failed — read its details."},{"field":"data.result.success[]","description":"{index, campaignId, suggestedBudget, sevenDaysMissedOpportunities{startDate, endDate, percentTimeInBudget, estimatedMissed...}}."},{"field":"data.result.error[]","description":"{index, campaignId, code, details}."}],"x-notes":{"Gotchas":["- Pair each suggestion with live ads_campaigns_budget_usage before","  raising a budget — a campaign nowhere near its cap does not need","  a raise regardless of the recommendation."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaignIds":{"items":{"type":"string"},"maxItems":100,"title":"Campaignids","type":"array","description":"1-100 SB campaign ids, as strings, from ads_query_campaign."}},"required":["store","countryCode","campaignIds"],"title":"ads_sb_get_budget_recommendationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"campaignId":{},"code":{},"details":{},"index":{}}},"description":"{index, campaignId, code, details}."},"success":{"items":{"properties":{"campaignId":{},"index":{},"sevenDaysMissedOpportunities":{"properties":{"endDate":{},"estimatedMissedClicksLower":{},"estimatedMissedClicksUpper":{},"estimatedMissedImpressionsLower":{},"estimatedMissedImpressionsUpper":{},"estimatedMissedSalesLower":{},"estimatedMissedSalesUpper":{},"percentTimeInBudget":{},"startDate":{}}},"suggestedBudget":{}}},"description":"{index, campaignId, suggestedBudget, sevenDaysMissedOpportunities{startDate, endDate, percentTimeInBudget, estimatedMissed...}}."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_budget_recommendation":{"post":{"operationId":"ads_get_budget_recommendation","summary":"Sponsored Products: a daily-budget suggestion for a new campaign, before it exists.","description":"Sponsored Products: a daily-budget suggestion for a new campaign, before it exists. Call before ads_create_campaign to start it with a budget Amazon predicts will not throttle delivery. (Distinct from ads_sp_get_budget_recommendations, which covers existing campaigns.) Amazon Ads API · getBudgetRecommendation · POST /sp/campaigns/initialBudgetRecommendation Docs: https://advertising.amazon.com/API/docs/en-us/sponsored-products/3-0/openapi/prod#tag/Budget-Recommendation-New-Campaigns/operation/getBudgetRecommendation","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_budget_recommendation"},"tags":["amazon_ads"],"x-title":"Ads Get Budget Recommendation","x-access":"read","x-family":"ads.sp","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result.dailyBudget","description":"the suggested daily budget."},{"field":"data.result.specialEvents[]","description":"up to 5 event-period budgets."},{"field":"data.result.benchmark","description":"the expected impressions / clicks / conversions range."}],"x-notes":{"Gotchas":["- Each targetingExpressions item is an OBJECT and needs a bid,","  although Amazon's schema lists only type and value — without","  one Amazon answers 'TargetingExpression bid cannot be null'.","  value carries the keyword text for the KEYWORD_* types.","- targetingType is lowercase ('auto'/'manual') on this endpoint","  only — every other v1 tool uses the uppercase enum."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adGroups":{"items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"asins":{"items":{"type":"string"},"maxItems":50,"minItems":1,"type":"array"},"targetingExpressions":{"description":"max 100 per request","items":{"additionalProperties":true,"properties":{"type":{"enum":["CLOSE_MATCH","COMPLEMENTS","KEYWORD_BROAD_MATCH","KEYWORD_EXACT_MATCH","KEYWORD_PHRASE_MATCH","LOOSE_MATCH","SUBSTITUTES"],"type":"string"},"value":{"type":"string"}},"required":["type"],"type":"object"},"maxItems":100,"minItems":1,"type":"array"}},"required":["asins","targetingExpressions"],"type":"object"},"maxItems":1,"minItems":1,"type":"array"},"bidding":{"additionalProperties":true,"properties":{"adjustments":{"items":{"additionalProperties":true,"properties":{"placementAdjustment":{"additionalProperties":true,"properties":{"percentage":{"maximum":900,"minimum":0,"type":"integer"},"predicate":{"enum":["PLACEMENT_PRODUCT_PAGE","PLACEMENT_REST_OF_SEARCH","PLACEMENT_TOP"],"type":"string"}},"type":"object"}},"type":"object"},"maxItems":2,"minItems":0,"type":"array"},"strategy":{"enum":["AUTO_FOR_SALES","LEGACY_FOR_SALES","MANUAL","RULE_BASED"],"type":"string"}},"required":["strategy"],"type":"object"},"endDate":{"type":"string"},"startDate":{"type":"string"},"targetingType":{"enum":["auto","manual"],"type":"string"}},"required":["adGroups","bidding","targetingType"],"title":"Body","type":"object","description":"{targetingType: 'auto'|'manual', adGroups: [{asins: [...], targetingExpressions: [{type, bid, value?}]}], bidding: {strategy}}."}},"required":["store","countryCode","body"],"title":"ads_get_budget_recommendationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"benchmark":{"properties":{"benchmarkStatus":{},"values":{"properties":{"clicks":{"properties":{"lower":{},"upper":{}}},"conversions":{"properties":{"lower":{},"upper":{}}},"impressions":{"properties":{"lower":{},"upper":{}}}}}},"description":"the expected impressions / clicks / conversions range."},"dailyBudget":{"description":"the suggested daily budget."},"recommendationId":{},"specialEvents":{"items":{"properties":{"benchmark":{"properties":{"benchmarkStatus":{},"values":{"properties":{"clicks":{"properties":{"lower":{},"upper":{}}},"conversions":{"properties":{"lower":{},"upper":{}}},"impressions":{"properties":{"lower":{},"upper":{}}}}}}},"budgetModifier":{},"dailyBudget":{},"endDate":{},"eventKey":{},"eventName":{},"startDate":{}}},"description":"up to 5 event-period budgets."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_query_campaign":{"post":{"operationId":"ads_query_campaign","summary":"Query (read) advertising campaigns across ALL ad products via the unified Amazon Ads API v1 common model — one shape for Sponsored Products, Brands, Display, Television and Amazon ","description":"Query (read) advertising campaigns across ALL ad products via the unified Amazon Ads API v1 common model — one shape for Sponsored Products, Brands, Display, Television and Amazon DSP; the ad product is the `adProduct` field, never a separate tool. Use it for a targeted read of current settings (by id, name or state); for a whole-account dump use ads_campaign_export, and for spend or sales use query_report_data. Amazon Ads API · QueryCampaign · POST /adsApi/v1/query/campaigns Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-campaigns#tag/Campaigns/operation/QueryCampaign","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_query_campaign"},"tags":["amazon_ads"],"x-title":"Ads Query Campaign","x-access":"read","x-family":"ads.v1","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result","description":"the matching campaigns — the server follows nextToken for up to 5 pages; maxResults caps the total."},{"field":"data.nextToken","description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adProductFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"campaignIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"goalFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AWARENESS","CONSIDERATION","CONVERSIONS"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"marketplaceScopeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"maxResults":{"format":"int32","maximum":1000,"minimum":1,"type":"integer"},"nameFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"},"queryTermMatchType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"}},"required":["include","queryTermMatchType"],"type":"object"},"nextToken":{"type":"string"},"portfolioIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"retailerScopeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON","OTHER_RETAILERS"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"stateFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["ARCHIVED","DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"required":["include"],"type":"object"}},"required":["adProductFilter"],"title":"Body","type":"object","description":"the filter object — adProductFilter is required, e.g. {adProductFilter: {include: ['SPONSORED_PRODUCTS']}, stateFilter: {include: ['ENABLED']}}."}},"required":["store","countryCode","body"],"title":"ads_query_campaignArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"campaigns":{"items":{"description":"36 fields (adProduct, adomains, autoCreationSettings, autoScaleGlobalCampaign, brandId, budgets, …) — see the Docs link"}},"nextToken":{}},"description":"the matching campaigns — the server follows nextToken for up to 5 pages; maxResults caps the total."},"nextToken":{"description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_campaign":{"post":{"operationId":"ads_create_campaign","summary":"Create advertising campaigns across ALL ad products via the unified Amazon Ads API v1 common model — one shape for Sponsored Products, Brands, Display, Television and Amazon DSP; t","description":"Create advertising campaigns across ALL ad products via the unified Amazon Ads API v1 common model — one shape for Sponsored Products, Brands, Display, Television and Amazon DSP; the ad product is the `adProduct` field, never a separate tool. Amazon Ads API · CreateCampaign · POST /adsApi/v1/create/campaigns Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-campaigns#tag/Campaigns/operation/CreateCampaign Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_campaign"},"tags":["amazon_ads"],"x-title":"Ads Create Campaign","x-access":"write","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].campaign","description":"each created campaign with its campaignId; index is its position in your list — partialSuccess[] items were created with errors, error[] items were not."}],"x-notes":{"Gotchas":["- To launch a whole Sponsored Products structure (campaign, ad groups, product ads, targets) in one validated call use ads_sp_bulk_create.","- SPONSORED_PRODUCTS also needs marketplaceScope=SINGLE_MARKETPLACE, marketplaces=[the profile's country code — 'GB' for a 'UK' profile] (country codes, not marketplace ids — empty -> 400), startDateTime (ISO 8601 date-time, e.g. '2026-12-01T00:00:00Z'), autoCreationSettings: {autoCreateTargets: true for an auto campaign, false for manual} and budgets: [{budgetType: 'MONETARY', recurrenceTimePeriod: 'DAILY', budgetValue: {monetaryBudgetValue: {monetaryBudget: {value: <amount>}}}}].","- SPONSORED_BRANDS and SPONSORED_DISPLAY also need budgets, costType (SD: CPC | VCPM), marketplaceScope and startDateTime; SPONSORED_TELEVISION budgets and startDateTime; AMAZON_DSP flights and optimizations.","- Create test campaigns PAUSED; delete = archive (Amazon never hard-deletes)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adProduct":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"adomains":{"items":{"type":"string"},"maxItems":2,"minItems":0,"type":"array"},"autoCreationSettings":{"additionalProperties":true,"properties":{"autoCreateTargets":{"type":"boolean"},"autoManageCampaign":{"type":"boolean"}},"type":"object"},"brandId":{"type":"string"},"budgets":{"items":{"additionalProperties":true,"properties":{"budgetType":{"enum":["MONETARY"],"type":"string"},"budgetValue":{"additionalProperties":true,"description":"1 fields (monetaryBudgetValue) — see the Docs link","type":"object"},"recurrenceTimePeriod":{"enum":["DAILY","LIFETIME","MONTHLY"],"type":"string"}},"required":["budgetType","budgetValue","recurrenceTimePeriod"],"type":"object"},"maxItems":2,"minItems":0,"type":"array"},"costType":{"enum":["CPC","CPM","FIXED_PRICE","VCPM"],"type":"string"},"countries":{"items":{"enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","OTHER","OTHER_EEA","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW","ZZ"],"type":"string"},"maxItems":249,"minItems":0,"type":"array"},"endDateTime":{"format":"date-time","type":"string"},"fees":{"items":{"additionalProperties":true,"properties":{"feeType":{"enum":["AGENCY"],"type":"string"},"feeValue":{"format":"double","type":"number"},"feeValueType":{"enum":["PERCENTAGE_OF_BUDGET"],"type":"string"}},"required":["feeType","feeValue","feeValueType"],"type":"object"},"maxItems":1,"minItems":0,"type":"array"},"flights":{"items":{"additionalProperties":true,"properties":{"budget":{"additionalProperties":true,"description":"2 fields (budgetType, budgetValue) — see the Docs link","type":"object"},"endDateTime":{"format":"date-time","type":"string"},"flightId":{"type":"string"},"name":{"type":"string"},"startDateTime":{"format":"date-time","type":"string"}},"required":["budget","endDateTime","startDateTime"],"type":"object"},"maxItems":150,"minItems":0,"type":"array"},"frequencies":{"items":{"additionalProperties":true,"properties":{"eventCount":{"format":"int32","maximum":500,"minimum":1,"type":"integer"},"eventMaxCount":{"format":"int32","maximum":99000,"minimum":1,"type":"integer"},"eventType":{"enum":["IMPRESSION"],"type":"string"},"extraFrequencyCapImpressionTypes":{"items":{"enum":["LinearTVImpression"],"type":"string"},"maxItems":10,"minItems":0,"type":"array"},"frequencyTargetingSetting":{"enum":["HOUSEHOLD","USER"],"type":"string"},"timeCount":{"format":"int32","maximum":60,"minimum":1,"type":"integer"},"timeUnit":{"enum":["DAYS","HOURS","MINUTES"],"type":"string"}},"required":["eventMaxCount","frequencyTargetingSetting","timeCount","timeUnit"],"type":"object"},"maxItems":3,"minItems":0,"type":"array"},"marketplaceConfigurations":{"items":{"additionalProperties":true,"properties":{"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"overrides":{"additionalProperties":true,"description":"6 fields (endDateTime, name, optimizations, startDateTime, state, tags) — see the Docs link","type":"object"}},"required":["marketplace","overrides"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"},"marketplaceScope":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"marketplaces":{"items":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"maxItems":30,"minItems":0,"type":"array"},"name":{"type":"string"},"optimizations":{"additionalProperties":true,"properties":{"bidSettings":{"additionalProperties":true,"description":"2 fields (bidAdjustments, bidStrategy) — see the Docs link","type":"object"},"budgetSettings":{"additionalProperties":true,"description":"3 fields (budgetAllocation, flightBudgetRolloverStrategy, offAmazonBudgetControlStrategy) — see the Docs link","type":"object"},"conversionSettings":{"additionalProperties":true,"description":"1 fields (viewWeight) — see the Docs link","type":"object"},"goalSettings":{"additionalProperties":true,"description":"2 fields (kpi, kpiValue) — see the Docs link","type":"object"},"primaryInventoryTypes":{"items":{"enum":["AUDIO","DISPLAY","VIDEO_OLV","VIDEO_STV"],"type":"string"},"maxItems":10,"minItems":0,"type":"array"}},"type":"object"},"portfolioId":{"type":"string"},"purchaseOrderNumber":{"type":"string"},"retailerScope":{"enum":["AMAZON","OTHER_RETAILERS"],"type":"string"},"salesChannel":{"enum":["AMAZON","OFF_AMAZON"],"type":"string"},"siteRestrictions":{"items":{"enum":["AMAZON_BUSINESS","AMAZON_HAUL"],"type":"string"},"maxItems":1,"minItems":0,"type":"array"},"skanAppId":{"type":"string"},"startDateTime":{"format":"date-time","type":"string"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"},"targetedPGDealId":{"type":"string"}},"required":["adProduct","name","state"],"type":"object"},"maxItems":1000,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {campaigns: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of campaign objects (or {campaigns: [...]})."}},"required":["store","countryCode","body"],"title":"ads_create_campaignArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"campaign":{"description":"36 fields (adProduct, adomains, autoCreationSettings, autoScaleGlobalCampaign, brandId, budgets, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"campaign":{"description":"36 fields (adProduct, adomains, autoCreationSettings, autoScaleGlobalCampaign, brandId, budgets, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_campaign":{"post":{"operationId":"ads_update_campaign","summary":"Update advertising campaigns across ALL ad products via the unified Amazon Ads API v1 common model — one shape for Sponsored Products, Brands, Display, Television and Amazon DSP; t","description":"Update advertising campaigns across ALL ad products via the unified Amazon Ads API v1 common model — one shape for Sponsored Products, Brands, Display, Television and Amazon DSP; the ad product is the `adProduct` field, never a separate tool. Amazon Ads API · UpdateCampaign · POST /adsApi/v1/update/campaigns Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-campaigns#tag/Campaigns/operation/UpdateCampaign Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_campaign"},"tags":["amazon_ads"],"x-title":"Ads Update Campaign","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].campaign","description":"each changed campaign; index is its position in your list — error[] items were not changed."}],"x-notes":{"Gotchas":["- For a budget-only or a state-only change use ads_update_campaign_budget / ads_update_campaign_state.","- budgets replaces the campaign's whole list; each entry is shaped as on create: {budgetType, recurrenceTimePeriod, budgetValue: {monetaryBudgetValue: {monetaryBudget: {value}}}}.","- state is ENABLED or PAUSED on SP, SB, SD and ST (DRAFT and PROPOSED are DSP values); to archive use ads_delete_campaign."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adProduct":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"adomains":{"items":{"type":"string"},"maxItems":2,"minItems":0,"type":"array"},"budgets":{"items":{"additionalProperties":true,"properties":{"budgetType":{"enum":["MONETARY"],"type":"string"},"budgetValue":{"additionalProperties":true,"description":"1 fields (monetaryBudgetValue) — see the Docs link","type":"object"},"recurrenceTimePeriod":{"enum":["DAILY","LIFETIME","MONTHLY"],"type":"string"}},"required":["budgetType","budgetValue","recurrenceTimePeriod"],"type":"object"},"maxItems":2,"minItems":0,"type":"array"},"campaignId":{"type":"string"},"costType":{"enum":["CPC","CPM","FIXED_PRICE","VCPM"],"type":"string"},"countries":{"items":{"enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","OTHER","OTHER_EEA","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW","ZZ"],"type":"string"},"maxItems":249,"minItems":0,"type":"array"},"endDateTime":{"format":"date-time","type":"string"},"fees":{"items":{"additionalProperties":true,"properties":{"feeType":{"enum":["AGENCY"],"type":"string"},"feeValue":{"format":"double","type":"number"},"feeValueType":{"enum":["PERCENTAGE_OF_BUDGET"],"type":"string"}},"required":["feeType","feeValue","feeValueType"],"type":"object"},"maxItems":1,"minItems":0,"type":"array"},"flights":{"items":{"additionalProperties":true,"properties":{"budget":{"additionalProperties":true,"description":"2 fields (budgetType, budgetValue) — see the Docs link","type":"object"},"endDateTime":{"format":"date-time","type":"string"},"flightId":{"type":"string"},"name":{"type":"string"},"startDateTime":{"format":"date-time","type":"string"}},"required":["budget","endDateTime","startDateTime"],"type":"object"},"maxItems":150,"minItems":0,"type":"array"},"frequencies":{"items":{"additionalProperties":true,"properties":{"eventCount":{"format":"int32","maximum":500,"minimum":1,"type":"integer"},"eventMaxCount":{"format":"int32","maximum":99000,"minimum":1,"type":"integer"},"eventType":{"enum":["IMPRESSION"],"type":"string"},"extraFrequencyCapImpressionTypes":{"items":{"enum":["LinearTVImpression"],"type":"string"},"maxItems":10,"minItems":0,"type":"array"},"frequencyTargetingSetting":{"enum":["HOUSEHOLD","USER"],"type":"string"},"timeCount":{"format":"int32","maximum":60,"minimum":1,"type":"integer"},"timeUnit":{"enum":["DAYS","HOURS","MINUTES"],"type":"string"}},"required":["eventMaxCount","frequencyTargetingSetting","timeCount","timeUnit"],"type":"object"},"maxItems":3,"minItems":0,"type":"array"},"marketplaceConfigurations":{"items":{"additionalProperties":true,"properties":{"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"overrides":{"additionalProperties":true,"description":"6 fields (endDateTime, name, optimizations, startDateTime, state, tags) — see the Docs link","type":"object"}},"required":["marketplace","overrides"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"},"marketplaces":{"items":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"maxItems":30,"minItems":0,"type":"array"},"name":{"type":"string"},"optimizations":{"additionalProperties":true,"properties":{"bidSettings":{"additionalProperties":true,"description":"2 fields (bidAdjustments, bidStrategy) — see the Docs link","type":"object"},"budgetSettings":{"additionalProperties":true,"description":"3 fields (budgetAllocation, flightBudgetRolloverStrategy, offAmazonBudgetControlStrategy) — see the Docs link","type":"object"},"conversionSettings":{"additionalProperties":true,"description":"1 fields (viewWeight) — see the Docs link","type":"object"},"goalSettings":{"additionalProperties":true,"description":"2 fields (kpi, kpiValue) — see the Docs link","type":"object"},"primaryInventoryTypes":{"items":{"enum":["AUDIO","DISPLAY","VIDEO_OLV","VIDEO_STV"],"type":"string"},"maxItems":10,"minItems":0,"type":"array"}},"type":"object"},"portfolioId":{"type":"string"},"purchaseOrderNumber":{"type":"string"},"siteRestrictions":{"items":{"enum":["AMAZON_BUSINESS","AMAZON_HAUL"],"type":"string"},"maxItems":1,"minItems":0,"type":"array"},"skanAppId":{"type":"string"},"startDateTime":{"format":"date-time","type":"string"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"},"targetedPGDealId":{"type":"string"}},"required":["campaignId"],"type":"object"},"maxItems":1000,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {campaigns: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of {campaignId*, ...fields to change} (or {campaigns: [...]}) — never adProduct: Amazon refuses it on an update (measured 2026-10-26)."}},"required":["store","countryCode","body"],"title":"ads_update_campaignArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"campaign":{"description":"36 fields (adProduct, adomains, autoCreationSettings, autoScaleGlobalCampaign, brandId, budgets, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"campaign":{"description":"36 fields (adProduct, adomains, autoCreationSettings, autoScaleGlobalCampaign, brandId, budgets, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_campaign":{"post":{"operationId":"ads_delete_campaign","summary":"Delete (archive) advertising campaigns across ALL ad products via the unified Amazon Ads API v1 common model — one shape for Sponsored Products, Brands, Display, Television and Ama","description":"Delete (archive) advertising campaigns across ALL ad products via the unified Amazon Ads API v1 common model — one shape for Sponsored Products, Brands, Display, Television and Amazon DSP; the ad product is the `adProduct` field, never a separate tool. Amazon Ads API · DeleteCampaign · POST /adsApi/v1/delete/campaigns Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-campaigns#tag/Campaigns/operation/DeleteCampaign Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_campaign"},"tags":["amazon_ads"],"x-title":"Ads Delete Campaign","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].campaign","description":"each deleted campaign; error[] items were not."}],"x-notes":{"Gotchas":["- Delete = archive (state -> ARCHIVED); the campaign stays queryable, it is never hard-deleted.","- Only SPONSORED_PRODUCTS, SPONSORED_BRANDS and SPONSORED_DISPLAY campaigns can be deleted (no Television or DSP delete); SB takes at most 10 ids per call, SD 100."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"campaignIds":{"items":{"type":"string"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["campaignIds"],"title":"Body","type":"object","description":"{campaignIds: [...]} — a plain ID array, not a filter."}},"required":["store","countryCode","body"],"title":"ads_delete_campaignArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"campaign":{"description":"36 fields (adProduct, adomains, autoCreationSettings, autoScaleGlobalCampaign, brandId, budgets, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"campaign":{"description":"36 fields (adProduct, adomains, autoCreationSettings, autoScaleGlobalCampaign, brandId, budgets, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_query_ad_group":{"post":{"operationId":"ads_query_ad_group","summary":"Query (read) ad groups across ALL ad products via the unified Amazon Ads API v1 (adProduct is a payload field; one shape for SP/SB/SD/ST/DSP).","description":"Query (read) ad groups across ALL ad products via the unified Amazon Ads API v1 (adProduct is a payload field; one shape for SP/SB/SD/ST/DSP). Use it for a targeted read of current settings (by id, name or state); for a whole-account dump use ads_ad_group_export, and for spend or sales use query_report_data. Amazon Ads API · QueryAdGroup · POST /adsApi/v1/query/adGroups Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adgroups#tag/AdGroups/operation/QueryAdGroup","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_query_ad_group"},"tags":["amazon_ads"],"x-title":"Ads Query Ad Group","x-access":"read","x-family":"ads.v1","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result","description":"the matching ad groups — the server follows nextToken for up to 5 pages; maxResults caps the total."},{"field":"data.nextToken","description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adGroupIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"adProductFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"campaignIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"inventoryTypeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AAP_MOBILE_APP","ALEXA_DEVICES","ALL","AMAZON_MOBILE_DISPLAY","AUDIO","AUDIO_AMAZON_DEAL","DIGITAL_OUT_OF_HOME","DISPLAY","LIVE_EVENTS","MOBILE_DISPLAY","NATIVE","ONLINE_VIDEO","PODCAST","STANDARD_DISPLAY","STREAMING_TV","STREAMING_TV_AMAZON_DEAL","VIDEO"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"marketplaceScopeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"maxResults":{"format":"int32","maximum":1000,"minimum":1,"type":"integer"},"nameFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"},"queryTermMatchType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"}},"required":["include","queryTermMatchType"],"type":"object"},"nextToken":{"type":"string"},"retailerScopeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON","OTHER_RETAILERS"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"stateFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["ARCHIVED","DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"required":["include"],"type":"object"}},"required":["adProductFilter"],"title":"Body","type":"object","description":"the filter object — adProductFilter is required, e.g. {adProductFilter: {include: ['SPONSORED_PRODUCTS']}, campaignIdFilter: {include: ['<campaignId>']}}."}},"required":["store","countryCode","body"],"title":"ads_query_ad_groupArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"adGroups":{"items":{"properties":{"adGroupId":{},"adProduct":{},"adSettings":{"description":"1 fields (productAttributeSetRefinementConfigurationId) — see the Docs link"},"advertisedProductCategoryIds":{"items":{}},"bid":{"description":"5 fields (baseBid, currencyCode, defaultBid, marketplaceSettings, maxAverageBid) — see the Docs link"},"budgets":{"items":{"description":"3 fields (budgetType, budgetValue, recurrenceTimePeriod) — see the Docs link"}},"campaignId":{},"creationDateTime":{},"creativeRotationType":{},"creativeType":{},"endDateTime":{},"fees":{"items":{"description":"6 fields (addToBudgetSpentAmount, currencyCode, feeType, feeValue, feeValueType, thirdPartyProvider) — see the Docs link"}},"frequencies":{"items":{"description":"7 fields (eventCount, eventMaxCount, eventType, extraFrequencyCapImpressionTypes, frequencyTargetingSetting, timeCount, …) — see the Docs link"}},"globalAdGroupId":{},"inventoryType":{},"lastUpdatedDateTime":{},"marketplaceConfigurations":{"items":{"description":"3 fields (adGroupId, marketplace, overrides) — see the Docs link"}},"marketplaceScope":{},"marketplaces":{"items":{}},"name":{},"optimization":{"description":"3 fields (bidStrategy, budgetSettings, goalSettings) — see the Docs link"},"pacing":{"description":"1 fields (deliveryProfile) — see the Docs link"},"purchaseOrderNumber":{},"retailerId":{},"retailerScope":{},"startDateTime":{},"state":{},"status":{"description":"3 fields (deliveryReasons, deliveryStatus, marketplaceSettings) — see the Docs link"},"tags":{"items":{"description":"2 fields (key, value) — see the Docs link"}},"targetingSettings":{"description":"10 fields (amazonViewability, automatedTargetingTactic, defaultAudienceTargetingMatchType, enableLanguageTargeting, siteLanguage, tacticsConvertersExclusionType, …) — see the Docs link"}}}},"nextToken":{}},"description":"the matching ad groups — the server follows nextToken for up to 5 pages; maxResults caps the total."},"nextToken":{"description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_ad_group":{"post":{"operationId":"ads_create_ad_group","summary":"Create ad groups across ALL ad products via the unified Amazon Ads API v1 (adProduct is a payload field; one shape for SP/SB/SD/ST/DSP).","description":"Create ad groups across ALL ad products via the unified Amazon Ads API v1 (adProduct is a payload field; one shape for SP/SB/SD/ST/DSP). Amazon Ads API · CreateAdGroup · POST /adsApi/v1/create/adGroups Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adgroups#tag/AdGroups/operation/CreateAdGroup Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_ad_group"},"tags":["amazon_ads"],"x-title":"Ads Create Ad Group","x-access":"write","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].adGroup","description":"each created ad group with its adGroupId; index is its position in your list — partialSuccess[] items were created with errors, error[] items were not."}],"x-notes":{"Gotchas":["- The parent campaign must already exist (ads_create_campaign).","- SPONSORED_PRODUCTS also requires bid: {defaultBid: <amount>} — the ad group's default max bid; SPONSORED_DISPLAY requires marketplaceScope and marketplaces ('GB' for a 'UK' profile)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adProduct":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"adSettings":{"additionalProperties":true,"properties":{"productAttributeSetRefinementConfigurationId":{"type":"string"}},"type":"object"},"advertisedProductCategoryIds":{"items":{"type":"string"},"maxItems":500,"minItems":0,"type":"array"},"bid":{"additionalProperties":true,"properties":{"baseBid":{"format":"double","type":"number"},"defaultBid":{"format":"double","type":"number"},"marketplaceSettings":{"items":{"additionalProperties":true,"description":"3 fields (currencyCode, defaultBid, marketplace) — see the Docs link","type":"object"},"maxItems":30,"minItems":0,"type":"array"},"maxAverageBid":{"format":"double","type":"number"}},"type":"object"},"budgets":{"items":{"additionalProperties":true,"properties":{"budgetType":{"enum":["MONETARY"],"type":"string"},"budgetValue":{"additionalProperties":true,"description":"1 fields (monetaryBudgetValue) — see the Docs link","type":"object"},"recurrenceTimePeriod":{"enum":["DAILY","LIFETIME","MONTHLY"],"type":"string"}},"required":["budgetType","budgetValue","recurrenceTimePeriod"],"type":"object"},"maxItems":3,"minItems":0,"type":"array"},"campaignId":{"type":"string"},"creativeRotationType":{"enum":["RANDOM","WEIGHTED"],"type":"string"},"creativeType":{"enum":["IMAGE","VIDEO"],"type":"string"},"endDateTime":{"format":"date-time","type":"string"},"fees":{"items":{"additionalProperties":true,"properties":{"addToBudgetSpentAmount":{"type":"boolean"},"feeType":{"enum":["AMAZON_AUDIENCE","AMAZON_DSP","MANAGED_SERVICE_FEE","OMNICHANNEL_METRICS","THIRD_PARTY_APPLIED","THIRD_PARTY_AUDIENCE","THIRD_PARTY_TARGETING"],"type":"string"},"feeValue":{"format":"double","type":"number"},"thirdPartyProvider":{"enum":["COM_SCORE","CPM_1","CPM_2","CPM_3","DOUBLE_CLICK_CAMPAIGN_MANAGER","DOUBLE_VERIFY","INTEGRAL_AD_SCIENCE"],"type":"string"}},"required":["addToBudgetSpentAmount","feeType","feeValue","thirdPartyProvider"],"type":"object"},"maxItems":7,"minItems":0,"type":"array"},"frequencies":{"items":{"additionalProperties":true,"properties":{"eventCount":{"format":"int32","maximum":500,"minimum":1,"type":"integer"},"eventMaxCount":{"format":"int32","maximum":99000,"minimum":1,"type":"integer"},"eventType":{"enum":["IMPRESSION"],"type":"string"},"extraFrequencyCapImpressionTypes":{"items":{"enum":["LinearTVImpression"],"type":"string"},"maxItems":10,"minItems":0,"type":"array"},"frequencyTargetingSetting":{"enum":["HOUSEHOLD","USER"],"type":"string"},"timeCount":{"format":"int32","maximum":60,"minimum":1,"type":"integer"},"timeUnit":{"enum":["DAYS","HOURS","MINUTES"],"type":"string"}},"required":["eventMaxCount","frequencyTargetingSetting","timeCount","timeUnit"],"type":"object"},"maxItems":3,"minItems":0,"type":"array"},"inventoryType":{"enum":["AAP_MOBILE_APP","ALEXA_DEVICES","ALL","AMAZON_MOBILE_DISPLAY","AUDIO","AUDIO_AMAZON_DEAL","DIGITAL_OUT_OF_HOME","DISPLAY","LIVE_EVENTS","MOBILE_DISPLAY","NATIVE","ONLINE_VIDEO","PODCAST","STANDARD_DISPLAY","STREAMING_TV","STREAMING_TV_AMAZON_DEAL","VIDEO"],"type":"string"},"marketplaceConfigurations":{"items":{"additionalProperties":true,"properties":{"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"overrides":{"additionalProperties":true,"description":"3 fields (name, state, tags) — see the Docs link","type":"object"}},"required":["marketplace","overrides"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"},"marketplaceScope":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"marketplaces":{"items":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"maxItems":30,"minItems":0,"type":"array"},"name":{"type":"string"},"optimization":{"additionalProperties":true,"properties":{"bidStrategy":{"enum":["MANUAL","NEW_TO_BRAND","PRIORITIZE_KPI_TARGET","RULE_BASED","SALES_DOWN_ONLY","SALES_UP_AND_DOWN","SPEND_BUDGET_IN_FULL","USE_CAMPAIGN_STRATEGY"],"type":"string"},"budgetSettings":{"additionalProperties":true,"description":"2 fields (budgetAllocation, dailyMinSpendValue) — see the Docs link","type":"object"},"goalSettings":{"additionalProperties":true,"description":"1 fields (kpi) — see the Docs link","type":"object"}},"type":"object"},"pacing":{"additionalProperties":true,"properties":{"deliveryProfile":{"enum":["ASAP","EVEN","PACE_AHEAD"],"type":"string"}},"required":["deliveryProfile"],"type":"object"},"purchaseOrderNumber":{"type":"string"},"retailerId":{"type":"string"},"startDateTime":{"format":"date-time","type":"string"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"},"targetingSettings":{"additionalProperties":true,"properties":{"amazonViewability":{"additionalProperties":true,"description":"2 fields (includeUnmeasurableImpressions, viewabilityTier) — see the Docs link","type":"object"},"automatedTargetingTactic":{"enum":["AWARENESS","CUSTOMER_ACQUISITION","MAXIMIZE_PERFORMANCE","PROSPECTING","REMARKETING","RETENTION","SEARCH"],"type":"string"},"defaultAudienceTargetingMatchType":{"enum":["EXACT","SIMILAR"],"type":"string"},"enableLanguageTargeting":{"type":"boolean"},"tacticsConvertersExclusionType":{"enum":["NO_EXCLUSION","RECENT_CONVERTERS"],"type":"string"},"targetedPGDealId":{"type":"string"},"timeZoneType":{"enum":["ADVERTISER_REGION","VIEWER"],"type":"string"},"userLocationSignal":{"enum":["CURRENT","MULTIPLE_SIGNALS"],"type":"string"},"videoCompletionTier":{"enum":["ALL_TIERS","GREATER_THAN_10_PERCENT","GREATER_THAN_20_PERCENT","GREATER_THAN_30_PERCENT","GREATER_THAN_40_PERCENT","GREATER_THAN_50_PERCENT","GREATER_THAN_60_PERCENT","GREATER_THAN_70_PERCENT","GREATER_THAN_80_PERCENT","GREATER_THAN_90_PERCENT"],"type":"string"}},"required":["amazonViewability","timeZoneType","userLocationSignal"],"type":"object"}},"required":["adProduct","campaignId","name","state"],"type":"object"},"maxItems":1000,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {adGroups: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of ad-group objects (or {adGroups: [...]})."}},"required":["store","countryCode","body"],"title":"ads_create_ad_groupArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"adGroup":{"description":"30 fields (adGroupId, adProduct, adSettings, advertisedProductCategoryIds, bid, budgets, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"adGroup":{"description":"30 fields (adGroupId, adProduct, adSettings, advertisedProductCategoryIds, bid, budgets, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_ad_group":{"post":{"operationId":"ads_update_ad_group","summary":"Update ad groups across ALL ad products via the unified Amazon Ads API v1 (adProduct is a payload field; one shape for SP/SB/SD/ST/DSP).","description":"Update ad groups across ALL ad products via the unified Amazon Ads API v1 (adProduct is a payload field; one shape for SP/SB/SD/ST/DSP). Amazon Ads API · UpdateAdGroup · POST /adsApi/v1/update/adGroups Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adgroups#tag/AdGroups/operation/UpdateAdGroup Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_ad_group"},"tags":["amazon_ads"],"x-title":"Ads Update Ad Group","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].adGroup","description":"each changed ad group; index is its position in your list — error[] items were not changed."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"adProduct":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"adSettings":{"additionalProperties":true,"properties":{"productAttributeSetRefinementConfigurationId":{"type":"string"}},"type":"object"},"advertisedProductCategoryIds":{"items":{"type":"string"},"maxItems":500,"minItems":0,"type":"array"},"bid":{"additionalProperties":true,"properties":{"baseBid":{"format":"double","type":"number"},"defaultBid":{"format":"double","type":"number"},"marketplaceSettings":{"items":{"additionalProperties":true,"properties":{"currencyCode":{"enum":["AED","ARS","AUD","BGN","BHD","BOB","BRL","CAD","CHF","CLP","CNY","COP","CRC","CZK","DKK","DOP","DZD","EGP","EUR","GBP","GTQ","HKD","HNL","HRK","HUF","IDR","ILS","INR","JMD","JOD","JPY","KRW","KWD","MAD","MXN","MXP","MYR","NGN","NOK","NZD","PAB","PEN","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","SAR","SEK","SGD","THB","TND","TRY","TWD","UAH","USD","UYU","VND","ZAR"],"type":"string"},"defaultBid":{"format":"double","type":"number"},"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"}},"required":["currencyCode","marketplace"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"},"maxAverageBid":{"format":"double","type":"number"}},"type":"object"},"budgets":{"items":{"additionalProperties":true,"properties":{"budgetType":{"enum":["MONETARY"],"type":"string"},"budgetValue":{"additionalProperties":true,"properties":{"monetaryBudgetValue":{"additionalProperties":true,"properties":{"marketplaceSettings":{"items":{"additionalProperties":true,"description":"2 fields (marketplace, monetaryBudget) — see the Docs link","type":"object"},"maxItems":30,"minItems":0,"type":"array"},"monetaryBudget":{"additionalProperties":true,"description":"3 fields (currencyCode, ruleValue, value) — see the Docs link","type":"object"}},"type":"object"}},"required":["monetaryBudgetValue"],"type":"object"},"recurrenceTimePeriod":{"enum":["DAILY","LIFETIME","MONTHLY"],"type":"string"}},"required":["budgetType","budgetValue","recurrenceTimePeriod"],"type":"object"},"maxItems":3,"minItems":0,"type":"array"},"creativeRotationType":{"enum":["RANDOM","WEIGHTED"],"type":"string"},"endDateTime":{"format":"date-time","type":"string"},"fees":{"items":{"additionalProperties":true,"properties":{"addToBudgetSpentAmount":{"type":"boolean"},"feeType":{"enum":["AMAZON_AUDIENCE","AMAZON_DSP","MANAGED_SERVICE_FEE","OMNICHANNEL_METRICS","THIRD_PARTY_APPLIED","THIRD_PARTY_AUDIENCE","THIRD_PARTY_TARGETING"],"type":"string"},"feeValue":{"format":"double","type":"number"},"thirdPartyProvider":{"enum":["COM_SCORE","CPM_1","CPM_2","CPM_3","DOUBLE_CLICK_CAMPAIGN_MANAGER","DOUBLE_VERIFY","INTEGRAL_AD_SCIENCE"],"type":"string"}},"required":["addToBudgetSpentAmount","feeType","feeValue","thirdPartyProvider"],"type":"object"},"maxItems":7,"minItems":0,"type":"array"},"frequencies":{"items":{"additionalProperties":true,"properties":{"eventCount":{"format":"int32","maximum":500,"minimum":1,"type":"integer"},"eventMaxCount":{"format":"int32","maximum":99000,"minimum":1,"type":"integer"},"eventType":{"enum":["IMPRESSION"],"type":"string"},"extraFrequencyCapImpressionTypes":{"items":{"enum":["LinearTVImpression"],"type":"string"},"maxItems":10,"minItems":0,"type":"array"},"frequencyTargetingSetting":{"enum":["HOUSEHOLD","USER"],"type":"string"},"timeCount":{"format":"int32","maximum":60,"minimum":1,"type":"integer"},"timeUnit":{"enum":["DAYS","HOURS","MINUTES"],"type":"string"}},"required":["eventMaxCount","frequencyTargetingSetting","timeCount","timeUnit"],"type":"object"},"maxItems":3,"minItems":0,"type":"array"},"marketplaceConfigurations":{"items":{"additionalProperties":true,"properties":{"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"overrides":{"additionalProperties":true,"properties":{"name":{"type":"string"},"state":{"enum":["ARCHIVED","DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"}},"type":"object"}},"required":["marketplace","overrides"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"},"marketplaceScope":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"marketplaces":{"items":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"maxItems":30,"minItems":0,"type":"array"},"name":{"type":"string"},"optimization":{"additionalProperties":true,"properties":{"bidStrategy":{"enum":["MANUAL","NEW_TO_BRAND","PRIORITIZE_KPI_TARGET","RULE_BASED","SALES_DOWN_ONLY","SALES_UP_AND_DOWN","SPEND_BUDGET_IN_FULL","USE_CAMPAIGN_STRATEGY"],"type":"string"},"budgetSettings":{"additionalProperties":true,"properties":{"budgetAllocation":{"enum":["AUTO","MANUAL"],"type":"string"},"dailyMinSpendValue":{"format":"double","type":"number"}},"type":"object"},"goalSettings":{"additionalProperties":true,"properties":{"kpi":{"enum":["ADD_TO_CART","APPLICATIONS","CHECKOUTS","CLICKS","CLICK_THROUGH_RATE","COMBINED_RETURN_ON_AD_SPEND","CONTACTS","COST_PER_ACTION","COST_PER_CLICK","COST_PER_CONVERSION_OFF_AMAZON","COST_PER_DETAIL_PAGE_VIEW","COST_PER_FIRST_APP_OPEN","COST_PER_INSTALL","COST_PER_SIGN_UP","COST_PER_VIDEO_COMPLETION","DETAIL_PAGE_VIEW_RATE","FREQUENCY_AVERAGE","LEADS","OTHER","PAGE_VIEWS","PURCHASES","REACH","RETURN_ON_AD_SPEND","ROAS","ROAS_COMBINED","ROAS_OFF_AMAZON","ROAS_PROMOTED","SEARCH","SIGN_UP","SUBSCRIBE","TOP_OF_SEARCH_IMPRESSION_SHARE","TOTAL_RETURN_ON_AD_SPEND","VIDEO_COMPLETION_RATE"],"type":"string"}},"type":"object"}},"type":"object"},"pacing":{"additionalProperties":true,"properties":{"deliveryProfile":{"enum":["ASAP","EVEN","PACE_AHEAD"],"type":"string"}},"type":"object"},"purchaseOrderNumber":{"type":"string"},"startDateTime":{"format":"date-time","type":"string"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"},"targetingSettings":{"additionalProperties":true,"properties":{"amazonViewability":{"additionalProperties":true,"properties":{"includeUnmeasurableImpressions":{"type":"boolean"},"viewabilityTier":{"enum":["ALL_TIERS","GREATER_THAN_40_PERCENT","GREATER_THAN_50_PERCENT","GREATER_THAN_60_PERCENT","GREATER_THAN_70_PERCENT","LESS_THAN_40_PERCENT"],"type":"string"}},"type":"object"},"defaultAudienceTargetingMatchType":{"enum":["EXACT","SIMILAR"],"type":"string"},"enableLanguageTargeting":{"type":"boolean"},"tacticsConvertersExclusionType":{"enum":["NO_EXCLUSION","RECENT_CONVERTERS"],"type":"string"},"targetedPGDealId":{"type":"string"},"timeZoneType":{"enum":["ADVERTISER_REGION","VIEWER"],"type":"string"},"userLocationSignal":{"enum":["CURRENT","MULTIPLE_SIGNALS"],"type":"string"},"videoCompletionTier":{"enum":["ALL_TIERS","GREATER_THAN_10_PERCENT","GREATER_THAN_20_PERCENT","GREATER_THAN_30_PERCENT","GREATER_THAN_40_PERCENT","GREATER_THAN_50_PERCENT","GREATER_THAN_60_PERCENT","GREATER_THAN_70_PERCENT","GREATER_THAN_80_PERCENT","GREATER_THAN_90_PERCENT"],"type":"string"}},"type":"object"}},"required":["adGroupId"],"type":"object"},"maxItems":1000,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {adGroups: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of {adGroupId*, ...fields to change} (or {adGroups: [...]}) — a bid change is bid: {defaultBid: <amount>}, not a bare number."}},"required":["store","countryCode","body"],"title":"ads_update_ad_groupArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"adGroup":{"description":"30 fields (adGroupId, adProduct, adSettings, advertisedProductCategoryIds, bid, budgets, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"adGroup":{"description":"30 fields (adGroupId, adProduct, adSettings, advertisedProductCategoryIds, bid, budgets, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_ad_group":{"post":{"operationId":"ads_delete_ad_group","summary":"Delete (archive) ad groups across ALL ad products via the unified Amazon Ads API v1 (adProduct is a payload field; one shape for SP/SB/SD/ST/DSP).","description":"Delete (archive) ad groups across ALL ad products via the unified Amazon Ads API v1 (adProduct is a payload field; one shape for SP/SB/SD/ST/DSP). Amazon Ads API · DeleteAdGroup · POST /adsApi/v1/delete/adGroups Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adgroups#tag/AdGroups/operation/DeleteAdGroup Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_ad_group"},"tags":["amazon_ads"],"x-title":"Ads Delete Ad Group","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].adGroup","description":"each deleted ad group; error[] items were not."}],"x-notes":{"Gotchas":["- Delete = archive (state -> ARCHIVED); the ad group stays queryable.","- Only SPONSORED_PRODUCTS, SPONSORED_BRANDS and SPONSORED_DISPLAY ad groups can be deleted; SB takes at most 10 ids per call, SD 100."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adGroupIds":{"items":{"type":"string"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["adGroupIds"],"title":"Body","type":"object","description":"{adGroupIds: [...]} — an ID array, not a filter."}},"required":["store","countryCode","body"],"title":"ads_delete_ad_groupArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"adGroup":{"description":"30 fields (adGroupId, adProduct, adSettings, advertisedProductCategoryIds, bid, budgets, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"adGroup":{"description":"30 fields (adGroupId, adProduct, adSettings, advertisedProductCategoryIds, bid, budgets, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_query_target":{"post":{"operationId":"ads_query_target","summary":"Query (read) targets across ALL ad products via the unified Amazon Ads API v1 — keywords, product and category targets, audiences, themes and locations, and every negative (negativ","description":"Query (read) targets across ALL ad products via the unified Amazon Ads API v1 — keywords, product and category targets, audiences, themes and locations, and every negative (negative=true, ad-group or campaign level); there is no separate keywords entity in v1. Use it for a targeted read of current settings (by id, name or state); for a whole-account dump use ads_target_export, and for spend or sales use query_report_data. Amazon Ads API · QueryTarget · POST /adsApi/v1/query/targets Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-targets#tag/Targets/operation/QueryTarget","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_query_target"},"tags":["amazon_ads"],"x-title":"Ads Query Target","x-access":"read","x-family":"ads.v1","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result","description":"the matching targets — the server follows nextToken for up to 5 pages; maxResults caps the total."},{"field":"data.nextToken","description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adGroupIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"adProductFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"campaignIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"inventorySourceIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"additionalProperties":true,"properties":{"defaultValue":{"type":"string"}},"type":"object"},"maxItems":10,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"inventorySourceTypeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON","APD","DEAL","INVENTORY_GROUP","THIRD_PARTY_EXCHANGE"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"keywordFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"},"queryTermMatchType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"}},"required":["include","queryTermMatchType"],"type":"object"},"marketplaceScopeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"matchTypeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["BROAD","EXACT","INTERESTED_AUDIENCE","KEYWORDS_CLOSE_MATCH","KEYWORDS_LOOSE_MATCH","KEYWORDS_RELATED_TO_GIFTS","KEYWORDS_RELATED_TO_PEER_BRANDS_PRODUCT_CATEGORY","KEYWORDS_RELATED_TO_PRIME_DAY","KEYWORDS_RELATED_TO_YOUR_BRAND","KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES","KEYWORDS_RELATED_TO_YOUR_PRODUCT_CATEGORY","PHRASE","PRODUCTS_SIMILAR_TO_ADVERTISED_PRODUCTS","PRODUCT_COMPLEMENTS","PRODUCT_EXACT","PRODUCT_REMARKETING","PRODUCT_SIMILAR","PRODUCT_SUBSTITUTES"],"type":"string"},"maxItems":10,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"maxResults":{"format":"int32","maximum":5000,"minimum":1,"type":"integer"},"nativeLanguageLocaleFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["aa_ET","ab_GE","ae_INT","af_ZA","ak_GH","am_ET","an_ES","ar_AE","as_IN","av_RU","ay_BO","az_AZ","ba_RU","be_BY","bg_BG","bh_IN","bi_VU","bm_ML","bn_BD","bo_CN","br_FR","bs_BA","ca_ES","ce_RU","ch_GU","co_FR","cr_CA","cs_CZ","cu_INT","cv_RU","cy_GB","da_DK","de_DE","dv_MV","dz_BT","ee_GH","el_GR","en_US","eo_INT","es_ES","et_EE","eu_ES","fa_IR","ff_SN","fi_FI","fj_FJ","fo_FO","fr_FR","fy_NL","ga_IE","gd_GB","gl_ES","gn_PY","gu_IN","gv_IM","ha_NG","he_IL","hi_IN","ho_PG","hr_HR","ht_HT","hu_HU","hy_AM","hz_NA","ia_INT","id_ID","ie_INT","ig_NG","ii_CN","ik_US","io_INT","is_IS","it_IT","iu_CA","iw_IL","ja_JP","ji_IL","jv_ID","ka_GE","kg_CD","ki_KE","kj_NA","kk_KZ","kl_GL","km_KH","kn_IN","ko_KR","kr_NG","ks_IN","ku_TR","kv_RU","kw_GB","ky_KG","la_VA","lb_LU","lg_UG","li_NL","ln_CD","lo_LA","lt_LT","lu_CD","lv_LV","mg_MG","mh_MH","mi_NZ","mk_MK","ml_IN","mn_MN","mo_MD","mr_IN","ms_MY","mt_MT","my_MM","na_NR","nb_NO","nd_ZW","ne_NP","ng_NA","nl_NL","nn_NO","no_NO","nr_ZA","nv_US","ny_MW","oc_FR","oj_CA","om_ET","or_IN","os_RU","pa_IN","pi_IN","pl_PL","ps_AF","pt_PT","qu_PE","rm_CH","rn_BI","ro_RO","ru_RU","rw_RW","sa_IN","sc_IT","sd_PK","se_NO","sg_CF","si_LK","sk_SK","sl_SI","sm_WS","sn_ZW","so_SO","sq_AL","sr_RS","ss_SZ","st_LS","su_ID","sv_SE","sw_TZ","ta_IN","te_IN","tg_TJ","th_TH","ti_ET","tk_TM","tl_PH","tn_BW","to_TO","tr_TR","ts_ZA","tt_RU","tw_GH","ty_PF","ug_CN","uk_UA","ur_PK","uz_UZ","ve_ZA","vi_VN","vo_INT","wa_BE","wo_SN","xh_ZA","yi_IL","yo_NG","za_CN","zh_CN","zu_ZA"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"negativeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"boolean"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"nextToken":{"type":"string"},"productIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"},"queryTermMatchType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"}},"required":["include","queryTermMatchType"],"type":"object"},"retailerIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"retailerScopeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON","OTHER_RETAILERS"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"stateFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["ARCHIVED","DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"targetIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"targetTypeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AD_INITIATION","AD_PLAYER_SIZE","APP","AUDIENCE","BRAND_SAFETY_CATEGORY","BRAND_SAFETY_TIER","CONTENT_CATEGORY","CONTENT_GENRE","CONTENT_INSTREAM_POSITION","CONTENT_OUTSTREAM_POSITION","CONTENT_RATING","DAYPART","DEVICE","DOMAIN","FOLD_POSITION","INVENTORY_SOURCE","KEYWORD","LOCATION","NATIVE_CONTENT_POSITION","PLACEMENT_TYPE","PRODUCT","PRODUCT_AUDIENCE","PRODUCT_CATEGORY","THEME","THIRD_PARTY","VIDEO_AD_FORMAT","VIDEO_CONTENT_DURATION"],"type":"string"},"maxItems":17,"minItems":1,"type":"array"}},"required":["include"],"type":"object"}},"required":["adProductFilter"],"title":"Body","type":"object","description":"the filter object — adProductFilter is required; e.g. {adProductFilter: {include: ['SPONSORED_PRODUCTS']}, adGroupIdFilter: {include: ['<adGroupId>']}, negativeFilter: {include: [true]}} lists that ad group's negative targets; targetTypeFilter {include: ['KEYWORD']} and keywordFilter {include: [...], queryTermMatchType: EXACT_MATCH | BROAD_MATCH} narrow further."}},"required":["store","countryCode","body"],"title":"ads_query_targetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"nextToken":{},"targets":{"items":{"description":"19 fields (adGroupId, adProduct, bid, campaignId, creationDateTime, globalTargetId, …) — see the Docs link"}},"totalResults":{}},"description":"the matching targets — the server follows nextToken for up to 5 pages; maxResults caps the total."},"nextToken":{"description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_target":{"post":{"operationId":"ads_create_target","summary":"Create targets across ALL ad products via the unified Amazon Ads API v1 — keywords, product and category targets, audiences, themes and locations, and every negative (negative=true","description":"Create targets across ALL ad products via the unified Amazon Ads API v1 — keywords, product and category targets, audiences, themes and locations, and every negative (negative=true, ad-group or campaign level); there is no separate keywords entity in v1. Amazon Ads API · CreateTarget · POST /adsApi/v1/create/targets Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-targets#tag/Targets/operation/CreateTarget Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_target"},"tags":["amazon_ads"],"x-title":"Ads Create Target","x-access":"write","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].target","description":"each created target with its targetId; index is its position in your list — partialSuccess[] items were created with errors, error[] items were not."}],"x-notes":{"Gotchas":["- negative=false is a biddable target; true is a negative (block) target. Set campaignId + adGroupId for an ad-group-level target; set campaignId and OMIT adGroupId for a CAMPAIGN-LEVEL target (e.g. a campaign negative keyword; SPONSORED_PRODUCTS and SPONSORED_DISPLAY only — SB, ST and DSP targets require adGroupId) — Amazon echoes targetLevel: CAMPAIGN.","- targetType by ad product: SP KEYWORD | PRODUCT | PRODUCT_CATEGORY | THEME | LOCATION; SB KEYWORD | PRODUCT | PRODUCT_CATEGORY | THEME; SD AUDIENCE | CONTENT_CATEGORY | KEYWORD | LOCATION | PRODUCT | PRODUCT_AUDIENCE | PRODUCT_CATEGORY | THEME; ST AUDIENCE | LOCATION; every other value is AMAZON_DSP's.","- A keyword target is {adProduct, campaignId, adGroupId, negative: false, state: 'ENABLED', targetType: 'KEYWORD', bid: {bid: <amount>}, targetDetails: {keywordTarget: {keyword, matchType: BROAD | EXACT | PHRASE}}} — bid wraps the number.","- An SP ad group is SINGLE-targeting-type: keyword targets and product targets cannot coexist in one ad group. Adding the second type fails with the misleading FIELD_VALUE_NOT_UNIQUE \"Duplicate object found\" — use separate ad groups per targeting type.","- productTarget.product is an OBJECT wrapping productId, not a bare string (a bare string 400s \"Expected null\").","- productCategoryTarget nests productCategoryRefinement TWICE — the outer key is the wrapper, the inner one holds the fields; a single level 400s."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"adProduct":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"bid":{"additionalProperties":true,"description":"2 fields (bid, marketplaceSettings) — see the Docs link","type":"object"},"campaignId":{"type":"string"},"marketplaceConfigurations":{"items":{"additionalProperties":true,"description":"2 fields (marketplace, overrides) — see the Docs link","type":"object"},"maxItems":30,"minItems":0,"type":"array"},"marketplaceScope":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"marketplaces":{"items":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"maxItems":30,"minItems":0,"type":"array"},"negative":{"type":"boolean"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"description":"2 fields (key, value) — see the Docs link","type":"object"},"maxItems":50,"minItems":0,"type":"array"},"targetDetails":{"anyOf":[{"additionalProperties":true,"description":"1 fields (keywordTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (productTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (productCategoryTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (productAudienceTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (audienceTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (locationTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (domainTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (appTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (deviceTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (dayPartTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (contentCategoryTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (contentGenreTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (contentRatingTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (brandSafetyTierTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (brandSafetyCategoryTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (inventorySourceTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (adInitiationTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (adPlayerSizeTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (videoAdFormatTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (thirdPartyTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (themeTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (contentInstreamPositionTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (contentOutstreamPositionTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (videoContentDurationTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (foldPositionTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (nativeContentPositionTarget) — see the Docs link","type":"object"},{"additionalProperties":true,"description":"1 fields (placementTypeTarget) — see the Docs link","type":"object"}]},"targetType":{"enum":["AD_INITIATION","AD_PLAYER_SIZE","APP","AUDIENCE","BRAND_SAFETY_CATEGORY","BRAND_SAFETY_TIER","CONTENT_CATEGORY","CONTENT_GENRE","CONTENT_INSTREAM_POSITION","CONTENT_OUTSTREAM_POSITION","CONTENT_RATING","DAYPART","DEVICE","DOMAIN","FOLD_POSITION","INVENTORY_SOURCE","KEYWORD","LOCATION","NATIVE_CONTENT_POSITION","PLACEMENT_TYPE","PRODUCT","PRODUCT_AUDIENCE","PRODUCT_CATEGORY","THEME","THIRD_PARTY","VIDEO_AD_FORMAT","VIDEO_CONTENT_DURATION"],"type":"string"}},"required":["adProduct","negative","state","targetDetails","targetType"],"type":"object"},"maxItems":1000,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {targets: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of target objects (or {targets: [...]})."}},"required":["store","countryCode","body"],"title":"ads_create_targetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{},"target":{"description":"19 fields (adGroupId, adProduct, bid, campaignId, creationDateTime, globalTargetId, …) — see the Docs link"}}}},"success":{"items":{"properties":{"index":{},"target":{"description":"19 fields (adGroupId, adProduct, bid, campaignId, creationDateTime, globalTargetId, …) — see the Docs link"}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_target":{"post":{"operationId":"ads_update_target","summary":"Update targets across ALL ad products via the unified Amazon Ads API v1 — keywords, product and category targets, audiences, themes and locations, and every negative (negative=true","description":"Update targets across ALL ad products via the unified Amazon Ads API v1 — keywords, product and category targets, audiences, themes and locations, and every negative (negative=true, ad-group or campaign level); there is no separate keywords entity in v1. Amazon Ads API · UpdateTarget · POST /adsApi/v1/update/targets Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-targets#tag/Targets/operation/UpdateTarget Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_target"},"tags":["amazon_ads"],"x-title":"Ads Update Target","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].target","description":"each changed target; index is its position in your list — error[] items were not changed."}],"x-notes":{"Gotchas":["- Keyword text, match type, targetType and negative cannot be updated (TargetUpdate has no top-level targetDetails or negative; only a per-marketplace override for GLOBAL campaigns) — archive with ads_delete_target and create the new target.","- AMAZON_DSP targets cannot be updated (Amazon has no DSP UpdateTarget), so state is ENABLED or PAUSED — DRAFT and PROPOSED are DSP values."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"bid":{"additionalProperties":true,"properties":{"bid":{"format":"double","type":"number"},"marketplaceSettings":{"items":{"additionalProperties":true,"properties":{"bid":{"format":"double","type":"number"},"currencyCode":{"enum":["AED","ARS","AUD","BGN","BHD","BOB","BRL","CAD","CHF","CLP","CNY","COP","CRC","CZK","DKK","DOP","DZD","EGP","EUR","GBP","GTQ","HKD","HNL","HRK","HUF","IDR","ILS","INR","JMD","JOD","JPY","KRW","KWD","MAD","MXN","MXP","MYR","NGN","NOK","NZD","PAB","PEN","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","SAR","SEK","SGD","THB","TND","TRY","TWD","UAH","USD","UYU","VND","ZAR"],"type":"string"},"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"}},"required":["currencyCode","marketplace"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"}},"type":"object"},"campaignId":{"type":"string"},"marketplaceConfigurations":{"items":{"additionalProperties":true,"properties":{"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"overrides":{"additionalProperties":true,"properties":{"state":{"enum":["ARCHIVED","DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"},"targetDetails":{"anyOf":[{"additionalProperties":true,"properties":{"keywordTarget":{"additionalProperties":true,"description":"4 fields (keyword, matchType, nativeLanguageKeyword, nativeLanguageLocale) — see the Docs link","type":"object"}},"required":["keywordTarget"],"type":"object"},{"additionalProperties":true,"properties":{"themeTarget":{"additionalProperties":true,"description":"1 fields (matchType) — see the Docs link","type":"object"}},"required":["themeTarget"],"type":"object"}]}},"type":"object"}},"required":["marketplace","overrides"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"},"marketplaceScope":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"marketplaces":{"items":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"maxItems":30,"minItems":0,"type":"array"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"},"targetId":{"type":"string"}},"required":["targetId"],"type":"object"},"maxItems":1000,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {targets: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of {targetId*, state?, bid?: {bid: <amount>}} (or {targets: [...]}) — bid wraps the number; for a single bid change use ads_update_target_bid."}},"required":["store","countryCode","body"],"title":"ads_update_targetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{},"target":{"description":"19 fields (adGroupId, adProduct, bid, campaignId, creationDateTime, globalTargetId, …) — see the Docs link"}}}},"success":{"items":{"properties":{"index":{},"target":{"description":"19 fields (adGroupId, adProduct, bid, campaignId, creationDateTime, globalTargetId, …) — see the Docs link"}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_target":{"post":{"operationId":"ads_delete_target","summary":"Delete (archive) targets across ALL ad products via the unified Amazon Ads API v1 — keywords, product and category targets, audiences, themes and locations, and every negative (neg","description":"Delete (archive) targets across ALL ad products via the unified Amazon Ads API v1 — keywords, product and category targets, audiences, themes and locations, and every negative (negative=true, ad-group or campaign level); there is no separate keywords entity in v1. Amazon Ads API · DeleteTarget · POST /adsApi/v1/delete/targets Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-targets#tag/Targets/operation/DeleteTarget Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_target"},"tags":["amazon_ads"],"x-title":"Ads Delete Target","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].target","description":"each deleted target; error[] items were not."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"targetIds":{"items":{"type":"string"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["targetIds"],"title":"Body","type":"object","description":"{targetIds: [...]} — an ID array; a filter 400s."}},"required":["store","countryCode","body"],"title":"ads_delete_targetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{},"target":{"description":"19 fields (adGroupId, adProduct, bid, campaignId, creationDateTime, globalTargetId, …) — see the Docs link"}}}},"success":{"items":{"properties":{"index":{},"target":{"description":"19 fields (adGroupId, adProduct, bid, campaignId, creationDateTime, globalTargetId, …) — see the Docs link"}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_query_ad":{"post":{"operationId":"ads_query_ad","summary":"Query (read) ads (creatives) across ALL ad products via the unified Amazon Ads API v1.","description":"Query (read) ads (creatives) across ALL ad products via the unified Amazon Ads API v1. In the v1 model an \"ad\" is the creative unit inside an ad group; a sponsored ad's advertised product is inside its creative (productCreative for SP, componentCreative for SB and SD, videoCreative for ST) — ad associations (ads_query_ad_association) are AMAZON_DSP's ad-to-ad-group links, not product links. Use it for a targeted read of current settings (by id, name or state); for a whole-account dump use ads_ad_export, and for spend or sales use query_report_data. Amazon Ads API · QueryAd · POST /adsApi/v1/query/ads Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-ads#tag/Ads/operation/QueryAd","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_query_ad"},"tags":["amazon_ads"],"x-title":"Ads Query Ad","x-access":"read","x-family":"ads.v1","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result","description":"the matching ads — the server follows nextToken for up to 5 pages; maxResults caps the total."},{"field":"data.nextToken","description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adGroupIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"adIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"adProductFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"campaignIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"marketplaceScopeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"maxResults":{"format":"int32","maximum":1000,"minimum":1,"type":"integer"},"nameFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":10,"minItems":1,"type":"array"},"queryTermMatchType":{"enum":["BROAD_MATCH","EXACT_MATCH"],"type":"string"}},"required":["include","queryTermMatchType"],"type":"object"},"nextToken":{"type":"string"},"retailerScopeFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["AMAZON","OTHER_RETAILERS"],"type":"string"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"stateFilter":{"additionalProperties":true,"properties":{"include":{"items":{"enum":["ARCHIVED","DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"maxItems":3,"minItems":1,"type":"array"}},"required":["include"],"type":"object"}},"required":["adProductFilter"],"title":"Body","type":"object","description":"the filter object — adProductFilter is required, e.g. {adProductFilter: {include: ['SPONSORED_PRODUCTS']}, adGroupIdFilter: {include: ['<adGroupId>']}}."}},"required":["store","countryCode","body"],"title":"ads_query_adArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"ads":{"items":{"properties":{"activeCreative":{"anyOf":[{"description":"1 fields (audioCreative) — see the Docs link"},{"description":"1 fields (componentCreative) — see the Docs link"},{"description":"1 fields (displayCreative) — see the Docs link"},{"description":"1 fields (productCreative) — see the Docs link"},{"description":"1 fields (thirdPartyCreative) — see the Docs link"},{"description":"1 fields (videoCreative) — see the Docs link"}]},"adGroupId":{},"adId":{},"adProduct":{},"adType":{},"campaignId":{},"creationDateTime":{},"creative":{"anyOf":[{"description":"1 fields (audioCreative) — see the Docs link"},{"description":"1 fields (componentCreative) — see the Docs link"},{"description":"1 fields (displayCreative) — see the Docs link"},{"description":"1 fields (productCreative) — see the Docs link"},{"description":"1 fields (thirdPartyCreative) — see the Docs link"},{"description":"1 fields (videoCreative) — see the Docs link"}]},"globalAdId":{},"lastUpdatedDateTime":{},"marketplaceConfigurations":{"items":{"description":"3 fields (adId, marketplace, overrides) — see the Docs link"}},"marketplaceScope":{},"marketplaces":{"items":{}},"name":{},"retailerScope":{},"state":{},"status":{"description":"3 fields (deliveryReasons, deliveryStatus, marketplaceSettings) — see the Docs link"},"tags":{"items":{"description":"2 fields (key, value) — see the Docs link"}}}}},"nextToken":{}},"description":"the matching ads — the server follows nextToken for up to 5 pages; maxResults caps the total."},"nextToken":{"description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_ad":{"post":{"operationId":"ads_create_ad","summary":"Create ads (creatives) across ALL ad products via the unified Amazon Ads API v1.","description":"Create ads (creatives) across ALL ad products via the unified Amazon Ads API v1. In the v1 model an \"ad\" is the creative unit inside an ad group; a sponsored ad's advertised product is inside its creative (productCreative for SP, componentCreative for SB and SD, videoCreative for ST) — ad associations (ads_query_ad_association) are AMAZON_DSP's ad-to-ad-group links, not product links. Amazon Ads API · CreateAd · POST /adsApi/v1/create/ads Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-ads#tag/Ads/operation/CreateAd Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_ad"},"tags":["amazon_ads"],"x-title":"Ads Create Ad","x-access":"write","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].ad","description":"each created ad with its adId; index is its position in your list — partialSuccess[] items were created with errors, error[] items were not."}],"x-notes":{"Gotchas":["- adGroupId is REQUIRED for SPONSORED_PRODUCTS, SPONSORED_BRANDS, SPONSORED_DISPLAY and SPONSORED_TELEVISION — only AMAZON_DSP creates ads without an ad group.","- adType and creative follow adProduct: SP PRODUCT_AD + productCreative, SB and SD COMPONENT + componentCreative, ST VIDEO + videoCreative (SB and ST also require name); AUDIO, DISPLAY and THIRD_PARTY are AMAZON_DSP's.","- productIdType is SKU or ASIN (SP also lists RETAILER_OFFER); a SELLER should use SKU (one SKU names exactly one ASIN, whereas one ASIN can cover several SKUs) — a VENDOR account has no seller SKUs and uses ASIN. SB creatives are ASIN-only.","- A well-formed create can still fail per-index with PRODUCT_INELIGIBLE when the product is not currently buyable — check listing status first."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"adProduct":{"enum":["AMAZON_DSP","SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"type":"string"},"adType":{"enum":["AUDIO","COMPONENT","DISPLAY","PRODUCT_AD","THIRD_PARTY","VIDEO"],"type":"string"},"creative":{"anyOf":[{"additionalProperties":true,"properties":{"audioCreative":{"additionalProperties":true,"properties":{"standardAudioSettings":{"additionalProperties":true,"description":"7 fields (audio, callToActions, companionImages, headlines, impressionTrackingUrls, language, …) — see the Docs link","type":"object"}},"required":["standardAudioSettings"],"type":"object"}},"required":["audioCreative"],"type":"object"},{"additionalProperties":true,"properties":{"displayCreative":{"additionalProperties":true,"properties":{"standardDisplaySettings":{"additionalProperties":true,"description":"7 fields (adChoicesPosition, callToAction, clickTrackingUrls, creativeSizes, customImages, impressionTrackingUrls, …) — see the Docs link","type":"object"}},"type":"object"}},"required":["displayCreative"],"type":"object"},{"additionalProperties":true,"properties":{"thirdPartyCreative":{"additionalProperties":true,"properties":{"thirdPartyDisplaySettings":{"additionalProperties":true,"description":"8 fields (adChoicesPosition, additionalHtml, clickTrackingUrls, creativeSizes, impressionTrackingUrls, language, …) — see the Docs link","type":"object"},"thirdPartyVideoSettings":{"additionalProperties":true,"description":"4 fields (impressionTrackingUrls, language, publisherHostedCreativeSource, vastUrl) — see the Docs link","type":"object"}},"type":"object"}},"required":["thirdPartyCreative"],"type":"object"},{"additionalProperties":true,"properties":{"videoCreative":{"additionalProperties":true,"properties":{"onlineVideoSettings":{"additionalProperties":true,"description":"6 fields (callToActions, clickTrackingUrls, impressionTrackingUrls, language, products, videos) — see the Docs link","type":"object"},"streamingTvSettings":{"additionalProperties":true,"description":"6 fields (callToActions, impressionTrackingUrls, landingPage, language, products, videos) — see the Docs link","type":"object"}},"type":"object"}},"required":["videoCreative"],"type":"object"},{"additionalProperties":true,"properties":{"componentCreative":{"additionalProperties":true,"properties":{"assetBasedCreativeSettings":{"additionalProperties":true,"description":"19 fields (additionalHtml, bodyText, brand, callToActions, clickTrackingUrls, creativeSizes, …) — see the Docs link","type":"object"},"autoCollectionSettings":{"additionalProperties":true,"description":"2 fields (productExclusions, sharedSettings) — see the Docs link","type":"object"},"brandGallerySettings":{"additionalProperties":true,"description":"8 fields (brand, brandLogos, cards, creativePropertiesToOptimize, customImages, enableCreativeAutoTranslation, …) — see the Docs link","type":"object"},"brandStoreSettings":{"additionalProperties":true,"description":"17 fields (additionalHtml, bodyText, brand, callToActions, clickTrackingUrls, creativeSizes, …) — see the Docs link","type":"object"},"manualCollectionSettings":{"additionalProperties":true,"description":"4 fields (landingPage, productInclusions, sharedSettings, title) — see the Docs link","type":"object"},"productCollectionSettings":{"additionalProperties":true,"description":"8 fields (brand, brandLogos, creativePropertiesToOptimize, customImages, enableCreativeAutoTranslation, headlines, …) — see the Docs link","type":"object"},"productVideoSettings":{"additionalProperties":true,"description":"7 fields (brand, brandLogos, enableCreativeAutoTranslation, headlines, landingPage, products, …) — see the Docs link","type":"object"},"responsiveEcommerceSettings":{"additionalProperties":true,"description":"16 fields (clickTrackingUrls, creativePropertiesToOptimize, creativeSizes, disclaimers, headlines, images, …) — see the Docs link","type":"object"},"storeSpotlightSettings":{"additionalProperties":true,"description":"7 fields (brand, brandLogos, cards, creativePropertiesToOptimize, enableCreativeAutoTranslation, headlines, …) — see the Docs link","type":"object"}},"type":"object"}},"required":["componentCreative"],"type":"object"},{"additionalProperties":true,"properties":{"productCreative":{"additionalProperties":true,"properties":{"productCreativeSettings":{"additionalProperties":true,"description":"3 fields (advertisedProduct, headline, spotlightVideos) — see the Docs link","type":"object"}},"required":["productCreativeSettings"],"type":"object"}},"required":["productCreative"],"type":"object"}]},"marketplaceConfigurations":{"items":{"additionalProperties":true,"properties":{"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"overrides":{"additionalProperties":true,"properties":{"state":{"enum":["ARCHIVED","DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"description":"2 fields (key, value) — see the Docs link","type":"object"},"maxItems":50,"minItems":0,"type":"array"}},"type":"object"}},"required":["marketplace","overrides"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"},"marketplaceScope":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"marketplaces":{"items":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"maxItems":30,"minItems":0,"type":"array"},"name":{"type":"string"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"}},"required":["adProduct","adType","creative","state"],"type":"object"},"maxItems":1000,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {ads: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of ad objects (or {ads: [...]})."}},"required":["store","countryCode","body"],"title":"ads_create_adArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"ad":{"description":"18 fields (activeCreative, adGroupId, adId, adProduct, adType, campaignId, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"ad":{"description":"18 fields (activeCreative, adGroupId, adId, adProduct, adType, campaignId, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_ad":{"post":{"operationId":"ads_update_ad","summary":"Update ads (creatives) across ALL ad products via the unified Amazon Ads API v1.","description":"Update ads (creatives) across ALL ad products via the unified Amazon Ads API v1. In the v1 model an \"ad\" is the creative unit inside an ad group; a sponsored ad's advertised product is inside its creative (productCreative for SP, componentCreative for SB and SD, videoCreative for ST) — ad associations (ads_query_ad_association) are AMAZON_DSP's ad-to-ad-group links, not product links. Amazon Ads API · UpdateAd · POST /adsApi/v1/update/ads Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-ads#tag/Ads/operation/UpdateAd Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_ad"},"tags":["amazon_ads"],"x-title":"Ads Update Ad","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].ad","description":"each changed ad; index is its position in your list — error[] items were not changed."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adId":{"type":"string"},"creative":{"anyOf":[{"additionalProperties":true,"properties":{"audioCreative":{"additionalProperties":true,"properties":{"standardAudioSettings":{"additionalProperties":true,"description":"7 fields (audio, callToActions, companionImages, headlines, impressionTrackingUrls, language, …) — see the Docs link","type":"object"}},"required":["standardAudioSettings"],"type":"object"}},"required":["audioCreative"],"type":"object"},{"additionalProperties":true,"properties":{"displayCreative":{"additionalProperties":true,"properties":{"standardDisplaySettings":{"additionalProperties":true,"description":"7 fields (adChoicesPosition, callToAction, clickTrackingUrls, creativeSizes, customImages, impressionTrackingUrls, …) — see the Docs link","type":"object"}},"type":"object"}},"required":["displayCreative"],"type":"object"},{"additionalProperties":true,"properties":{"thirdPartyCreative":{"additionalProperties":true,"properties":{"thirdPartyDisplaySettings":{"additionalProperties":true,"description":"8 fields (adChoicesPosition, additionalHtml, clickTrackingUrls, creativeSizes, impressionTrackingUrls, language, …) — see the Docs link","type":"object"},"thirdPartyVideoSettings":{"additionalProperties":true,"description":"4 fields (impressionTrackingUrls, language, publisherHostedCreativeSource, vastUrl) — see the Docs link","type":"object"}},"type":"object"}},"required":["thirdPartyCreative"],"type":"object"},{"additionalProperties":true,"properties":{"videoCreative":{"additionalProperties":true,"properties":{"onlineVideoSettings":{"additionalProperties":true,"description":"6 fields (callToActions, clickTrackingUrls, impressionTrackingUrls, language, products, videos) — see the Docs link","type":"object"},"streamingTvSettings":{"additionalProperties":true,"description":"5 fields (callToActions, impressionTrackingUrls, language, products, videos) — see the Docs link","type":"object"}},"type":"object"}},"required":["videoCreative"],"type":"object"},{"additionalProperties":true,"properties":{"componentCreative":{"additionalProperties":true,"properties":{"assetBasedCreativeSettings":{"additionalProperties":true,"description":"18 fields (additionalHtml, bodyText, brand, callToActions, clickTrackingUrls, creativeSizes, …) — see the Docs link","type":"object"},"autoCollectionSettings":{"additionalProperties":true,"description":"2 fields (productExclusions, sharedSettings) — see the Docs link","type":"object"},"brandGallerySettings":{"additionalProperties":true,"description":"8 fields (brand, brandLogos, cards, creativePropertiesToOptimize, customImages, enableCreativeAutoTranslation, …) — see the Docs link","type":"object"},"brandStoreSettings":{"additionalProperties":true,"description":"17 fields (additionalHtml, bodyText, brand, callToActions, clickTrackingUrls, creativeSizes, …) — see the Docs link","type":"object"},"manualCollectionSettings":{"additionalProperties":true,"description":"4 fields (landingPage, productInclusions, sharedSettings, title) — see the Docs link","type":"object"},"productCollectionSettings":{"additionalProperties":true,"description":"8 fields (brand, brandLogos, creativePropertiesToOptimize, customImages, enableCreativeAutoTranslation, headlines, …) — see the Docs link","type":"object"},"productVideoSettings":{"additionalProperties":true,"description":"7 fields (brand, brandLogos, enableCreativeAutoTranslation, headlines, landingPage, products, …) — see the Docs link","type":"object"},"responsiveEcommerceSettings":{"additionalProperties":true,"description":"15 fields (clickTrackingUrls, creativePropertiesToOptimize, creativeSizes, disclaimers, headlines, images, …) — see the Docs link","type":"object"},"storeSpotlightSettings":{"additionalProperties":true,"description":"7 fields (brand, brandLogos, cards, creativePropertiesToOptimize, enableCreativeAutoTranslation, headlines, …) — see the Docs link","type":"object"}},"type":"object"}},"required":["componentCreative"],"type":"object"},{"additionalProperties":true,"properties":{"productCreative":{"additionalProperties":true,"properties":{"productCreativeSettings":{"additionalProperties":true,"description":"2 fields (advertisedProduct, spotlightVideos) — see the Docs link","type":"object"}},"type":"object"}},"required":["productCreative"],"type":"object"}]},"marketplaceConfigurations":{"items":{"additionalProperties":true,"properties":{"marketplace":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"overrides":{"additionalProperties":true,"properties":{"state":{"enum":["ARCHIVED","DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"description":"2 fields (key, value) — see the Docs link","type":"object"},"maxItems":50,"minItems":0,"type":"array"}},"type":"object"}},"required":["marketplace","overrides"],"type":"object"},"maxItems":30,"minItems":0,"type":"array"},"marketplaceScope":{"enum":["GLOBAL","SINGLE_MARKETPLACE"],"type":"string"},"marketplaces":{"items":{"enum":["AE","AU","BE","BR","CA","DE","EG","ES","FR","GB","IE","IN","IT","JP","MX","NL","PL","SA","SE","SG","TR","US","ZA"],"type":"string"},"maxItems":30,"minItems":0,"type":"array"},"name":{"type":"string"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"tags":{"items":{"additionalProperties":true,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"maxItems":50,"minItems":0,"type":"array"}},"required":["adId"],"type":"object"},"maxItems":1000,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {ads: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of {adId*, name?, state?, creative?} (or {ads: [...]})."}},"required":["store","countryCode","body"],"title":"ads_update_adArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"ad":{"description":"18 fields (activeCreative, adGroupId, adId, adProduct, adType, campaignId, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"ad":{"description":"18 fields (activeCreative, adGroupId, adId, adProduct, adType, campaignId, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_ad":{"post":{"operationId":"ads_delete_ad","summary":"Delete (archive) ads (creatives) across ALL ad products via the unified Amazon Ads API v1.","description":"Delete (archive) ads (creatives) across ALL ad products via the unified Amazon Ads API v1. In the v1 model an \"ad\" is the creative unit inside an ad group; a sponsored ad's advertised product is inside its creative (productCreative for SP, componentCreative for SB and SD, videoCreative for ST) — ad associations (ads_query_ad_association) are AMAZON_DSP's ad-to-ad-group links, not product links. Amazon Ads API · DeleteAd · POST /adsApi/v1/delete/ads Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-ads#tag/Ads/operation/DeleteAd Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_ad"},"tags":["amazon_ads"],"x-title":"Ads Delete Ad","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].ad","description":"each deleted ad; error[] items were not."}],"x-notes":{"Gotchas":["- AMAZON_DSP ads cannot be deleted here (Amazon has no DSP DeleteAd); SB takes at most 10 ids per call, SD and ST 100."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adIds":{"items":{"type":"string"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["adIds"],"title":"Body","type":"object","description":"{adIds: [...]} — an ID array, not a filter."}},"required":["store","countryCode","body"],"title":"ads_delete_adArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"partialSuccess":{"items":{"properties":{"ad":{"description":"18 fields (activeCreative, adGroupId, adId, adProduct, adType, campaignId, …) — see the Docs link"},"errors":{"items":{"description":"3 fields (code, fieldLocation, message) — see the Docs link"}},"index":{}}}},"success":{"items":{"properties":{"ad":{"description":"18 fields (activeCreative, adGroupId, adId, adProduct, adType, campaignId, …) — see the Docs link"},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_query_ad_association":{"post":{"operationId":"ads_query_ad_association","summary":"Query (read) ad<->ad-group associations via the unified Amazon Ads API v1 — an AMAZON_DSP resource (creative rotation across ad groups); sponsored-ads products embed the product li","description":"Query (read) ad<->ad-group associations via the unified Amazon Ads API v1 — an AMAZON_DSP resource (creative rotation across ad groups); sponsored-ads products embed the product link in the ad itself (see ads_query_ad). Amazon Ads API · QueryAdAssociation · POST /adsApi/v1/query/adAssociations Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adassociations#tag/AdAssociations/operation/QueryAdAssociation","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_query_ad_association"},"tags":["amazon_ads"],"x-title":"Ads Query Ad Association","x-access":"read","x-family":"ads.v1","x-returns":[{"description":"Amazon's payload in data.result."},{"field":"data.result","description":"the matching ad associations — the server follows nextToken for up to 5 pages; maxResults caps the total."},{"field":"data.nextToken","description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}],"x-notes":{"Gotchas":["- DSP-only: on a sponsored-ads profile the call fails with Amazon's 401 \"not authorized to access account\", returned as a 400 — only call this entity for DSP work."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"additionalProperties":true,"properties":{"adAssociationIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"adGroupIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"adIdFilter":{"additionalProperties":true,"properties":{"include":{"items":{"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"maxResults":{"default":100,"format":"int32","maximum":100,"minimum":1,"type":"integer"},"nextToken":{"type":"string"}},"type":"object"},{"type":"null"}],"default":null,"title":"Body","description":"filter dict (no adProductFilter on this entity)."}},"required":["store","countryCode"],"title":"ads_query_ad_associationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"adAssociations":{"items":{"properties":{"adAssociationId":{},"adGroupId":{},"adId":{},"endDateTime":{},"startDateTime":{},"state":{},"weight":{}}}},"nextToken":{}},"description":"the matching ad associations — the server follows nextToken for up to 5 pages; maxResults caps the total."},"nextToken":{"description":"set when more remain — call again with the SAME filters plus this nextToken (a token-only body 400s)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_ad_association":{"post":{"operationId":"ads_create_ad_association","summary":"Create ad<->ad-group associations via the unified Amazon Ads API v1 — an AMAZON_DSP resource (creative rotation across ad groups); sponsored-ads products embed the product link in ","description":"Create ad<->ad-group associations via the unified Amazon Ads API v1 — an AMAZON_DSP resource (creative rotation across ad groups); sponsored-ads products embed the product link in the ad itself (see ads_query_ad). Amazon Ads API · CreateAdAssociation · POST /adsApi/v1/create/adAssociations Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adassociations#tag/AdAssociations/operation/CreateAdAssociation Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_ad_association"},"tags":["amazon_ads"],"x-title":"Ads Create Ad Association","x-access":"write","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].adAssociation","description":"each created ad association with its adAssociationId; index is its position in your list — partialSuccess[] items were created with errors, error[] items were not."}],"x-notes":{"Gotchas":["- DSP-only: on a sponsored-ads profile the call fails with Amazon's 401 \"not authorized to access account\", returned as a 400 — only call this entity for DSP work.","- Both the ad (ads_create_ad) and the ad group must already exist."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adGroupId":{"type":"string"},"adId":{"type":"string"},"endDateTime":{"format":"date-time","type":"string"},"startDateTime":{"format":"date-time","type":"string"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"weight":{"format":"int32","type":"integer"}},"required":["adGroupId","adId","state"],"type":"object"},"maxItems":20,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {adAssociations: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of {adId*, adGroupId*, state*, weight?, startDateTime?, endDateTime?} (or {adAssociations: [...]}), at most 20 — weight is the percentage of the ad group's traffic this creative receives."}},"required":["store","countryCode","body"],"title":"ads_create_ad_associationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"properties":{"code":{},"fieldLocation":{},"message":{}}}},"index":{}}}},"success":{"items":{"properties":{"adAssociation":{"properties":{"adAssociationId":{},"adGroupId":{},"adId":{},"endDateTime":{},"startDateTime":{},"state":{},"weight":{}},"description":"each created ad association with its adAssociationId; index is its position in your list — partialSuccess[] items were created with errors, error[] items were not."},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_ad_association":{"post":{"operationId":"ads_update_ad_association","summary":"Update ad<->ad-group associations via the unified Amazon Ads API v1 — an AMAZON_DSP resource (creative rotation across ad groups); sponsored-ads products embed the product link in ","description":"Update ad<->ad-group associations via the unified Amazon Ads API v1 — an AMAZON_DSP resource (creative rotation across ad groups); sponsored-ads products embed the product link in the ad itself (see ads_query_ad). Amazon Ads API · UpdateAdAssociation · POST /adsApi/v1/update/adAssociations Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adassociations#tag/AdAssociations/operation/UpdateAdAssociation Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_ad_association"},"tags":["amazon_ads"],"x-title":"Ads Update Ad Association","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].adAssociation","description":"each changed ad association; index is its position in your list — error[] items were not changed."}],"x-notes":{"Gotchas":["- DSP-only: on a sponsored-ads profile the call fails with Amazon's 401 \"not authorized to access account\", returned as a 400 — only call this entity for DSP work."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"anyOf":[{"items":{"additionalProperties":true,"properties":{"adAssociationId":{"type":"string"},"endDateTime":{"format":"date-time","type":"string"},"startDateTime":{"format":"date-time","type":"string"},"state":{"enum":["DRAFT","ENABLED","PAUSED","PROPOSED"],"type":"string"},"weight":{"format":"int32","type":"integer"}},"required":["adAssociationId"],"type":"object"},"maxItems":20,"minItems":1,"title":"items","type":"array"},{"additionalProperties":true,"description":"the envelope form {adAssociations: [<item>, …]} — the same items","title":"envelope","type":"object"}],"title":"Body","description":"list of {adAssociationId*, state?, startDateTime?, endDateTime?, weight?} (or {adAssociations: [...]})."}},"required":["store","countryCode","body"],"title":"ads_update_ad_associationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"properties":{"code":{},"fieldLocation":{},"message":{}}}},"index":{}}}},"success":{"items":{"properties":{"adAssociation":{"properties":{"adAssociationId":{},"adGroupId":{},"adId":{},"endDateTime":{},"startDateTime":{},"state":{},"weight":{}},"description":"each changed ad association; index is its position in your list — error[] items were not changed."},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_ad_association":{"post":{"operationId":"ads_delete_ad_association","summary":"Delete (archive) ad<->ad-group associations via the unified Amazon Ads API v1 — an AMAZON_DSP resource (creative rotation across ad groups); sponsored-ads products embed the produc","description":"Delete (archive) ad<->ad-group associations via the unified Amazon Ads API v1 — an AMAZON_DSP resource (creative rotation across ad groups); sponsored-ads products embed the product link in the ad itself (see ads_query_ad). Amazon Ads API · DeleteAdAssociation · POST /adsApi/v1/delete/adAssociations Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-adassociations#tag/AdAssociations/operation/DeleteAdAssociation Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_ad_association"},"tags":["amazon_ads"],"x-title":"Ads Delete Ad Association","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."},{"field":"data.result.success[].adAssociation","description":"each deleted ad association; error[] items were not."}],"x-notes":{"Gotchas":["- DSP-only: on a sponsored-ads profile the call fails with Amazon's 401 \"not authorized to access account\", returned as a 400 — only call this entity for DSP work."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"adAssociationIds":{"items":{"type":"string"},"maxItems":20,"minItems":1,"type":"array"}},"required":["adAssociationIds"],"title":"Body","type":"object","description":"{adAssociationIds: [...]} — an ID array."}},"required":["store","countryCode","body"],"title":"ads_delete_ad_associationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"error":{"items":{"properties":{"errors":{"items":{"properties":{"code":{},"fieldLocation":{},"message":{}}}},"index":{}}}},"success":{"items":{"properties":{"adAssociation":{"properties":{"adAssociationId":{},"adGroupId":{},"adId":{},"endDateTime":{},"startDateTime":{},"state":{},"weight":{}},"description":"each deleted ad association; error[] items were not."},"index":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_campaign_budget":{"post":{"operationId":"ads_update_campaign_budget","summary":"Change ONE campaign's budget amount — nothing else about the campaign.","description":"Change ONE campaign's budget amount — nothing else about the campaign. Amazon Ads API · UpdateCampaign · POST /adsApi/v1/update/campaigns Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-campaigns#tag/Campaigns/operation/UpdateCampaign Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_campaign_budget"},"tags":["amazon_ads"],"x-title":"Ads Update Campaign Budget","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."}],"x-notes":{"Gotchas":["- For any other campaign change use ads_update_campaign.","- The campaign's budgets list is replaced by this one MONETARY entry."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaignId":{"title":"Campaignid","type":"string","description":"the campaign, from ads_query_campaign."},"budget":{"title":"Budget","type":"number","description":"the new budget amount in the campaign's currency, above 0."},"recurrenceTimePeriod":{"title":"Recurrencetimeperiod","type":"string","description":"DAILY | LIFETIME | MONTHLY — the period the amount caps; pass the campaign's current value unless you mean to change it."}},"required":["store","countryCode","campaignId","budget","recurrenceTimePeriod"],"title":"ads_update_campaign_budgetArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_campaign_state":{"post":{"operationId":"ads_update_campaign_state","summary":"Enable or pause ONE campaign — nothing else about it.","description":"Enable or pause ONE campaign — nothing else about it. Amazon Ads API · UpdateCampaign · POST /adsApi/v1/update/campaigns Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-campaigns#tag/Campaigns/operation/UpdateCampaign Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_campaign_state"},"tags":["amazon_ads"],"x-title":"Ads Update Campaign State","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."}],"x-notes":{"Gotchas":["- To archive a campaign use ads_delete_campaign (Amazon's delete is an archive).","- ENABLED starts spending."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"campaignId":{"title":"Campaignid","type":"string","description":"the campaign, from ads_query_campaign."},"state":{"title":"State","type":"string","description":"ENABLED or PAUSED — the update states Amazon's spec lists for a live campaign."}},"required":["store","countryCode","campaignId","state"],"title":"ads_update_campaign_stateArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_target_bid":{"post":{"operationId":"ads_update_target_bid","summary":"Change ONE target's (keyword, product or audience target) bid.","description":"Change ONE target's (keyword, product or audience target) bid. Amazon Ads API · UpdateTarget · POST /adsApi/v1/update/targets Docs: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-targets#tag/Targets/operation/UpdateTarget Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_target_bid"},"tags":["amazon_ads"],"x-title":"Ads Update Target Bid","x-access":"destructive","x-family":"ads.v1","x-returns":[{"description":"207 {success, partialSuccess, error}. HTTP success does not mean every item succeeded; read error[] by index."}],"x-notes":{"Gotchas":["- For any other target change use ads_update_target."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"countryCode":{"title":"Countrycode","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"targetId":{"title":"Targetid","type":"string","description":"the target, from ads_query_target."},"bid":{"title":"Bid","type":"number","description":"the new maximum bid in the campaign's currency, above 0."}},"required":["store","countryCode","targetId","bid"],"title":"ads_update_target_bidArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_amc_turn_on":{"post":{"operationId":"ads_amc_turn_on","summary":"Turn Amazon Marketing Cloud (AMC) on for this store's Ads account in one country: finds the advertiser's AMC instance — creating it the first time — and remembers it.","description":"Turn Amazon Marketing Cloud (AMC) on for this store's Ads account in one country: finds the advertiser's AMC instance — creating it the first time — and remembers it. Every other AMC tool needs it on; get_user_context's amc says, per store and country, whether it is. Ask the seller before the first call: an AMC instance cannot be deleted. Calling it again is safe; when AMC is on it only reads. Amazon Ads API · listInstances · GET /amc/instances Amazon Ads API · ListAdsAccounts · POST /adsAccounts/list Docs: https://advertising.amazon.com/API/docs/en-us/amc-administration#tag/Instance-management/operation/listInstances Docs: https://advertising.amazon.com/API/docs/en-us/account-management#tag/Account/operation/ListAdsAccounts Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_amc_turn_on"},"tags":["amazon_ads"],"x-title":"Ads AMC Turn On","x-access":"write","x-family":"ads.amc-administration","x-returns":[{"description":"the orchestrated result described below."},{"field":"data.instance_id","description":"the store's AMC instance."},{"field":"data.creation_status","description":"COMPLETED, or IN_PROGRESS while Amazon builds it (up to 5 minutes; call again to finish)."},{"field":"data.already_on","type":"bool","description":"true when nothing was created or looked up at Amazon."}],"x-notes":{"Gotchas":["- Gate: commit — the first call creates an instance at Amazon that cannot be removed.","- The Amazon login that connected Ads must accept the AMC terms once per region (NA,","      EU, FE) at https://advertising.amazon.com/marketing-cloud; until then the call","      is refused with error_code amc_terms_not_accepted. Only the seller can do it.","- Amazon offers AMC to advertisers with campaigns live in the last 28 days."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US'). One AMC instance per country of the Ads account."}},"required":["store","country_code"],"title":"ads_amc_turn_onArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"instance_id":{"description":"the store's AMC instance."},"creation_status":{"description":"COMPLETED, or IN_PROGRESS while Amazon builds it (up to 5 minutes; call again to finish)."},"already_on":{"description":"true when nothing was created or looked up at Amazon."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_data_sources":{"post":{"operationId":"ads_list_data_sources","summary":"List the AMC tables the store's instance can query — sponsored_ads_traffic, conversions, amazon_attributed_events_by_conversion_time and the rest — with their column counts.","description":"List the AMC tables the store's instance can query — sponsored_ads_traffic, conversions, amazon_attributed_events_by_conversion_time and the rest — with their column counts. ads_get_data_source gives a table's columns and privacy classes. Amazon Ads API · listDataSources · GET /amc/reporting/{instanceId}/dataSources Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Data-sources/operation/listDataSources","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_data_sources"},"tags":["amazon_ads"],"x-title":"Ads List Data Sources","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.data_sources[]","description":"{data_source_id, description, columns}."},{"field":"data.nextToken","description":"set when more tables remain."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit","description":"tables per page, 1–100 (Amazon's default 100)."}},"required":["store","country_code"],"title":"ads_list_data_sourcesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"data_sources":{"description":"{data_source_id, description, columns}."},"nextToken":{"description":"set when more tables remain."},"result":{"properties":{"dataSources":{"items":{"properties":{"columns":{"items":{"properties":{"columnType":{},"description":{},"name":{}}}},"dataSourceId":{},"description":{},"outputChannels":{"items":{"properties":{"channel":{"properties":{"acrMemberId":{},"acrMembershipId":{},"type":{}}},"outputAvailable":{},"outputUnavailableReason":{}}}},"owner":{},"provider":{},"tags":{"items":{"properties":{"description":{},"subtext":{},"title":{},"type":{}}}},"warnings":{"items":{"properties":{"message":{}}}}}}},"nextToken":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_data_source":{"post":{"operationId":"ads_get_data_source","summary":"One AMC table's columns, each with its type and privacy class — read it before writing SQL against a table you have not used.","description":"One AMC table's columns, each with its type and privacy class — read it before writing SQL against a table you have not used. Amazon Ads API · getDataSource · GET /amc/reporting/{instanceId}/dataSources/{dataSourceId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Data-sources/operation/getDataSource","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_data_source"},"tags":["amazon_ads"],"x-title":"Ads Get Data Source","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.columns[]","description":"{name, data_type, column_type (DIMENSION | METRIC), sensitivity (NONE | LOW | MEDIUM | HIGH | VERY_HIGH | INTERNAL), min_distinct_users, description}."}],"x-notes":{"Gotchas":["- A VERY_HIGH column (user_id, ip_address) can never be in the final SELECT — use it","      inside COUNT(DISTINCT …) or a join only.","- A result row whose dimension values cover fewer shoppers than min_distinct_users","      comes back with those dimensions blank; its metrics stay."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"data_source_id":{"title":"Data Source Id","type":"string","description":"the table name from ads_list_data_sources, e.g. 'sponsored_ads_traffic' or 'conversions'."}},"required":["store","country_code","data_source_id"],"title":"ads_get_data_sourceArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"columns":{"description":"{name, data_type, column_type (DIMENSION | METRIC), sensitivity (NONE | LOW | MEDIUM | HIGH | VERY_HIGH | INTERNAL), min_distinct_users, description}."},"result":{"properties":{"dataSource":{"properties":{"columns":{"items":{"properties":{"columnType":{},"description":{},"name":{}}}},"dataSourceId":{},"description":{},"outputChannels":{"items":{"properties":{"channel":{"properties":{"acrMemberId":{},"acrMembershipId":{},"type":{}}},"outputAvailable":{},"outputUnavailableReason":{}}}},"owner":{},"provider":{},"tags":{"items":{"properties":{"description":{},"subtext":{},"title":{},"type":{}}}},"warnings":{"items":{"properties":{"message":{}}}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_workflow_execution":{"post":{"operationId":"ads_create_workflow_execution","summary":"Run an AMC SQL query over the store's AMC data (an ad-hoc execution).","description":"Run an AMC SQL query over the store's AMC data (an ad-hoc execution). Answers at once with an execution id; poll ads_get_workflow_execution, then read the rows with ads_get_workflow_execution_download_urls. Check a new query with dry_run first: AMC validates it in seconds without running it. Amazon Ads API · createWorkflowExecution · POST /amc/reporting/{instanceId}/workflowExecutions Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflow-executions/operation/createWorkflowExecution","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_workflow_execution"},"tags":["amazon_ads"],"x-title":"Ads Create Workflow Execution","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.workflow_execution_id","description":"pass to ads_get_workflow_execution."},{"field":"data.status","description":"PENDING at first."}],"x-notes":{"Body (Amazon schema)":["timeWindowType: ALL | CURRENT_MONTH | EXPLICIT | MOST_RECENT_DAY | MOST_RECENT_WEEK | PREVIOUS_MONTH","+ 15 more: additionalAcrResultsReceivers, advertisers, disableAggregationControls, dryRun,","  maxCertifiedTime, maxDimensionTime, parameterValues, requireSyntheticData, skipPublish, timeWindowEnd,","  timeWindowStart, timeWindowTimeZone, workflow, workflowExecutionTimeoutSeconds, workflowId","Full schema: the Docs link above."],"Gotchas":["- Gate: none — a report request; it reads the advertiser's own AMC data.","- AMC runs at most 10 queries at a time per instance; wait for one to finish before","      starting more.","- For numbers that no longer change, query amazon_attributed_events_by_conversion_time:","      its window is complete once it ends. The by_traffic_time table (the SP console's","      view) keeps adding purchases for up to 30 days after the window.","- A SQL keyword as a column alias (`hour`, `date`) is REJECTED as unparsable.","- Outputting user_id or another VERY_HIGH column is REJECTED.","- spend is in microcents: divide by 100,000,000 for the currency.","- For Sponsored Products the detail_page_view / add_to_cart columns of the","      attributed-events tables are 0; join the clickers in sponsored_ads_traffic to","      `conversions` (event_subtype 'shoppingCart') on user_id instead."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"sql_query":{"title":"Sql Query","type":"string","description":"AMC SQL; line breaks are joined into one line for Amazon. The final SELECT must aggregate (GROUP BY dimensions, SUM / COUNT(DISTINCT user_id))."},"time_window_type":{"anyOf":[{"enum":["ALL","CURRENT_MONTH","EXPLICIT","MOST_RECENT_DAY","MOST_RECENT_WEEK","PREVIOUS_MONTH"],"type":"string"},{"type":"null"}],"default":null,"title":"Time Window Type","description":"which days of data the query reads; EXPLICIT needs time_window_start and time_window_end. Amazon's default is MOST_RECENT_DAY. Allowed: ALL | CURRENT_MONTH | EXPLICIT | MOST_RECENT_DAY | MOST_RECENT_WEEK | PREVIOUS_MONTH."},"time_window_start":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Time Window Start","description":"EXPLICIT only — 'YYYY-MM-DDTHH:MM:SS'."},"time_window_end":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Time Window End","description":"EXPLICIT only — 'YYYY-MM-DDTHH:MM:SS', exclusive."},"time_window_time_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Time Window Time Zone","description":"the window's IANA zone, e.g. 'Asia/Dubai' (the marketplace's own day); default UTC."},"parameter_values":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Parameter Values","description":"values for parameters the SQL declares."},"dry_run":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Dry Run","description":"true to validate the SQL and the time window only — nothing is computed, no Amazon quota is used; the run then ends SUCCEEDED (valid, no rows) or REJECTED with Amazon's reason."}},"required":["store","country_code","sql_query"],"title":"ads_create_workflow_executionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"workflow_execution_id":{"description":"pass to ads_get_workflow_execution."},"status":{"description":"PENDING at first."},"result":{"properties":{"workflowExecution":{"properties":{"acrCollaborationId":{},"acrCustomerMembershipId":{},"acrDetailPageUrl":{},"acrProtectedQueryId":{},"advertisers":{"items":{"properties":{"id":{},"marketplaceId":{},"type":{}}}},"createTime":{},"disableAggregationControls":{},"expireTime":{},"invalidationOffsetSecs":{},"lastUpdatedTime":{},"outputChannels":{"items":{"properties":{"acrDetailPageUrl":{},"channel":{"properties":{"acrMemberId":{},"acrMembershipId":{},"type":{}}},"status":{},"statusReason":{}}}},"outputS3URI":{},"requireSyntheticData":{},"sqlQuery":{},"status":{},"timeWindowEnd":{},"timeWindowEndOriginal":{},"timeWindowStart":{},"timeWindowStartOriginal":{},"timeWindowTimeZoneOriginal":{},"waitUntil":{},"warnings":{"items":{"properties":{"message":{}}}},"workflowExecutionId":{},"workflowExecutionTimeoutSeconds":{},"workflowId":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_workflow_executions":{"post":{"operationId":"ads_list_workflow_executions","summary":"List the AMC queries run on the store's instance — from these tools, the AMC console or a schedule — newest first, with their status.","description":"List the AMC queries run on the store's instance — from these tools, the AMC console or a schedule — newest first, with their status. Use it to find a run whose id you no longer have, or to see how many are still running before starting more. Amazon does not list dry runs. Amazon Ads API · listWorkflowExecutions · GET /amc/reporting/{instanceId}/workflowExecutions Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflow-executions/operation/listWorkflowExecutions","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_workflow_executions"},"tags":["amazon_ads"],"x-title":"Ads List Workflow Executions","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.executions[]","description":"{workflow_execution_id, status, status_reason, workflow_id, create_time, time_window_start, time_window_end, execution_seconds, sql_query}."},{"field":"data.min_creation_time","description":"the start of the period listed."},{"field":"data.nextToken","description":"set when more runs remain."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"min_creation_time":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Min Creation Time","description":"runs created at or after 'YYYY-MM-DDTHH:MM:SS'. Default: 7 days ago (UTC) when workflow_id is not given either — Amazon needs one of the two."},"max_creation_time":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Max Creation Time","description":"runs created before 'YYYY-MM-DDTHH:MM:SS'."},"time_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Time Zone","description":"the IANA zone of the two times, e.g. 'Asia/Dubai'; default UTC."},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Workflow Id","description":"only the runs of this saved workflow."},"include_cancelled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Include Cancelled","description":"true to list cancelled runs too."},"include_workflow":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Include Workflow","description":"true to add each run's SQL (data.executions[].sql_query)."},"sort_ascending":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Sort Ascending","description":"true for oldest first."},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit","description":"runs per page, 1–100."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","country_code"],"title":"ads_list_workflow_executionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"executions":{"description":"{workflow_execution_id, status, status_reason, workflow_id, create_time, time_window_start, time_window_end, execution_seconds, sql_query}."},"min_creation_time":{"description":"the start of the period listed."},"nextToken":{"description":"set when more runs remain."},"result":{"properties":{"executions":{"items":{"properties":{"acrCollaborationId":{},"acrCustomerMembershipId":{},"acrDetailPageUrl":{},"acrProtectedQueryId":{},"advertisers":{"items":{"properties":{"id":{},"marketplaceId":{},"type":{}}}},"createTime":{},"disableAggregationControls":{},"expireTime":{},"invalidationOffsetSecs":{},"lastUpdatedTime":{},"outputChannels":{"items":{"properties":{"acrDetailPageUrl":{},"channel":{"properties":{"acrMemberId":{},"acrMembershipId":{},"type":{}}},"status":{},"statusReason":{}}}},"outputS3URI":{},"requireSyntheticData":{},"sqlQuery":{},"status":{},"timeWindowEnd":{},"timeWindowEndOriginal":{},"timeWindowStart":{},"timeWindowStartOriginal":{},"timeWindowTimeZoneOriginal":{},"waitUntil":{},"warnings":{"items":{"properties":{"message":{}}}},"workflowExecutionId":{},"workflowExecutionTimeoutSeconds":{},"workflowId":{}}}},"nextToken":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_workflow_execution":{"post":{"operationId":"ads_update_workflow_execution","summary":"Cancel an AMC query that is still PENDING or RUNNING — Amazon's UpdateWorkflowExecution, whose one documented change is the status CANCELLED.","description":"Cancel an AMC query that is still PENDING or RUNNING — Amazon's UpdateWorkflowExecution, whose one documented change is the status CANCELLED. Use it to stop a query started by mistake or one that runs too long; it frees one of the instance's 10 parallel runs. Amazon Ads API · UpdateWorkflowExecution · PUT /amc/reporting/{instanceId}/workflowExecutions/{workflowExecutionId} Amazon Ads API · getWorkflowExecution · GET /amc/reporting/{instanceId}/workflowExecutions/{workflowExecutionId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflow-executions/operation/UpdateWorkflowExecution Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflow-executions/operation/getWorkflowExecution","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_workflow_execution"},"tags":["amazon_ads"],"x-title":"Ads Update Workflow Execution","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"description":"the orchestrated result described below."},{"field":"data.status","description":"CANCELLED."}],"x-notes":{"Gotchas":["- Gate: none — it stops a report request; nothing the seller owns changes.","- A run that has already finished (SUCCEEDED, FAILED, REJECTED) cannot be cancelled:","      Amazon answers 400."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"workflow_execution_id":{"title":"Workflow Execution Id","type":"string","description":"data.workflow_execution_id from ads_create_workflow_execution or ads_list_workflow_executions."}},"required":["store","country_code","workflow_execution_id"],"title":"ads_update_workflow_executionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"CANCELLED."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_workflow_execution":{"post":{"operationId":"ads_get_workflow_execution","summary":"The status of an AMC query from ads_create_workflow_execution.","description":"The status of an AMC query from ads_create_workflow_execution. Poll every 15–30 seconds; most queries finish within two minutes. Amazon Ads API · getWorkflowExecution · GET /amc/reporting/{instanceId}/workflowExecutions/{workflowExecutionId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflow-executions/operation/getWorkflowExecution","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_workflow_execution"},"tags":["amazon_ads"],"x-title":"Ads Get Workflow Execution","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.status","description":"SUCCEEDED when the rows are ready; PENDING or RUNNING while AMC works; REJECTED when AMC refused the SQL (a privacy rule or a syntax error — Amazon answers it although its spec omits it), FAILED or CANCELLED otherwise."},{"field":"data.status_reason","description":"Amazon's sentence when REJECTED or FAILED — fix the SQL by it."},{"field":"data.output_columns[]","description":"{name, column_type, data_type} once validated."}],"x-notes":{"Params (Amazon schema)":["instanceId*: string","workflowExecutionId*: string","includeWorkflow: boolean"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"workflow_execution_id":{"title":"Workflow Execution Id","type":"string","description":"data.workflow_execution_id from ads_create_workflow_execution."}},"required":["store","country_code","workflow_execution_id"],"title":"ads_get_workflow_executionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"SUCCEEDED when the rows are ready; PENDING or RUNNING while AMC works; REJECTED when AMC refused the SQL (a privacy rule or a syntax error — Amazon answers it although its spec omits it), FAILED or CANCELLED otherwise."},"status_reason":{"description":"Amazon's sentence when REJECTED or FAILED — fix the SQL by it."},"output_columns":{"description":"{name, column_type, data_type} once validated."},"result":{"properties":{"workflowExecution":{"properties":{"acrCollaborationId":{},"acrCustomerMembershipId":{},"acrDetailPageUrl":{},"acrProtectedQueryId":{},"advertisers":{"items":{"properties":{"id":{},"marketplaceId":{},"type":{}}}},"createTime":{},"disableAggregationControls":{},"expireTime":{},"invalidationOffsetSecs":{},"lastUpdatedTime":{},"outputChannels":{"items":{"properties":{"acrDetailPageUrl":{},"channel":{"properties":{"acrMemberId":{},"acrMembershipId":{},"type":{}}},"status":{},"statusReason":{}}}},"outputS3URI":{},"requireSyntheticData":{},"sqlQuery":{},"status":{},"timeWindowEnd":{},"timeWindowEndOriginal":{},"timeWindowStart":{},"timeWindowStartOriginal":{},"timeWindowTimeZoneOriginal":{},"waitUntil":{},"warnings":{"items":{"properties":{"message":{}}}},"workflowExecutionId":{},"workflowExecutionTimeoutSeconds":{},"workflowId":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_workflow_execution_download_urls":{"post":{"operationId":"ads_get_workflow_execution_download_urls","summary":"The finished result of an AMC query as rows: the tool downloads Amazon's result file and returns its rows (no download links).","description":"The finished result of an AMC query as rows: the tool downloads Amazon's result file and returns its rows (no download links). Only for a SUCCEEDED query. Amazon Ads API · getWorkflowExecutionDownloadUrls · GET /amc/reporting/{instanceId}/workflowExecutions/{workflowExecutionId}/downloadUrls Amazon Ads API · getWorkflowExecution · GET /amc/reporting/{instanceId}/workflowExecutions/{workflowExecutionId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflow-executions/operation/getWorkflowExecutionDownloadUrls Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflow-executions/operation/getWorkflowExecution","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_workflow_execution_download_urls"},"tags":["amazon_ads"],"x-title":"Ads Get Workflow Execution Download Urls","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"description":"the orchestrated result described below."},{"field":"data.columns","description":"the result's column names."},{"field":"data.rows[]","description":"one dict per row; every value is a string, as in Amazon's CSV."},{"field":"data.row_count","description":"the result's rows; data.returned_rows: the rows in data.rows."},{"field":"data.row_count_complete","type":"bool","description":"false when the result is over 20 MB — row_count then counts only the rows read; aggregate more and run it again."},{"field":"data.truncated","type":"bool","description":"true when data.rows holds fewer rows than the result."},{"field":"data.hidden_rows","description":"rows, of the whole result, whose group columns are blank — AMC hides a group with too few shoppers (an empty value looks the same); their metrics still add up; group more broadly to see them."}],"x-notes":{"Gotchas":["- AMC `purchases` counts the advertised product only; `total_purchases` adds the","      brand's other products (what the Ads reports call purchases)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"workflow_execution_id":{"title":"Workflow Execution Id","type":"string","description":"data.workflow_execution_id from ads_create_workflow_execution."},"max_rows":{"default":1000,"title":"Max Rows","type":"integer","description":"rows to return, 1–10000 (default 1000); every row is still counted in data.row_count."}},"required":["store","country_code","workflow_execution_id"],"title":"ads_get_workflow_execution_download_urlsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"columns":{"description":"the result's column names."},"rows":{"description":"one dict per row; every value is a string, as in Amazon's CSV."},"row_count":{"description":"the result's rows; data.returned_rows: the rows in data.rows."},"row_count_complete":{"description":"false when the result is over 20 MB — row_count then counts only the rows read; aggregate more and run it again."},"truncated":{"description":"true when data.rows holds fewer rows than the result."},"hidden_rows":{"description":"rows, of the whole result, whose group columns are blank — AMC hides a group with too few shoppers (an empty value looks the same); their metrics still add up; group more broadly to see them."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/list_amc_templates":{"post":{"operationId":"list_amc_templates","summary":"The AMC queries SellerSheet runs for every store whose AMC is on, and the warehouse table each one fills.","description":"The AMC queries SellerSheet runs for every store whose AMC is on, and the warehouse table each one fills. Read this before writing your own AMC SQL: the answer may already be synced — query its table with query_report_data (get_table_schema gives the columns) instead of running ads_create_workflow_execution.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/list_amc_templates"},"tags":["sellersheet"],"x-title":"List AMC Templates","x-access":"read","x-family":null,"x-returns":[{"field":"data.templates[]","description":"{key, version, question, how_to_read, sql, data_sources, mode, cadence, period_days, synced_table, dimensions, metrics, hidden_column, enabled_by_default, notes}."},{"field":"data.templates[].synced_table","description":"the rpt_amc_* table; one row per store, country, period_start and group of dimensions."},{"field":"data.templates[].how_to_read","description":"units and caveats — read it before quoting a number."}],"x-notes":{"Gotchas":["Each period has ONE row with hidden=true: everything AMC suppressed under its","    privacy floor, summed. Totals include it; per-group answers leave it out.","period_start is the first marketplace-local day of the period (7 or 28 days,","    period_days), not a day of activity.","mode scheduled = Amazon runs it weekly; on_demand = every 4 weeks, 15 days after","    the period ends (attribution settles). A template with enabled_by_default false","    is not synced unless turned on."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Key","description":"one template, e.g. 'AMC_NTB_BY_CAMPAIGN'; omit for all of them."}},"title":"list_amc_templatesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"templates":{"description":"{key, version, question, how_to_read, sql, data_sources, mode, cadence, period_days, synced_table, dimensions, metrics, hidden_column, enabled_by_default, notes}.","items":{"properties":{"synced_table":{"description":"the rpt_amc_* table; one row per store, country, period_start and group of dimensions."},"how_to_read":{"description":"units and caveats — read it before quoting a number."}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_all_query_based_audiences_by_instance_id":{"post":{"operationId":"ads_get_all_query_based_audiences_by_instance_id","summary":"List the AMC audiences of the store's instance — rule-based and lookalike, made by these tools or in the AMC console — with their status and size.","description":"List the AMC audiences of the store's instance — rule-based and lookalike, made by these tools or in the AMC console — with their status and size. Amazon Ads API · getAllQueryBasedAudiencesByInstanceId · GET /amc/audiences/query Docs: https://advertising.amazon.com/API/docs/en-us/amc-rba#tag/Rule-based-audience/operation/getAllQueryBasedAudiencesByInstanceId","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_all_query_based_audiences_by_instance_id"},"tags":["amazon_ads"],"x-title":"Ads Get All Query Based Audiences by Instance ID","x-access":"read","x-family":"ads.amc-audiences","x-returns":[{"field":"data.audiences[]","description":"{audience_execution_id, audience_name, audience_type (RULE_BASED | LOOKALIKE), status (PENDING | RUNNING | SUCCEEDED | FAILED | DEACTIVATED), status_reason, audience_count, deletable, create_time, last_refreshed_time, query}."},{"field":"data.nextToken","description":"set when more audiences remain."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"max_results":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Results","description":"audiences per page, 1–100 (Amazon's default 100)."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store","country_code"],"title":"ads_get_all_query_based_audiences_by_instance_idArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"audiences":{"description":"{audience_execution_id, audience_name, audience_type (RULE_BASED | LOOKALIKE), status (PENDING | RUNNING | SUCCEEDED | FAILED | DEACTIVATED), status_reason, audience_count, deletable, create_time, last_refreshed_time, query}."},"nextToken":{"description":"set when more audiences remain."},"result":{"properties":{"executionMetadata":{"items":{"properties":{"advertiserId":{},"audienceDescription":{},"audienceExecutionId":{},"audienceName":{},"countryCode":{},"createTime":{},"dspAudienceId":{},"instanceId":{},"lastRefreshedTime":{},"query":{},"refreshRateDays":{},"status":{},"statusReason":{},"timeWindowEnd":{},"timeWindowRelative":{},"timeWindowStart":{}}}},"nextToken":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_query_based_audience_by_audience_execution_id":{"post":{"operationId":"ads_get_query_based_audience_by_audience_execution_id","summary":"One AMC audience's status — poll it after creating one.","description":"One AMC audience's status — poll it after creating one. SUCCEEDED means Amazon has sent it to the store's sponsored-ads account, where it appears within 2–24 hours; ads_list_targetable_entities then gives the audienceId campaigns take. Amazon Ads API · getQueryBasedAudienceByAudienceExecutionId · GET /amc/audiences/query/{audienceExecutionId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-rba#tag/Rule-based-audience/operation/getQueryBasedAudienceByAudienceExecutionId","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_query_based_audience_by_audience_execution_id"},"tags":["amazon_ads"],"x-title":"Ads Get Query Based Audience by Audience Execution ID","x-access":"read","x-family":"ads.amc-audiences","x-returns":[{"field":"data.audience","description":"{audience_execution_id, audience_name, audience_type, status, status_reason, audience_count, deletable, time_window_start, time_window_end, query}."}],"x-notes":{"Gotchas":["- FAILED comes back as an error notification carrying Amazon's status_reason — most","      often fewer than 2,000 shoppers, or a table without the _for_audiences suffix.","      Fix it with ads_update_query_based_audience_by_audience_execution_id or delete it.","- DEACTIVATED: the audience has no members any more (unused for long, or refresh off)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"audience_execution_id":{"title":"Audience Execution Id","type":"string","description":"data.audience_execution_id from a create, or from ads_get_all_query_based_audiences_by_instance_id."}},"required":["store","country_code","audience_execution_id"],"title":"ads_get_query_based_audience_by_audience_execution_idArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"audience":{"description":"{audience_execution_id, audience_name, audience_type, status, status_reason, audience_count, deletable, time_window_start, time_window_end, query}."},"result":{"properties":{"advertiserId":{},"audienceDescription":{},"audienceExecutionId":{},"audienceName":{},"countryCode":{},"createTime":{},"dspAudienceId":{},"instanceId":{},"lastRefreshedTime":{},"query":{},"refreshRateDays":{},"status":{},"statusReason":{},"timeWindowEnd":{},"timeWindowRelative":{},"timeWindowStart":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_query_based_audience":{"post":{"operationId":"ads_create_query_based_audience","summary":"Create an AMC rule-based audience: the shoppers an AMC query selects become an audience in the store's sponsored-ads account — a Sponsored Products / Brands bid adjustment (bidAdju","description":"Create an AMC rule-based audience: the shoppers an AMC query selects become an audience in the store's sponsored-ads account — a Sponsored Products / Brands bid adjustment (bidAdjustments.audienceBidAdjustments in ads_update_campaign) or a Sponsored Display target. Ask the seller first: an audience cannot be edited once created. Amazon Ads API · createQueryBasedAudience · POST /amc/audiences/query Docs: https://advertising.amazon.com/API/docs/en-us/amc-rba#tag/Rule-based-audience/operation/createQueryBasedAudience Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_query_based_audience"},"tags":["amazon_ads"],"x-title":"Ads Create Query Based Audience","x-access":"write","x-family":"ads.amc-audiences","x-returns":[{"field":"data.audience_execution_id","description":"poll it with ads_get_query_based_audience_by_audience_execution_id."},{"field":"data.status","description":"PENDING at first."}],"x-notes":{"Body (Amazon schema)":["advertiserId*: string","audienceDescription: string","audienceName*: string","countryCode: AE | AU | BR | CA | DE | ES | FR | IN | IT | JP | MX | NL | SA | SE | TR | UK | US","inputParameters: [{columnType: DIMENSION | METRIC, dataType*: string | {elementDataType, elementNullable, type} | {precision, type} | {keyDataType, type, valueDataType, valueNullable} | {fields, type}, defaultValue, description, name*}] (max 100)","inputParameters.dataType.type: ARRAY | DECIMAL | MAP | STRUCT","parameterValues: object","query: string","refreshRateDays: integer (0–21; default 21)","timeWindowEnd*: string (date-time)","timeWindowRelative: boolean (default False)","timeWindowStart*: string (date-time)","workflowId: string"],"Gotchas":["- Gate: commit — the audience goes to the seller's ads account and cannot be changed.","- The advertiser is the store's AMC instance's own; it is not a parameter.","- Amazon refreshes the audience itself; one left unused in campaigns is refreshed","      less often and deactivated after about 100 days."],"Workflow":["1. Count the shoppers first with ads_create_workflow_execution","   (SELECT COUNT(DISTINCT user_id) … over the same tables without _for_audiences);","   Amazon fails an audience under 2,000 (aim for 2,500).","2. Create it here; poll ads_get_query_based_audience_by_audience_execution_id.","3. When it SUCCEEDED, find its audienceId with ads_list_targetable_entities."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"audience_name":{"title":"Audience Name","type":"string","description":"shown in the Ads console; use a new name for each audience."},"sql_query":{"title":"Sql Query","type":"string","description":"AMC SQL over the *_for_audiences tables (sponsored_ads_traffic_for_audiences, conversions_for_audiences, …) whose SELECT returns user_id."},"time_window_start":{"format":"date-time","title":"Time Window Start","type":"string","description":"UTC 'YYYY-MM-DDTHH:MM:SSZ'."},"time_window_end":{"format":"date-time","title":"Time Window End","type":"string","description":"UTC 'YYYY-MM-DDTHH:MM:SSZ'."},"audience_description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Audience Description","description":"optional text shown with the audience."},"time_window_relative":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Time Window Relative","description":"true to move the window forward at each refresh (recent shoppers)."},"parameter_values":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Parameter Values","description":"values for parameters the SQL declares."}},"required":["store","country_code","audience_name","sql_query","time_window_start","time_window_end"],"title":"ads_create_query_based_audienceArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"audience_execution_id":{"description":"poll it with ads_get_query_based_audience_by_audience_execution_id."},"status":{"description":"PENDING at first."},"result":{"properties":{"audienceExecutionDescription":{},"audienceExecutionId":{},"status":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_lookalike_audience":{"post":{"operationId":"ads_create_lookalike_audience","summary":"Create an AMC lookalike audience: Amazon models shoppers similar to a seed the AMC query selects (for example the store's ad clickers) and activates them in the store's sponsored-a","description":"Create an AMC lookalike audience: Amazon models shoppers similar to a seed the AMC query selects (for example the store's ad clickers) and activates them in the store's sponsored-ads account. Ask the seller first. Amazon Ads API · createLookalikeAudience · POST /amc/audiences/lookalike Docs: https://advertising.amazon.com/API/docs/en-us/amc-rba#tag/Rule-based-audience-lookalike/operation/createLookalikeAudience Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_lookalike_audience"},"tags":["amazon_ads"],"x-title":"Ads Create Lookalike Audience","x-access":"write","x-family":"ads.amc-audiences","x-returns":[{"field":"data.audience_execution_id","description":"poll it with ads_get_query_based_audience_by_audience_execution_id."},{"field":"data.status","description":"PENDING at first."}],"x-notes":{"Body (Amazon schema)":["advertiserId*: string","audienceDescription: string","audienceName*: string","countryCode: AE | AU | BR | CA | DE | ES | FR | IN | IT | JP | MX | NL | SA | SE | TR | UK | US","inputParameters: [{columnType: DIMENSION | METRIC, dataType*: string | {elementDataType, elementNullable, type} | {precision, type} | {keyDataType, type, valueDataType, valueNullable} | {fields, type}, defaultValue, description, name*}] (max 100)","inputParameters.dataType.type: ARRAY | DECIMAL | MAP | STRUCT","parameterValues: object","query: string","refreshRateDays: integer (7–21; default 21)","timeWindowEnd*: string (date-time)","timeWindowRelative: boolean (default False)","timeWindowStart*: string (date-time)","workflowId: string","lookalikeAudienceExpectedReach*: string"],"Gotchas":["- Gate: commit — the audience goes to the seller's ads account and cannot be changed.","- Only the lookalike is created, not a copy of the seed.","- A seed that clears 500 in an AMC count can still FAIL after about 20 minutes with \"did","- not find a sufficient match for seed users\" (measured: 716 ad clickers over 28 days) —","- Amazon keeps only shoppers it can match; seed broadly (reach, or a longer window)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"audience_name":{"title":"Audience Name","type":"string","description":"shown in the Ads console; use a new name for each audience."},"sql_query":{"title":"Sql Query","type":"string","description":"AMC SQL over the *_for_audiences tables whose SELECT returns user_id — the seed, 500 to 500,000 shoppers (count it first with ads_create_workflow_execution)."},"time_window_start":{"format":"date-time","title":"Time Window Start","type":"string","description":"UTC 'YYYY-MM-DDTHH:MM:SSZ'."},"time_window_end":{"format":"date-time","title":"Time Window End","type":"string","description":"UTC 'YYYY-MM-DDTHH:MM:SSZ'."},"lookalike_audience_expected_reach":{"title":"Lookalike Audience Expected Reach","type":"string","description":"how far from the seed to reach. Allowed: MOST_SIMILAR | SIMILAR | BALANCED | BROAD | MOST_BROAD. MOST_SIMILAR gives the smallest, closest audience (about 500K–1M shoppers in Europe and the Americas, 200K–300K in Asia); MOST_BROAD the largest."},"audience_description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Audience Description","description":"optional text shown with the audience."},"time_window_relative":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Time Window Relative","description":"true to move the seed's window forward at each refresh."},"parameter_values":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Parameter Values","description":"values for parameters the SQL declares."}},"required":["store","country_code","audience_name","sql_query","time_window_start","time_window_end","lookalike_audience_expected_reach"],"title":"ads_create_lookalike_audienceArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"audience_execution_id":{"description":"poll it with ads_get_query_based_audience_by_audience_execution_id."},"status":{"description":"PENDING at first."},"result":{"properties":{"audienceExecutionDescription":{},"audienceExecutionId":{},"status":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_query_based_audience_by_audience_execution_id":{"post":{"operationId":"ads_update_query_based_audience_by_audience_execution_id","summary":"Fix a FAILED AMC audience and run it again — Amazon accepts an update on a FAILED audience only; a working one cannot be changed (create a new one).","description":"Fix a FAILED AMC audience and run it again — Amazon accepts an update on a FAILED audience only; a working one cannot be changed (create a new one). Pass only what changes: the name, type and description stay as they are. Amazon Ads API · updateQueryBasedAudienceByAudienceExecutionId · PUT /amc/audiences/query/{audienceExecutionId} Amazon Ads API · getQueryBasedAudienceByAudienceExecutionId · GET /amc/audiences/query/{audienceExecutionId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-rba#tag/Rule-based-audience/operation/updateQueryBasedAudienceByAudienceExecutionId Docs: https://advertising.amazon.com/API/docs/en-us/amc-rba#tag/Rule-based-audience/operation/getQueryBasedAudienceByAudienceExecutionId Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_query_based_audience_by_audience_execution_id"},"tags":["amazon_ads"],"x-title":"Ads Update Query Based Audience by Audience Execution ID","x-access":"destructive","x-family":"ads.amc-audiences","x-returns":[{"description":"the orchestrated result described below."},{"field":"data.audience","description":"the audience as updated, status PENDING again."}],"x-notes":{"Gotchas":["- Refused before any change when the audience is not FAILED."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"audience_execution_id":{"title":"Audience Execution Id","type":"string","description":"the FAILED audience's data.audience_execution_id."},"sql_query":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sql Query","description":"the corrected AMC SQL (still over *_for_audiences tables, SELECT user_id)."},"time_window_start":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Time Window Start","description":"UTC 'YYYY-MM-DDTHH:MM:SSZ'."},"time_window_end":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Time Window End","description":"UTC 'YYYY-MM-DDTHH:MM:SSZ'."},"time_window_relative":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Time Window Relative","description":"true to move the window forward at each refresh."},"parameter_values":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Parameter Values","description":"values for parameters the SQL declares."},"lookalike_audience_expected_reach":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Lookalike Audience Expected Reach","description":"a lookalike's reach. Allowed: MOST_SIMILAR | SIMILAR | BALANCED | BROAD | MOST_BROAD."}},"required":["store","country_code","audience_execution_id"],"title":"ads_update_query_based_audience_by_audience_execution_idArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"audience":{"description":"the audience as updated, status PENDING again."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_query_based_audience_by_audience_execution_id":{"post":{"operationId":"ads_delete_query_based_audience_by_audience_execution_id","summary":"Delete an AMC audience (FAILED or SUCCEEDED) and its segment in the sponsored-ads account.","description":"Delete an AMC audience (FAILED or SUCCEEDED) and its segment in the sponsored-ads account. Ask the seller first: it cannot be undone. Amazon Ads API · deleteQueryBasedAudienceByAudienceExecutionId · DELETE /amc/audiences/query/{audienceExecutionId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-rba#tag/Rule-based-audience/operation/deleteQueryBasedAudienceByAudienceExecutionId Gate: commit — interactive: restate exactly what will happen, wait for a typed CONFIRM; autopilot: only within the seller's instruction and stated limits; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_query_based_audience_by_audience_execution_id"},"tags":["amazon_ads"],"x-title":"Ads Delete Query Based Audience by Audience Execution ID","x-access":"destructive","x-family":"ads.amc-audiences","x-returns":[{"field":"data.deleted","type":"bool","description":"true when Amazon removed it."}],"x-notes":{"Gotchas":["- Gate: commit — irreversible.","- Take it out of every campaign first: Amazon refuses an audience it sees in use, but","      only on a best-effort check."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"audience_execution_id":{"title":"Audience Execution Id","type":"string","description":"the audience's data.audience_execution_id."}},"required":["store","country_code","audience_execution_id"],"title":"ads_delete_query_based_audience_by_audience_execution_idArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"deleted":{"description":"true when Amazon removed it."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_targetable_entities":{"post":{"operationId":"ads_list_targetable_entities","summary":"List what a sponsored-ads campaign can target in the store's Ads account (Amazon's Discovery API).","description":"List what a sponsored-ads campaign can target in the store's Ads account (Amazon's Discovery API). By default it lists the store's AMC audiences — the audienceId a Sponsored Products / Brands audience bid adjustment or a Sponsored Display target takes. Amazon Ads API · ListTargetableEntities · POST /targetableEntities/list Docs: https://advertising.amazon.com/API/docs/en-us/targetable-entities#operation/ListTargetableEntities","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_targetable_entities"},"tags":["amazon_ads"],"x-title":"Ads List Targetable Entities","x-access":"read","x-family":"ads.targetable-entities","x-returns":[{"field":"data.targetable_entities[]","description":"Amazon's entities — {audienceId, audienceResolved, path, targetType, …}."},{"field":"data.nextToken","description":"set when more entities remain."}],"x-notes":{"Body (Amazon schema)":["adProduct*: SPONSORED_BRANDS | SPONSORED_DISPLAY | SPONSORED_PRODUCTS | SPONSORED_TELEVISION","locale: ar_AE | de_DE | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | en_ZA | es_ES | es_MX | fr_CA | fr_FR | hi_IN | it_IT | ja_JP | ko_KR | nl_NL | pl_PL | pt_BR | sv_SE | ta_IN | th_TH | tr_TR | vi_VN | zh_CN","maxResults: number (1–250)","nextToken: string","parentBrowseNodeIdFilter: [string] (max 1000)","pathsFilter: [[string] (max 10)] (max 10)","productCategoryIdFilter: [string] (max 1000)","searchQueryFilter: string","targetTypeFilter: [AUDIENCE | CONTENT_CATEGORY | PRODUCT_CATEGORY | PRODUCT_CATEGORY_AUDIENCE] (max 4)"],"Gotchas":["- An AMC audience appears here 2–24 hours after it SUCCEEDED."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"ad_product":{"enum":["SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"title":"Ad Product","type":"string","description":"the campaign type the entities are for. Allowed: SPONSORED_BRANDS | SPONSORED_DISPLAY | SPONSORED_PRODUCTS | SPONSORED_TELEVISION."},"target_type_filter":{"anyOf":[{"items":{"enum":["AUDIENCE","CONTENT_CATEGORY","PRODUCT_CATEGORY","PRODUCT_CATEGORY_AUDIENCE"],"type":"string"},"maxItems":4,"type":"array"},{"type":"null"}],"default":null,"title":"Target Type Filter","description":"entity types; default ['AUDIENCE']. Allowed: AUDIENCE | CONTENT_CATEGORY | PRODUCT_CATEGORY | PRODUCT_CATEGORY_AUDIENCE."},"paths_filter":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Paths Filter","description":"taxonomy paths to list under; default [['Audience Category', 'Custom-built', 'AMC']] (the AMC audiences)."},"search_query_filter":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Search Query Filter","description":"words to search the entities for."},"max_results":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Results","description":"entities per page."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."},"locale":{"anyOf":[{"enum":["ar_AE","de_DE","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","en_ZA","es_ES","es_MX","fr_CA","fr_FR","hi_IN","it_IT","ja_JP","ko_KR","nl_NL","pl_PL","pt_BR","sv_SE","ta_IN","th_TH","tr_TR","vi_VN","zh_CN"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"names in this locale, e.g. 'en_AE'. Allowed: ar_AE | de_DE | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | en_ZA | es_ES | es_MX | fr_CA | fr_FR | hi_IN | it_IT | ja_JP | ko_KR | nl_NL | pl_PL | pt_BR | sv_SE | ta_IN | th_TH | tr_TR | vi_VN | zh_CN."}},"required":["store","country_code","ad_product"],"title":"ads_list_targetable_entitiesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"targetable_entities":{"description":"Amazon's entities — {audienceId, audienceResolved, path, targetType, …}."},"nextToken":{"description":"set when more entities remain."},"result":{"properties":{"nextToken":{},"targetableEntities":{"items":{"properties":{"audienceId":{},"audienceResolved":{},"audienceTooltip":{},"behaviouralTargetingEligibility":{},"childCount":{},"contentCategoryId":{},"contentCategoryResolved":{},"parentBrowseNodeId":{},"path":{"items":{}},"pathNodeIds":{"items":{}},"productCategoryId":{},"productCategoryResolved":{},"targetType":{}}}},"totalResults":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_workflows":{"post":{"operationId":"ads_list_workflows","summary":"List the saved AMC queries (workflows) on the store's instance: the seller's own, and SellerSheet's synced report templates (named in data.synced_ids — read-only here; their rows a","description":"List the saved AMC queries (workflows) on the store's instance: the seller's own, and SellerSheet's synced report templates (named in data.synced_ids — read-only here; their rows are in the rpt_amc_* tables, see list_amc_templates). Amazon Ads API · listWorkflows · GET /amc/reporting/{instanceId}/workflows Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflows/operation/listWorkflows","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_workflows"},"tags":["amazon_ads"],"x-title":"Ads List Workflows","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.workflows[]","description":"Amazon's saved workflows — {workflowId, sqlQuery, …}."},{"field":"data.synced_ids[]","description":"the workflows that are SellerSheet's synced reports."},{"field":"data.nextToken","description":"set when more workflows remain."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit","description":"workflows per page."}},"required":["store","country_code"],"title":"ads_list_workflowsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"workflows":{"description":"Amazon's saved workflows — {workflowId, sqlQuery, …}."},"synced_ids":{"description":"the workflows that are SellerSheet's synced reports."},"nextToken":{"description":"set when more workflows remain."},"result":{"properties":{"nextToken":{},"workflows":{"items":{"properties":{"filteredMetricsDiscriminatorColumn":{},"inputParameters":{"items":{"properties":{"columnType":{},"dataType":{},"defaultValue":{},"description":{},"displayName":{},"name":{}}}},"inputSchema":{},"outputColumns":{"items":{"properties":{"columnType":{},"dataType":{},"dataTypePrecision":{},"dataTypeScale":{},"description":{},"name":{}}}},"outputFormat":{"properties":{"escapeCharacter":{},"quoteCharacter":{},"separatorCharacter":{}}},"privacyFilteringBehavior":{},"query":{"items":{}},"sqlQuery":{},"workflowId":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_workflow":{"post":{"operationId":"ads_get_workflow","summary":"Read one saved AMC query (workflow) on the store's instance: its SQL, parameters and output settings.","description":"Read one saved AMC query (workflow) on the store's instance: its SQL, parameters and output settings. Amazon Ads API · getWorkflow · GET /amc/reporting/{instanceId}/workflows/{workflowId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflows/operation/getWorkflow","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_workflow"},"tags":["amazon_ads"],"x-title":"Ads Get Workflow","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.workflow","description":"Amazon's workflow — {workflowId, sqlQuery, inputParameters, …}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"workflow_id":{"title":"Workflow Id","type":"string","description":"the saved workflow's id (data.workflows[].workflowId)."}},"required":["store","country_code","workflow_id"],"title":"ads_get_workflowArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"workflow":{"description":"Amazon's workflow — {workflowId, sqlQuery, inputParameters, …}."},"result":{"properties":{"workflow":{"properties":{"filteredMetricsDiscriminatorColumn":{},"inputParameters":{"items":{"properties":{"columnType":{},"dataType":{},"defaultValue":{},"description":{},"displayName":{},"name":{}}}},"inputSchema":{},"outputColumns":{"items":{"properties":{"columnType":{},"dataType":{},"dataTypePrecision":{},"dataTypeScale":{},"description":{},"name":{}}}},"outputFormat":{"properties":{"escapeCharacter":{},"quoteCharacter":{},"separatorCharacter":{}}},"privacyFilteringBehavior":{},"query":{"items":{}},"sqlQuery":{},"workflowId":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_workflow":{"post":{"operationId":"ads_create_workflow","summary":"Save an AMC query on the store's instance under an id of your choosing, so a schedule (ads_create_schedule) can run it every day or week.","description":"Save an AMC query on the store's instance under an id of your choosing, so a schedule (ads_create_schedule) can run it every day or week. Ask the seller first. Amazon Ads API · createWorkflow · POST /amc/reporting/{instanceId}/workflows Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflows/operation/createWorkflow Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_workflow"},"tags":["amazon_ads"],"x-title":"Ads Create Workflow","x-access":"write","x-family":"ads.amc-reporting","x-returns":[{"field":"data.workflow_id","description":"the saved workflow's id."}],"x-notes":{"Gotchas":["- A synced report's workflow (data.synced_ids of ads_list_workflows) is refused.","- Check the SQL first with ads_create_workflow_execution (dry_run true)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"filteredMetricsDiscriminatorColumn":{"type":"string"},"inputParameters":{"items":{"additionalProperties":true,"properties":{"columnType":{"enum":["DIMENSION","METRIC"],"type":"string"},"dataType":{"enum":["BINARY","BOOLEAN","BYTE","CALENDAR_INTERVAL","DATE","DECIMAL","DOUBLE","FLOAT","INTEGER","LONG","SHORT","STRING","TIMESTAMP"],"type":"string"},"defaultValue":{"type":"string"},"description":{"type":"string"},"displayName":{"type":"string"},"name":{"type":"string"}},"type":"object"},"maxItems":100,"minItems":0,"type":"array"},"inputSchema":{"type":"string"},"outputColumns":{"items":{"additionalProperties":true,"properties":{"columnType":{"enum":["DIMENSION","METRIC"],"type":"string"},"dataType":{"enum":["BINARY","BOOLEAN","BYTE","CALENDAR_INTERVAL","DATE","DECIMAL","DOUBLE","FLOAT","INTEGER","LONG","SHORT","STRING","TIMESTAMP"],"type":"string"},"dataTypePrecision":{"type":"integer"},"dataTypeScale":{"type":"integer"},"description":{"type":"string"},"name":{"type":"string"}},"type":"object"},"maxItems":100,"minItems":0,"type":"array"},"outputFormat":{"additionalProperties":true,"properties":{"escapeCharacter":{"type":"string"},"quoteCharacter":{"type":"string"},"separatorCharacter":{"type":"string"}},"type":"object"},"privacyFilteringBehavior":{"enum":["REMOVE_ROWS","REMOVE_VALUES"],"type":"string"},"query":{"items":{"format":"byte","type":"string"},"maxItems":100,"minItems":0,"type":"array"},"sqlQuery":{"type":"string"},"workflowId":{"type":"string"}},"title":"Body","type":"object","description":"the request body — its fields, enums and required marks are in this parameter's schema. workflowId (letters, digits, '_', '-', '.') and sqlQuery are required; the SQL is the same AMC SQL as ads_create_workflow_execution's."}},"required":["store","country_code","body"],"title":"ads_create_workflowArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"workflow_id":{"description":"the saved workflow's id."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_workflow":{"post":{"operationId":"ads_update_workflow","summary":"Replace a saved AMC query on the store's instance.","description":"Replace a saved AMC query on the store's instance. Amazon replaces the whole workflow: send every field to keep (read it first with ads_get_workflow). Ask the seller first. Amazon Ads API · updateWorkflow · PUT /amc/reporting/{instanceId}/workflows/{workflowId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflows/operation/updateWorkflow Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_workflow"},"tags":["amazon_ads"],"x-title":"Ads Update Workflow","x-access":"destructive","x-family":"ads.amc-reporting","x-returns":[{"field":"data.workflow_id","description":"the workflow's id."}],"x-notes":{"Gotchas":["- Every schedule that runs the workflow runs the new SQL from then on.","- A synced report's workflow (data.synced_ids of ads_list_workflows) is refused."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"workflow_id":{"title":"Workflow Id","type":"string","description":"the saved workflow's id."},"body":{"additionalProperties":true,"properties":{"filteredMetricsDiscriminatorColumn":{"type":"string"},"inputParameters":{"items":{"additionalProperties":true,"properties":{"columnType":{"enum":["DIMENSION","METRIC"],"type":"string"},"dataType":{"enum":["BINARY","BOOLEAN","BYTE","CALENDAR_INTERVAL","DATE","DECIMAL","DOUBLE","FLOAT","INTEGER","LONG","SHORT","STRING","TIMESTAMP"],"type":"string"},"defaultValue":{"type":"string"},"description":{"type":"string"},"displayName":{"type":"string"},"name":{"type":"string"}},"type":"object"},"maxItems":100,"minItems":0,"type":"array"},"inputSchema":{"type":"string"},"outputColumns":{"items":{"additionalProperties":true,"properties":{"columnType":{"enum":["DIMENSION","METRIC"],"type":"string"},"dataType":{"enum":["BINARY","BOOLEAN","BYTE","CALENDAR_INTERVAL","DATE","DECIMAL","DOUBLE","FLOAT","INTEGER","LONG","SHORT","STRING","TIMESTAMP"],"type":"string"},"dataTypePrecision":{"type":"integer"},"dataTypeScale":{"type":"integer"},"description":{"type":"string"},"name":{"type":"string"}},"type":"object"},"maxItems":100,"minItems":0,"type":"array"},"outputFormat":{"additionalProperties":true,"properties":{"escapeCharacter":{"type":"string"},"quoteCharacter":{"type":"string"},"separatorCharacter":{"type":"string"}},"type":"object"},"privacyFilteringBehavior":{"enum":["REMOVE_ROWS","REMOVE_VALUES"],"type":"string"},"query":{"items":{"format":"byte","type":"string"},"maxItems":100,"minItems":0,"type":"array"},"sqlQuery":{"type":"string"},"workflowId":{"type":"string"}},"title":"Body","type":"object","description":"the request body — its fields, enums and required marks are in this parameter's schema; sqlQuery is required. Its workflowId is always workflow_id."}},"required":["store","country_code","workflow_id","body"],"title":"ads_update_workflowArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"workflow_id":{"description":"the workflow's id."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_workflow":{"post":{"operationId":"ads_delete_workflow","summary":"Delete a saved AMC query from the store's instance.","description":"Delete a saved AMC query from the store's instance. Ask the seller first. Amazon Ads API · deleteWorkflow · DELETE /amc/reporting/{instanceId}/workflows/{workflowId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Workflows/operation/deleteWorkflow Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_workflow"},"tags":["amazon_ads"],"x-title":"Ads Delete Workflow","x-access":"destructive","x-family":"ads.amc-reporting","x-returns":[{"field":"data.deleted","type":"bool","description":"true when Amazon removed it."}],"x-notes":{"Gotchas":["- Its past runs stay, but it cannot be run by id again.","- Delete the schedules that run it first (ads_list_schedules names their workflowId).","- A synced report's workflow (data.synced_ids of ads_list_workflows) is refused."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"workflow_id":{"title":"Workflow Id","type":"string","description":"the saved workflow's id."}},"required":["store","country_code","workflow_id"],"title":"ads_delete_workflowArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"deleted":{"description":"true when Amazon removed it."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_schedules":{"post":{"operationId":"ads_list_schedules","summary":"List the AMC schedules on the store's instance — each runs a saved workflow Daily or Weekly.","description":"List the AMC schedules on the store's instance — each runs a saved workflow Daily or Weekly. SellerSheet's synced reports appear too (named in data.synced_ids — read-only here). Amazon Ads API · listSchedules · GET /amc/reporting/{instanceId}/schedules Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Schedules/operation/listSchedules","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_schedules"},"tags":["amazon_ads"],"x-title":"Ads List Schedules","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.schedules[]","description":"Amazon's schedules — {scheduleId, workflowId, aggregationPeriod, scheduleEnabled, …}."},{"field":"data.synced_ids[]","description":"the schedules that are SellerSheet's synced reports."},{"field":"data.nextToken","description":"set when more schedules remain."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Limit","description":"schedules per page."}},"required":["store","country_code"],"title":"ads_list_schedulesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"schedules":{"description":"Amazon's schedules — {scheduleId, workflowId, aggregationPeriod, scheduleEnabled, …}."},"synced_ids":{"description":"the schedules that are SellerSheet's synced reports."},"nextToken":{"description":"set when more schedules remain."},"result":{"properties":{"nextToken":{},"schedules":{"items":{"properties":{"aggregationHourUtc":{},"aggregationPeriod":{},"aggregationStartDay":{},"disableAggregationControls":{},"requireSyntheticData":{},"scheduleEnabled":{},"scheduleId":{},"workflowId":{}}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_get_schedule":{"post":{"operationId":"ads_get_schedule","summary":"Read one AMC schedule on the store's instance: the workflow it runs, its period and whether it is enabled.","description":"Read one AMC schedule on the store's instance: the workflow it runs, its period and whether it is enabled. Amazon Ads API · getSchedule · GET /amc/reporting/{instanceId}/schedules/{scheduleId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Schedules/operation/getSchedule","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_get_schedule"},"tags":["amazon_ads"],"x-title":"Ads Get Schedule","x-access":"read","x-family":"ads.amc-reporting","x-returns":[{"field":"data.schedule","description":"Amazon's schedule — {scheduleId, workflowId, aggregationPeriod, aggregationStartDay, aggregationHourUtc, scheduleEnabled, …}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"schedule_id":{"title":"Schedule Id","type":"string","description":"the schedule's id (data.schedules[].scheduleId)."}},"required":["store","country_code","schedule_id"],"title":"ads_get_scheduleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"schedule":{"description":"Amazon's schedule — {scheduleId, workflowId, aggregationPeriod, aggregationStartDay, aggregationHourUtc, scheduleEnabled, …}."},"result":{"properties":{"schedule":{"properties":{"aggregationHourUtc":{},"aggregationPeriod":{},"aggregationStartDay":{},"disableAggregationControls":{},"requireSyntheticData":{},"scheduleEnabled":{},"scheduleId":{},"workflowId":{}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_create_schedule":{"post":{"operationId":"ads_create_schedule","summary":"Run a saved AMC workflow on a schedule — Daily or Weekly — on the store's instance.","description":"Run a saved AMC workflow on a schedule — Daily or Weekly — on the store's instance. Each run appears in ads_list_workflow_executions (filter by its workflow_id). Ask the seller first. Amazon Ads API · createSchedule · POST /amc/reporting/{instanceId}/schedules Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Schedules/operation/createSchedule Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_create_schedule"},"tags":["amazon_ads"],"x-title":"Ads Create Schedule","x-access":"write","x-family":"ads.amc-reporting","x-returns":[{"field":"data.schedule_id","description":"the schedule's id."},{"field":"data.workflow_id","description":"the workflow it runs."}],"x-notes":{"Gotchas":["- A run's result can be downloaded for about a day; read each run in time.","- A synced report's schedule or workflow (data.synced_ids of the two list tools) is","      refused."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"body":{"additionalProperties":true,"properties":{"aggregationHourUtc":{"type":"integer"},"aggregationPeriod":{"enum":["Daily","Weekly"],"type":"string"},"aggregationStartDay":{"enum":["Friday","Monday","Saturday","Sunday","Thursday","Tuesday","Wednesday"],"type":"string"},"disableAggregationControls":{"type":"boolean"},"marketplaceId":{"type":"string"},"requireSyntheticData":{"type":"boolean"},"scheduleEnabled":{"type":"boolean"},"scheduleId":{"type":"string"},"workflowId":{"type":"string"}},"title":"Body","type":"object","description":"the request body — its fields, enums and required marks are in this parameter's schema. scheduleId, workflowId (a saved workflow) and aggregationPeriod are needed; scheduleEnabled false saves it paused. The marketplace is the store's."}},"required":["store","country_code","body"],"title":"ads_create_scheduleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"schedule_id":{"description":"the schedule's id."},"workflow_id":{"description":"the workflow it runs."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_update_schedule":{"post":{"operationId":"ads_update_schedule","summary":"Replace an AMC schedule on the store's instance — e.g.","description":"Replace an AMC schedule on the store's instance — e.g. pause it (scheduleEnabled false) or change its period. Amazon replaces the whole schedule: send every field to keep (read it first with ads_get_schedule). Ask the seller first. Amazon Ads API · updateSchedule · PUT /amc/reporting/{instanceId}/schedules/{scheduleId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Schedules/operation/updateSchedule Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_update_schedule"},"tags":["amazon_ads"],"x-title":"Ads Update Schedule","x-access":"destructive","x-family":"ads.amc-reporting","x-returns":[{"field":"data.schedule_id","description":"the schedule's id."}],"x-notes":{"Gotchas":["- A synced report's schedule or workflow (data.synced_ids of the two list tools) is","      refused."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"schedule_id":{"title":"Schedule Id","type":"string","description":"the schedule's id."},"body":{"additionalProperties":true,"properties":{"aggregationHourUtc":{"type":"integer"},"aggregationPeriod":{"enum":["Daily","Weekly"],"type":"string"},"aggregationStartDay":{"enum":["Friday","Monday","Saturday","Sunday","Thursday","Tuesday","Wednesday"],"type":"string"},"disableAggregationControls":{"type":"boolean"},"marketplaceId":{"type":"string"},"requireSyntheticData":{"type":"boolean"},"scheduleEnabled":{"type":"boolean"},"scheduleId":{"type":"string"},"workflowId":{"type":"string"}},"title":"Body","type":"object","description":"the request body — its fields, enums and required marks are in this parameter's schema. Its scheduleId is always schedule_id; the marketplace is the store's."}},"required":["store","country_code","schedule_id","body"],"title":"ads_update_scheduleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"schedule_id":{"description":"the schedule's id."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_delete_schedule":{"post":{"operationId":"ads_delete_schedule","summary":"Delete an AMC schedule from the store's instance; its workflow stays saved.","description":"Delete an AMC schedule from the store's instance; its workflow stays saved. Ask the seller first. Amazon Ads API · deleteSchedule · DELETE /amc/reporting/{instanceId}/schedules/{scheduleId} Docs: https://advertising.amazon.com/API/docs/en-us/amc-reporting#tag/Schedules/operation/deleteSchedule Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_delete_schedule"},"tags":["amazon_ads"],"x-title":"Ads Delete Schedule","x-access":"destructive","x-family":"ads.amc-reporting","x-returns":[{"field":"data.deleted","type":"bool","description":"true when Amazon removed it."}],"x-notes":{"Gotchas":["- A synced report's schedule (data.synced_ids of ads_list_schedules) is refused:","      SellerSheet removes its own when the store leaves it."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"schedule_id":{"title":"Schedule Id","type":"string","description":"the schedule's id."}},"required":["store","country_code","schedule_id"],"title":"ads_delete_scheduleArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"deleted":{"description":"true when Amazon removed it."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/ads_list_targetable_entity_paths":{"post":{"operationId":"ads_list_targetable_entity_paths","summary":"List the taxonomy paths under which ads_list_targetable_entities finds entities (Amazon's Discovery API): the direct sub-paths of each path in paths_filter, or the top level.","description":"List the taxonomy paths under which ads_list_targetable_entities finds entities (Amazon's Discovery API): the direct sub-paths of each path in paths_filter, or the top level. Amazon Ads API · ListTargetableEntityPaths · POST /targetableEntities/paths/list Docs: https://advertising.amazon.com/API/docs/en-us/targetable-entities#operation/ListTargetableEntityPaths","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/ads_list_targetable_entity_paths"},"tags":["amazon_ads"],"x-title":"Ads List Targetable Entity Paths","x-access":"read","x-family":"ads.targetable-entities","x-returns":[{"field":"data.paths[]","description":"the sub-paths, each a list of names — pass one to ads_list_targetable_entities' paths_filter."},{"field":"data.total_results","description":"how many paths Amazon has there."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"country_code":{"title":"Country Code","type":"string","description":"the Ads profile's 2-letter country code (e.g. 'US')."},"ad_product":{"enum":["SPONSORED_BRANDS","SPONSORED_DISPLAY","SPONSORED_PRODUCTS","SPONSORED_TELEVISION"],"title":"Ad Product","type":"string","description":"the campaign type the paths are for. Allowed: SPONSORED_BRANDS | SPONSORED_DISPLAY | SPONSORED_PRODUCTS | SPONSORED_TELEVISION."},"paths_filter":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Paths Filter","description":"paths to list the children of, each a list of names, e.g. [['Audience Category']]; omit for the top level."},"locale":{"anyOf":[{"enum":["ar_AE","de_DE","en_AE","en_AU","en_CA","en_GB","en_IN","en_SG","en_US","en_ZA","es_ES","es_MX","fr_CA","fr_FR","hi_IN","it_IT","ja_JP","ko_KR","nl_NL","pl_PL","pt_BR","sv_SE","ta_IN","th_TH","tr_TR","vi_VN","zh_CN"],"type":"string"},{"type":"null"}],"default":null,"title":"Locale","description":"names in this locale, e.g. 'en_AE'. Allowed: ar_AE | de_DE | en_AE | en_AU | en_CA | en_GB | en_IN | en_SG | en_US | en_ZA | es_ES | es_MX | fr_CA | fr_FR | hi_IN | it_IT | ja_JP | ko_KR | nl_NL | pl_PL | pt_BR | sv_SE | ta_IN | th_TH | tr_TR | vi_VN | zh_CN."}},"required":["store","country_code","ad_product"],"title":"ads_list_targetable_entity_pathsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"paths":{"description":"the sub-paths, each a list of names — pass one to ads_list_targetable_entities' paths_filter."},"total_results":{"description":"how many paths Amazon has there."},"result":{"properties":{"nextToken":{},"paths":{"items":{"items":{}}},"totalResults":{}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/list_report_syncs":{"post":{"operationId":"list_report_syncs","summary":"List a store's report sync schedules — check sync health before trusting rpt_* data.","description":"List a store's report sync schedules — check sync health before trusting rpt_* data. Syncs start automatically when a store (SP reports) or its Ads account (Ads reports) is authorized. The report-data skill says what to tell the user for each disabled_reason; never enable, trigger or disable a sync yourself (admin-only).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/list_report_syncs"},"tags":["sellersheet"],"x-title":"List Report Syncs","x-access":"read","x-family":null,"x-returns":[{"field":"data.schedules","description":"one row per report type — report_type, is_enabled, cron_expression, last_run_at, next_run_at, consecutive_failures (auto-disabled at a threshold), target_table (the rpt_* table to query with query_report_data; null when unmapped), lookback_days, chunk_days, disabled_reason (null | 'auth_revoked' | 'auto_disabled:<category>' | 'amazon_refused' | 'no_brand_registry' | 'unsupported' | 'backfill_complete' | 'paused_by_parent' | 'pending_delete' | 'force_cancelled_by_delete' | 'scheduler_tick_error:<exception>'; legacy rows: 'consecutive_failures'), disabled_marketplaces (marketplaces being skipped), disabled_message."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"report_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Report Type","description":"optional — return only this report type's schedule (exact name, case-insensitive, e.g. 'GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL'). Omit for every schedule."},"target_table":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Target Table","description":"optional — return only the schedules that feed this rpt_* table (e.g. 'rpt_orders'), the way to check one table's freshness before querying it."}},"required":["store"],"title":"list_report_syncsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"schedules":{"description":"one row per report type — report_type, is_enabled, cron_expression, last_run_at, next_run_at, consecutive_failures (auto-disabled at a threshold), target_table (the rpt_* table to query with query_report_data; null when unmapped), lookback_days, chunk_days, disabled_reason (null | 'auth_revoked' | 'auto_disabled:<category>' | 'amazon_refused' | 'no_brand_registry' | 'unsupported' | 'backfill_complete' | 'paused_by_parent' | 'pending_delete' | 'force_cancelled_by_delete' | 'scheduler_tick_error:<exception>'; legacy rows: 'consecutive_failures'), disabled_marketplaces (marketplaces being skipped), disabled_message."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/query_report_data":{"post":{"operationId":"query_report_data","summary":"Query the synced report warehouse (rpt_* tables) — rows without calling Amazon.","description":"Query the synced report warehouse (rpt_* tables) — rows without calling Amazon. Table and column names: the report-data skill, or get_table_schema(table); a wrong column is a 400 naming the valid ones. `tables` takes the physical name (rpt_get_merchant_listings_all_data), an alias (rpt_listings) or the report-type name (GET_MERCHANT_LISTINGS_ALL_DATA, spCampaigns); data.resolved_tables says what was rewritten.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/query_report_data"},"tags":["sellersheet"],"x-title":"Query Report Data","x-access":"read","x-family":null,"x-returns":[{"description":"data.rows, data.columns: the page; columns are 'table.column' under the physical name."},{"field":"data.total_count","description":"the full match count, on page 1 only (null later)."},{"description":"data.truncated, next_offset, page, total_pages: paging."},{"description":"data.report_date, data.report_date_span, data.stale_partitions, data.report_date_note."},{"field":"data.time_zone","description":"the times' zone."}],"x-notes":{"Gotchas":["Ads (rpt_sp_* / rpt_sb_* / rpt_sd_*) and Data Kiosk (rpt_dk_*) tables are one row per","entity per DAY: an explicit 'latest' is one scalar date there, often a partial day —","add a date filter for any range or ranking; only campaigns that delivered on a day","appear, so for a campaign inventory use ads_query_campaign.","rpt_get_fba_inventory_planning_data.days_of_supply is NULL for SKUs with no recent","sales — filter days_of_supply > 0 for a lowest-cover ranking.","Times and days are the store ref's marketplace's ('YYYY-MM-DD HH:MM:SS'). PII blocked."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. rpt_noon_* tables: the noon ref `<account>-<CC>` (e.g. 'myNoon-AE'), never a bare name."},"tables":{"items":{},"title":"Tables","type":"array","description":"table refs; the first is the primary table."},"columns":{"items":{},"title":"Columns","type":"array","description":"'table.column' strings; '*' = every column of the primary, 'tbl.*' of tbl. Ignored when aggregations is set."},"filters":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Filters","description":"[{column: 'table.col', op, value}]. Allowed op: eq, neq, gt, lt, gte, lte, contains (case-insensitive), in (a list), not_null, is_null (no value)."},"joins":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Joins","description":"[{table: 'rpt_x', on: {primary_col: joined_col}}] — LEFT JOIN on bare column names."},"order_by":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Order By","description":"[{column: 'table.col' | aggregation alias, dir: 'asc'|'desc'}]. DESC sorts NULLs last. Required whenever offset > 0, or pages overlap."},"limit":{"default":100,"title":"Limit","type":"integer","description":"rows per page, 1–1000 (default 100). Every row enters your context."},"offset":{"default":0,"title":"Offset","type":"integer","description":"pass data.next_offset from the previous page."},"report_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Report Date","description":"'latest' | 'all' | 'YYYY-MM-DD'. Omitted → 'latest' (each marketplace's newest snapshot; data.stale_partitions flags a lagging one) on snapshot/roster tables, 'all' on daily-fact and ledger tables (data.report_date_note says which). A date-column filter makes 'latest' act as 'all'. Unbounded 'all' stops at offset 20000: add a date or eq/in filter, or aggregate."},"aggregations":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Aggregations","description":"[{column: 'table.col', op: 'sum'|'count'|'avg'|'min'|'max', alias}] — the key is op; sort groups with order_by on the alias."},"group_by":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Group By","description":"['table.col', 'rpt_orders.purchase_date:month'] — ':day|week|month|quarter|year' buckets a date; total_count is then the group count."},"having":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Having","description":"[{column: '<aggregation alias>', op, value}]; op: eq, neq, gt, lt, gte, lte, in."}},"required":["store","tables","columns"],"title":"query_report_dataArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"total_count":{"description":"the full match count, on page 1 only (null later)."},"time_zone":{"description":"the times' zone."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/get_table_schema":{"post":{"operationId":"get_table_schema","summary":"Return the schema for one rpt_* table — column names, types, unique key.","description":"Return the schema for one rpt_* table — column names, types, unique key. Cheaper than loading the full report-data skill when you already know which table you need and just want column names to build a query. For business-question → table mapping (e.g. \"what table answers 'restock needs'?\"), per-column gotchas, calibration notes, or the cross-table workflow (manual create-poll-download, disabled_reason decoding) — load the 'report-data' skill instead. This tool returns the schema only; it does NOT teach which table to use.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/get_table_schema"},"tags":["sellersheet"],"x-title":"Get Table Schema","x-access":"read","x-family":null,"x-returns":[{"field":"data.table_name","description":"the resolved physical table."},{"field":"data.resolved_from","description":"the ref you passed, when it differed (else null)."},{"field":"data.columns","description":"[{name, type, nullable, default, note}] — note is a per-column trap (e.g. the days_of_supply NULL-sort trap) or null."},{"field":"data.unique_constraint","description":"the dedup key; on a snapshot/roster table its marketplace column (country_code, country, marketplace_id, profile_id) is what report_date='latest' resolves one date per."},{"field":"data.indexes / data.fed_by_report_types / data.notes","description":"indexes ({name, columns, unique}), the Amazon report types that feed the table, and table-level warnings (PII-blocked, schema-variant, retired/aliased; empty when healthy)."}],"x-notes":{"Gotchas":["400 — ref not resolvable to an allow-listed table. The error carries the","      full available_tables list + a fuzzy suggestion; a retired","      report-type name names its replacement."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"table_name":{"title":"Table Name","type":"string","description":"physical rpt_* table (e.g. 'rpt_orders'), a friendly alias ('rpt_listings' → rpt_get_merchant_listings_all_data), OR an Amazon report-type name ('GET_FBA_MYI_ALL_INVENTORY_DATA', 'spCampaigns' — case-insensitive). Resolved server-side."}},"required":["table_name"],"title":"get_table_schemaArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"table_name":{"description":"the resolved physical table."},"resolved_from":{"description":"the ref you passed, when it differed (else null)."},"columns":{"description":"[{name, type, nullable, default, note}] — note is a per-column trap (e.g. the days_of_supply NULL-sort trap) or null."},"unique_constraint":{"description":"the dedup key; on a snapshot/roster table its marketplace column (country_code, country, marketplace_id, profile_id) is what report_date='latest' resolves one date per."},"indexes":{"description":"indexes ({name, columns, unique}), the Amazon report types that feed the table, and table-level warnings (PII-blocked, schema-variant, retired/aliased; empty when healthy)."},"fed_by_report_types":{"description":"indexes ({name, columns, unique}), the Amazon report types that feed the table, and table-level warnings (PII-blocked, schema-variant, retired/aliased; empty when healthy)."},"notes":{"description":"indexes ({name, columns, unique}), the Amazon report types that feed the table, and table-level warnings (PII-blocked, schema-variant, retired/aliased; empty when healthy)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_getItemReviewTopics":{"post":{"operationId":"customerFeedback_getItemReviewTopics","summary":"The 10 most positive and 10 most negative review topics of one ASIN (US, UK, FR, IT, DE, ES, JP only), each with review snippets, occurrence %, star-rating impact and the browse-no","description":"The 10 most positive and 10 most negative review topics of one ASIN (US, UK, FR, IT, DE, ES, JP only), each with review snippets, occurrence %, star-rating impact and the browse-node benchmark. Call it TWICE per ASIN — sortBy MENTIONS (recent ~6 months: what customers mention most) and sortBy STAR_RATING_IMPACT (~18 months: what moves the star rating). Then customerFeedback_getItemReviewTrends. Amazon SP-API · getItemReviewTopics · GET /customerFeedback/2024-06-01/items/{asin}/reviews/topics","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_getItemReviewTopics"},"tags":["amazon_sp"],"x-title":"Customer Feedback Get Item Review Topics","x-access":"read","x-family":"sp.customerFeedback_2024-06-01","x-returns":[{"field":"data.reviewTopics","description":"raw — {asin, itemName, marketplaceId, countryCode, dateRange: {startDate, endDate}, topics: {positiveTopics: [Topic], negativeTopics: [Topic]}} (up to 10 each), Topic = {topic (e.g. 'Assembly/Installation'), asinMetrics: {numberOfMentions, occurrencePercentage (% of this ASIN's reviews mentioning it), starRatingImpact (star points the topic adds or removes)}, parentAsinMetrics (the same over the parent's children), browseNodeMetrics: {occurrencePercentage: {allProducts}, starRatingImpact: {allProducts}} (the CATEGORY benchmark),"},{"field":"data.reviewTopics.childAsinMetrics","description":"{mostMentions: {asin, numberOfMentions}, leastMentions: {asin,"},{"description":"numberOfMentions}}, reviewSnippets: [str], subtopics: [{subtopic, metrics:"},{"description":"{numberOfMentions, occurrencePercentage}, reviewSnippets}]}. Slim — {topics:"},{"description":"{positiveTopics: [SlimTopic], negativeTopics: [SlimTopic]}}, SlimTopic = {topic,"},{"description":"asinMetrics, browseNodeMetrics, reviewSnippets (top 3), subtopics (top 3,"},{"description":"{subtopic, occurrencePercentage}), gap_ratio (asinMetrics.occurrencePercentage ÷"},{"description":"the category allProducts, null when either is missing — above 1 the ASIN"},{"description":"over-indexes; on a NEGATIVE topic that is worse than the category), gap_class"},{"description":"CRITICAL (>2×) | HIGH (>1.5×) | MEDIUM (>1×) | LOW (≤1×) | null, or the low-sample"},{"description":"class (fewer than 5 mentions of the topic or 10 across the ASIN — gap_ratio is then"},{"description":"null), cat_source browse_node | item_payload (where the category figure came from)};"},{"description":"parentAsinMetrics, childAsinMetrics and anything beyond the top 3 are dropped."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"sortBy":{"enum":["MENTIONS","STAR_RATING_IMPACT"],"title":"Sortby","type":"string","description":"the metric the topics are ranked by — one per call, each described above. Allowed: MENTIONS | STAR_RATING_IMPACT."},"summarize":{"default":false,"title":"Summarize","type":"boolean","description":"true returns the slim shape below (~90 % smaller) — use it in AI workflows; default false returns Amazon's raw payload."}},"required":["store","asin","sortBy"],"title":"customerFeedback_getItemReviewTopicsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reviewTopics":{"description":"raw — {asin, itemName, marketplaceId, countryCode, dateRange: {startDate, endDate}, topics: {positiveTopics: [Topic], negativeTopics: [Topic]}} (up to 10 each), Topic = {topic (e.g. 'Assembly/Installation'), asinMetrics: {numberOfMentions, occurrencePercentage (% of this ASIN's reviews mentioning it), starRatingImpact (star points the topic adds or removes)}, parentAsinMetrics (the same over the parent's children), browseNodeMetrics: {occurrencePercentage: {allProducts}, starRatingImpact: {allProducts}} (the CATEGORY benchmark),","properties":{"childAsinMetrics":{"description":"{mostMentions: {asin, numberOfMentions}, leastMentions: {asin,"}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_getItemBrowseNode":{"post":{"operationId":"customerFeedback_getItemBrowseNode","summary":"Get the browse node (category) ID for a specific ASIN.","description":"Get the browse node (category) ID for a specific ASIN. Amazon SP-API · getItemBrowseNode · GET /customerFeedback/2024-06-01/items/{asin}/browseNode Supported marketplaces: US, UK (GB), FR, IT, DE, ES, JP only. This is Step 1 of the Browse Node Feedback workflow. The returned browseNodeId feeds the four customerFeedback_getBrowseNode* tools.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_getItemBrowseNode"},"tags":["amazon_sp"],"x-title":"Customer Feedback Get Item Browse Node","x-access":"read","x-family":"sp.customerFeedback_2024-06-01","x-returns":[{"field":"data.browseNode.browseNodeId","description":"pass it as browseNodeId."},{"field":"data.browseNode.displayName","description":"human-readable category name."}],"x-notes":{"Workflow":["Browse Node Feedback workflow:","1. customerFeedback_getItemBrowseNode                              ← you are here","2. customerFeedback_getBrowseNodeReviewTopics (MENTIONS + STAR_RATING_IMPACT)","3. customerFeedback_getBrowseNodeReviewTrends","4. customerFeedback_getBrowseNodeReturnTopics (single call — no sortBy on this","   operation)","5. customerFeedback_getBrowseNodeReturnTrends"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."}},"required":["store","asin"],"title":"customerFeedback_getItemBrowseNodeArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"browseNode":{"properties":{"browseNodeId":{"description":"pass it as browseNodeId."},"displayName":{"description":"human-readable category name."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_getBrowseNodeReviewTopics":{"post":{"operationId":"customerFeedback_getBrowseNodeReviewTopics","summary":"The 10 most positive and 10 most negative review topics of a whole browse node (US, UK, FR, IT, DE, ES, JP only).","description":"The 10 most positive and 10 most negative review topics of a whole browse node (US, UK, FR, IT, DE, ES, JP only). Call it TWICE per node — sortBy MENTIONS (recent 6 months: what customers mention most) and sortBy STAR_RATING_IMPACT (~18 months: what moves the star rating); the two datasets are complementary. Then customerFeedback_getBrowseNodeReviewTrends. Amazon SP-API · getBrowseNodeReviewTopics · GET /customerFeedback/2024-06-01/browseNodes/{browseNodeId}/reviews/topics","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_getBrowseNodeReviewTopics"},"tags":["amazon_sp"],"x-title":"Customer Feedback Get Browse Node Review Topics","x-access":"read","x-family":"sp.customerFeedback_2024-06-01","x-returns":[{"field":"data.reviewTopics","description":"category-level — no asinMetrics or childAsinMetrics (item-only)."},{"field":"data.reviewTopics.Raw","description":"{browseNodeId, displayName, marketplaceId, countryCode, dateRange:"},{"description":"{startDate, endDate}, topics: {positiveTopics: [Topic], negativeTopics: [Topic]}}"},{"description":"(up to 10 each), Topic = {topic, browseNodeMetrics: {occurrencePercentage:"},{"description":"{allProducts, topTwentyFivePercentProducts}, starRatingImpact: {allProducts,"},{"description":"topTwentyFivePercentProducts}}, reviewSnippets: [str] (up to 3), subtopics:"},{"description":"[{subtopic, metrics: {occurrencePercentage}, reviewSnippets}] (up to 5)} —"},{"description":"allProducts is the whole category, topTwentyFivePercentProducts the best-selling"},{"description":"quartile (the leaders). Slim: {topics: {positiveTopics: [SlimTopic],"},{"description":"negativeTopics: [SlimTopic]}}, SlimTopic = {topic, browseNodeMetrics,"},{"description":"reviewSnippets (top 3), subtopics (top 3, {subtopic, occurrencePercentage}),"},{"description":"leaders_pct_ratio (topTwentyFivePercentProducts ÷ allProducts, null when either is"},{"description":"missing)} — on a NEGATIVE topic a ratio above 1 means the category leaders still"},{"description":"suffer the issue: an unsolved category-wide gap."}],"x-notes":{"Gotchas":["Some STAR_RATING_IMPACT topics have no occurrencePercentage, and Amazon may return an","unresolved '$…' placeholder string there — treat a non-numeric value as absent. The","browse-node subtopic metric is occurrencePercentage only (numberOfMentions is","item-level, on customerFeedback_getItemReviewTopics)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"browseNodeId":{"title":"Browsenodeid","type":"string","description":"from customerFeedback_getItemBrowseNode (e.g. '10671064011')."},"sortBy":{"enum":["MENTIONS","STAR_RATING_IMPACT"],"title":"Sortby","type":"string","description":"the metric the topics are ranked by — one per call, each described above. Allowed: MENTIONS | STAR_RATING_IMPACT."},"summarize":{"default":false,"title":"Summarize","type":"boolean","description":"true returns the slim shape below (~93 % smaller) — use it in AI workflows; default false returns Amazon's raw payload."}},"required":["store","browseNodeId","sortBy"],"title":"customerFeedback_getBrowseNodeReviewTopicsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reviewTopics":{"description":"category-level — no asinMetrics or childAsinMetrics (item-only).","properties":{"Raw":{"description":"{browseNodeId, displayName, marketplaceId, countryCode, dateRange:"}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_getItemReviewTrends":{"post":{"operationId":"customerFeedback_getItemReviewTrends","summary":"Month-by-month occurrence trends (past 6 months, newest first) of one ASIN's 10 most positive and 10 most negative review topics, beside the category's — to see whether a fix impro","description":"Month-by-month occurrence trends (past 6 months, newest first) of one ASIN's 10 most positive and 10 most negative review topics, beside the category's — to see whether a fix improved sentiment or an issue is growing (US, UK, FR, IT, DE, ES, JP only). Call after customerFeedback_getItemReviewTopics (both sortBy values). Amazon SP-API · getItemReviewTrends · GET /customerFeedback/2024-06-01/items/{asin}/reviews/trends","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_getItemReviewTrends"},"tags":["amazon_sp"],"x-title":"Customer Feedback Get Item Review Trends","x-access":"read","x-family":"sp.customerFeedback_2024-06-01","x-returns":[{"field":"data.reviewTrends","description":"the Amazon payload; the topics sit one level down under a second reviewTrends key (data.reviewTrends.reviewTrends) in both shapes."},{"field":"data.reviewTrends.Raw","description":"{asin, itemName, marketplaceId, countryCode, dateRange: {startDate,"},{"description":"endDate}, reviewTrends: {positiveTopics: [TrendTopic], negativeTopics:"},{"description":"[TrendTopic]}}, TrendTopic = {topic, trendMetrics: [Period]}, one Period per"},{"description":"month, newest first = {dateRange, asinMetrics: {occurrencePercentage},"},{"description":"parentAsinMetrics: {occurrencePercentage} (null with too little data),"},{"description":"browseNodeMetrics: {occurrencePercentage: {allProducts}}}. Trends carry"},{"description":"occurrence percentages ONLY — numberOfMentions and starRatingImpact are on"},{"description":"customerFeedback_getItemReviewTopics. Slim: {positiveTopics: [SlimTrend],"},{"description":"negativeTopics: [SlimTrend]}, SlimTrend = {topic, asin_pct: [float] (this"},{"description":"ASIN's monthly occurrencePercentage), cat_pct: [float] (the category's monthly"},{"description":"allProducts occurrencePercentage)} — parallel, newest first (index ="},{"description":"months ago); watch for a rising negative-topic asin_pct against cat_pct."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"summarize":{"default":false,"title":"Summarize","type":"boolean","description":"true returns the slim shape (~90 % smaller: flat asin_pct and cat_pct lists instead of trendMetrics, no dateRange) — use it in AI workflows; default false returns Amazon's raw payload."}},"required":["store","asin"],"title":"customerFeedback_getItemReviewTrendsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reviewTrends":{"description":"the Amazon payload; the topics sit one level down under a second reviewTrends key (data.reviewTrends.reviewTrends) in both shapes.","properties":{"Raw":{"description":"{asin, itemName, marketplaceId, countryCode, dateRange: {startDate,"}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_getBrowseNodeReviewTrends":{"post":{"operationId":"customerFeedback_getBrowseNodeReviewTrends","summary":"Month-by-month occurrence trends (past 6 months, newest first) of a browse node's top review topics — the category baseline for customerFeedback_getItemReviewTrends (US, UK, FR, IT","description":"Month-by-month occurrence trends (past 6 months, newest first) of a browse node's top review topics — the category baseline for customerFeedback_getItemReviewTrends (US, UK, FR, IT, DE, ES, JP only). Call after customerFeedback_getBrowseNodeReviewTopics (both sortBy values); then customerFeedback_getBrowseNodeReturnTopics. Amazon SP-API · getBrowseNodeReviewTrends · GET /customerFeedback/2024-06-01/browseNodes/{browseNodeId}/reviews/trends","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_getBrowseNodeReviewTrends"},"tags":["amazon_sp"],"x-title":"Customer Feedback Get Browse Node Review Trends","x-access":"read","x-family":"sp.customerFeedback_2024-06-01","x-returns":[{"field":"data.reviewTrends","description":"the Amazon payload; the topics sit one level down under a second reviewTrends key (data.reviewTrends.reviewTrends) in both shapes."},{"field":"data.reviewTrends.Raw","description":"{browseNodeId, displayName, marketplaceId, countryCode, dateRange:"},{"description":"{startDate, endDate}, reviewTrends: {positiveTopics: [TrendTopic],"},{"description":"negativeTopics: [TrendTopic]}}, TrendTopic = {topic, trendMetrics: [Period]},"},{"description":"one Period per month, newest first = {dateRange, browseNodeMetrics:"},{"description":"{occurrencePercentage: {allProducts, topTwentyFivePercentProducts}}}"},{"description":"(category-level — no asinMetrics). Slim: {positiveTopics: [SlimTrend],"},{"description":"negativeTopics: [SlimTrend]}, SlimTrend = {topic, cat_pct: [float] (the"},{"description":"category's monthly allProducts occurrencePercentage, newest first)}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"browseNodeId":{"title":"Browsenodeid","type":"string","description":"Browse node ID from customerFeedback_getItemBrowseNode."},"summarize":{"default":false,"title":"Summarize","type":"boolean","description":"true returns the slim shape (~98 % smaller, ~55 KB → ~1 KB: flat cat_pct lists, allProducts only, no topTwentyFivePercentProducts or dateRange) — use it in AI workflows; default false returns Amazon's raw payload."}},"required":["store","browseNodeId"],"title":"customerFeedback_getBrowseNodeReviewTrendsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"reviewTrends":{"description":"the Amazon payload; the topics sit one level down under a second reviewTrends key (data.reviewTrends.reviewTrends) in both shapes.","properties":{"Raw":{"description":"{browseNodeId, displayName, marketplaceId, countryCode, dateRange:"}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_getBrowseNodeReturnTopics":{"post":{"operationId":"customerFeedback_getBrowseNodeReturnTopics","summary":"The top 10 reasons customers give when returning products in a browse node, each with its share of the category's returns (US, UK, FR, IT, DE, ES, JP only) — use them to set accura","description":"The top 10 reasons customers give when returning products in a browse node, each with its share of the category's returns (US, UK, FR, IT, DE, ES, JP only) — use them to set accurate expectations in the listing. One call — this operation takes no sortBy. Call after customerFeedback_getBrowseNodeReviewTrends; then customerFeedback_getBrowseNodeReturnTrends. Amazon SP-API · getBrowseNodeReturnTopics · GET /customerFeedback/2024-06-01/browseNodes/{browseNodeId}/returns/topics","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_getBrowseNodeReturnTopics"},"tags":["amazon_sp"],"x-title":"Customer Feedback Get Browse Node Return Topics","x-access":"read","x-family":"sp.customerFeedback_2024-06-01","x-returns":[{"field":"data.returnTopics","description":"the Amazon payload (already compact ~2 KB — there is no slim mode on this operation): {browseNodeId, displayName, marketplaceId, countryCode, dateRange: {startDate, endDate}, topics: [ReturnTopic] (up to 10)}, ReturnTopic = {topic (the return-reason theme), browseNodeMetrics: {occurrencePercentage: {allProducts}} (the share of category returns that cite this reason)}. Return topics carry NO reviewSnippets and NO subtopics — unlike the review-topics operations."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"browseNodeId":{"title":"Browsenodeid","type":"string","description":"Browse node ID from customerFeedback_getItemBrowseNode."}},"required":["store","browseNodeId"],"title":"customerFeedback_getBrowseNodeReturnTopicsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"returnTopics":{"description":"the Amazon payload (already compact ~2 KB — there is no slim mode on this operation): {browseNodeId, displayName, marketplaceId, countryCode, dateRange: {startDate, endDate}, topics: [ReturnTopic] (up to 10)}, ReturnTopic = {topic (the return-reason theme), browseNodeMetrics: {occurrencePercentage: {allProducts}} (the share of category returns that cite this reason)}. Return topics carry NO reviewSnippets and NO subtopics — unlike the review-topics operations."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_getBrowseNodeReturnTrends":{"post":{"operationId":"customerFeedback_getBrowseNodeReturnTrends","summary":"Month-by-month share of the category's returns that cite each return reason (past 6 months, newest first) for a browse node (US, UK, FR, IT, DE, ES, JP only) — whether a reason is ","description":"Month-by-month share of the category's returns that cite each return reason (past 6 months, newest first) for a browse node (US, UK, FR, IT, DE, ES, JP only) — whether a reason is growing, and seasonal patterns. The last step, after customerFeedback_getBrowseNodeReturnTopics. Amazon SP-API · getBrowseNodeReturnTrends · GET /customerFeedback/2024-06-01/browseNodes/{browseNodeId}/returns/trends","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_getBrowseNodeReturnTrends"},"tags":["amazon_sp"],"x-title":"Customer Feedback Get Browse Node Return Trends","x-access":"read","x-family":"sp.customerFeedback_2024-06-01","x-returns":[{"field":"data.returnTrends","description":"the Amazon payload; the topics sit one level down under a second returnTrends key (data.returnTrends.returnTrends) in both shapes, as one flat list (NOT split positive/negative). Raw: {browseNodeId, displayName, marketplaceId, countryCode, dateRange: {startDate, endDate}, returnTrends: [TrendTopic]}, TrendTopic = {topic, trendMetrics: [Period]}, one Period per month, newest first = {dateRange, browseNodeMetrics: {occurrencePercentage: {allProducts}}}. Slim: [SlimTrend], SlimTrend = {topic, cat_pct: [float] (the reason's monthly share, newest first), direction: RISING | STABLE | FALLING | null (newest-2-month vs oldest-2-month average, ±10 %; null below 3 reported months once Amazon's zero-padded edge months are trimmed), delta: newest − oldest reported month (positive = that reason's share is growing; null below 2 reported months)}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"browseNodeId":{"title":"Browsenodeid","type":"string","description":"Browse node ID from customerFeedback_getItemBrowseNode."},"summarize":{"default":false,"title":"Summarize","type":"boolean","description":"true returns the slim shape (~80 % smaller: flat cat_pct lists plus a computed direction and delta) — use it in AI workflows; default false returns Amazon's raw payload."}},"required":["store","browseNodeId"],"title":"customerFeedback_getBrowseNodeReturnTrendsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"returnTrends":{"description":"the Amazon payload; the topics sit one level down under a second returnTrends key (data.returnTrends.returnTrends) in both shapes, as one flat list (NOT split positive/negative). Raw: {browseNodeId, displayName, marketplaceId, countryCode, dateRange: {startDate, endDate}, returnTrends: [TrendTopic]}, TrendTopic = {topic, trendMetrics: [Period]}, one Period per month, newest first = {dateRange, browseNodeMetrics: {occurrencePercentage: {allProducts}}}. Slim: [SlimTrend], SlimTrend = {topic, cat_pct: [float] (the reason's monthly share, newest first), direction: RISING | STABLE | FALLING | null (newest-2-month vs oldest-2-month average, ±10 %; null below 3 reported months once Amazon's zero-padded edge months are trimmed), delta: newest − oldest reported month (positive = that reason's share is growing; null below 2 reported months)}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_insights_report":{"post":{"operationId":"customerFeedback_insights_report","summary":"Buyer insights report for ONE ASIN — what buyers of this CATEGORY praise, complain about and return, turned into the questions to answer before writing listing copy.","description":"Buyer insights report for ONE ASIN — what buyers of this CATEGORY praise, complain about and return, turned into the questions to answer before writing listing copy. An async job: returns data.job_id at once; poll customerFeedback_insights_report_status every ~4 s until data.status is 'done' (the report is data.report) or 'error'; a report takes 1–3 minutes. A credits hold is taken at submit (price it with credits_quote) and settled by the worker; nothing is charged when the marketplace has no buyer-feedback data (US, UK, FR, IT, DE, ES, JP only) or the build fails; HTTP 402 with error_code insufficient_credits when the balance is short — top up at sellersheetai.com/billing. Amazon SP-API · getItemBrowseNode · GET /customerFeedback/2024-06-01/items/{asin}/browseNode Amazon SP-API · getBrowseNodeReviewTopics · GET /customerFeedback/2024-06-01/browseNodes/{browseNodeId}/reviews/topics Amazon SP-API · getBrowseNodeReturnTopics · GET /customerFeedback/2024-06-01/browseNodes/{browseNodeId}/returns/topics Amazon SP-API · getBrowseNodeReviewTrends · GET /customerFeedback/2024-06-01/browseNodes/{browseNodeId}/reviews/trends Amazon SP-API · getBrowseNodeReturnTrends · GET /customerFeedback/2024-06-01/browseNodes/{browseNodeId}/returns/trends Amazon SP-API · getItemReviewTopics · GET /customerFeedback/2024-06-01/items/{asin}/reviews/topics Amazon SP-API · getItemReviewTrends · GET /customerFeedback/2024-06-01/items/{asin}/reviews/trends Amazon SP-API · searchCatalogItems · GET /catalog/2022-04-01/items","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_insights_report"},"tags":["amazon_sp"],"x-title":"Customer Feedback Insights Report","x-access":"write","x-family":"sp.customerFeedback_2024-06-01","x-returns":[{"field":"data.job_id","description":"the job; data.status 'pending'; data.credits {charged, balance}."},{"field":"data.report","type":"from customerFeedback_insights_report_status once done","description":"supported false means the marketplace is not covered and nothing was charged — reason choose_marketplace | no_matching_category | marketplace_unsupported, with candidates to pass as via or category. Otherwise credits {charged, balance}; category and category_chosen_by; report_version 3; tiles (the three headline"},{"field":"data.report.findings","description":"type, topic, number, unit, chips, so_what, question n); cluster (one"},{"description":"sentence when several topics are one fact); verdicts[] (every complaint topic:"},{"description":"kind fix | watch | pre_empt | fine, priority, you vs category vs the top-25 %"},{"description":"sellers as gap and gap_leaders, trend, star, category return share, subtopics"},{"description":"with quotes, so_what — what to do in the LISTING); strengths[], pre_empt[],"},{"description":"category_complaints[], category_praise[], returns[], star_lifters[] (the evidence"},{"description":"tables); questions[] (one per FACT: n, group, question, why, buyers_say, example"},{"description":"— a complete sample answer with {number} and {detail} slots — line with {answer},"},{"description":"listing_use, coverage from_listing | from_draft | partial (+missing) | contested"},{"description":"(+disputed_by) | needs_you, answer, source {field, quote}); skipped[] (return"},{"description":"reasons the product cannot have); keywords[] (buyer-language phrases). Read the"},{"description":"tiles and so-whats, then answer the questions — a sample answer is a starting"},{"description":"point, never a fact until confirmed."}],"x-notes":{"Params (Amazon schema; getItemBrowseNode)":["asin*: string","marketplaceId*: string"],"Params (Amazon schema; getBrowseNodeReviewTopics)":["browseNodeId*: string","marketplaceId*: string","sortBy*: MENTIONS | STAR_RATING_IMPACT"],"Params (Amazon schema; getBrowseNodeReturnTopics)":["browseNodeId*: string","marketplaceId*: string"],"Params (Amazon schema; getBrowseNodeReviewTrends)":["browseNodeId*: string","marketplaceId*: string"],"Params (Amazon schema; getBrowseNodeReturnTrends)":["browseNodeId*: string","marketplaceId*: string"],"Params (Amazon schema; getItemReviewTopics)":["asin*: string","marketplaceId*: string","… (18 more lines; the Docs link above)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"asin":{"title":"Asin","type":"string","description":"the ASIN (e.g. 'B0XXXXXXXX')."},"via":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Via","description":"a store ref to VIEW through — one of the candidates a 'choose_marketplace' report returned (a US/UK/FR/IT/DE/ES/JP store)."},"listing_context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Listing Context","description":"{title, bullets, description} of the hero SKU — grounds the suggested answers (truncated server-side at ~1,500 chars)."},"category":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Category","description":"a pick from a 'no_matching_category' report's candidates — {classificationId, displayName, marketplace}, in the viewing marketplace; the report then records category_chosen_by 'operator'."}},"required":["store","asin"],"title":"customerFeedback_insights_reportArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"job_id":{"description":"the job; data.status 'pending'; data.credits {charged, balance}."},"report":{"description":"supported false means the marketplace is not covered and nothing was charged — reason choose_marketplace | no_matching_category | marketplace_unsupported, with candidates to pass as via or category. Otherwise credits {charged, balance}; category and category_chosen_by; report_version 3; tiles (the three headline","properties":{"findings":{"description":"type, topic, number, unit, chips, so_what, question n); cluster (one"}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/customerFeedback_insights_report_status":{"post":{"operationId":"customerFeedback_insights_report_status","summary":"Poll a Buyer insights job submitted by customerFeedback_insights_report — every ~4 s until status is done or error.","description":"Poll a Buyer insights job submitted by customerFeedback_insights_report — every ~4 s until status is done or error.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/customerFeedback_insights_report_status"},"tags":["sellersheet"],"x-title":"Customer Feedback Insights Report Status","x-access":"read","x-family":null,"x-returns":[{"field":"data.status","description":"'pending' | 'processing' | 'done' | 'error'. An unknown job_id, or another user's job, is refused (HTTP 400)."},{"field":"data.report","type":"when done","description":"the full report — see customerFeedback_insights_report's Returns; data.supported mirrors data.report.supported."},{"field":"data.error","type":"when error","description":"one sentence; nothing was charged."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"title":"Job Id","type":"string","description":"the job id customerFeedback_insights_report returned."}},"required":["job_id"],"title":"customerFeedback_insights_report_statusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"'pending' | 'processing' | 'done' | 'error'. An unknown job_id, or another user's job, is refused (HTTP 400)."},"report":{"description":"the full report — see customerFeedback_insights_report's Returns; data.supported mirrors data.report.supported."},"error":{"description":"one sentence; nothing was charged."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/dataKiosk_createQuery":{"post":{"operationId":"dataKiosk_createQuery","summary":"Submit a Data Kiosk GraphQL query; returns queryId at once.","description":"Submit a Data Kiosk GraphQL query; returns queryId at once. Poll dataKiosk_getQuery until processingStatus is DONE — it returns the result itself (data.result.documentContent); dataKiosk_getDocument only reads a FATAL query's errorDocumentId. When the DONE query reports data.result.pagination.nextToken, resubmit the SAME query string with it as paginationToken for the next page. Requires SP write access. Amazon SP-API · createQuery · POST /dataKiosk/2023-11-15/queries","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/dataKiosk_createQuery"},"tags":["amazon_sp"],"x-title":"Data Kiosk Create Query","x-access":"read","x-family":"sp.dataKiosk_2023-11-15","x-returns":[{"field":"data.queryId","description":"poll it with dataKiosk_getQuery."},{"field":"data.marketplaceId","description":"the store's marketplace id — the value the query must name."}],"x-notes":{"Gotchas":["The marketplace is named INSIDE the query and the spelling differs per dataset field","(a wrong one ends FATAL) — a list argument","marketplaceIds: [String!]! on salesAndTrafficByDate, salesAndTrafficByAsin, economics","and economicsPreview; a singular marketplaceId: String! on economicsSimulation; per","filter inside filters: [MarketplaceAsinFilter!]! on salesAndTrafficTrends (no","marketplaceIds argument); none at all on manufacturingView and sourcingView (args","exactly aggregateBy, currencyCode, endDate, startDate).","Aggregation is spelled differently per field — salesAndTrafficByDate aggregateBy","DateGranularity! (DAY | WEEK | MONTH); salesAndTrafficByAsin aggregateBy","AsinGranularity! (CHILD | PARENT | SKU); salesAndTrafficTrends takes asinAggregation","(CHILD only) AND dateAggregation and has no aggregateBy; manufacturingView and","sourcingView aggregateBy DateGranularity!; economics aggregateBy is an optional input","OBJECT {date: DateGranularity, productId: ProductIdentifierGranularity} defaulting to","DAY and MSKU (aggregateBy: DAY is a type error); economicsPreview likewise, its date","enum EconomicsPreviewDateGranularity (RANGE only); economicsSimulation has none.","Rate limit ~one submission a minute (0.0167 req/s, burst 15) — pace a pagination loop. The query and its documents are kept for the SHORTEST","@resultRetention among the requested fields (commonly 30 days): download before then."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"query":{"title":"Query","type":"string","description":"the GraphQL query string, ≤8,000 chars. Pick a versioned root type, then a dataset field under it — analytics_salesAndTraffic_2024_04_24 (salesAndTrafficByDate, salesAndTrafficByAsin, salesAndTrafficTrends), analytics_economics_2024_03_15 (economics, economicsPreview, economicsSimulation), analytics_vendorAnalytics_2024_09_30 (manufacturingView, sourcingView); the 2023_11_15 sales root is deprecated. Example, daily sales for one month — 'query { analytics_salesAndTraffic_2024_04_24 { salesAndTrafficByDate(aggregateBy: DAY, startDate: \"2026-07-01\", endDate: \"2026-07-31\", marketplaceIds: [\"A2VIGQ35RCS4UG\"]) { startDate endDate sales { orderedProductSales { amount currencyCode } unitsOrdered } traffic { sessions pageViews } } } }'. startDate is at most two years back."},"paginationToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Paginationtoken","description":"the DONE query's data.result.pagination.nextToken (from dataKiosk_getQuery); omit for the first page."}},"required":["store","query"],"title":"dataKiosk_createQueryArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"queryId":{"description":"poll it with dataKiosk_getQuery."},"marketplaceId":{"description":"the store's marketplace id — the value the query must name."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/dataKiosk_getQuery":{"post":{"operationId":"dataKiosk_getQuery","summary":"Poll Data Kiosk query status.","description":"Poll Data Kiosk query status. Auto-downloads document when processingStatus == DONE. Amazon SP-API · getQuery · GET /dataKiosk/2023-11-15/queries/{queryId} Amazon SP-API · getDocument · GET /dataKiosk/2023-11-15/documents/{documentId} When the query is DONE, the response includes documentContent with the full result. If not yet done, call again in a few seconds. On FATAL, read the named errorDocumentId with dataKiosk_getDocument before resubmitting.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/dataKiosk_getQuery"},"tags":["amazon_sp"],"x-title":"Data Kiosk Get Query","x-access":"read","x-family":"sp.dataKiosk_2023-11-15","x-returns":[{"field":"data.queryId","description":"the polled query id."},{"field":"data.processingStatus","description":"CANCELLED | DONE | FATAL | IN_PROGRESS | IN_QUEUE"},{"field":"data.result.dataDocumentId","description":"result document id (present only when DONE and the query produced data). NOTE: the field is dataDocumentId, NOT dataDocument."},{"field":"data.result.errorDocumentId","description":"error document id (present only when the query failed with FATAL and produced an error document). Pass it to dataKiosk_getDocument to read WHY the query failed before resubmitting — human_action names it for you on a FATAL."},{"field":"data.result.documentContent","description":"auto-downloaded getDocument payload — present only when DONE and a dataDocumentId existed. It is the getDocument response: {documentId, documentUrl, document}, where `document` is the raw document bytes (the actual result rows)."},{"field":"data.result.pagination.nextToken","description":"present when the result spans multiple pages; submit a new dataKiosk_createQuery with the SAME query string plus that token (as paginationToken) to fetch the next page."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"queryId":{"title":"Queryid","type":"string","description":"Query ID from dataKiosk_createQuery response."}},"required":["store","queryId"],"title":"dataKiosk_getQueryArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"queryId":{"description":"the polled query id."},"processingStatus":{"description":"CANCELLED | DONE | FATAL | IN_PROGRESS | IN_QUEUE"},"result":{"properties":{"dataDocumentId":{"description":"result document id (present only when DONE and the query produced data). NOTE: the field is dataDocumentId, NOT dataDocument."},"errorDocumentId":{"description":"error document id (present only when the query failed with FATAL and produced an error document). Pass it to dataKiosk_getDocument to read WHY the query failed before resubmitting — human_action names it for you on a FATAL."},"documentContent":{"description":"auto-downloaded getDocument payload — present only when DONE and a dataDocumentId existed. It is the getDocument response: {documentId, documentUrl, document}, where `document` is the raw document bytes (the actual result rows)."},"pagination":{"properties":{"nextToken":{"description":"present when the result spans multiple pages; submit a new dataKiosk_createQuery with the SAME query string plus that token (as paginationToken) to fetch the next page."}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/dataKiosk_getDocument":{"post":{"operationId":"dataKiosk_getDocument","summary":"Fetch a Data Kiosk document by document ID.","description":"Fetch a Data Kiosk document by document ID. Amazon SP-API · getDocument · GET /dataKiosk/2023-11-15/documents/{documentId} Use this when you already have a documentId (from a completed query's dataDocumentId field — note the field is dataDocumentId, NOT dataDocument). For the typical poll-and-download flow, use dataKiosk_getQuery instead.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/dataKiosk_getDocument"},"tags":["amazon_sp"],"x-title":"Data Kiosk Get Document","x-access":"read","x-family":"sp.dataKiosk_2023-11-15","x-returns":[{"field":"data.documentId","description":"the requested document id."},{"field":"data.result.documentId","description":"Amazon document id."},{"field":"data.result.documentUrl","description":"presigned URL to retrieve the document (expires after 5 minutes)."},{"field":"data.result.document","description":"raw document bytes (present only when download=True). This is the actual document content."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"documentId":{"title":"Documentid","type":"string","description":"Document ID string (the dataDocumentId from a DONE query, or an errorDocumentId from a FATAL query)."},"download":{"default":true,"title":"Download","type":"boolean","description":"If True (default), fetches and returns document content."}},"required":["store","documentId"],"title":"dataKiosk_getDocumentArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"documentId":{"description":"the requested document id."},"result":{"properties":{"documentId":{"description":"Amazon document id."},"documentUrl":{"description":"presigned URL to retrieve the document (expires after 5 minutes)."},"document":{"description":"raw document bytes (present only when download=True). This is the actual document content."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/dataKiosk_cancelQuery":{"post":{"operationId":"dataKiosk_cancelQuery","summary":"Cancel a Data Kiosk query that is IN_QUEUE or IN_PROGRESS.","description":"Cancel a Data Kiosk query that is IN_QUEUE or IN_PROGRESS. Amazon SP-API · cancelQuery · DELETE /dataKiosk/2023-11-15/queries/{queryId} Only IN_QUEUE and IN_PROGRESS queries can be cancelled; re-cancelling an already-CANCELLED query is a no-op (it succeeds). DONE and FATAL queries cannot be cancelled. Cancelled queries still appear in dataKiosk_getQuery / dataKiosk_getQueries results. Cancelling is a write operation and requires SP write access.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/dataKiosk_cancelQuery"},"tags":["amazon_sp"],"x-title":"Data Kiosk Cancel Query","x-access":"read","x-family":"sp.dataKiosk_2023-11-15","x-returns":[{"field":"data.queryId","description":"the cancelled query id."},{"field":"data.result","description":"empty — Amazon returns 204 No Content on success."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"queryId":{"title":"Queryid","type":"string","description":"Query ID to cancel."}},"required":["store","queryId"],"title":"dataKiosk_cancelQueryArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"queryId":{"description":"the cancelled query id."},"result":{"description":"empty — Amazon returns 204 No Content on success."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/dataKiosk_getQueries":{"post":{"operationId":"dataKiosk_getQueries","summary":"List Data Kiosk queries for this store with optional filters.","description":"List Data Kiosk queries for this store with optional filters. Amazon SP-API · getQueries · GET /dataKiosk/2023-11-15/queries Useful for checking query history or finding queryIds for completed queries. Read a DONE query's results with dataKiosk_getQuery.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/dataKiosk_getQueries"},"tags":["amazon_sp"],"x-title":"Data Kiosk Get Queries","x-access":"read","x-family":"sp.dataKiosk_2023-11-15","x-returns":[{"field":"data.queries","description":"list of query objects, each with queryId, query, processingStatus, createdTime, and (when DONE/FATAL) dataDocumentId or errorDocumentId."},{"field":"data.pagination.nextToken","description":"present when more results are available; pass back as paginationToken for the next page."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"processingStatuses":{"anyOf":[{"items":{"enum":["CANCELLED","DONE","FATAL","IN_PROGRESS","IN_QUEUE"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Processingstatuses","description":"the query statuses to keep (at least 1 value if given); omit for all. Allowed: CANCELLED | DONE | FATAL | IN_PROGRESS | IN_QUEUE."},"pageSize":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Pagesize","description":"Number of results per page (1-100; defaults to 10)."},"createdSince":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Createdsince","description":"Earliest query-creation time to include, ISO 8601 date time (e.g. '2026-06-01T00:00:00Z'). Defaults to 90 days ago."},"createdUntil":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Createduntil","description":"Latest query-creation time to include, ISO 8601 date time. Defaults to the time of the request."},"paginationToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Paginationtoken","description":"Token from a previous response (data.pagination.nextToken) for the next page. When paging, resend processingStatuses / createdSince / createdUntil unchanged (only pageSize may change)."}},"required":["store"],"title":"dataKiosk_getQueriesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"queries":{"description":"list of query objects, each with queryId, query, processingStatus, createdTime, and (when DONE/FATAL) dataDocumentId or errorDocumentId."},"pagination":{"properties":{"nextToken":{"description":"present when more results are available; pass back as paginationToken for the next page."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/finances_listFinancialEvents":{"post":{"operationId":"finances_listFinancialEvents","summary":"List Amazon financial events (charges, credits, fees, etc.) by posted-date range.","description":"List Amazon financial events (charges, credits, fees, etc.) by posted-date range. Amazon SP-API · listFinancialEvents · GET /finances/v0/financialEvents Amazon op: listFinancialEvents (Finances v0). Read-only. Events come grouped by type (ShipmentEventList, RefundEventList, …); for deferred/released status or a per-transaction breakdown use finances_listTransactions, and for settlement-level analysis finances_listFinancialEventGroups.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/finances_listFinancialEvents"},"tags":["amazon_sp"],"x-title":"Finances List Financial Events","x-access":"read","x-family":"sp.financesV0","x-returns":[{"field":"data.result.FinancialEvents","description":"event lists (ShipmentEventList, RefundEventList, ServiceFeeEventList, AdjustmentEventList, etc.)."},{"field":"data.nextToken","description":"the cursor for the next page (null on the last page)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"postedAfter":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Postedafter","description":"ISO 8601 date-time (e.g. '2026-01-01T00:00:00Z'). The response includes events posted on or after this date. Must be more than two minutes before the request time."},"postedBefore":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Postedbefore","description":"ISO 8601 date-time. Events posted before (not on) this date. MUST be sent together with postedAfter — Amazon rejects postedBefore on its own. Must be later than postedAfter and more than two minutes before the request time. A window wider than 180 days returns an EMPTY response (not an error) — page month by month. Default when omitted: two minutes before the request."},"maxResultsPerPage":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Maxresultsperpage","description":"Max events per page (Amazon allows 1-100)."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page. Send it with the same other arguments."}},"required":["store"],"title":"finances_listFinancialEventsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"FinancialEvents":{"description":"event lists (ShipmentEventList, RefundEventList, ServiceFeeEventList, AdjustmentEventList, etc.)."}}},"nextToken":{"description":"the cursor for the next page (null on the last page)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/finances_listFinancialEventGroups":{"post":{"operationId":"finances_listFinancialEventGroups","summary":"List Amazon financial event groups (settlement periods).","description":"List Amazon financial event groups (settlement periods). Amazon SP-API · listFinancialEventGroups · GET /finances/v0/financialEventGroups Amazon op: listFinancialEventGroups (Finances v0). Read-only. Each group is a settlement period. Use its FinancialEventGroupId with finances_listFinancialEventsByGroupId to drill into a settlement's events.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/finances_listFinancialEventGroups"},"tags":["amazon_sp"],"x-title":"Finances List Financial Event Groups","x-access":"read","x-family":"sp.financesV0","x-returns":[{"field":"data.result.FinancialEventGroupList","description":"array of groups, each with FinancialEventGroupId, ProcessingStatus (Open | Closed), FundTransferStatus, OriginalTotal, BeginningBalance, FinancialEventGroupStart / FinancialEventGroupEnd."},{"field":"data.nextToken","description":"the cursor for the next page (null on the last page)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"financialEventGroupStartedAfter":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Financialeventgroupstartedafter","description":"ISO 8601 date-time. Groups that started on or after this date. Defaults to ~last 30 days when both bounds are omitted (Amazon rejects an empty window). Must be more than two minutes before the request time."},"financialEventGroupStartedBefore":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Financialeventgroupstartedbefore","description":"ISO 8601 date-time. Groups that started before (not at) this date. Must be after financialEventGroupStartedAfter and more than two minutes before the request time. A window wider than 180 days returns NO groups (an empty response, not an error) — page month by month."},"maxResultsPerPage":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Maxresultsperpage","description":"groups per page, 1-100 (Amazon's default is 10 — pass 100 to page less)."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page. Send it with the same other arguments."}},"required":["store"],"title":"finances_listFinancialEventGroupsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"FinancialEventGroupList":{"description":"array of groups, each with FinancialEventGroupId, ProcessingStatus (Open | Closed), FundTransferStatus, OriginalTotal, BeginningBalance, FinancialEventGroupStart / FinancialEventGroupEnd."}}},"nextToken":{"description":"the cursor for the next page (null on the last page)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/finances_listFinancialEventsByGroupId":{"post":{"operationId":"finances_listFinancialEventsByGroupId","summary":"List all financial events for a specific settlement group.","description":"List all financial events for a specific settlement group. Amazon SP-API · listFinancialEventsByGroupId · GET /finances/v0/financialEventGroups/{eventGroupId}/financialEvents Amazon op: listFinancialEventsByGroupId (Finances v0). Read-only. Use after finances_listFinancialEventGroups to drill into one settlement.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/finances_listFinancialEventsByGroupId"},"tags":["amazon_sp"],"x-title":"Finances List Financial Events by Group ID","x-access":"read","x-family":"sp.financesV0","x-returns":[{"field":"data.groupId","description":"the requested group ID."},{"field":"data.result.FinancialEvents","description":"detailed event lists for this settlement (same shape as finances_listFinancialEvents)."},{"field":"data.nextToken","description":"the cursor for the next page (null on the last page)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"groupId":{"title":"Groupid","type":"string","description":"FinancialEventGroupId from finances_listFinancialEventGroups (maps to the eventGroupId path param)."},"postedAfter":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Postedafter","description":"optional ISO 8601 date-time. Scope the group's events to those posted on or after this date. Must be more than two minutes before the request time."},"postedBefore":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Postedbefore","description":"optional ISO 8601 date-time. Posted before (not on) this date. MUST be sent together with postedAfter — Amazon rejects postedBefore on its own. Must be later than postedAfter and more than two minutes before the request time. A window wider than 180 days returns an EMPTY response (not an error) — page month by month. Default when omitted: two minutes before the request."},"maxResultsPerPage":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Maxresultsperpage","description":"Max events per page (Amazon allows 1-100)."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page. Send it with the same other arguments."}},"required":["store","groupId"],"title":"finances_listFinancialEventsByGroupIdArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"groupId":{"description":"the requested group ID."},"result":{"properties":{"FinancialEvents":{"description":"detailed event lists for this settlement (same shape as finances_listFinancialEvents)."}}},"nextToken":{"description":"the cursor for the next page (null on the last page)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/finances_listFinancialEventsByOrderId":{"post":{"operationId":"finances_listFinancialEventsByOrderId","summary":"Get all financial events for a specific Amazon order ID.","description":"Get all financial events for a specific Amazon order ID. Amazon SP-API · listFinancialEventsByOrderId · GET /finances/v0/orders/{orderId}/financialEvents Amazon op: listFinancialEventsByOrderId (Finances v0). Read-only. Useful for per-order profitability — shows fees, credits, and charges tied to one order.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/finances_listFinancialEventsByOrderId"},"tags":["amazon_sp"],"x-title":"Finances List Financial Events by Order ID","x-access":"read","x-family":"sp.financesV0","x-returns":[{"field":"data.orderId","description":"the requested order ID."},{"field":"data.result.FinancialEvents","description":"event lists (ShipmentEventList, RefundEventList, etc.) filtered to this order."},{"field":"data.nextToken","description":"the cursor for the next page (null on the last page)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"orderId":{"title":"Orderid","type":"string","description":"Amazon order ID (e.g. '114-1234567-1234567')."},"maxResultsPerPage":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Maxresultsperpage","description":"Max events per page (Amazon allows 1-100)."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page. Send it with the same other arguments."}},"required":["store","orderId"],"title":"finances_listFinancialEventsByOrderIdArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"orderId":{"description":"the requested order ID."},"result":{"properties":{"FinancialEvents":{"description":"event lists (ShipmentEventList, RefundEventList, etc.) filtered to this order."}}},"nextToken":{"description":"the cursor for the next page (null on the last page)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/finances_listTransactions":{"post":{"operationId":"finances_listTransactions","summary":"List Amazon financial transactions by posted-date range.","description":"List Amazon financial transactions by posted-date range. Amazon SP-API · listTransactions · GET /finances/2024-06-19/transactions Amazon op: listTransactions (Finances 2024-06-19, served at /finances/2024-06-19/transactions — NOT the v0 events API). Read-only. Each transaction carries transactionType, transactionStatus, totalAmount, postedDate, items, contexts, and breakdowns — useful for detailed reconciliation. Use it for deferred/released status (DEFERRED_RELEASED) and one row per transaction with breakdowns; use finances_listFinancialEvents for the v0 event lists by type.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/finances_listTransactions"},"tags":["amazon_sp"],"x-title":"Finances List Transactions","x-access":"read","x-family":"sp.finances_2024-06-19","x-returns":[{"field":"data.result.transactions","description":"array of transactions — each with transactionId, transactionType, transactionStatus, description, postedDate, totalAmount {currencyCode, currencyAmount}, marketplaceDetails, sellingPartnerMetadata, items, contexts, breakdowns[]."},{"field":"data.nextToken","description":"the cursor for the next page (null on the last page)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"postedAfter":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Postedafter","description":"ISO 8601 date-time (e.g. '2026-01-01T00:00:00Z'). Transactions posted on or after this date. REQUIRED by Amazon unless you pass relatedIdentifierName + relatedIdentifierValue. Must be more than two minutes before the request time. When you pass neither a window nor a related identifier the server defaults it to ~30 days ago."},"postedBefore":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Postedbefore","description":"ISO 8601 date-time. Posted before (not on) this date. Must be later than postedAfter and more than two minutes before the request time. A window wider than 180 days returns an EMPTY response (not an error) — page month by month. Default when omitted: two minutes before the request."},"transactionStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transactionstatus","description":"optional filter. Allowed: DEFERRED (currently deferred) | RELEASED (currently released) | DEFERRED_RELEASED (was deferred, now released)."},"relatedIdentifierName":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Relatedidentifiername","description":"optional. Filter by a related identifier; must be sent together with relatedIdentifierValue. Allowed: FINANCIAL_EVENT_GROUP_ID (the settlement group ID) | ORDER_ID (the Amazon order ID)."},"relatedIdentifierValue":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Relatedidentifiervalue","description":"optional. The value matching relatedIdentifierName (e.g. the group ID or order ID string)."},"nextToken":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Nexttoken","description":"the cursor from the previous call's data.nextToken; omit for the first page. Send it with the same other arguments."}},"required":["store"],"title":"finances_listTransactionsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"transactions":{"description":"array of transactions — each with transactionId, transactionType, transactionStatus, description, postedDate, totalAmount {currencyCode, currencyAmount}, marketplaceDetails, sellingPartnerMetadata, items, contexts, breakdowns[]."}}},"nextToken":{"description":"the cursor for the next page (null on the last page)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/replenishment_getSellingPartnerMetrics":{"post":{"operationId":"replenishment_getSellingPartnerMetrics","summary":"Get aggregated, account-level Subscribe & Save replenishment metrics for the selling partner.","description":"Get aggregated, account-level Subscribe & Save replenishment metrics for the selling partner. Amazon SP-API · getSellingPartnerMetrics · POST /replenishment/2022-11-07/sellingPartners/metrics/search Returns program-wide numbers (active subscriptions, subscription revenue, OOS loss, retention, revenue penetration) — NOT per-offer data. For per-ASIN drill-down use replenishment_listOfferMetrics.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/replenishment_getSellingPartnerMetrics"},"tags":["amazon_sp"],"x-title":"Replenishment Get Selling Partner Metrics","x-access":"read","x-family":"sp.replenishment-2022-11-07","x-returns":[{"field":"data.result.metrics[]","description":"per-interval objects (activeSubscriptions, totalSubscriptionsRevenue, shippedSubscriptionUnits, notDeliveredDueToOOS, lostRevenueDueToOOS, subscriberRetentionFor30Days/90Days, revenuePenetration, timeInterval, currencyCode, ...)."}],"x-notes":{"Body (Amazon schema)":["aggregationFrequency: DAY | WEEK | MONTH | QUARTER | YEAR","timeInterval*: {startDate*, endDate*}","metrics: [SHIPPED_SUBSCRIPTION_UNITS | TOTAL_SUBSCRIPTIONS_REVENUE | ACTIVE_SUBSCRIPTIONS | NOT_DELIVERED_DUE_TO_OOS | SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REVENUE | LOST_REVENUE_DUE_TO_OOS | SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REORDERS | COUPONS_REVENUE_PENETRATION | REVENUE_BY_DELIVERIES | SUBSCRIBER_RETENTION | REVENUE_PENETRATION_BY_SELLER_FUNDING | SHARE_OF_COUPON_SUBSCRIPTIONS | SUBSCRIBER_LIFETIME_VALUE_BY_CUSTOMER_SEGMENT | SIGNUP_CONVERSION_BY_SELLER_FUNDING | REVENUE_PENETRATION] (min 1)","filters: {asins: [string] (1–20), skus: [string] (1–20), fulfillmentChannelTypes: [AMAZON | MERCHANT] (1–2), brandNames: [string] (1–20), productGroups: [string] (1–20)}","timePeriodType*: PERFORMANCE | FORECAST","marketplaceId*: string","programTypes*: [SUBSCRIBE_AND_SAVE] (min 1)"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"timeInterval":{"additionalProperties":true,"title":"Timeinterval","type":"object","description":"{startDate, endDate}, both ISO 8601 datetimes with timezone, e.g. {\"startDate\": \"2026-04-01T00:00:00Z\", \"endDate\": \"2026-04-30T00:00:00Z\"}."},"timePeriodType":{"anyOf":[{"enum":["PERFORMANCE","FORECAST"],"type":"string"},{"type":"null"}],"default":null,"title":"Timeperiodtype","description":"PERFORMANCE (backward-looking; the default when omitted) or FORECAST (forward-looking projection)."},"aggregationFrequency":{"anyOf":[{"enum":["DAY","WEEK","MONTH","QUARTER","YEAR"],"type":"string"},{"type":"null"}],"default":null,"title":"Aggregationfrequency","description":"how to group rows in the response. Amazon REQUIRES it when timePeriodType=PERFORMANCE (else it 400s \"aggregationFrequency is required for PERFORMANCE timePeriodType\"); omit it with FORECAST. startDate / endDate are widened to whole buckets (WEEK = Monday–Sunday, MONTH = the calendar month, and so on). Allowed: DAY | WEEK | MONTH | QUARTER | YEAR."},"programTypes":{"anyOf":[{"items":{"const":"SUBSCRIBE_AND_SAVE","type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Programtypes","description":"omit — SUBSCRIBE_AND_SAVE, the only value, is sent for you."},"metrics":{"anyOf":[{"items":{"enum":["SHIPPED_SUBSCRIPTION_UNITS","TOTAL_SUBSCRIPTIONS_REVENUE","ACTIVE_SUBSCRIPTIONS","NOT_DELIVERED_DUE_TO_OOS","SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REVENUE","LOST_REVENUE_DUE_TO_OOS","SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REORDERS","COUPONS_REVENUE_PENETRATION","REVENUE_BY_DELIVERIES","SUBSCRIBER_RETENTION","REVENUE_PENETRATION_BY_SELLER_FUNDING","SHARE_OF_COUPON_SUBSCRIPTIONS","SUBSCRIBER_LIFETIME_VALUE_BY_CUSTOMER_SEGMENT","SIGNUP_CONVERSION_BY_SELLER_FUNDING","REVENUE_PENETRATION"],"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Metrics","description":"optional allowlist of metric names; omit for all. Allowed: SHIPPED_SUBSCRIPTION_UNITS | TOTAL_SUBSCRIPTIONS_REVENUE | ACTIVE_SUBSCRIPTIONS | NOT_DELIVERED_DUE_TO_OOS | SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REVENUE | LOST_REVENUE_DUE_TO_OOS | SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REORDERS | COUPONS_REVENUE_PENETRATION | REVENUE_BY_DELIVERIES | SUBSCRIBER_RETENTION | REVENUE_PENETRATION_BY_SELLER_FUNDING | SHARE_OF_COUPON_SUBSCRIPTIONS | SUBSCRIBER_LIFETIME_VALUE_BY_CUSTOMER_SEGMENT | SIGNUP_CONVERSION_BY_SELLER_FUNDING | REVENUE_PENETRATION."},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Filters","description":"Optional dict (each list maxItems 20, minItems 1): {\"asins\": [...], \"skus\": [...] (sellers only), \"fulfillmentChannelTypes\": [...]  (each AMAZON | MERCHANT; sellers only), \"brandNames\": [...] (US only), \"productGroups\": [...] (vendors only)}."},"marketplaceId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Marketplaceid","description":"optional Amazon marketplaceId; defaults to the store ref's marketplace."}},"required":["store","timeInterval"],"title":"replenishment_getSellingPartnerMetricsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"metrics":{"description":"per-interval objects (activeSubscriptions, totalSubscriptionsRevenue, shippedSubscriptionUnits, notDeliveredDueToOOS, lostRevenueDueToOOS, subscriberRetentionFor30Days/90Days, revenuePenetration, timeInterval, currencyCode, ...)."}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/replenishment_listOfferMetrics":{"post":{"operationId":"replenishment_listOfferMetrics","summary":"List Subscribe & Save replenishment metrics per offer (ASIN/SKU).","description":"List Subscribe & Save replenishment metrics per offer (ASIN/SKU). Amazon SP-API · listOfferMetrics · POST /replenishment/2022-11-07/offers/metrics/search Drill into per-offer performance (and forecast) to see which products carry the program. Pass the filters as flat arguments; the server nests them under Amazon's filters and fills marketplaceId, programTypes and (when omitted) timePeriodType=PERFORMANCE.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/replenishment_listOfferMetrics"},"tags":["amazon_sp"],"x-title":"Replenishment List Offer Metrics","x-access":"read","x-family":"sp.replenishment-2022-11-07","x-returns":[{"field":"data.result.offers[]","description":"per-offer metrics (asin, sku, fulfillmentChannelType, brandName, productGroup, activeSubscriptions, totalSubscriptionsRevenue, shippedSubscriptionUnits, notDeliveredDueToOOS, revenuePenetration, next30/60/90DayTotalSubscriptionsRevenue, next30/60/90DayShippedSubscriptionUnits, timeInterval, currencyCode, ...)."},{"field":"data.result.pagination.totalResults","description":"total matching offers (for paging)."}],"x-notes":{"Body (Amazon schema)":["pagination*: {limit* (1–500), offset* (0–9000)}","sort: {order*: ASC | DESC, key*}","sort.key: SHIPPED_SUBSCRIPTION_UNITS | TOTAL_SUBSCRIPTIONS_REVENUE | ACTIVE_SUBSCRIPTIONS | NEXT_90DAYS_SHIPPED_SUBSCRIPTION_UNITS | NEXT_60DAYS_SHIPPED_SUBSCRIPTION_UNITS | NEXT_30DAYS_SHIPPED_SUBSCRIPTION_UNITS | NEXT_90DAYS_TOTAL_SUBSCRIPTIONS_REVENUE | NEXT_60DAYS_TOTAL_SUBSCRIPTIONS_REVENUE | NEXT_30DAYS_TOTAL_SUBSCRIPTIONS_REVENUE","filters*: {aggregationFrequency: DAY | WEEK | MONTH | QUARTER | YEAR, timeInterval*: {startDate*, endDate*}, timePeriodType*: PERFORMANCE | FORECAST, marketplaceId*, programTypes*: [SUBSCRIBE_AND_SAVE] (min 1), asins: [string] (1–20), skus: [string] (1–20), fulfillmentChannelTypes: [AMAZON | MERCHANT] (1–2), brandNames: [string] (1–20), productGroups: [string] (1–20)}"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"timeInterval":{"additionalProperties":true,"title":"Timeinterval","type":"object","description":"{startDate, endDate}, ISO 8601 datetimes with timezone, e.g. {\"startDate\": \"2026-04-01T00:00:00Z\", \"endDate\": \"2026-04-15T00:00:00Z\"}."},"timePeriodType":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Timeperiodtype","description":"PERFORMANCE (historical; the default when omitted) or FORECAST (fills the next30/60/90Day* fields)."},"aggregationFrequency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Aggregationfrequency","description":"optional row grouping, PERFORMANCE only — omit it with FORECAST."},"programTypes":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Programtypes","description":"omit — SUBSCRIBE_AND_SAVE, the only value, is sent for you."},"asins":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Asins","description":"Filter by ASIN list. maxItems 20."},"skus":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Skus","description":"Filter by SKU list (sellers only). maxItems 20."},"fulfillmentChannelTypes":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Fulfillmentchanneltypes","description":"Filter list (sellers only), at most 2 values."},"brandNames":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Brandnames","description":"Filter list (US marketplace only). maxItems 20."},"productGroups":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Productgroups","description":"Filter list (vendors only). maxItems 20."},"sort":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Sort","description":"Optional {\"order\": ASC or DESC, \"key\": one of the sort keys the Body block lists}."},"pageSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pagesize","description":"Results per page → pagination.limit. 1-500; default 20."},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Offset","description":"Pagination offset → pagination.offset. 0-9000; default 0."},"marketplaceId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Marketplaceid","description":"optional Amazon marketplaceId; defaults to the store ref's marketplace."}},"required":["store","timeInterval"],"title":"replenishment_listOfferMetricsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"offers":{"description":"per-offer metrics (asin, sku, fulfillmentChannelType, brandName, productGroup, activeSubscriptions, totalSubscriptionsRevenue, shippedSubscriptionUnits, notDeliveredDueToOOS, revenuePenetration, next30/60/90DayTotalSubscriptionsRevenue, next30/60/90DayShippedSubscriptionUnits, timeInterval, currencyCode, ...)."},"pagination":{"properties":{"totalResults":{"description":"total matching offers (for paging)."}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/replenishment_listOffers":{"post":{"operationId":"replenishment_listOffers","summary":"List Subscribe & Save offers with eligibility, pricing, inventory, program config, and delivery forecasts.","description":"List Subscribe & Save offers with eligibility, pricing, inventory, program config, and delivery forecasts. Amazon SP-API · listOffers · POST /replenishment/2022-11-07/offers/search Shows which products are eligible for Subscribe & Save plus per-offer config (discount funding, auto-enrollment, upcoming deliveries). Pass the filters as flat arguments; the server nests them under Amazon's filters and fills marketplaceId and programTypes.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/replenishment_listOffers"},"tags":["amazon_sp"],"x-title":"Replenishment List Offers","x-access":"read","x-family":"sp.replenishment-2022-11-07","x-returns":[{"field":"data.result.offers[]","description":"per-offer data (sku, asin, marketplaceId, eligibility, offerProgramConfiguration.{preferences.autoEnrollment, promotions.*FundedBaseDiscount.percentage, enrollmentMethod (MANUAL|AUTOMATIC)}, programType, vendorCodes, price, priceCurrencyCode, inventory, stockRisk, deliveriesConditions[].{condition,next30DaysDeliveries}, subscriptions, fulfillmentNetworkIDType, forecastDeliveries.next15/30/60/90DaysDeliveries)."},{"field":"data.result.pagination.totalResults","description":"total matching offers (for paging)."}],"x-notes":{"Body (Amazon schema)":["pagination*: {limit* (1–100), offset* (0–9000)}","filters*: {marketplaceId*, skus: [string] (1–20), asins: [string] (1–20), eligibilities, preferences: {autoEnrollment}, promotions: {sellingPartnerFundedBaseDiscount, sellingPartnerFundedTieredDiscount, amazonFundedBaseDiscount, amazonFundedTieredDiscount}, programTypes*: [SUBSCRIBE_AND_SAVE] (min 1), deliveriesConditions}","filters.eligibilities: [ELIGIBLE | INELIGIBLE | SUSPENDED | REPLENISHMENT_ONLY_ORDERING]","filters.preferences.autoEnrollment: [OPTED_IN | OPTED_OUT]","filters.deliveriesConditions: [NEXT_30_DAYS_DELIVERIES_PAUSED_PRICING | NEXT_30_DAYS_DELIVERIES_PAUSED_NON_BUYABLE | NEXT_30_DAYS_DELIVERIES_AT_LOW_INVENTORY_RISK_ONLY | NEXT_30_DAYS_DELIVERIES_AT_LOW_INVENTORY_RISK | NO_ISSUES_FOR_NEXT_30_DAYS_DELIVERIES]","sort: {order*: ASC | DESC, key*}","sort.key: ASIN | SELLING_PARTNER_FUNDED_BASE_DISCOUNT_PERCENTAGE | SELLING_PARTNER_FUNDED_TIERED_DISCOUNT_PERCENTAGE | AMAZON_FUNDED_BASE_DISCOUNT_PERCENTAGE | AMAZON_FUNDED_TIERED_DISCOUNT_PERCENTAGE | INVENTORY | PRICE | SUBSCRIPTION_COUNT | FULFILLMENT_NETWORK_ID_TYPE"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"programTypes":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Programtypes","description":"omit — SUBSCRIBE_AND_SAVE, the only value, is sent for you."},"asins":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Asins","description":"Filter by ASIN list. maxItems 20."},"skus":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Skus","description":"Filter by SKU list (sellers only). maxItems 20."},"eligibilities":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Eligibilities","description":"Filter by eligibility status (this is an ARRAY, not a single value). Allowed: ELIGIBLE | INELIGIBLE | SUSPENDED | REPLENISHMENT_ONLY_ORDERING."},"preferences":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Preferences","description":"Preference filter {\"autoEnrollment\": [<...>]} (opted-in or opted-out offers)."},"promotions":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Promotions","description":"Discount-funding percentage filters, e.g. {\"sellingPartnerFundedBaseDiscount\": {\"percentage\": [5, 10]}} — any of the four discount keys the Body block lists, each {\"percentage\": [int,...]} maxItems 10."},"deliveriesConditions":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Deliveriesconditions","description":"Delivery-health filter list (next-30-day delivery conditions)."},"sort":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Sort","description":"Optional {\"order\": ASC or DESC, \"key\": one of the sort keys the Body block lists}."},"pageSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pagesize","description":"Results per page → pagination.limit. 1-100; default 20."},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Offset","description":"Pagination offset → pagination.offset. 0-9000; default 0."},"marketplaceId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Marketplaceid","description":"optional Amazon marketplaceId; defaults to the store ref's marketplace."}},"required":["store"],"title":"replenishment_listOffersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"result":{"properties":{"offers":{"description":"per-offer data (sku, asin, marketplaceId, eligibility, offerProgramConfiguration.{preferences.autoEnrollment, promotions.*FundedBaseDiscount.percentage, enrollmentMethod (MANUAL|AUTOMATIC)}, programType, vendorCodes, price, priceCurrencyCode, inventory, stockRisk, deliveriesConditions[].{condition,next30DaysDeliveries}, subscriptions, fulfillmentNetworkIDType, forecastDeliveries.next15/30/60/90DaysDeliveries)."},"pagination":{"properties":{"totalResults":{"description":"total matching offers (for paging)."}}}}}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/sales_getOrderMetrics":{"post":{"operationId":"sales_getOrderMetrics","summary":"Order metrics (units, order count, revenue) as a time series per granularity — sales trends, year-over-year comparisons, revenue reporting.","description":"Order metrics (units, order count, revenue) as a time series per granularity — sales trends, year-over-year comparisons, revenue reporting. Read-only. Amazon SP-API · getOrderMetrics · GET /sales/v1/orderMetrics","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/sales_getOrderMetrics"},"tags":["amazon_sp"],"x-title":"Sales Get Order Metrics","x-access":"read","x-family":"sp.sales","x-returns":[{"field":"data.granularity / data.interval","description":"as requested."},{"field":"data.result","description":"one per period — {interval, unitCount, orderItemCount, orderCount, averageUnitPrice {amount, currencyCode}, totalSales {amount, currencyCode}}."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"interval":{"title":"Interval","type":"string","description":"two ISO-8601 datetimes joined by '--', BOTH with a timezone offset ('2026-01-01T00:00:00-07:00--2026-02-01T00:00:00-07:00', or 'Z' for UTC) — a single datetime is rejected before the call, and Amazon refuses an offset-less interval even with granularity_time_zone set. Hour works only for an interval within the last 30 days; every other granularity within the last 2 years."},"granularity":{"enum":["Hour","Day","Week","Month","Year","Total"],"title":"Granularity","type":"string","description":"the bucket size of the series; Total returns one sum for the interval. Allowed: Hour | Day | Week | Month | Year | Total."},"marketplace_ids":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"default":null,"title":"Marketplace Ids","description":"optional single-element override of the store's marketplace (['ATVPDKIKX0DER']) — Amazon allows EXACTLY ONE per call, so compare marketplaces one call each; omit to use the store's."},"granularity_time_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Granularity Time Zone","description":"IANA zone ('UTC', 'Asia/Dubai') that sets the day boundary for Day-or-longer granularity; Amazon requires it above Hour. Match it to the interval's offset (a 'Z' interval → 'UTC', '+04:00' → 'Asia/Dubai') or the buckets are re-cut in that zone with partial-day edges."},"buyer_type":{"anyOf":[{"enum":["B2B","B2C","All"],"type":"string"},{"type":"null"}],"default":null,"title":"Buyer Type","description":"whose orders to count — business buyers, consumers or both. Default: All. Allowed: B2B | B2C | All."},"fulfillment_network":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Fulfillment Network","description":"AFN (FBA) | MFN (seller-fulfilled); omit for both."},"first_day_of_week":{"anyOf":[{"enum":["Monday","Sunday"],"type":"string"},{"type":"null"}],"default":null,"title":"First Day Of Week","description":"the day a Week bucket starts on. Default: Monday. Allowed: Monday | Sunday."},"asin":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Asin","description":"the ASIN (e.g. 'B0XXXXXXXX'). Mutually exclusive with sku."},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sku","description":"one seller SKU. Mutually exclusive with asin."},"amazon_program":{"anyOf":[{"const":"AmazonHaul","type":"string"},{"type":"null"}],"default":null,"title":"Amazon Program","description":"limits the metrics to one Amazon program — AmazonHaul is the low-cost storefront; omit for all programs."}},"required":["store","interval","granularity"],"title":"sales_getOrderMetricsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"granularity":{"description":"as requested."},"interval":{"description":"as requested."},"result":{"description":"one per period — {interval, unitCount, orderItemCount, orderCount, averageUnitPrice {amount, currencyCode}, totalSales {amount, currencyCode}}."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/solicitations_getSolicitationActionsForOrder":{"post":{"operationId":"solicitations_getSolicitationActionsForOrder","summary":"Check which solicitation actions are available for an order.","description":"Check which solicitation actions are available for an order. (Amazon operationId: getSolicitationActionsForOrder.) Amazon SP-API · getSolicitationActionsForOrder · GET /solicitations/v1/orders/{amazonOrderId} Always call this before solicitations_createProductReviewAndSellerFeedbackSolicitation to verify the action is permitted; if no action is listed, skip the order. Amazon restricts solicitations based on order age, category, and whether a solicitation was already sent.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/solicitations_getSolicitationActionsForOrder"},"tags":["amazon_sp"],"x-title":"Solicitations Get Solicitation Actions for Order","x-access":"read","x-family":"sp.solicitations","x-returns":[{"field":"data.orderId","description":"the queried order ID."},{"field":"data.result","description":"HATEOAS payload. Eligible actions live under _links.actions (and _embedded.actions) — a non-empty actions list means a solicitation is permitted for this order."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"orderId":{"title":"Orderid","type":"string","description":"Amazon order ID (e.g. '114-1234567-1234567'). Maps to the {amazonOrderId} path."},"marketplaceId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Marketplaceid","description":"optional Amazon marketplaceId; defaults to the store ref's marketplace."}},"required":["store","orderId"],"title":"solicitations_getSolicitationActionsForOrderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"orderId":{"description":"the queried order ID."},"result":{"description":"HATEOAS payload. Eligible actions live under _links.actions (and _embedded.actions) — a non-empty actions list means a solicitation is permitted for this order."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/solicitations_createProductReviewAndSellerFeedbackSolicitation":{"post":{"operationId":"solicitations_createProductReviewAndSellerFeedbackSolicitation","summary":"Send a product review and seller feedback solicitation for an order.","description":"Send a product review and seller feedback solicitation for an order. (Amazon operationId: createProductReviewAndSellerFeedbackSolicitation.) Amazon SP-API · createProductReviewAndSellerFeedbackSolicitation · POST /solicitations/v1/orders/{amazonOrderId}/solicitations/productReviewAndSellerFeedback Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask. Sends the productReviewAndSellerFeedback solicitation — a single combined request covering both a product review and seller feedback (the only solicitation type Amazon exposes via this API). This is a real Amazon WRITE: it dispatches a request-review message to the buyer. Requires SP write access. Call solicitations_getSolicitationActionsForOrder first and send only when it lists an action — Amazon allows one productReviewAndSellerFeedback solicitation OR one free-form proactive message per order, and a second attempt returns an error.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/solicitations_createProductReviewAndSellerFeedbackSolicitation"},"tags":["amazon_sp"],"x-title":"Solicitations Request Product Review and Seller Feedback","x-access":"write","x-family":"sp.solicitations","x-returns":[{"field":"data.orderId","description":"the order ID for which solicitation was sent."},{"field":"data.result","description":"Amazon response payload (empty on success — a 201 with no body means the solicitation was created)."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"orderId":{"title":"Orderid","type":"string","description":"Amazon order ID (e.g. '114-1234567-1234567'). Maps to the {amazonOrderId} path."},"marketplaceId":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Marketplaceid","description":"optional Amazon marketplaceId; defaults to the store ref's marketplace."}},"required":["store","orderId"],"title":"solicitations_createProductReviewAndSellerFeedbackSolicitationArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"orderId":{"description":"the order ID for which solicitation was sent."},"result":{"description":"Amazon response payload (empty on success — a 201 with no body means the solicitation was created)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/generate_image":{"post":{"operationId":"generate_image","summary":"Generate images from a text prompt — listing photos, A+ banners, lifestyle and infographic shots, icons.","description":"Generate images from a text prompt — listing photos, A+ banners, lifestyle and infographic shots, icons. Priced per delivered image (credits_quote gives the number; HTTP 402 with error_code insufficient_credits when the balance is short — top up at sellersheetai.com/billing); a failure is refunded.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/generate_image"},"tags":["sellersheet"],"x-title":"Generate Image","x-access":"write","x-family":null,"x-returns":[{"field":"data.images","description":"one entry per image — cdn_url (saved at store/parent_sku/sku/slot), thumbnail_url, provider, model, revised_prompt (how the model rewrote the prompt — mention it), background_note (relay it when set), or error. An entry with r2_upload_error has no cdn_url; its image arrives as an inline image block."},{"field":"data.credits.charged / data.credits.balance","description":"this call's cost and what is left."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prompt":{"title":"Prompt","type":"string","description":"the image description."},"provider":{"default":"openai","title":"Provider","type":"string","description":"'openai' (default; gpt-image-2 — precise, legible text) | 'nanobanana' (Gemini — fast, search-grounded; renders and is priced at the default canvas, so size, quality and background apply to openai only) | 'both'."},"size":{"default":"1024x1024","title":"Size","type":"string","description":"'1024x1024' (default, the same canvas Studio uses) | '2048x2048' (Amazon zoom headroom; costs more) | '1024x1536' | '1536x1024' | 'auto'."},"quality":{"default":"high","title":"Quality","type":"string","description":"'low' | 'medium' | 'high' (default) | 'auto'."},"n":{"default":1,"title":"N","type":"integer","description":"variations, 1–4 (default 1)."},"background":{"default":"auto","title":"Background","type":"string","description":"'auto' (default) | 'opaque'. gpt-image-2 has no transparent background — 'transparent' is treated as 'auto' and the response carries background_note; generate opaque and remove the background downstream."},"output_format":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Output Format","description":"'png' | 'jpeg' | 'webp'; omit and the server decides (currently jpeg)."},"use_search_grounding":{"default":false,"title":"Use Search Grounding","type":"boolean","description":"Google Search grounding (nanobanana); default false."},"synthetic_performer":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Synthetic Performer","description":"Amazon's contains-synthetic-performer disclosure (XMP metadata in the upload); omit and the server infers it from the prompt; true or false overrides. set_synthetic_performer toggles it later without regenerating."},"store":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Store","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. Required."},"parent_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Sku","description":"the family SKU; defaults to sku."},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sku","description":"the child SKU. Required."},"slot":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Slot","description":"the Image Library slot: 's0'–'s8' (PDP) or 'a1'–'a5' / 'p1'–'p5' (A+). Required — a call missing store, sku or slot is refused (400) before billing."},"filename_prefix":{"default":"generated","title":"Filename Prefix","type":"string","description":"upload filename prefix."}},"required":["prompt"],"title":"generate_imageArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success"]}}},"data":{"type":"object","properties":{"content":{"type":"array","description":"the MCP content blocks the tool answers with (text, image)","items":{"type":"object","properties":{"type":{"type":"string"}}}}}},"human_action":{"type":"string"}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/edit_image":{"post":{"operationId":"edit_image","summary":"Edit one image, or compose 2–10 into one, from a text instruction (1 input = revise, 2 or more = compose): background swaps, style transfer, object add/remove, composites.","description":"Edit one image, or compose 2–10 into one, from a text instruction (1 input = revise, 2 or more = compose): background swaps, style transfer, object add/remove, composites. Returns a job receipt — poll check_image_job until status is 'done', then read cdn_url and revised_prompt (the drift signal). Priced per delivered image (credits_quote gives the number; HTTP 402 with error_code insufficient_credits when the balance is short — top up at sellersheetai.com/billing); a failure is refunded.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/edit_image"},"tags":["sellersheet"],"x-title":"Edit Image","x-access":"write","x-family":null,"x-returns":[{"field":"data.job_id","description":"the receipt — poll check_image_job."}],"x-notes":{"Gotchas":["store, sku and slot are required — a call missing one is refused (400) before","anything is charged. A single edit takes ~60–120 s (openai) or ~10–30 s","(nanobanana), a compose 2–5 minutes. Never resubmit a 'processing' job (a resubmit is","a new, billed job); re-run only on status 'error'."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prompt":{"title":"Prompt","type":"string","description":"the edit or composition instruction; for a restyle, the adapted json_prompt from reverse_prompt, stringified. Restate the preserve-list every turn (\"change only X; keep geometry, branding, text and camera identical\") and index several inputs (\"Image 1 = master, Image 2 = colour reference only\")."},"image_sources":{"items":{},"title":"Image Sources","type":"array","description":"1–10 sources — a public URL (a Drive link must be shared 'anyone with the link') or base64; for a refinement turn, the previous turn's cdn_url."},"provider":{"default":"openai","title":"Provider","type":"string","description":"'openai' (default; up to 10 inputs + mask) | 'nanobanana' (first image only; priced at its ~1K canvas) | 'both'."},"size":{"default":"2048x2048","title":"Size","type":"string","description":"'2048x2048' (default; best for Amazon zoom) | '1536x1536' | '1024x1024' | '1024x1536' | '1536x1024'."},"quality":{"default":"high","title":"Quality","type":"string","description":"'low' | 'medium' | 'high' (default)."},"mask_source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mask Source","description":"optional PNG mask (transparent = edit area). Applied as a real mask only when the user's model route has a mask-capable model (get_user_context data.credits.routes[key = data.credits.route].answers.image_mask non-null); otherwise the server describes the painted box in the instruction and runs the edit unmasked (check_image_job's data.mask = 'described' — check the result stayed inside the area), and a route that cannot edit at all is refused before billing. For exact masked edits switch route on Billing & Credits."},"output_format":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Output Format","description":"'png' | 'jpeg' | 'webp'; omit and the server decides (currently jpeg)."},"synthetic_performer":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Synthetic Performer","description":"Amazon's contains-synthetic-performer disclosure (XMP metadata in the upload); omit and the server infers it from the prompt; true or false overrides. set_synthetic_performer toggles it later without regenerating."},"store":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Store","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. Required."},"parent_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Sku","description":"the family SKU; defaults to sku."},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sku","description":"the child SKU. Required."},"slot":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Slot","description":"the Image Library slot: 's0'–'s8' (PDP) or 'a1'–'a5' / 'p1'–'p5' (A+). Required."},"filename_prefix":{"default":"edited","title":"Filename Prefix","type":"string","description":"upload filename prefix."}},"required":["prompt","image_sources"],"title":"edit_imageArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success"]}}},"data":{"type":"object","properties":{"content":{"type":"array","description":"the MCP content blocks the tool answers with (text, image)","items":{"type":"object","properties":{"type":{"type":"string"}}}}}},"human_action":{"type":"string"}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/list_generated_images":{"post":{"operationId":"list_generated_images","summary":"List images already generated and saved for a store — newest first.","description":"List images already generated and saved for a store — newest first. Use this to FIND an image you or the user made earlier instead of regenerating it (a regeneration is billed again and returns a different image; the library is free and returns the exact one). Also the way to answer \"what images do we have for this SKU?\".","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/list_generated_images"},"tags":["sellersheet"],"x-title":"List Generated Images","x-access":"read","x-family":null,"x-returns":[{"field":"data.images","description":"newest first; each carries id (pass it to set_synthetic_performer), parent_sku, child_sku, slot, version, lang, cdn_url, thumbnail_url, source, created_at and synthetic_performer."},{"field":"data.next_before_id","description":"pass as before_id for the next page; null on the last page — stop there."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. Required."},"parent_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Sku","description":"narrow to one product family."},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sku","description":"narrow to one SKU — matches parent OR child, so pass whichever you have."},"slot":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Slot","description":"narrow to one position ('s0'-'s8', 'a1'-'a5', 'p1'-'p5')."},"limit":{"default":50,"title":"Limit","type":"integer","description":"page size, 1-200 (default 50). Above 200 is REJECTED (422), not clamped — ask for 200 and page with before_id."},"before_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Before Id","description":"paging cursor — pass the previous response's `next_before_id`. Do NOT compute an offset: rows are keyset- paged by id, so an offset would skip or repeat images when new ones land while you page."}},"required":["store"],"title":"list_generated_imagesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success"]}}},"data":{"type":"object","properties":{"content":{"type":"array","description":"the MCP content blocks the tool answers with (text, image)","items":{"type":"object","properties":{"type":{"type":"string"}}}}}},"human_action":{"type":"string"}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/reverse_prompt":{"post":{"operationId":"reverse_prompt","summary":"Describe reference image(s) as a structured English prompt — step 1 of a restyle: adapt the fields to your product (subject, colors and materials stay faithful; swap scene, lightin","description":"Describe reference image(s) as a structured English prompt — step 1 of a restyle: adapt the fields to your product (subject, colors and materials stay faithful; swap scene, lighting and camera), stringify it and pass it as edit_image's prompt with your product photos as image_sources. Billed per call on the text meter, refunded on failure; synchronous, ~5–30 s. Then write the adapted prompt yourself: edit data.json_prompt so subject, details_appearance, colors and materials are YOUR product (exact geometry, proportions and label text kept; nothing of the reference product leaks in); set intended_use to the target slot (an Amazon main image is pure white, product only, no text); borrow only the look — environment_background, lighting_atmosphere, style_camera, composition, aspect_ratio; put the invariants in `constraints` (no watermark, no extra text, no new objects; 'photorealistic' for a photo; literal copy in straight quotes, brand names spelled letter by letter); one tight phrase per field, the stringified prompt under 2,500 characters. Then json.dumps it and pass it as edit_image's prompt with the product photos as image_sources and quality='high'.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/reverse_prompt"},"tags":["sellersheet"],"x-title":"Reverse Prompt","x-access":"write","x-family":null,"x-returns":[{"field":"data.json_prompt","description":"field dict (subject, action_pose, environment_background, lighting_atmosphere, style_camera, colors, materials, aspect_ratio, …)."},{"field":"data.style_tags / data.analysis / data.confidence / data.vision_provider","description":"supporting detail and which model answered."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"images":{"items":{},"title":"Images","type":"array","description":"1+ sources — a public URL (a Drive link must be shared 'anyone with the link') or base64; for a restyle, the reference shot. Required."},"vision_provider":{"default":"auto","title":"Vision Provider","type":"string","description":"'auto' (OpenAI→Gemini) | 'openai' | 'gemini'. Default 'auto'."}},"required":["images"],"title":"reverse_promptArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success"]}}},"data":{"type":"object","properties":{"content":{"type":"array","description":"the MCP content blocks the tool answers with (text, image)","items":{"type":"object","properties":{"type":{"type":"string"}}}}}},"human_action":{"type":"string"}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/check_image_jobs":{"post":{"operationId":"check_image_jobs","summary":"Batch-poll multiple async image jobs in one call.","description":"Batch-poll multiple async image jobs in one call. Use this when you have submitted several edit_image jobs in parallel (e.g. a family-recolor fan-out) — avoids N separate round trips per polling cycle. Rows stay small (~1 KB per job) and carry no image. Each row already carries cdn_url; call check_image_job only for a 'done' job whose cdn_url is still null.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/check_image_jobs"},"tags":["sellersheet"],"x-title":"Check Image Jobs","x-access":"read","x-family":null,"x-returns":[{"field":"data.jobs","description":"one row per id, in input order — id, status ('pending' | 'processing' | 'done' | 'error' | 'not_found' = unknown or past its ~15-minute retention), progress, elapsed_s, queue_wait_s, cdn_url, error."},{"field":"data.done / data.pending / data.error","description":"counts — poll until data.pending is 0."}],"x-notes":{"Workflow":["1. Submit N jobs via edit_image → collect job_ids","2. Poll check_image_jobs(job_ids) every 20–30s","3. When data.pending is 0, read cdn_url from each 'done' row."],"Gotchas":["Successes = data.done (or cdn_url); failures = data.error only, not slow jobs.","Re-submit only 'error' jobs, never a 'pending'/'processing' one (that duplicates","and rebills)."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_ids":{"items":{},"title":"Job Ids","type":"array","description":"up to 20 job_ids from edit_image; ids past the 20th are dropped without notice."}},"required":["job_ids"],"title":"check_image_jobsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success"]}}},"data":{"type":"object","properties":{"content":{"type":"array","description":"the MCP content blocks the tool answers with (text, image)","items":{"type":"object","properties":{"type":{"type":"string"}}}}}},"human_action":{"type":"string"}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/check_image_job":{"post":{"operationId":"check_image_job","summary":"Poll an async image job (edit_image).","description":"Poll an async image job (edit_image). Call every ~15–30s until status='done' or 'error'. The deliverable is cdn_url. For a multi-turn refine chain, read cdn_url from the done payload and pass it as the next edit_image's image_sources.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/check_image_job"},"tags":["sellersheet"],"x-title":"Check Image Job","x-access":"read","x-family":null,"x-returns":[{"field":"data.status","description":"'pending' | 'processing' | 'done' | 'error'."},{"field":"data.progress","description":"human-readable status string."},{"field":"data.elapsed_s","description":"seconds since the worker started (null before); use it to estimate the time left (elapsed 30 s on a typical 90 s job → ~60 s more)."},{"field":"data.queue_wait_s","description":"seconds from submit to worker pickup."},{"field":"data.cdn_url","description":"the saved image — the input for the next refine turn. A job that names a store and SKU reads 'done' only once its image is saved, so cdn_url is set; if the save fails the job ends 'error', nothing is charged and no image is attached. A job without a store and SKU saves nothing: its image comes back as an inline image block and cdn_url stays null."},{"field":"data.error","description":"the error message when status is 'error'."},{"field":"data.revised_prompt","description":"how the model rewrote the prompt — mention it so the user can spot drift; relay data.background_note when set."},{"field":"data.mask","description":"'mask' (a real mask was applied) | 'described' (the box was written into the instruction — check the edit stayed inside it) | null."}],"x-notes":{"Gotchas":["Poll every ~20 s for nanobanana jobs (~15–30 s total), every ~30 s for OpenAI","jobs (~60–120 s). There is no client timeout: a long 'processing' (edit up to","~2 min, compose ~5 min) is normal — never resubmit it (that rebills and","duplicates); only 'error' warrants a fresh edit_image. Status is dropped ~15 min","after submit — read cdn_url before then."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"title":"Job Id","type":"string","description":"id returned by edit_image."}},"required":["job_id"],"title":"check_image_jobArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success"]}}},"data":{"type":"object","properties":{"content":{"type":"array","description":"the MCP content blocks the tool answers with (text, image)","items":{"type":"object","properties":{"type":{"type":"string"}}}}}},"human_action":{"type":"string"}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/set_synthetic_performer":{"post":{"operationId":"set_synthetic_performer","summary":"Toggle Amazon's contains-synthetic-performer disclosure tag on an already-saved image, without regenerating it.","description":"Toggle Amazon's contains-synthetic-performer disclosure tag on an already-saved image, without regenerating it. Set value=True when the image depicts an AI-generated person (Amazon requires the disclosure); set False to remove a tag that was added in error. Rewrites the R2 file in place — same cdn_url and version, only the embedded XMP metadata changes (webp is not yet supported: the tag needs a png/jpeg container).","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/set_synthetic_performer"},"tags":["sellersheet"],"x-title":"Set Synthetic Performer","x-access":"destructive","x-family":null,"x-returns":[{"field":"data.id / data.synthetic_performer","description":"the image and its flag as now stored."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. Required — authorizes the image."},"id":{"title":"Id","type":"integer","description":"the canonical_images row id — read it from a list_generated_images row (NOT the job_id from generate_image / edit_image)."},"value":{"title":"Value","type":"boolean","description":"True to add the disclosure tag, False to remove it."}},"required":["store","id","value"],"title":"set_synthetic_performerArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success"]}}},"data":{"type":"object","properties":{"content":{"type":"array","description":"the MCP content blocks the tool answers with (text, image)","items":{"type":"object","properties":{"type":{"type":"string"}}}}}},"human_action":{"type":"string"}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorInvoices_submitInvoices":{"post":{"operationId":"vendorInvoices_submitInvoices","summary":"Submit vendor invoices or credit notes to Amazon.","description":"Submit vendor invoices or credit notes to Amazon. Amazon write; blocks until the transaction reaches Success or Failure. Amazon SP-API · submitInvoices · POST /vendor/payments/v1/invoices Amazon SP-API · getTransaction · GET /vendor/transactions/v1/transactions/{transactionId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorInvoices_submitInvoices"},"tags":["amazon_sp"],"x-title":"Vendor Invoices Submit Invoices","x-access":"destructive","x-family":"sp.vendorInvoices","x-returns":[{"field":"data.status","description":"SUCCESS, or Failure with data.errors [{code, message, details}] — fix them and resubmit with a NEW invoice id."},{"field":"data.transactionId / data.raw","description":"the finished transaction (raw on success only)."}],"x-notes":{"Body (Amazon schema; submitInvoices): {invoices: [Invoice]}, each item":["invoiceType*: Invoice | CreditNote","id*: string","date*: string (date-time)","remitToParty*: {partyId*, address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalOrZipCode, countryCode*, phone}, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}","invoiceTotal*: {currencyCode, amount}","+ 10 more: referenceNumber, shipToParty, shipFromParty, billToParty, paymentTerms, taxDetails,","  additionalDetails, chargeDetails, allowanceDetails, items","Full schema: the Docs link above."],"Gotchas":["India takes Invoice only (no CreditNote) and requires HSN, GST tax, shipFromParty","and a 15-char GST id; Europe takes Invoice and CreditNote (PO number optional on a","credit note) and requires VAT registration; North America takes Invoice only, tax","optional.","HTTP 502 = still Processing after 60 s; the error names the transactionId — check it","with vendorTransactionStatus_getTransaction before resubmitting."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"invoices_payload":{"additionalProperties":true,"title":"Invoices Payload","type":"object","description":"{\"invoices\": [Invoice, …]}. Per Invoice, required: invoiceType (Invoice | CreditNote), id (your unique invoice or credit-note number — NEVER reused), date (ISO-8601, now or earlier), remitToParty (a Party — partyId, address, taxRegistrationDetails; full shape in the Body block below), invoiceTotal (Money {currencyCode ISO-4217, amount as a decimal string}; non-zero and equal to items + charges − allowances). Optional: items: [{itemSequenceNumber (int), amazonProductIdentifier (ASIN) or vendorProductIdentifier, invoicedQuantity {amount (non-zero int), unitOfMeasure Cases | Eaches, unitSize}, netCost (Money), purchaseOrderNumber (8-char alphanumeric; required on an Invoice), hsnCode (India, digits), taxDetails, chargeDetails, allowanceDetails, creditNoteDetails (required on a CreditNote — {referenceInvoiceNumber, returnsReferenceNumber, goodsReturnDate, rmaId, debitNoteNumber})}]; billToParty (a Party); referenceNumber (India: the mandatory government ref); shipToParty; shipFromParty (required in India and the EU); paymentTerms {type Basic | EndOfMonth | FixedDate | Proximo | PaymentDueUponReceiptOfInvoice | LetterofCredit, discountPercent, discountDueDays, netDueDays}; taxDetails (required in India): [{taxType CGST | SGST | CESS | UTGST | IGST | MwSt. | PST | TVA | VAT | GST | ST | Consumption | MutuallyDefined | DomesticVAT, taxRate, taxAmount, taxableAmount}]; chargeDetails: [{type Freight | Packing | Duty | Service | SmallOrder | InsurancePlacementCost | InsuranceFee | SpecialHandlingService | CollectionAndRecyclingService | EnvironmentalProtectionService | TaxCollectedAtSource, description, chargeAmount, taxDetails}]; allowanceDetails: [{type Discount | DiscountIncentive | Defective | Promotional | UnsaleableMerchandise | Special, description, allowanceAmount, taxDetails}]; additionalDetails: [{type SUR | OCR | CartonCount, detail, languageCode}]. Full tree: https://developer-docs.amazon.com/sp-api/docs/submit-invoices"}},"required":["store","invoices_payload"],"title":"vendorInvoices_submitInvoicesArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"SUCCESS, or Failure with data.errors [{code, message, details}] — fix them and resubmit with a NEW invoice id."},"transactionId":{"description":"the finished transaction (raw on success only)."},"raw":{"description":"the finished transaction (raw on success only)."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorOrders_getPurchaseOrders":{"post":{"operationId":"vendorOrders_getPurchaseOrders","summary":"List vendor purchase orders created or changed in a window of at most 7 days, no older than 6 months.","description":"List vendor purchase orders created or changed in a window of at most 7 days, no older than 6 months. Amazon SP-API · getPurchaseOrders · GET /vendor/orders/v1/purchaseOrders","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorOrders_getPurchaseOrders"},"tags":["amazon_sp"],"x-title":"Vendor Orders Get Purchase Orders","x-access":"read","x-family":"sp.vendorOrders","x-returns":[{"field":"data.orders","description":"list of purchase order dicts."},{"field":"data.count","description":"number of orders in this page."},{"field":"data.nextToken","description":"pass to next call if present."}],"x-notes":{"Workflow":["1. Call with created_after/created_before for new POs, or changed_after/changed_before for","   changed POs (window ≤ 7 days).","2. While data.nextToken is present, call again with it as next_token.","3. For each new PO, call vendorOrders_getPurchaseOrder for full item details.","4. Call vendorOrders_submitAcknowledgement to accept/reject items."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"created_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created After","description":"ISO 8601. POs created after this time."},"created_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created Before","description":"ISO 8601. POs created before this time."},"changed_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Changed After","description":"ISO 8601. POs changed after this time."},"changed_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Changed Before","description":"ISO 8601. POs changed before this time."},"purchase_order_state":{"anyOf":[{"enum":["New","Acknowledged","Closed"],"type":"string"},{"type":"null"}],"default":null,"title":"Purchase Order State","description":"keeps only POs in this state. Allowed: New | Acknowledged | Closed."},"include_details":{"default":true,"title":"Include Details","type":"boolean","description":"True = full PO body, False = PO numbers only (default True)."},"ordering_vendor_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ordering Vendor Code","description":"Filter by sellingParty.partyId value."},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Limit","description":"Max records returned, 1–100 (Amazon default 100)."},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"title":"Sort Order","description":"ASC or DESC."},"po_item_state":{"anyOf":[{"const":"Cancelled","type":"string"},{"type":"null"}],"default":null,"title":"Po Item State","description":"Cancelled keeps only POs with an item Amazon cancelled (quantity now zero)."},"is_po_changed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Is Po Changed","description":"True = changed POs only."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"vendorOrders_getPurchaseOrdersArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"orders":{"description":"list of purchase order dicts."},"count":{"description":"number of orders in this page."},"nextToken":{"description":"pass to next call if present."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorOrders_getPurchaseOrder":{"post":{"operationId":"vendorOrders_getPurchaseOrder","summary":"Get full details for a single vendor purchase order.","description":"Get full details for a single vendor purchase order. Amazon SP-API · getPurchaseOrder · GET /vendor/orders/v1/purchaseOrders/{purchaseOrderNumber}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorOrders_getPurchaseOrder"},"tags":["amazon_sp"],"x-title":"Vendor Orders Get Purchase Order","x-access":"read","x-family":"sp.vendorOrders","x-returns":[{"field":"data.order","description":"the PO — purchaseOrderState, orderDetails.items[] {itemSequenceNumber, amazonProductIdentifier, vendorProductIdentifier, orderedQuantity, netCost, isBackOrderAllowed}, orderDetails.shipToParty and deliveryWindow; an acknowledgement echoes these item fields."},{"field":"data.purchaseOrderNumber","description":"the PO number echoed back."}],"x-notes":{"Workflow":["1. Call with the purchaseOrderNumber from vendorOrders_getPurchaseOrders.","2. Review data.order for item quantities, delivery windows, and ship-to location.","3. Call vendorOrders_submitAcknowledgement with accepted/rejected items."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"purchase_order_number":{"title":"Purchase Order Number","type":"string","description":"8-character alpha-numeric PO number."}},"required":["store","purchase_order_number"],"title":"vendorOrders_getPurchaseOrderArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"order":{"description":"the PO — purchaseOrderState, orderDetails.items[] {itemSequenceNumber, amazonProductIdentifier, vendorProductIdentifier, orderedQuantity, netCost, isBackOrderAllowed}, orderDetails.shipToParty and deliveryWindow; an acknowledgement echoes these item fields."},"purchaseOrderNumber":{"description":"the PO number echoed back."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorOrders_submitAcknowledgement":{"post":{"operationId":"vendorOrders_submitAcknowledgement","summary":"Acknowledge (accept, backorder or reject) one or more purchase orders.","description":"Acknowledge (accept, backorder or reject) one or more purchase orders. Blocks until the transaction reaches SUCCESS or FAILURE — no separate polling. Build one acknowledgement per purchaseOrderNumber from vendorOrders_getPurchaseOrder, one item per PO line. Amazon SP-API · submitAcknowledgement · POST /vendor/orders/v1/acknowledgements Amazon SP-API · getTransaction · GET /vendor/transactions/v1/transactions/{transactionId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorOrders_submitAcknowledgement"},"tags":["amazon_sp"],"x-title":"Vendor Orders Submit Acknowledgement","x-access":"destructive","x-family":"sp.vendorOrders","x-returns":[{"field":"data.transactionId","description":"the Amazon transaction, already final when this returns."},{"field":"data.status","description":"SUCCESS, or Failure with data.errors [{code, message, details}]."}],"x-notes":{"Body (Amazon schema; submitAcknowledgement): {acknowledgements: [OrderAcknowledgement]}, each item":["purchaseOrderNumber*: string","sellingParty*: {partyId*, address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, taxInfo: {taxRegistrationType*, taxRegistrationNumber*}}","sellingParty.taxInfo.taxRegistrationType: VAT | GST","acknowledgementDate*: string (date-time)","items*: [{itemSequenceNumber, amazonProductIdentifier, vendorProductIdentifier, orderedQuantity*: {amount, unitOfMeasure, unitSize}, netCost: {currencyCode, amount, unitOfMeasure}, listPrice: {currencyCode, amount, unitOfMeasure}, discountMultiplier, itemAcknowledgements*: [{acknowledgementCode*, acknowledgedQuantity*, scheduledShipDate, scheduledDeliveryDate, rejectionReason}]}]","items.orderedQuantity.unitOfMeasure: Cases | Eaches","items.netCost.unitOfMeasure: POUNDS | OUNCES | GRAMS | KILOGRAMS","items.listPrice.unitOfMeasure: POUNDS | OUNCES | GRAMS | KILOGRAMS","items.itemAcknowledgements.acknowledgementCode: Accepted | Backordered | Rejected","items.itemAcknowledgements.acknowledgedQuantity.unitOfMeasure: Cases | Eaches","items.itemAcknowledgements.rejectionReason: TemporarilyUnavailable | InvalidProductIdentifier | ObsoleteProduct"],"Gotchas":["Backordered is accepted only on a PO line whose isBackOrderAllowed is true","(vendorOrders_getPurchaseOrder).","An HTTP 502 means Amazon was still Processing after 60 s — the error names the","transactionId; check it with vendorTransactionStatus_getTransaction before","acknowledging again."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"acknowledgement_payload":{"additionalProperties":true,"title":"Acknowledgement Payload","type":"object","description":"{\"acknowledgements\": [Acknowledgement, …]}. Per Acknowledgement, required: purchaseOrderNumber (8-char alphanumeric), acknowledgementDate (ISO-8601), sellingParty {partyId (the vendor or warehouse code) required; address: {name, addressLine1, countryCode (2 chars) required; addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, phone}; taxInfo: {taxRegistrationType VAT | GST, taxRegistrationNumber}}, items: [{itemSequenceNumber (the PO line), amazonProductIdentifier (ASIN) or vendorProductIdentifier (one, so Amazon matches the line), orderedQuantity {amount (non-zero int), unitOfMeasure Cases | Eaches, unitSize} required, netCost (Money {currencyCode ISO-4217, amount as a decimal string, unitOfMeasure POUNDS | OUNCES | GRAMS | KILOGRAMS for items priced by weight}) required — Amazon rejects the file without it; acknowledge at a CORRECTED cost when the PO price is wrong; listPrice (Money), discountMultiplier (decimal string), itemAcknowledgements required: [{acknowledgementCode Accepted | Backordered | Rejected, acknowledgedQuantity {amount, unitOfMeasure, unitSize}, scheduledShipDate, scheduledDeliveryDate (ISO-8601), rejectionReason (required when Rejected: TemporarilyUnavailable | InvalidProductIdentifier | ObsoleteProduct)}]}]. Split a line across codes with several itemAcknowledgements whose amounts sum to orderedQuantity. Full tree: https://developer-docs.amazon.com/sp-api/docs/vendor-orders-api-v1-reference"}},"required":["store","acknowledgement_payload"],"title":"vendorOrders_submitAcknowledgementArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"transactionId":{"description":"the Amazon transaction, already final when this returns."},"status":{"description":"SUCCESS, or Failure with data.errors [{code, message, details}]."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorOrders_getPurchaseOrdersStatus":{"post":{"operationId":"vendorOrders_getPurchaseOrdersStatus","summary":"Get purchase order status list.","description":"Get purchase order status list. Date range must not exceed 7 days. Amazon SP-API · getPurchaseOrdersStatus · GET /vendor/orders/v1/purchaseOrdersStatus Useful for monitoring whether Amazon has received and accepted acknowledgements, or to check delivery/receipt status of fulfilment.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorOrders_getPurchaseOrdersStatus"},"tags":["amazon_sp"],"x-title":"Vendor Orders Get Purchase Orders Status","x-access":"read","x-family":"sp.vendorOrders","x-returns":[{"field":"data.ordersStatus","description":"list of PO status dicts."},{"field":"data.count","description":"number of statuses returned."},{"field":"data.nextToken","description":"pass to next call if present."}],"x-notes":{"Workflow":["1. Call with updated_after/updated_before to find recently changed POs.","2. Narrow with purchase_order_status, item_confirmation_status or item_receive_status.","3. While data.nextToken is present, call again with it as next_token."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"created_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created After","description":"ISO 8601 bounds on when the PO became available (window ≤ 7 days)."},"created_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created Before","description":"ISO 8601 bounds on when the PO became available (window ≤ 7 days)."},"updated_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Updated After","description":"ISO 8601 — POs updated after this."},"updated_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Updated Before","description":"ISO 8601 — POs updated before this."},"purchase_order_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Purchase Order Number","description":"Filter to a single PO number."},"purchase_order_status":{"anyOf":[{"enum":["OPEN","CLOSED"],"type":"string"},{"type":"null"}],"default":null,"title":"Purchase Order Status","description":"keeps only POs in this status. Allowed: OPEN | CLOSED."},"item_confirmation_status":{"anyOf":[{"enum":["ACCEPTED","PARTIALLY_ACCEPTED","REJECTED","UNCONFIRMED"],"type":"string"},{"type":"null"}],"default":null,"title":"Item Confirmation Status","description":"keeps only POs with items in this confirmation state. Allowed: ACCEPTED | PARTIALLY_ACCEPTED | REJECTED | UNCONFIRMED."},"item_receive_status":{"anyOf":[{"enum":["NOT_RECEIVED","PARTIALLY_RECEIVED","RECEIVED"],"type":"string"},{"type":"null"}],"default":null,"title":"Item Receive Status","description":"keeps only POs with items in this receive state. Allowed: NOT_RECEIVED | PARTIALLY_RECEIVED | RECEIVED."},"ordering_vendor_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ordering Vendor Code","description":"Filter by vendor code."},"ship_to_party_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ship To Party Id","description":"Filter by fulfilment centre ID."},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Limit","description":"Max records returned, 1–100 (Amazon default 100)."},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"title":"Sort Order","description":"ASC or DESC."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"vendorOrders_getPurchaseOrdersStatusArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"ordersStatus":{"description":"list of PO status dicts."},"count":{"description":"number of statuses returned."},"nextToken":{"description":"pass to next call if present."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorShipments_SubmitShipmentConfirmations":{"post":{"operationId":"vendorShipments_SubmitShipmentConfirmations","summary":"Confirm vendor shipments AFTER dispatch (the advance notice before dispatch is vendorShipments_SubmitShipments).","description":"Confirm vendor shipments AFTER dispatch (the advance notice before dispatch is vendorShipments_SubmitShipments). One or many confirmations per call. Amazon write; blocks until the transaction reaches Success or Failure. Amazon SP-API · SubmitShipmentConfirmations · POST /vendor/shipping/v1/shipmentConfirmations Amazon SP-API · getTransaction · GET /vendor/transactions/v1/transactions/{transactionId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorShipments_SubmitShipmentConfirmations"},"tags":["amazon_sp"],"x-title":"Vendor Shipments Submit Shipment Confirmations","x-access":"destructive","x-family":"sp.vendorShipments","x-returns":[{"field":"data.transactionId","description":"the transaction, already final when this returns."},{"field":"data.status","description":"SUCCESS, or Failure with data.errors [{code, message, details}]."}],"x-notes":{"Body (Amazon schema; SubmitShipmentConfirmations): {shipmentConfirmations: [ShipmentConfirmation]}, each item":["shipmentIdentifier*: string","shipmentConfirmationType*: Original | Replace","shipmentConfirmationDate*: string (date-time)","sellingParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}","shipFromParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}","shipToParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}","shippedItems*: [{itemSequenceNumber*, amazonProductIdentifier, vendorProductIdentifier, shippedQuantity*: {amount*, unitOfMeasure*, unitSize, totalWeight}, itemDetails: {purchaseOrderNumber, lotNumber, lotNumberSourceReference, lotNumberSourceType, countryOfOrigin, regulationReferences, expiry, maximumRetailPrice, handlingCode}}]","shipmentType: TruckLoad | LessThanTruckLoad | SmallParcel","shipmentStructure: PalletizedAssortmentCase | LooseAssortmentCase | PalletOfItems | PalletizedStandardCase | LooseStandardCase | MasterPallet | MasterCase","+ 8 more: transportationDetails, amazonReferenceNumber, shippedDate, estimatedDeliveryDate,","  shipmentMeasurements, importDetails, cartons, pallets","Full schema: the Docs link above."],"Gotchas":["HTTP 502 = still Processing after 60 s; the error names the transactionId — check it","with vendorTransactionStatus_getTransaction before resubmitting."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"confirmations_payload":{"additionalProperties":true,"title":"Confirmations Payload","type":"object","description":"{\"shipmentConfirmations\": [Confirmation, …]}. Per Confirmation, required: shipmentIdentifier (unique, unused in the last 365 days), shipmentConfirmationType (Original | Replace), shipmentConfirmationDate (ISO-8601), sellingParty, shipFromParty and shipToParty (each {partyId, address}), shippedItems: [{itemSequenceNumber ('001', '002', …), amazonProductIdentifier (ASIN) or vendorProductIdentifier, shippedQuantity {amount, unitOfMeasure Cases | Eaches, unitSize, totalWeight {unitOfMeasure POUNDS | OUNCES | GRAMS | KILOGRAMS, amount}}, itemDetails {purchaseOrderNumber, lotNumber, lotNumberSourceReference, lotNumberSourceType GLN | FFRN | USDA_E | URL, countryOfOrigin (2-letter), regulationReferences (EUDR: dueDiligenceReference, dueDiligenceVerification, dueDiligenceInformation, dueDiligenceExemptionCode), expiry {manufacturerDate, expiryDate, expiryAfterDuration}, maximumRetailPrice {currencyCode, amount}, handlingCode Oversized | Fragile | Food | HandleWithCare}}]. Optional: shippedDate and estimatedDeliveryDate (ISO-8601); shipmentType and shipmentStructure (values in the Body block); transportationDetails {carrierScac, carrierShipmentReferenceNumber, transportationMode Road | Air | Ocean, billOfLadingNumber}; shipmentMeasurements {grossShipmentWeight {unitOfMeasure G | Kg | Oz | Lb, value}, shipmentVolume {unitOfMeasure CuFt | CuIn | CuM | CuY, value}, cartonCount, palletCount}; importDetails {methodOfPayment PaidByBuyer | CollectOnDelivery | DefinedByBuyerAndSeller | FOBPortOfCall | PrepaidBySeller | PaidBySeller, handlingInstructions Oversized | Fragile | Food | HandleWithCare, route, billableWeight}; cartons (a SmallParcel shipment, one entry per carton): [{cartonSequenceNumber ('001', … — pallets reference cartons by it), cartonIdentifiers: [{containerIdentificationType SSCC | AMZNCC | GTIN | BPS | CID, containerIdentificationNumber}], trackingNumber (Amazon requires one per carton), dimensions {length, width, height, unitOfMeasure In | Ft | Meter | Yard}, weight {unitOfMeasure G | Kg | Oz | Lb, value}, items: [{itemReference (the itemSequenceNumber from shippedItems), shippedQuantity {amount, unitOfMeasure, unitSize}, itemDetails}] required}]; pallets (a palletized shipment): [{palletIdentifiers: [{containerIdentificationType, containerIdentificationNumber}] required, tier (layers per pallet), block (cartons per layer), dimensions, weight, cartonReferenceDetails {cartonCount (mandatory for a single-item pallet), cartonReferenceNumbers — the cartonSequenceNumbers on this pallet}, items}]. Full tree: https://developer-docs.amazon.com/sp-api/docs/vendor-shipments-api-v1-reference"}},"required":["store","confirmations_payload"],"title":"vendorShipments_SubmitShipmentConfirmationsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"transactionId":{"description":"the transaction, already final when this returns."},"status":{"description":"SUCCESS, or Failure with data.errors [{code, message, details}]."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorShipments_SubmitShipments":{"post":{"operationId":"vendorShipments_SubmitShipments","summary":"Submit vendor shipment requests — the advance shipment notice, BEFORE goods ship (after dispatch use vendorShipments_SubmitShipmentConfirmations).","description":"Submit vendor shipment requests — the advance shipment notice, BEFORE goods ship (after dispatch use vendorShipments_SubmitShipmentConfirmations). Amazon write; blocks until the transaction reaches Success or Failure. Amazon SP-API · SubmitShipments · POST /vendor/shipping/v1/shipments Amazon SP-API · getTransaction · GET /vendor/transactions/v1/transactions/{transactionId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorShipments_SubmitShipments"},"tags":["amazon_sp"],"x-title":"Vendor Shipments Submit Shipments","x-access":"destructive","x-family":"sp.vendorShipments","x-returns":[{"field":"data.transactionId","description":"the transaction, already final when this returns."},{"field":"data.status","description":"SUCCESS, or Failure with data.errors [{code, message, details}]."}],"x-notes":{"Body (Amazon schema; SubmitShipments): {shipments: [Shipment]}, each item":["vendorShipmentIdentifier*: string","transactionType*: New | Cancel","transactionDate*: string (date-time)","sellingParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}","shipFromParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}","shipToParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}","currentShipmentStatus: Created | TransportationRequested | CarrierAssigned | Shipped","shipmentFreightTerm: Collect | Prepaid","+ 12 more: buyerReferenceNumber, currentshipmentStatusDate, shipmentStatusDetails, shipmentCreateDate,","  shipmentConfirmDate, packageLabelCreateDate, shipmentMeasurements, collectFreightPickupDetails,","  purchaseOrders, importDetails, containers, transportationDetails","Full schema: the Docs link above."],"Gotchas":["A Shipment has NO top-level items array — line items live under","purchaseOrders[].items. The item identifier here is buyerProductIdentifier, not","amazonProductIdentifier (that name belongs to the shippedItems of","vendorShipments_SubmitShipmentConfirmations).","HTTP 502 = still Processing after 60 s; the error names the transactionId — check it","with vendorTransactionStatus_getTransaction before resubmitting."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"shipments_payload":{"additionalProperties":true,"title":"Shipments Payload","type":"object","description":"{\"shipments\": [Shipment, …]}. Per Shipment, required: vendorShipmentIdentifier (unique, unused in the last 365 days), transactionType (New | Cancel), transactionDate (ISO-8601), sellingParty, shipFromParty and shipToParty — each a Party (partyId, address, taxRegistrationDetails; full shape in the Body block below). Optional: buyerReferenceNumber; currentShipmentStatus (Created | TransportationRequested | CarrierAssigned | Shipped); shipmentFreightTerm (Collect | Prepaid); shipmentMeasurements {totalCartonCount, totalPalletStackable, totalPalletNonStackable, shipmentWeight {unitOfMeasure G | Kg | Oz | Lb, value}, shipmentVolume {unitOfMeasure CuFt | CuIn | CuM | CuY, value}}; collectFreightPickupDetails {requestedPickUp, scheduledPickUp, carrierAssignmentDate}; purchaseOrders: [{purchaseOrderNumber, purchaseOrderDate, shipWindow, items: [{itemSequenceNumber ('001', '002', …) required, buyerProductIdentifier (ASIN) or vendorProductIdentifier, shippedQuantity {amount, unitOfMeasure Cases | Eaches, unitSize, totalWeight {unitOfMeasure POUNDS | OUNCES | GRAMS | KILOGRAMS, amount}} required, maximumRetailPrice {currencyCode, amount}}]}]; containers: [{containerType carton | pallet, containerSequenceNumber, containerIdentifiers: [{containerIdentificationType SSCC | AMZNCC | GTIN | BPS | CID, containerIdentificationNumber}] required, trackingNumber, dimensions {length, width, height, unitOfMeasure In | Ft | Meter | Yard}, weight {unitOfMeasure G | Kg | Oz | Lb, value}, tier, block, innerContainersDetails, packedItems: [{itemSequenceNumber, buyerProductIdentifier or vendorProductIdentifier, packedQuantity {amount, unitOfMeasure Cases | Eaches, unitSize}, itemDetails {purchaseOrderNumber, lotNumber, expiry}}]}]; importDetails {methodOfPayment PaidByBuyer | CollectOnDelivery | DefinedByBuyerAndSeller | FOBPortOfCall | PrepaidBySeller | PaidBySeller, sealNumber, route {stops: [{functionCode PortOfDischarge | FreightPayableAt | PortOfLoading, locationIdentification, arrivalTime, departureTime}]}, importContainers (≤64 chars), billableWeight, estimatedShipByDate, handlingInstructions Oversized | Fragile | Food | HandleWithCare}; transportationDetails {shipMode TruckLoad | LessThanTruckLoad | SmallParcel, transportationMode Road | Air | Ocean, shippedDate, estimatedDeliveryDate, shipmentDeliveryDate, carrierDetails {name, code (SCAC), phone, email, shipmentReferenceNumber}, billOfLadingNumber}; shipmentStatusDetails: [{shipmentStatus Created | TransportationRequested | CarrierAssigned | Shipped, shipmentStatusDate}]; shipmentCreateDate, shipmentConfirmDate, packageLabelCreateDate (ISO-8601). Full tree: https://developer-docs.amazon.com/sp-api/docs/vendor-shipments-api-v1-reference"}},"required":["store","shipments_payload"],"title":"vendorShipments_SubmitShipmentsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"transactionId":{"description":"the transaction, already final when this returns."},"status":{"description":"SUCCESS, or Failure with data.errors [{code, message, details}]."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorShipments_GetShipmentDetails":{"post":{"operationId":"vendorShipments_GetShipmentDetails","summary":"Get shipment details from Amazon with date and status filters.","description":"Get shipment details from Amazon with date and status filters. Amazon SP-API · GetShipmentDetails · GET /vendor/shipping/v1/shipments","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorShipments_GetShipmentDetails"},"tags":["amazon_sp"],"x-title":"Vendor Shipments Get Shipment Details","x-access":"read","x-family":"sp.vendorShipments","x-returns":[{"field":"data.shipments","description":"list of shipment detail dicts."},{"field":"data.count","description":"number of shipments returned."},{"field":"data.nextToken","description":"pass to next call if present."}],"x-notes":{"Workflow":["1. Call with created_after/created_before to fetch recent shipments.","2. Narrow by a date pair (shipped_*, shipment_confirmed_*, estimated_delivery_*,","   shipment_delivery_*, requested_pick_up_*, scheduled_pick_up_*) or an identifier","   (vendor_shipment_identifier, buyer_reference_number, buyer_warehouse_code,","   seller_warehouse_code).","3. While data.nextToken is present, call again with it as next_token."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"created_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created After","description":"ISO 8601 — shipment record created after."},"created_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created Before","description":"ISO 8601 — shipment record created before."},"shipment_confirmed_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Shipment Confirmed Before","description":"ISO 8601 — confirmed date upper bound."},"shipment_confirmed_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Shipment Confirmed After","description":"ISO 8601 — confirmed date lower bound."},"package_label_created_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Package Label Created Before","description":"ISO 8601 — buyer label creation date upper bound."},"package_label_created_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Package Label Created After","description":"ISO 8601 — buyer label creation date lower bound."},"shipped_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Shipped Before","description":"ISO 8601 — shipped date upper bound."},"shipped_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Shipped After","description":"ISO 8601 — shipped date lower bound."},"estimated_delivery_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Estimated Delivery Before","description":"ISO 8601 — estimated delivery upper bound."},"estimated_delivery_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Estimated Delivery After","description":"ISO 8601 — estimated delivery lower bound."},"shipment_delivery_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Shipment Delivery Before","description":"ISO 8601 — actual delivery upper bound."},"shipment_delivery_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Shipment Delivery After","description":"ISO 8601 — actual delivery lower bound."},"requested_pick_up_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Requested Pick Up Before","description":"ISO 8601 — requested pick-up upper bound."},"requested_pick_up_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Requested Pick Up After","description":"ISO 8601 — requested pick-up lower bound."},"scheduled_pick_up_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Scheduled Pick Up Before","description":"ISO 8601 — scheduled pick-up upper bound."},"scheduled_pick_up_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Scheduled Pick Up After","description":"ISO 8601 — scheduled pick-up lower bound."},"current_shipment_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Current Shipment Status","description":"filter by shipment status. Allowed: Created | TransportationRequested | CarrierAssigned | Shipped."},"vendor_shipment_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Vendor Shipment Identifier","description":"Filter by vendor's own shipment ID."},"buyer_reference_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Buyer Reference Number","description":"Filter by Amazon buyer reference number."},"buyer_warehouse_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Buyer Warehouse Code","description":"shipToParty.partyId value from the shipment."},"seller_warehouse_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Warehouse Code","description":"sellingParty.partyId value from the shipment."},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Limit","description":"Max records returned, 1–50 (Amazon default 50)."},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"title":"Sort Order","description":"ASC or DESC."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"vendorShipments_GetShipmentDetailsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"shipments":{"description":"list of shipment detail dicts."},"count":{"description":"number of shipments returned."},"nextToken":{"description":"pass to next call if present."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorShipments_GetShipmentLabels":{"post":{"operationId":"vendorShipments_GetShipmentLabels","summary":"Get small parcel transport labels from Amazon.","description":"Get small parcel transport labels from Amazon. Amazon SP-API · GetShipmentLabels · GET /vendor/shipping/v1/transportLabels","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorShipments_GetShipmentLabels"},"tags":["amazon_sp"],"x-title":"Vendor Shipments Get Shipment Labels","x-access":"read","x-family":"sp.vendorShipments","x-returns":[{"field":"data.transportLabels[]","description":"labelData[] {labelSequenceNumber, trackingId, carrierCode, labelFormat PDF, label (the base-64 PDF)} and shipmentInformation {buyerReferenceNumber, totalLabelCount, shipMode}."},{"field":"data.count","description":"number of labels returned."},{"field":"data.nextToken","description":"pass to next call if present."}],"x-notes":{"Workflow":["1. Call with label_created_after/label_created_before, or buyer_reference_number /","   vendor_shipment_identifier.","2. While data.nextToken is present, call again with it as next_token."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"label_created_after":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Label Created After","description":"ISO 8601 — labels created after this."},"label_created_before":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Label Created Before","description":"ISO 8601 — labels created before this."},"buyer_reference_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Buyer Reference Number","description":"Filter by buyer reference number."},"vendor_shipment_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Vendor Shipment Identifier","description":"Filter by vendor shipment ID."},"seller_warehouse_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Seller Warehouse Code","description":"Filter by vendor warehouse (sellingParty.partyId)."},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Limit","description":"Max records returned, 1–50 (Amazon default 50)."},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"title":"Sort Order","description":"ASC or DESC."},"next_token":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Token","description":"the cursor from the previous call's data.nextToken; omit for the first page."}},"required":["store"],"title":"vendorShipments_GetShipmentLabelsArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"transportLabels":{"description":"labelData[] {labelSequenceNumber, trackingId, carrierCode, labelFormat PDF, label (the base-64 PDF)} and shipmentInformation {buyerReferenceNumber, totalLabelCount, shipMode}."},"count":{"description":"number of labels returned."},"nextToken":{"description":"pass to next call if present."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/vendorTransactionStatus_getTransaction":{"post":{"operationId":"vendorTransactionStatus_getTransaction","summary":"Read the status of a vendor retail transaction (an invoice, acknowledgement or shipment submit).","description":"Read the status of a vendor retail transaction (an invoice, acknowledgement or shipment submit). The submit tools already wait for Success or Failure, so call this after a submit answered HTTP 502 (still Processing after 60 s; the error names the id) or for a transactionId from elsewhere. Amazon SP-API · getTransaction · GET /vendor/transactions/v1/transactions/{transactionId}","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/vendorTransactionStatus_getTransaction"},"tags":["amazon_sp"],"x-title":"Vendor Transaction Status Get Transaction","x-access":"read","x-family":"sp.vendorTransactionStatus","x-returns":[{"field":"data.status","description":"Amazon enum — 'Success', 'Failure', or 'Processing' (mirrors transactionStatus.status from data.raw)."},{"field":"data.errors","description":"list of error dicts (code, message, details) if 'Failure' (may be empty)."},{"field":"data.transactionId","description":"same as input."},{"field":"data.raw","description":"full Amazon transactionStatus payload."}],"x-notes":{"Workflow":["1. Pass the transactionId.","2. If status is 'Processing', wait 30–60 seconds and poll again.","3. On 'Failure': check data.errors for error codes and messages. Correct the submission","   payload and resubmit."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store":{"title":"Store","type":"string","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim."},"transaction_id":{"title":"Transaction Id","type":"string","description":"the transactionId (GUID) a vendor submit returned or named in its 502 error."}},"required":["store","transaction_id"],"title":"vendorTransactionStatus_getTransactionArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success","info","warning","error"]}}},"data":{"type":"object","properties":{"status":{"description":"Amazon enum — 'Success', 'Failure', or 'Processing' (mirrors transactionStatus.status from data.raw)."},"errors":{"description":"list of error dicts (code, message, details) if 'Failure' (may be empty)."},"transactionId":{"description":"same as input."},"raw":{"description":"full Amazon transactionStatus payload."}}},"human_action":{"type":"string"}},"required":["notification","data"]}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/credits_quote":{"post":{"operationId":"credits_quote","summary":"Price ONE paid action for this user, on their model route, before spending — quote data.credits to the user, never a number from memory.","description":"Price ONE paid action for this user, on their model route, before spending — quote data.credits to the user, never a number from memory. If data.sufficient is false, tell the user to top up at get_user_context's data.credits.topup_url (amounts in data.credits.rates.topup_usd). The route itself is changed only by the user, in the Dashboard credits card.","externalDocs":{"description":"Reference page","url":"https://api.sellersheetai.com/api/v1/docs/credits_quote"},"tags":["sellersheet"],"x-title":"Credits Quote","x-access":"read","x-family":null,"x-returns":[{"field":"data.credits","description":"what this user pays for the action — show this; the hold takes exactly this."},{"field":"data.sufficient / data.balance","description":"whether the balance covers it."},{"field":"data.meter","description":"the meter priced ('image' resolves to image.1k / image.2k)."},{"field":"data.route / data.multiplier / data.official_credits","description":"their route and its price against Official."}],"x-notes":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"meter":{"title":"Meter","type":"string","description":"'image' (generate_image / edit_image; size picks the band) | 'image.1k' | 'image.2k' | 'copy' (listing copy, per language) | 'text' (reverse_prompt, small text calls) | 'insights' (customerFeedback_insights_report)."},"units":{"default":1,"title":"Units","type":"integer","description":"how many images / reports / calls this action makes, 1–50. Default 1."},"languages":{"default":1,"title":"Languages","type":"integer","description":"for meter='copy', how many languages one call covers, 1–16."},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Size","description":"for meter='image', the requested canvas ('1024x1024', '1536x1024', '2K', 'auto'). Decides the image band (up to 1024 px on the longer side, or above)."},"both":{"default":false,"title":"Both","type":"boolean","description":"for meter='image', provider='both' renders twice — doubles it."},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Provider","description":"for meter='image', the provider the image call will use ('openai' | 'nanobanana' | 'both'). 'nanobanana' renders its ~1K canvas whatever size is asked, so it prices the 1K band; omit and the requested size is priced."},"store":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Store","description":"the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. Optional: pass the store the action will name — its organization pays, at its route, so the quote equals the charge; omit for an action that names no store."}},"required":["meter"],"title":"credits_quoteArguments","type":"object"}}}},"responses":{"200":{"description":"The call ran; the envelope says what happened","content":{"application/json":{"schema":{"type":"object","required":["notification","data"],"properties":{"notification":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["success"]}}},"data":{"type":"object","properties":{"content":{"type":"array","description":"the MCP content blocks the tool answers with (text, image)","items":{"type":"object","properties":{"type":{"type":"string"}}}}}},"human_action":{"type":"string"}}}}}},"4XX":{"description":"The call was not carried out (input, key, scope, credits, a plan window) — see the guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Amazon, noon or the backend could not answer — retry after Retry-After (503, never 502: the public edge replaces a 502 body with its own page)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}