Returns Intelligence

Authentication

API tokens are created in workspace settings by an owner or admin on a plan with API access. Tokens are shown once, scoped to one organization and shop, and checked on every request for billing, entitlements, token status, expiry, scope, Shopify readiness, and daily quota.

Authorization: Bearer rda_live_api_tok_...

Endpoints

GET /api/v1/entities

Find customer-safe SKU, product, and product-group selectors to use with report endpoints.

read:dashboard

GET /api/v1/summary

Return sold units, returned units, and cohort return rate for one selected entity.

read:dashboard

GET /api/v1/report

Return the expanded report view model for trends, reasons, refunds, timing, and lifecycle coverage.

read:reports

GET /api/v1/export/report.csv

Export a machine-oriented CSV with summary, trend, return reason, refund, timing, label cost, and lifecycle rows.

read:exports

Examples

Discover selectors

curl -sS "https://app.returnsintel.com/api/v1/entities?q=essential&type=sku&limit=10" \
  -H "Authorization: Bearer $RETURNS_API_TOKEN" \
  -H "X-Request-ID: ri-docs-entities-001"

Read cohort summary

curl -sS "https://app.returnsintel.com/api/v1/summary?sku=TSH-100-BLK-M&start_month=2026-01&end_month=2026-03&window=90d" \
  -H "Authorization: Bearer $RETURNS_API_TOKEN"

Download report CSV

curl -L "https://app.returnsintel.com/api/v1/export/report.csv?product_gid=gid://shopify/Product/123&start_month=2026-01&end_month=2026-03&window=lifetime" \
  -H "Authorization: Bearer $RETURNS_API_TOKEN" \
  -o returns-report.csv

Metric Contract

Return rate is cohort-based: units sold for the selected entity in an order month form the denominator, and units from that same order-month cohort classified as returned within the selected observation window form the numerator.

Supported windows are 30d, 90d, and lifetime. The default decision window is 90 days. Lifetime is lifetime-to-date and is open ended as of the response date in the reporting data.

Order-cohort months use YYYY-MM. Incomplete 30-day and 90-day cohorts are excluded unless include_incomplete=true is sent intentionally.

Freshness And Readiness

Returns Intelligence syncs tenant data through protected backend reconciliation jobs. API reads require a ready Shopify connection and ready dashboard data. A 409 response means the tenant shop is still installing, reconnecting, backfilling, or otherwise not ready for API reads; retry after the next sync or contact support with the response request id.

Responses And Errors

400

Invalid selector, date range, window, or query input.

401

Missing, malformed, expired, revoked, or unknown token.

403

Missing scope, inactive billing, or missing entitlement.

409

Tenant data is not ready for API reads.

429

Daily API quota exceeded.

500

Unexpected backend error logged server-side.

Every response includes X-Returns-API-Version and X-Request-ID. Plans with a finite daily quota also receive X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset after authentication and quota evaluation.

Security Guidance

Use tokens only from server-side systems.

Create least-privilege tokens and rotate them regularly.

Treat CSV exports as sensitive tenant analytics.

Do not use dashboard or internal routes as customer APIs.

Server-to-server returns intelligence for entitled workspaces