{"openapi":"3.1.0","info":{"title":"Returns Intelligence API","version":"2026-06-12","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/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, and export endpoints. Required scope: read:dashboard. Required entitlement: api_access.","security":[{"TenantApiToken":[]}],"parameters":[{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/EntityType"},{"$ref":"#/components/parameters/Limit"}],"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-06-12","organization_id":"org_alpha","shop_id":"shop_alpha","shop_domain":"alpha.myshopify.com","query":"essential","limit":10,"returned":1,"type":"sku"}}}}}}},"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/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":"90-day SKU return rate","value":{"data":{"sold_units":10,"returned_units":2,"return_rate":0.2},"meta":{"api_version":"2026-06-12","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":"90d","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/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/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"]}}},"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-06-12"}},"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":["30d","90d","lifetime"],"default":"90d"},"description":"Observation window for the cohort return-rate numerator. 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 30d/90d 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","mimo_class"]},"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":50,"default":20},"description":"Maximum rows to return. Values are clamped to 1-50."}},"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":"string"}}},"ApiMeta":{"type":"object","additionalProperties":true,"required":["api_version","organization_id","shop_id","shop_domain","selector","start_month","end_month","window","include_incomplete"],"properties":{"api_version":{"type":"string","const":"2026-06-12"},"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":["30d","90d","lifetime"]},"include_incomplete":{"type":"boolean"}}},"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","mimo_class"]},"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","mimo_class",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-06-12"},"organization_id":{"type":"string"},"shop_id":{"type":["string","null"]},"shop_domain":{"type":"string"},"query":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":50},"returned":{"type":"integer","minimum":0},"type":{"type":"string","enum":["all","sku","product","product_group"]}}},"EntitiesResponse":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicEntity"}},"meta":{"$ref":"#/components/schemas/EntitiesMeta"}}}}}}