How to design APIs and integrations for returns? An IT checklist for e-commerce

Does a return request in your organization automatically set off a flow of data between the WMS, the ERP, the payment system and accounting? Or does it still need someone to check several independent systems by hand? Many companies already run isolated automations, such as email notifications, yet the process as a whole stays fragmented and rests on incomplete integrations. Only 48% of companies use a dedicated returns management platform. On top of that comes the EU-mandated online withdrawal function and the job of integrating it with the store’s existing systems architecture. This guide shows you how to design APIs and system integrations that improve data flow and deliver consistent returns handling across the organization.

What will you learn from this article? In brief

• Automating individual tasks — email notifications, for example — is not the same as fully integrating the returns process.
• EU Directive 2023/2673 introduces an online withdrawal function. Even where national implementation is running late, as in Poland, IT teams should already be building an architecture that meets the requirement.
• The returns process needs a shared status model and durable identifiers linking the store, OMS, WMS, ERP and logistics operator.
• A solid returns API prevents duplicates and accidental repeat operations, connects systems securely, and keeps working even when one component fails for a while.
• Run the work in stages – from a process map, through a sandbox and failure testing, to a gradual production launch.

What do the new EU regulations change in e-commerce returns handling?

The new EU rules require online stores to give customers a simple way to withdraw from a contract directly in the store interface, though the final shape of that obligation in each country will be settled by national law. In practice, for the whole period in which the customer may return the goods, the store must provide a permanent, easily noticeable button or link, labeled unambiguously — for example “withdraw from your contract here”.

These rules matter to IT teams because designing the process badly creates real legal exposure. The procedure has two stages: the consumer first identifies the contract and submits the declaration, then confirms that decision with a separate action. Only after confirmation does the system automatically generate a document on a durable medium — a form that lets its content be stored and reproduced unchanged, such as a PDF attached to an email. Without separating the two steps and without automatic confirmation on a durable medium, a company may be unable to prove whether and when the consumer submitted the declaration.

Four concepts are worth keeping apart, because they are often confused in practice:

• withdrawal from the contract – the consumer’s declaration of intent,
• return request – the trigger that starts the logistics process,
• return shipment – the physical movement of the product,
• refund – returning all or part of the money to the customer, triggered in line with the grounds for the return, the applicable deadlines and the merchant’s policy.

The rules were due to apply from 19 June 2026, but the Polish government has for now stepped back from implementing them. The obligation stems from EU law rather than a national legislature’s decision, so the direction of travel is settled. Designing and launching a new interface and the integrations behind it usually takes many months, so IT teams that wait for the final wording of national legislation risk running out of time once the rules take effect.

How do you connect the systems that handle returns in e-commerce? One data flow reduces errors and discrepancies

Every stage of a return — request, transport, quality control, refund — involves a different system, and a failure to pass data correctly between them blocks the whole chain of decisions, including the moment the customer gets their money back. A consistent data flow reduces discrepancies and speeds up error detection: each component updates only its own part of the process instead of duplicating information in several places at once.

Large organizations working with many logistics operators and extensive system landscapes increasingly cut the number of separate point-to-point integrations in favor of a single integration layer. That is the role our Alsendo Innoship platform plays, bringing together APIs, multi-carrier support and returns management.

Dividing roles between the store, OMS, WMS, ERP and logistics operator – one owner for each type of data

Every type of data in the returns process should have exactly one source system — the system of record, holding the binding, current version of the information all other systems refer to. Without that division, the store and the ERP can easily show the customer different statuses for the same return, while the support team has no idea which version to trust.

System	What is it responsible for?	Typical system of record for…
Online store / front end	Accepting the return request, showing the status to the customer	The request interface and communication with the customer
OMS (order management system)	Linking the return to the order and its individual lines	Order data and the status of the return case
WMS (warehouse management system)	Receiving the parcel, quality control, warehouse disposition	The inspection result and the decision on what happens to the product
ERP (enterprise resource planning system)	Financial documents, stock levels, settlements	Accounting and stock data across the company as a whole
Payment system	Executing the refund and reporting its status	Payment state and transaction history
Logistics operator	Generating labels, return shipment status	Data on the parcel’s location and delivery

Return statuses and identifiers – a shared language for every system

A generic “return in progress” status is not enough in an enterprise organization, because it hides five mutually independent dimensions: the status of the withdrawal declaration, the return case, the shipment, the warehouse inspection and the refund — each changes at a different moment and each can create problems of its own.

To pull those dimensions together, agree on a minimum set of identifiers that every system passes on unchanged:

• withdrawalStatementId – the identifier of the withdrawal declaration;
• returnId – the identifier of the return case as a whole;
• orderId and orderLineId – the identifier of the order and of the specific line the return concerns;
• returnShipmentId and trackingNumber – the identifier of the return shipment and the tracking number at the operator;
• refundId – the identifier of the refund operation;
• eventId and correlationId – the identifier of a single event and the shared marker linking every event that belongs to the same case.

How do you design an API for returns handling? A stable contract, idempotency and webhooks keep errors out of the process

A returns API needs a versioned contract, an unambiguous data model, and mechanisms that guard against the same operation running twice. In practice that means documentation setting out the available operations, the formats for dates and amounts, and the rules for partial and multi-parcel returns — the industry standard here is OpenAPI, currently at version 3.2.0.

It also matters that new API versions do not break existing integrations and that errors come back in one predictable format. The key mechanism, though, is idempotency: it means sending the same request several times in a row — after a dropped connection, say — does not create a second return or a second refund.

Webhooks – protection against duplicates and out-of-order events

Beyond the API itself, the process needs webhooks: automated notifications telling other systems that a status has changed, without them polling for updates. Because such a notification sometimes arrives twice or arrives late, the receiving system must recognize and discard duplicates and cope with information arriving in a different order from the one in which things actually happened — a parcel-received confirmation turning up before the dispatch confirmation, for instance.

A further safeguard is a retry mechanism with a growing interval between attempts, so the system is not hit by a wave of simultaneous retries, plus periodic data comparison between systems, which catches discrepancies no single event would reveal.

System element	Requirement	Why does it matter?
Versioning	A version number in the path or a header, and a clear deprecation policy for older versions	Lets you evolve the API without giving up partner integrations
Data model	Shared identifiers and shared formats for dates, amounts and currencies	Removes ambiguity between systems
Idempotency	An idempotency key on state-changing operations	Guards against a duplicate return and a double refund
Partial and multi-parcel returns	Separate representation of order lines and of shipments	Mirrors the scenarios customers actually create
Error format	A unified structure compliant with RFC 9457	Makes automated error handling easier on the API client side
Webhooks	Signed events with a unique eventId	Enables source verification and duplicate detection
Data reconciliation	Periodic comparison of state between systems	Catches discrepancies that no event reported

How do you secure and monitor returns integrations? Access control and failure resilience reduce operational risk

A secure returns integration has to protect data and operations while behaving predictably when one system goes down. Traffic between systems should be encrypted, and the system calling the API must be authenticated beyond doubt — most often with an OAuth 2.0 token from the client credentials flow, a certificate in an mTLS setup, or both.

Every system should get only the permissions its own tasks require — separate scopes for reading and writing return data, for instance, rather than access to the whole order database. If the platform serves multiple customers, their data must be separated at every meaningful layer: authorization, database queries, queues, cache and backups.

It is also worth signing webhook notifications so the receiving system can verify they really come from a trusted source, and rotating keys and access credentials regularly in line with the OWASP recommendations for APIs.

Monitoring and failure resilience – how do you contain the impact of errors before the customer notices?

Failure resilience rests on a few simple principles — above all, a system should never wait indefinitely for another to respond. If that system stops responding, calls to it should be suspended temporarily rather than loaded with further attempts. Ideally, events that cannot be processed after several attempts land in a separate queue for the team to review manually later.

Logs, metrics and a trace of every request as it passes through successive systems give you full visibility, in line with the OpenTelemetry standard. It is also worth recording every data change in a history, so it is clear who made it and when. Alerts should react to failed refunds, unsent confirmations and stuck events before the customer notices.

How do you prepare a returns integration rollout in e-commerce? An IT plan from testing to production launch

A returns integration should start with a process map and clear ownership of data, and end with failure testing, monitoring and a controlled production launch. The team begins by auditing the current process and establishing which systems take part. Next comes the data and status model, then the API contract and authentication. A test environment with realistic data lets developers verify the integration before the first real return reaches production finance systems.

Then come the tests: integration, performance, failure and retry, and duplicates. Organizations preparing for the online withdrawal function should also run an end-to-end test of the whole path, from declaration to confirmation on a durable medium.

Once monitoring and alerting are live, the team rolls the integration out gradually — starting with one market or sales channel, with a rollback plan ready and an incident procedure defined. Large organizations with extensive system landscapes often decide at this point to cut the number of separate integrations in favor of a single platform, and this is exactly where we can help.

Alsendo Innoship centralizes returns handling, bringing statuses, labels and customer communication into one environment. For organizations with non-standard processes or legacy systems we offer Alsendo Enterprise, designed around the existing architecture and its integration requirements. Smaller and mid-sized companies with less complex processes can use Alsendo Business Pro, a platform that is ready to deploy.

The returns integration test matrix – which scenarios should you check before launch?

The scenarios below reflect real situations an integration team will sooner or later meet in production. The table sets out six types of test with a concrete example each, making it easier to scope the work before go-live. Work through it with the team responsible for every system involved in the returns process.

Type of test	What does it check?	Example scenario
Integration	That data flows correctly between systems	A return request passes correctly from the OMS to the WMS and the ERP
Performance	How the system behaves under increased load	A sudden spike in returns after a sale period
Failure and retry	How the integration behaves when one system is unavailable	The payment system is temporarily unavailable during a refund
Duplicate	How effective the idempotency mechanism is	The same parcel-received webhook arrives three times
Online withdrawal function	That the path complies with Directive 2023/2673	The customer submits a declaration and receives confirmation on a durable medium
Out-of-order events	Resilience to an unusual order of messages	The warehouse inspection confirmation arrives before the dispatch confirmation

A returns integration rollout plan – the next steps for the IT team

The plan organizes the IT team’s work from the first decisions to go-live. Each point relates to a specific decision or resource, so you can easily judge what already works in your organization and what is missing. Review the whole list with the people responsible for each system before the integration goes into testing.

Returns integration rollout checklist:

• if you do not yet have a map of the systems involved in the process -> start by drawing one up with the owners of each system;
• if the process rests on many point-to-point integrations today -> assess which of them are worth replacing with a single integration layer;
• if your organization sells in several markets -> build the separate currency and customs requirements into the design;
• if the team does not yet have a test environment -> set up a sandbox with data close to production;
• if you are planning a gradual launch -> prepare a rollback plan and the criteria for triggering it in advance;
• if your organization has no owner for the returns process yet -> appoint one before implementation work begins.

Getting your e-commerce ready for the online withdrawal function – a compliance checklist

The checklist below will help you establish whether your store is genuinely ready for the requirements of EU Directive 2023/2673. Each point covers a specific element of the interface or the process, so you can quickly pinpoint gaps before the withdrawal function goes live. Review it with your legal team, because the state of the legislation is still changing.

Readiness for the online withdrawal function:

• does the store interface have room for a visible, permanently available withdrawal function?
• can the system store the content of the declaration together with the date and time it was submitted?
• is there a mechanism for automatic confirmation on a durable medium?
• does data from the withdrawal form pass automatically to the system handling the rest of the return?
• does the process record an audit trail of every change to the status of the declaration?
• is your legal team monitoring the current state of the national legislation implementing the directive?
• does the form collect or confirm the data required to identify the consumer and the contract?
• is there a separate step after the form is filled in that confirms the declaration has been submitted?

Planning an integration between returns and your e-commerce, WMS or ERP systems? A well-designed architecture saves the IT team work and builds customer trust in the whole post-purchase process. Talk to the Alsendo team about the architecture of this process and what our platform can do.

FAQ – further questions about APIs and returns integrations in e-commerce

APIs and returns integrations raise plenty of questions, because they shape not only systems architecture but also operations, customer service, logistics and the way teams work together. So we have gathered answers to a few further points.

How do you move returns handling off old integrations without stopping sales?

Launch the new integration in stages — for a period the old and new processes should run in parallel, with the option to fall back quickly to the previous solution. Start with one market or one operator, compare statuses in both systems, and switch the old integration off only once they match.

How do you prepare returns integrations for cross-border sales?

A cross-border integration has to handle additional logistics operators, local drop-off methods, different currencies and time zones, and — for returns from outside the European Union — customs data. Our report Returns in Polish E-commerce 2026 found that 66% of companies selling abroad ask customers to send goods back to Poland only, while just 18.6% let them drop the parcel off at a local point. There is plenty of room for improvement.

Does automating return notifications already amount to full process integration?

No, these are two different things. Our report Returns in Polish E-commerce 2026 shows a clear gap in levels of automation. Automated return status notifications are used by 83% of the companies surveyed. Integration with a logistics operator via API and modules connected to the e-commerce system or ERP are much rarer — 56% of companies in each case. Only 48% use a dedicated returns management platform. The data suggests many businesses have automated customer communication alone, not the flow of data between systems.

Who should be responsible for the returns process in e-commerce – IT, logistics or finance?

The returns process needs a single business owner, while responsibility for specific data and operations is best split between IT, logistics and finance. Without that split, each department watches only its own segment and nobody oversees the full path from request to refund.

How long should you keep returns data, events and logs?

Retention periods should follow from the purpose of processing, legal obligations and audit needs — not from what the system can technically store. Data on a withdrawal, a shipment or a refund may need a different retention period than accounting documents; an application log, for example, need not hold full customer data as long as an invoice does. Set the final periods with your legal department and data protection officer.

Is it better to build your own returns integration or reach for a ready-made platform?

Building your own integration makes sense when the organization has unique processes, a team able to maintain the code for years, and time for a full implementation cycle. A ready-made platform wins where speed of launch, vendor support and lower maintenance risk count, particularly with many logistics operators and markets. In practice many organizations combine both: a ready-made platform for standard processes and a bespoke solution wherever requirements genuinely depart from the norm.

Sources:

• Prawo.pl – Returns in one click: who has to implement them, and when
• EUR-Lex – Directive (EU) 2023/2673
• UOKiK – Implementation of Directive (EU) 2023/2673 of the European Parliament and of the Council
• OpenAPI Initiative – OpenAPI Specification
• RFC Editor – RFC 9421, HTTP Message Signatures
• OWASP Cheat Sheet Series – Secrets Management Cheat Sheet
• OpenTelemetry – Signals (documentation)

Alsendo