JS Events

Swft Cart and Swft Checkout fire CustomEvent on document. Listen with document.addEventListener.

All events are prefixed with swftcart: (cart) or swftcheckout: (checkout).

---

Swft Cart events

swftcart:opened

Fires when the cart drawer opens.

document.addEventListener('swftcart:opened', (e) => {
  console.log(e.detail) // { timestamp: number }
})

Detail: { timestamp: number } — Unix timestamp in ms.

---

swftcart:closed

Fires when the cart drawer closes.

document.addEventListener('swftcart:closed', (e) => {
  console.log(e.detail) // { timestamp: number }
})

Detail: { timestamp: number }

---

swftcart:fab-clicked

Fires when the floating cart icon is clicked, before the drawer opens.

document.addEventListener('swftcart:fab-clicked', (e) => {
  console.log(e.detail) // { timestamp: number }
})

Detail: { timestamp: number }

---

swftcart:cart-updated

Fires when cart contents change (item added, removed, quantity changed, coupon applied/removed).

document.addEventListener('swftcart:cart-updated', (e) => {
  const { itemCount, subtotal, currency } = e.detail
  document.querySelector('.cart-count').textContent = itemCount
})

Detail:

{
  itemCount: number     // total quantity across all items
  subtotal: number      // in minor units (pence)
  currency: string      // ISO 4217 (e.g. 'GBP')
  cartHash: string      // WooCommerce cart hash
}

---

swftcart:checkout

Fires when the checkout button is clicked. This event is cancelable — call e.preventDefault() to stop the redirect to checkout.

document.addEventListener('swftcart:checkout', (e) => {
  if (!termsAccepted()) {
    e.preventDefault()
    SwftCart.toast('Please accept the terms and conditions before continuing.')
  }
})

Detail:

{
  total: number      // cart total in minor units (pence)
  currency: string
  itemCount: number
}

Cancelable: yes — e.preventDefault() blocks the checkout redirect.

---

swftcart:item-removed

Fires when an item is removed from the cart.

document.addEventListener('swftcart:item-removed', (e) => {
  console.log(`Removed: ${e.detail.name} (qty ${e.detail.quantity})`)
})

Detail:

{
  productId: number
  name: string
  quantity: number
  cartItemKey: string
}

---

swftcart:item-saved-for-later

Fires when an item is moved to the saved-for-later list.

document.addEventListener('swftcart:item-saved-for-later', (e) => {
  console.log(e.detail.productId)
})

Detail:

{
  productId: number
  name: string
  cartItemKey: string
}

---

swftcart:upsell-added

Fires when a customer adds an upsell product to the cart from the cart drawer.

document.addEventListener('swftcart:upsell-added', (e) => {
  console.log(`Upsell added: ${e.detail.name}`)
})

Detail:

{
  productId: number
  name: string
  price: number     // minor units
}

---

swftcart:coupon-applied

Fires when a coupon code is successfully applied.

document.addEventListener('swftcart:coupon-applied', (e) => {
  console.log(`Coupon ${e.detail.code} saved ${e.detail.discount} pence`)
})

Detail:

{
  code: string
  discount: number    // discount amount in minor units
  currency: string
}

---

swftcart:coupon-removed

Fires when a coupon code is removed.

document.addEventListener('swftcart:coupon-removed', (e) => {
  console.log(`Removed coupon: ${e.detail.code}`)
})

Detail:

{
  code: string
}

---

swftcart:cart-shared

Fires when the customer copies the share cart URL.

document.addEventListener('swftcart:cart-shared', (e) => {
  console.log(`Shared URL: ${e.detail.url}`)
})

Detail:

{
  url: string     // the share URL that was copied
}

---

swftcart:upsell-shown

Fires when the upsell strip renders (products became visible).

document.addEventListener('swftcart:upsell-shown', (e) => {
  console.log(`${e.detail.productIds.length} upsells shown`)
})

Detail:

{
  productIds: number[]
}

---

Swft Checkout events

swftcheckout:ready

Fires when the checkout app has initialised and window.SwftCheckout is available. Always listen for this event before using the SwftCheckout API.

document.addEventListener('swftcheckout:ready', (e) => {
  const { session } = e.detail
  console.log('Session loaded:', session.sessionId)

  // Now safe to use window.SwftCheckout
  window.SwftCheckout.addOrderRow({
    id:    'loyalty-discount',
    label: 'Loyalty discount',
    value: '-£5.00',
    pos:   'after-subtotal',
  })
})

Detail:

{
  session: SwftSession   // the full session object (window.__SWFT_SESSION__)
}

---

swftcheckout:details-complete

Fires when the customer submits the details step (email, address, shipping method) and the payment intent has been created.

document.addEventListener('swftcheckout:details-complete', (e) => {
  const { formData, session } = e.detail
  // Track InitiateCheckout on your own analytics
})

Detail:

{
  formData: {
    email: string
    firstName: string
    lastName: string
    line1: string
    line2: string
    city: string
    postcode: string
    country: string
    shippingMethodId: string
  }
  session: SwftSession
}

---

swftcheckout:payment-complete

Fires when payment succeeds, before the confirmation screen is shown. The session status in window.__SWFT_SESSION__ is updated to 'complete' before this fires.

document.addEventListener('swftcheckout:payment-complete', (e) => {
  const { orderRef, session } = e.detail
  // Fire client-side conversion events
  gtag('event', 'purchase', {
    transaction_id: orderRef,
    value: session.cart.total / 100,
    currency: session.cart.currency,
  })
})

Detail:

{
  orderRef: string      // WooCommerce order number, e.g. '#1042'
  session: SwftSession  // session with status: 'complete'
}

---

swftcheckout:upsell-shown

Fires when a post-payment upsell offer is shown on the confirmation screen.

document.addEventListener('swftcheckout:upsell-shown', (e) => {
  console.log(e.detail.products)
})

Detail:

{
  products: UpsellProduct[]
}

Where UpsellProduct is:

{
  id:       number | string
  name:     string
  price:    number          // minor units
  currency: string
  image?:   string
  url:      string
  tag?:     string          // e.g. 'Frequently bought together'
}