ORBCOMMERCE DOCUMENTATION
The withdrawal function
Let every shopper withdraw from an order in two steps, with the law's labels, without an account.
Since 19 June 2026 an online shop in the EU must let a shopper withdraw from a contract with a function of its own, as easily as they bought (Directive (EU) 2023/2673, Art. 11a of Directive 2011/83/EU; in Germany § 356a BGB). You host the two steps; OrbCart keeps every declaration, records it on its order, tells you, and answers what to show.
1. Link it on every page
Put a link in your footer, on every page, for the whole withdrawal period. It carries the law's first label, word for word:
| Language | The link opens the withdrawal | The second step sends it |
|---|---|---|
| German | Vertrag widerrufen | Widerruf bestätigen |
| English | Withdraw from contract here | Confirm withdrawal |
| French | Se rétracter du contrat ici | Confirmer la rétractation |
The German labels are § 356a BGB's. The English and French ones follow Art. 11a in those languages; check them against the Official Journal and your country's own act before you go live there.
2. Ask for the declaration, then confirm it
The first step asks for the shopper's name, the order number and the email they ordered with, and
whether they withdraw from the whole order or only some items, in their own words. A shopper without
an account withdraws the same way. The number is forgiving: NG-2026-004711, ng-2026-004711,
2026-4711 and the bare 4711 all name the same order, and the email's case and spaces do not
matter. Show the declaration back, and send it only from a button with the second label:
const receipt = await commerce.withdraw({
name: "Anna Berger",
number: "NG-2026-004711",
email: "anna@example.com",
goods: { type: "some", description: "The rain jacket in size M" },
locale: "en",
});locale is the language of the page the shopper declared on, and the receipt by mail is written
in it.
3. Show the receipt at once
The answer is what the shopper sent and when it arrived. Show all of it, date and time included:
receipt.receivedAt; // "2026-11-03T10:15:00.000Z"
receipt.goods; // { type: "some", description: "The rain jacket in size M" }The answer is the same whether or not the number and the email name an order. So nobody learns
from your page which orders exist, and the page must not say "withdrawal recorded" either: say that
the confirmation follows by email to the address they typed. Every declaration is received, and its
receipt goes to that address, matched or not: it repeats only what they declared and when it
arrived, so it reveals nothing either. The family's mail sends it from
withdrawal.received, or your own system does.
The call takes your publishable key, as creating a cart does, and finds the order only through the
email's own orders, in any Channel of yours. The same declaration again within ten minutes, from a
double click or a reload, is the one received before, with its time. Each email may declare 5
withdrawals and each client network (an IPv4 address or an IPv6 /64) send 20 in a minute; past that the call answers
429 rate_limited (Security), and a declaration received before stays
received.
What support sees
The order's history in the admin shows the withdrawal with its time, what was withdrawn and whether it came in time: before every unit shipped the period has not begun; after, it ends with the 14th day after the day of the last fulfillment you reported, or the Monday after when that day is a Saturday or a Sunday. Days are counted generously across Europe's time zones, so OrbCart never calls a timely withdrawal late. It knows no public holidays, though, and a fulfillment is the moment OrbCart knows of while a parcel arrives later: a withdrawal shown as "maybe late" asks support to check the date. Nothing is refused: support takes the goods back and refunds them as for any return. A second "whole order" after the first records nothing more.
A declaration whose number and email named no order is kept all the same and waits in the admin's inbox at Orders → Withdrawals, with the name, number, email and goods the shopper typed. Support attaches it to the order it meant by the order's number, which records it there at the moment it arrived, so its timing is judged by then, or marks it handled once settled another way. OrbCart keeps every declaration, and the personal data in it, for 180 days after it arrived, as long as a cart without an order; one attached to an order stays on it as long as the order does.
The shopper's receipt confirms that the declaration arrived, not that it has been recorded on an
order. A matched declaration also stays in support's inbox while recording is unconfirmed.
An attachment returns 200 with a withdrawal_attachment whose status is recorded only once
the order durably owns the name, goods and original receipt time. 202 with recording reserves
the target order and retries in the background; Retry checks or completes that same attachment.
It cannot be moved to another order or marked handled while the result is unknown.
Retention never waits for recording: the raw declaration is deleted at its original deadline.
An unconfirmed attachment remains in the inbox with only its ID, receipt time and reserved order,
as expired_unconfirmed. Retry can confirm an existing order receipt, but cannot recover a
declaration the order never received. An unconfirmed expired attachment returns 410 withdrawal_expired.
Reading the raw declaration returns 404 after retention, even when its order keeps the withdrawal.