Shipping order widget

A shipping order placed as a guest or signed in.

Each order widget works in one of two ways, chosen in the back office.

As a guest order_mode: guest

1. The visitor enters the sender, the recipient and the packages and asks for prices.
2. The visitor chooses a service and confirms an email address or phone number with a code sent to it.
3. The order is created and the visitor pays on the payment page. The order is placed when the payment is received.
4. The widget shows the shipment: its status, the payment link while it is unpaid, the tracking numbers, the label download for label shipments, and Cancel shipment while the shipment can still be cancelled. A cancellation needs a second confirmation.
5. My shipments lists the visitor's shipments of the last 90 days after the email address or phone number is confirmed again.

Guest shipping must be set up for the sWidget app in My Apps: which kinds of shipment guests may send and whether the code goes by email or SMS. The widget page in the back office says when something is missing.

The shipment and the confirmed contact are kept in the browser tab (sessionStorage) and are gone when the tab closes.

document.addEventListener('swidget:created', (event) => {
  const order = event.detail.guest_order;   // { id, kind, status, amount: '12.50', currency, pay_url, can_cancel, … }
});
document.addEventListener('swidget:cancelled', (event) => console.log(event.detail.guest_order.status));

Signed in order_mode: sign_in

1. Sign in opens the client's sign-in page in a pop-up window. The window opens during the click, so browsers that block pop-ups let it open.
2. After sign-in, the return page on open.superroute.ca sends the sign-in code to the widget's page, and only when that page is one of the widget's websites.
3. The widget exchanges the code (OAuth 2 with PKCE) and shows the shipping order form for the visitor's own account. The visitor's session is kept in the browser tab.

A signed-in order is placed on the visitor's account and announced with swidget:created. Payment for it follows the client's own account rules.

Calls

A guest order widget's key makes the guest calls below. A signed-in order widget's key reads only its configuration; the order is placed with the visitor's own token.

The calls are operations of the partner app API, in REST and GraphQL: Partner app REST reference · Partner app GraphQL reference