Checkout flow v2

Voog checkout v2 emits various events in the voog:checkout namespace, documented below. Note that the on-site modal uses the v1 API, documented here. The following only applies to the self-standing checkout module.

Conceptually, the checkout flow is a directed (but not necessarily acyclic) graph through the following phases. Parenthesized entries are external to the checkout module, but included here for completeness.

• (On-site shopping cart module)
• Customer information input — Initial view of the checkout module, customer information form.
• Shipping information input — Shipping options form.
• Payment information input — Payment options form.
• Checkout — The process of converting the Cart into an Order and returning details of dispatching to the payment gateway.
• (External payment gateway)
• Return — Report of success or failure of payment and order summary.

The emitted events are CustomEvent objects, containing an Object payload in the detail field. Every event’s payload contains the following fields, not documented separately below:

• cart or order — The relevant object. Before checkout, it is a Cart, after checkout, an Order. The commit event fired after the payment phase contains both.
• version — 2.

Some events may be cancelled. Cancelling an event prevents its default action to take place. A cancelable event receives the advance callback in its payload which may be invoked to execute the default action at a later time. To cancel an event, call its preventDefault method. For example, do delay the default action for 2000 ms:

document.addEventListener(`voog:checkout:close`, e => {
  e.preventDefault();
  setTimeout(() => e.detail.advance(), 2000);  
});

voog:checkout:show

Emitted upon displaying a sub-view of the checkout flow.

Fields:

• view
  • customer — Customer information form.
  • shipping — Shipping options form.
  • payment — Payment options form.
  • return — The return view.
  • cartcontent — The cart content view, on narrow viewports only.
• result — Only if view is return; the result returned from the payment gateway.
  • invoice — The user chose the offline payment option and was not directed to an external payment gateway.
  • success
  • pending
  • failed
  • cancelled

voog:checkout:commit

Emitted upon successfully committing changes to the server.

Fields:

• kind — A field signalling what kind of payload was commited.
  • customer — Customer information.
  • shipping — Shipping options.
  • payment — Payment options. Note that on return, the Cart object has been checked out into an Order object and both are included in the event payload. By cancelling this event, redirection to the payment gateway is prevented.
  • discount — A discount code.
• advance — Callback for the default action, see above.

This event may be cancelled to prevent advancing to the subsequent view (or payment gateway, if kind is payment).

voog:checkout:changeshippingmethod

Emitted upon the user selecting a shipping method. The passed Cart object contains the updated shipping method information.

voog:checkout:changeshippingoption

Emitted upon the user selecting a shipping method option. The passed Cart object contains the updated shipping method information.

voog:checkout:changepaymentmethod

Emitted upon the user selecting a payment method.

Fields:

• gateway_code — The gateway code.
• payment_method — The payment method code.

voog:checkout:close

Emitted upon the user navigating away from the checkout module outside of the flow.

Fields:

• view — See voog:checkout:show.
• reason
  • close — The user interacted with an element on the page redirecting back to the store.
  • history — The user navigated back in the browser history.
• advance — Callback for the default action, see above.

This event may be cancelled to prevent navigating away from the checkout flow.

voog:checkout:error

Emitted upon an error event.

Fields:

• action — load
• code — A string identifying the error condition.
  
  • load_error — Failed to load the cart
    
  • shipping_methods_load_error — Failed to load the shipping methods
  • no_store — Failed to load the store, store not configured or store disabled
    
  • no_uuid — No UUID passed to identify the cart
    
  • not_found — Cart with the given UUID not found
    
  • no_items — No items in the cart
    
  • checked_out — Cart has been checked out
    
  • no_payment_methods — No payment methods have been configured
    
• message — A human-readable message describing the error condition.