{"openapi":"3.1.0","info":{"title":"Returns Intelligence API","version":"2026-07-05","summary":"Tenant-scoped returns intelligence and margin-recovery API for ecommerce operators.","description":"Paid server-to-server API for entitled tenant workspaces. All endpoints require bearer-token authentication, enforce token scopes, re-check active billing plus the api_access entitlement, and return no-store responses. CSV export also requires data_export. Public developer docs are available at /developers/api and the hosted OpenAPI contract is available at /developers/openapi.json."},"servers":[{"url":"https://app.returnsintel.com","description":"Production app API host"}],"security":[{"TenantApiToken":[]}],"paths":{"/api/v1/alerts":{"get":{"operationId":"listAlerts","summary":"Workspace alert and notification feed","description":"Pull-based feed of workspace notifications (return-rate watchlist alerts, backfill completions, connection staleness, report-ready events). Poll with since (ISO 8601 floor) or follow meta.next_cursor for keyset pagination. Only workspace-wide broadcasts are returned; user-targeted notifications are not exposed. Required scope: read:alerts. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"parameters":[{"name":"since","in":"query","required":false,"description":"ISO 8601 timestamp floor.","schema":{"type":"string","format":"date-time"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Workspace notification rows, newest first.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/TenantDataNotReady"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"read:alerts","x-required-entitlements":["api_access"]}},"/api/v1/entities":{"get":{"operationId":"listReturnsEntities","summary":"Discover customer-safe entity selectors","description":"Returns tenant-scoped SKU, product, and product-group selectors that can be passed to summary, report, timeseries, leaderboard, and export endpoints. Without q the endpoint enumerates the full catalog with cursor pagination (follow meta.next_cursor until null); with q it returns ranked search matches without pagination. limit accepts 1-100. Required scope: read:dashboard. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"parameters":[{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/EntityType"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Vendor"}],"responses":{"200":{"description":"Tenant-scoped selector discovery rows.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitiesResponse"},"examples":{"sku":{"summary":"SKU selector result","value":{"data":[{"type":"sku","label":"TSH-100-BLK-M","subtitle":"Essential Tee · Black / M","product_gid":"gid://shopify/Product/123","sku":"TSH-100-BLK-M","product_title":"Essential Tee","vendor":"Demo Apparel","product_group_type":null,"product_group_key":null,"selector":{"sku":"TSH-100-BLK-M"}}],"meta":{"api_version":"2026-07-05","organization_id":"org_alpha","shop_id":"shop_alpha","shop_domain":"alpha.myshopify.com","query":"essential","limit":10,"returned":1,"type":"sku","vendor":null,"next_cursor":null,"freshness":{"data_updated_at":"2026-07-04T11:32:08.000Z","sources":[{"source":"shopify","last_synced_at":"2026-07-04T11:32:08.000Z","status":"succeeded","stale":false}]}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/TenantDataNotReady"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"read:dashboard","x-required-entitlements":["api_access"]}},"/api/v1/export/report.csv":{"get":{"operationId":"exportReturnsReportCsv","summary":"Export a machine-oriented returns report CSV","description":"Exports tenant-scoped summary, trend, return reason, refunded amount, timing, label cost, and lifecycle coverage rows. Unknown report-state query values are normalized to dashboard defaults.\n\nRequired scope: read:exports. Required entitlements: api_access and data_export.","security":[{"TenantApiToken":[]}],"parameters":[{"$ref":"#/components/parameters/Sku"},{"$ref":"#/components/parameters/ProductGid"},{"$ref":"#/components/parameters/ShopifyProductGid"},{"$ref":"#/components/parameters/ProductGroupType"},{"$ref":"#/components/parameters/ProductGroupKey"},{"$ref":"#/components/parameters/StartMonth"},{"$ref":"#/components/parameters/EndMonth"},{"$ref":"#/components/parameters/Window"},{"$ref":"#/components/parameters/IncludeIncomplete"},{"$ref":"#/components/parameters/IncludeUsedVariants"},{"$ref":"#/components/parameters/SaleEvent"},{"$ref":"#/components/parameters/SaleEventBaseline"},{"$ref":"#/components/parameters/SaleEventScope"}],"responses":{"200":{"description":"CSV export.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"Content-Disposition":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/TenantDataNotReady"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"read:exports","x-required-entitlement":"data_export","x-required-entitlements":["api_access","data_export"]}},"/api/v1/leaderboards/return-cost":{"get":{"operationId":"getReturnCostLeaderboard","summary":"SKUs ranked by returns cost","description":"SKUs costing the most in returns over a cohort month range: canonical returns cost (tax-excluded refund subtotal plus return-label spend when the tenant's label-cost source is usable), same basis as the dashboard Overview hero. Server-side filters: min_cost, vendor. Required scope: read:dashboard. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"parameters":[{"$ref":"#/components/parameters/StartMonth"},{"$ref":"#/components/parameters/EndMonth"},{"$ref":"#/components/parameters/Window"},{"$ref":"#/components/parameters/IncludeIncomplete"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"min_cost","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"$ref":"#/components/parameters/Vendor"}],"responses":{"200":{"description":"Ranked return-cost leaderboard rows.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCostLeaderboardRow"}},"currency_code":{"type":"string"},"total_eligible_count":{"type":"integer"},"label_costs_included":{"type":"boolean"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/TenantDataNotReady"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"read:dashboard","x-required-entitlements":["api_access"]}},"/api/v1/leaderboards/return-rate":{"get":{"operationId":"getReturnRateLeaderboard","summary":"SKUs ranked by highest return rate","description":"The workspace's worst performers by return rate over a trailing month or year, honoring the workspace minimum-sold-units threshold. Server-side filters (min_return_rate as a 0-1 fraction, min_sold_units, vendor) subset the ranked rows. Plans without the full_leaderboards entitlement are clamped to the visible card size. Required scope: read:dashboard. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["month","year"],"default":"year"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"min_return_rate","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":1}},{"name":"min_sold_units","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"$ref":"#/components/parameters/Vendor"}],"responses":{"200":{"description":"Ranked return-rate leaderboard rows.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ReturnRateLeaderboardRow"}},"total_eligible_count":{"type":"integer"},"min_sold_units":{"type":"integer"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/TenantDataNotReady"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"read:dashboard","x-required-entitlements":["api_access"]}},"/api/v1/mcp":{"post":{"operationId":"mcpServer","summary":"MCP server (Model Context Protocol over streamable HTTP)","description":"Stateless MCP server wrapping the v1 endpoints as tools (list_entities, get_summary, get_report, get_timeseries, get_return_rate_leaderboard, get_return_cost_leaderboard, list_alerts) so AI agents can query the workspace directly. JSON-RPC 2.0 over POST; supports initialize, ping, tools/list, and tools/call; no SSE stream or sessions. Authentication is the same bearer token as the REST API, and each tools/call enforces the wrapped endpoint's scope and daily quota. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A single JSON-RPC 2.0 request (batches are not supported).","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Notification acknowledged (no body)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-required-entitlements":["api_access"]}},"/api/v1/report":{"get":{"operationId":"getReturnsReport","summary":"Get a deep returns report","description":"Returns the tenant-scoped report view model used by the authenticated dashboard. Unknown report-state query values are normalized to dashboard defaults.\n\nRequired scope: read:reports. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"parameters":[{"$ref":"#/components/parameters/Sku"},{"$ref":"#/components/parameters/ProductGid"},{"$ref":"#/components/parameters/ShopifyProductGid"},{"$ref":"#/components/parameters/ProductGroupType"},{"$ref":"#/components/parameters/ProductGroupKey"},{"$ref":"#/components/parameters/StartMonth"},{"$ref":"#/components/parameters/EndMonth"},{"$ref":"#/components/parameters/Window"},{"$ref":"#/components/parameters/IncludeIncomplete"},{"$ref":"#/components/parameters/IncludeUsedVariants"},{"$ref":"#/components/parameters/ReportSection"},{"$ref":"#/components/parameters/SaleEvent"},{"$ref":"#/components/parameters/SaleEventBaseline"},{"$ref":"#/components/parameters/SaleEventScope"}],"responses":{"200":{"description":"Tenant-scoped report view model.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/TenantDataNotReady"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"read:reports","x-required-entitlements":["api_access"]}},"/api/v1/summary":{"get":{"operationId":"getReturnsSummary","summary":"Get a cohort return-rate summary","description":"Returns tenant-scoped summary metrics for one SKU, product, or product group.\n\nRequired scope: read:dashboard. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"parameters":[{"$ref":"#/components/parameters/Sku"},{"$ref":"#/components/parameters/ProductGid"},{"$ref":"#/components/parameters/ShopifyProductGid"},{"$ref":"#/components/parameters/ProductGroupType"},{"$ref":"#/components/parameters/ProductGroupKey"},{"$ref":"#/components/parameters/StartMonth"},{"$ref":"#/components/parameters/EndMonth"},{"$ref":"#/components/parameters/Window"},{"$ref":"#/components/parameters/IncludeIncomplete"},{"$ref":"#/components/parameters/IncludeUsedVariants"}],"responses":{"200":{"description":"Tenant-scoped summary metrics.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryResponse"},"examples":{"summary":{"summary":"Primary-window SKU return rate","value":{"data":{"sold_units":10,"returned_units":2,"return_rate":0.2},"meta":{"api_version":"2026-07-05","organization_id":"org_alpha","shop_id":"shop_alpha","shop_domain":"alpha.myshopify.com","selector":{"type":"sku","primarySku":"TSH-100-BLK-M","skus":["TSH-100-BLK-M"]},"start_month":"2026-01","end_month":"2026-03","window":"primary","include_incomplete":false}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/TenantDataNotReady"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"read:dashboard","x-required-entitlements":["api_access"]}},"/api/v1/timeseries":{"get":{"operationId":"getReturnsTimeseries","summary":"Monthly return-rate time series for one entity","description":"Monthly order-cohort series (sold units, returned units, return rate for the selected maturity window) for one SKU, product, or product group — the multi-month answer that would otherwise take one /summary call per month. Required scope: read:reports. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"parameters":[{"$ref":"#/components/parameters/Sku"},{"$ref":"#/components/parameters/ProductGid"},{"$ref":"#/components/parameters/ShopifyProductGid"},{"$ref":"#/components/parameters/ProductGroupType"},{"$ref":"#/components/parameters/ProductGroupKey"},{"$ref":"#/components/parameters/StartMonth"},{"$ref":"#/components/parameters/EndMonth"},{"$ref":"#/components/parameters/Window"},{"$ref":"#/components/parameters/IncludeIncomplete"}],"responses":{"200":{"description":"Monthly return-rate series rows.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/TimeseriesRow"}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/TenantDataNotReady"},"429":{"$ref":"#/components/responses/QuotaExceeded"},"500":{"$ref":"#/components/responses/ServerError"}},"x-required-scope":"read:reports","x-required-entitlements":["api_access"]}}},"components":{"securitySchemes":{"TenantApiToken":{"type":"http","scheme":"bearer","description":"Tenant API token created in workspace settings."}},"headers":{"X-Returns-API-Version":{"description":"Stable API contract version used by the response.","schema":{"type":"string","const":"2026-07-05"}},"RateLimitLimit":{"description":"Daily request limit for finite-plan tenants. Present on successful responses, quota rejections, and post-auth handler/validation errors after quota has been checked.","schema":{"type":"integer","minimum":0}},"RateLimitRemaining":{"description":"Requests remaining in the current UTC daily window.","schema":{"type":"integer","minimum":0}},"RateLimitReset":{"description":"UTC timestamp when the current daily quota window resets.","schema":{"type":"string","format":"date-time"}},"Cache-Control":{"description":"Responses are private and not cacheable by browsers or shared caches.","schema":{"type":"string","const":"private, no-store, no-cache, max-age=0, must-revalidate"}},"CDN-Cache-Control":{"description":"Shared caches must not store customer API responses.","schema":{"type":"string","const":"no-store"}},"Cloudflare-CDN-Cache-Control":{"description":"Cloudflare must not store customer API responses.","schema":{"type":"string","const":"no-store"}},"X-Request-ID":{"description":"Caller-supplied or API-generated request identifier for support and troubleshooting.","schema":{"type":"string"}}},"parameters":{"Sku":{"name":"sku","in":"query","required":false,"schema":{"type":"string"},"description":"Select by canonical SKU. Use one selector family per request."},"ProductGid":{"name":"product_gid","in":"query","required":false,"schema":{"type":"string"},"description":"Preferred public alias for selecting by Shopify product GID. Use one selector family per request."},"ShopifyProductGid":{"name":"shopify_product_gid","in":"query","required":false,"schema":{"type":"string"},"description":"Compatibility alias for selecting by Shopify product GID. Prefer product_gid for new clients. Use one selector family per request."},"StartMonth":{"name":"start_month","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"description":"First order-cohort month in YYYY-MM format."},"EndMonth":{"name":"end_month","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"description":"Last order-cohort month in YYYY-MM format."},"Window":{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["primary","30d","90d","lifetime"],"default":"primary"},"description":"Observation window for the cohort return-rate numerator. The primary enum value uses the workspace primary return window, which defaults to 30 days. The lifetime enum value is the API query value for the lifetime-to-date metric."},"IncludeIncomplete":{"name":"include_incomplete","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Intentionally include incomplete finite-window cohorts."},"IncludeUsedVariants":{"name":"include_used_variants","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Expand product selection to used variants where supported."},"ReportSection":{"name":"reportSection","in":"query","required":false,"schema":{"type":"string"},"description":"Optional dashboard report section identifier. Unknown values are normalized to the dashboard default."},"ProductGroupType":{"name":"product_group_type","in":"query","required":false,"schema":{"type":"string","enum":["family","analytics_category"]},"description":"Product-group selector type. Must be paired with product_group_key and cannot be combined with sku or product_gid."},"ProductGroupKey":{"name":"product_group_key","in":"query","required":false,"schema":{"type":"string"},"description":"Product-group selector key. Must be paired with product_group_type and cannot be combined with sku or product_gid."},"SaleEvent":{"name":"saleEvent","in":"query","required":false,"schema":{"type":"string"},"description":"Optional sale-event slug accepted by the dashboard report parser. Unknown values are ignored."},"SaleEventBaseline":{"name":"saleEventBaseline","in":"query","required":false,"schema":{"type":"string","enum":["matched_prior","selected_non_sale","prior_year"]},"description":"Optional sale-event baseline mode accepted by the dashboard report parser."},"SaleEventScope":{"name":"saleEventScope","in":"query","required":false,"schema":{"type":"string","enum":["current_selection","event_scope"]},"description":"Optional sale-event scope mode accepted by the dashboard report parser."},"Query":{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Optional search text for entity discovery."},"EntityType":{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["all","sku","product","product_group"],"default":"all"},"description":"Optional entity type filter for selector discovery."},"Limit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum rows to return, an integer from 1 to 100 (default 20). Out-of-range values return 400."},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque pagination cursor from a previous response's meta.next_cursor.","schema":{"type":"string"}},"Vendor":{"name":"vendor","in":"query","required":false,"description":"Exact vendor filter.","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"Invalid selector, date range, or window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"Unauthorized":{"description":"Missing, malformed, expired, revoked, or unknown token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}}},"Forbidden":{"description":"Missing scope, inactive billing, missing entitlement, or forbidden plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}}},"TenantDataNotReady":{"description":"The selected tenant shop is not ready for dashboard/API reads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"QuotaExceeded":{"description":"Daily API quota exceeded.","headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"Unexpected backend error. Details are logged server-side only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Cache-Control":{"$ref":"#/components/headers/Cache-Control"},"CDN-Cache-Control":{"$ref":"#/components/headers/CDN-Cache-Control"},"Cloudflare-CDN-Cache-Control":{"$ref":"#/components/headers/Cloudflare-CDN-Cache-Control"},"X-Returns-API-Version":{"$ref":"#/components/headers/X-Returns-API-Version"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}}},"schemas":{"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","enum":["unauthorized","forbidden","invalid_request","not_found","not_ready","rate_limited","internal_error"]},"message":{"type":"string","description":"Human-readable explanation; wording may change."}}}}},"ApiMeta":{"type":"object","additionalProperties":true,"required":["api_version","organization_id","shop_id","shop_domain"],"properties":{"api_version":{"type":"string","const":"2026-07-05"},"organization_id":{"type":"string"},"shop_id":{"type":["string","null"]},"shop_domain":{"type":"string"},"selector":{"type":"object","additionalProperties":true},"start_month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"end_month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"window":{"type":"string","enum":["primary","30d","90d","lifetime"]},"include_incomplete":{"type":"boolean"},"freshness":{"$ref":"#/components/schemas/Freshness"},"returned":{"type":"integer","description":"Rows returned in this response."},"next_cursor":{"type":["string","null"],"description":"Opaque pagination cursor; null when exhausted."},"vendor":{"type":["string","null"]},"query":{"type":"string"},"type":{"type":"string"},"period":{"type":"string","enum":["month","year"]},"limit":{"type":"integer"},"full_leaderboards":{"type":"boolean","description":"Whether the tenant plan may request the full leaderboard pool."},"filters":{"type":"object","description":"Echo of the server-side filters applied (leaderboards)."},"since":{"type":["string","null"],"format":"date-time"},"category":{"type":["string","null"]}}},"SummaryData":{"type":"object","additionalProperties":true,"required":["sold_units","returned_units","return_rate"],"properties":{"sold_units":{"type":"integer","minimum":0},"returned_units":{"type":"integer","minimum":0},"return_rate":{"type":"number"}}},"SummaryResponse":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SummaryData"},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ReportResponse":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":true},"meta":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","properties":{"section":{"type":"string"}}}]}}},"PublicEntitySelector":{"oneOf":[{"type":"object","additionalProperties":false,"required":["sku"],"properties":{"sku":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["product_gid"],"properties":{"product_gid":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["product_group_type","product_group_key"],"properties":{"product_group_type":{"type":"string","enum":["family","analytics_category"]},"product_group_key":{"type":"string"}}}]},"PublicEntity":{"type":"object","additionalProperties":false,"required":["type","label","subtitle","product_gid","sku","product_title","vendor","product_group_type","product_group_key","selector"],"properties":{"type":{"type":"string","enum":["sku","product","product_group"]},"label":{"type":"string"},"subtitle":{"type":["string","null"]},"product_gid":{"type":["string","null"]},"sku":{"type":["string","null"]},"product_title":{"type":["string","null"]},"vendor":{"type":["string","null"]},"product_group_type":{"type":["string","null"],"enum":["family","analytics_category",null]},"product_group_key":{"type":["string","null"]},"selector":{"$ref":"#/components/schemas/PublicEntitySelector"}}},"EntitiesMeta":{"type":"object","additionalProperties":false,"required":["api_version","organization_id","shop_id","shop_domain","query","limit","returned","type"],"properties":{"api_version":{"type":"string","const":"2026-07-05"},"organization_id":{"type":"string"},"shop_id":{"type":["string","null"]},"shop_domain":{"type":"string"},"query":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":100},"returned":{"type":"integer","minimum":0},"type":{"type":"string","enum":["all","sku","product","product_group"]},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next catalog page. Null when the listing is exhausted or when q was supplied (search results are ranked, not paginated)."},"vendor":{"type":["string","null"]},"freshness":{"$ref":"#/components/schemas/Freshness"}}},"EntitiesResponse":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicEntity"}},"meta":{"$ref":"#/components/schemas/EntitiesMeta"}}},"Freshness":{"type":["object","null"],"description":"Data-freshness metadata. Reporting facts are refreshed asynchronously; data_updated_at is the most recent successful sync across connected sources (the as-of timestamp for the numbers in the response). Null when freshness cannot be resolved.","required":["data_updated_at","sources"],"properties":{"data_updated_at":{"type":["string","null"],"format":"date-time"},"sources":{"type":"array","items":{"type":"object","required":["source","last_synced_at","status","stale"],"properties":{"source":{"type":"string"},"last_synced_at":{"type":["string","null"],"format":"date-time"},"status":{"type":["string","null"]},"stale":{"type":"boolean","description":"True when the source never synced, failed, or is more than 36 hours old."}}}}}},"ReturnRateLeaderboardRow":{"type":"object","required":["sku","sold_units","returned_units","return_rate"],"properties":{"sku":{"type":"string"},"sold_units":{"type":"integer"},"returned_units":{"type":"integer"},"return_rate":{"type":"number"},"shopify_product_gid":{"type":["string","null"]},"product_title":{"type":["string","null"]},"handle":{"type":["string","null"]},"vendor":{"type":["string","null"]},"product_image_url":{"type":["string","null"]},"product_image_alt_text":{"type":["string","null"]}}},"ReturnCostLeaderboardRow":{"type":"object","required":["sku","total_cost_amount","total_refunded_amount","total_return_label_cost","sold_units","returned_units","return_rate"],"properties":{"sku":{"type":"string"},"total_cost_amount":{"type":"number","description":"Canonical returns cost: tax-excluded merchandise refund subtotal plus (when included) return-label spend."},"total_refunded_amount":{"type":"number"},"total_return_label_cost":{"type":"number"},"refunded_units":{"type":"integer"},"sold_units":{"type":"integer"},"returned_units":{"type":"integer"},"return_rate":{"type":"number"},"estimated_margin_impact":{"type":["number","null"]},"cogs_coverage":{"type":"integer"},"shopify_product_gid":{"type":["string","null"]},"product_title":{"type":["string","null"]},"handle":{"type":["string","null"]},"vendor":{"type":["string","null"]},"product_image_url":{"type":["string","null"]},"product_image_alt_text":{"type":["string","null"]}}},"TimeseriesRow":{"type":"object","required":["cohort_month","sold_units","returned_units","return_rate"],"properties":{"cohort_month":{"type":"string","description":"Order-cohort month, YYYY-MM-01."},"sold_units":{"type":"integer"},"returned_units":{"type":"integer"},"return_rate":{"type":"number"},"is_complete":{"type":"boolean"}}},"Alert":{"type":"object","required":["id","category","severity","title","created_at"],"properties":{"id":{"type":"string"},"category":{"type":"string"},"severity":{"type":"string"},"title":{"type":"string"},"body":{"type":["string","null"]},"link_url":{"type":["string","null"]},"link_label":{"type":["string","null"]},"metadata":{"type":["object","null"]},"created_at":{"type":"string","format":"date-time"}}}}}}