Technical project case study
A returns application was developed to bring marketplace and ERP return records into one operational view, with search, filtering, report polling and source-specific detail.
01The operational problem
Returns arrive through different channels with different identifiers, statuses and data availability. Customer service needs to search by order, RMA, SKU, tracking reference or platform, while warehouse and finance teams need the source record to remain traceable.
A single synchronous API call is not enough for every provider. Amazon report generation is asynchronous, eBay queries can be expensive at scale and historical data benefits from caching and targeted search.
02What was built
ECom Clarity built a web-based returns manager with a common operational model over Sellercloud, eBay and Amazon data. The interface provides platform filters, status filters, pagination, search and return detail while retaining each provider’s source identifiers.
Amazon returns use the official SP-API Reports flow: request a report, poll its status, download the result, normalise the data and cache it for the user interface. The architecture also supports fallback and diagnostic endpoints so a provider failure does not make the entire application opaque.
03Technical design
- React-based client and Node.js service layer with provider-specific adapters.
- Amazon SP-API report requests followed by bounded polling and TSV, XML or CSV parsing.
- Normalised return records preserve order ID, RMA, SKU, ASIN, reason, resolution, quantity, tracking and source.
- Parallel source loading allows one provider to fail without discarding successful results from the others.
- Cached Amazon results reduce rate pressure and improve repeat views.
- Search and pagination work across the operational dataset rather than forcing staff back into each marketplace portal.
04Controls, failure handling and operational safety
- Polling stops on completion, failure or a fixed timeout.
- Provider errors are surfaced as provider-specific operational messages.
- Rate limiting and cached results reduce unnecessary API traffic.
- Source and extraction metadata remain attached to normalised records.
- Manual tracking lookup remains available when an asynchronous report is delayed.
05Why the design matters
The application creates a consistent place to understand a return without pretending that all marketplaces behave identically. Normalisation supports one workflow; provenance allows staff to verify the original record.
Using Amazon’s official report interface rather than scraping the portal improves maintainability and supports larger historical extracts, while bounded polling gives operators honest progress feedback.
06What this project demonstrates
- Marketplace and ERP data normalisation.
- Asynchronous API orchestration and user-facing progress states.
- Performance tuning for search, caching and large result sets.
- Operational resilience when one external provider is slow or unavailable.
07Practical lessons for similar integrations
Normalise only what the shared workflow needs, and retain provider fields for audit and diagnosis. Over-normalisation can erase information that matters during a dispute.
Long-running provider jobs need a user experience of their own: a report ID, progress state, timeout, retry path and a cached last-known result are all part of the integration.