SwftCheckout API — window.SwftCheckout

window.SwftCheckout is available after the swftcheckout:ready event fires. Always wait for this event before calling any methods.

document.addEventListener('swftcheckout:ready', () => {
  // window.SwftCheckout is now available
})

---

Methods

.on(event, fn)

Subscribe to a swftcheckout:* event. The event parameter should be the suffix after swftcheckout:.

on(event: string, fn: (detail: unknown) => void): void

window.SwftCheckout.on('payment-complete', (detail) => {
  console.log(detail.orderRef)
})

Equivalent to document.addEventListener('swftcheckout:payment-complete', ...).

---

.off(event, fn)

Unsubscribe from a swftcheckout:* event.

off(event: string, fn: (detail: unknown) => void): void

---

.addOrderRow(row)

Inject a custom row into the order summary. Rows are rendered between the line items and the total. Use pos to control placement.

addOrderRow(row: SwftOrderRow): void

SwftOrderRow:

interface SwftOrderRow {
  id:    string                                                           // unique identifier
  label: string                                                           // label text
  value: string                                                           // formatted value string (e.g. '£5.00' or '-£5.00')
  pos?:  'before-subtotal' | 'after-subtotal' | 'after-total'            // default: 'after-subtotal'
}

If a row with the same id already exists, it is replaced in-place.

document.addEventListener('swftcheckout:ready', () => {
  window.SwftCheckout.addOrderRow({
    id:    'gift-wrap',
    label: 'Gift wrap',
    value: '£2.99',
    pos:   'after-subtotal',
  })
})

---

.removeOrderRow(id)

Remove a custom order row by its id.

removeOrderRow(id: string): void

---

.addCustomField(field)

Inject a custom form field into the checkout. Fields appear in the details step or payment step depending on the section property.

addCustomField(field: SwftCustomField): void

SwftCustomField:

interface SwftCustomField {
  id:           string
  label:        string
  type:         'text' | 'textarea' | 'select' | 'checkbox'
  placeholder?: string
  required?:    boolean
  options?:     Array<{ value: string; label: string }>   // for type: 'select' only
  section?:     'details' | 'payment'                    // default: 'details'
}

If a field with the same id already exists, it is replaced in-place.

document.addEventListener('swftcheckout:ready', () => {
  window.SwftCheckout.addCustomField({
    id:          'gift-message',
    label:       'Gift message (optional)',
    type:        'textarea',
    placeholder: 'Write something nice...',
    section:     'details',
  })
})

Custom field values entered by the customer are submitted alongside the payment intent. They are available in the order meta as _swft_field_{id}.

---

.removeCustomField(id)

Remove a custom field by its id.

removeCustomField(id: string): void

---

.getExtension(key)

Read extension data from the session. Data was added by a WP plugin via the swft_session_extensions filter.

getExtension<T = unknown>(key: string): T | undefined

document.addEventListener('swftcheckout:ready', () => {
  const gifts = window.SwftCheckout.getExtension('gift_options')
  // { message: '...', wrap: true }

  if (gifts?.wrap) {
    window.SwftCheckout.addOrderRow({
      id:    'gift-wrap-fee',
      label: 'Gift wrap',
      value: '£2.99',
    })
  }
})

Returns undefined if the key does not exist in the extensions object.

---

Properties

.version

The version of the SwftCheckout API.

version: string   // e.g. '1.0.0'

---

.session

The full SwftSession object (same as window.__SWFT_SESSION__).

session: SwftSession | null

SwftSession shape:

interface SwftSession {
  sessionId:            string
  status:               'pending' | 'processing' | 'complete' | 'expired'
  merchant:             Merchant
  cart:                 Cart
  shippingMethods:      ShippingMethod[]
  stripePublishableKey: string
  mapboxToken:          string | null
  extensions:           Record<string, unknown>
  // Set only after payment completes:
  orderRef?:            string
  deliveryAddress?:     DeliveryAddress
  deliveryCoords?:      { lat: number; lng: number }
  estimatedDelivery?:   string
}

interface Merchant {
  id:                string
  name:              string
  logoUrl:           string | null
  accentColor:       string | null
  storeUrl:          string
  wcOrderUrl:        string | null
  googleMapsApiKey?: string
  checkoutTemplate?: 'minimal' | 'split' | 'express'
  policies?: {
    returns?:  string
    shipping?: string
    privacy?:  string
  }
}

interface Cart {
  currency:       string    // ISO 4217
  items:          LineItem[]
  subtotal:       number    // pence
  tax:            number    // pence
  total:          number    // pence
  needsShipping?: boolean
}

---

window.SWFT_SESSION

The raw session object injected by the Cloudflare Worker. Identical to SwftCheckout.session before payment, updated to status: 'complete' with orderRef after swftcheckout:payment-complete fires.

console.log(window.__SWFT_SESSION__.extensions)
// { gift_options: { message: '...', wrap: true } }

This object is set before the React app boots, making it available immediately without waiting for swftcheckout:ready.