Events

Commerce broadcasts events when changes occur to the internal state.

These events allow your own application to respond accordingly with additional handling.

app.error

The app.error event is broadcast when Commerce fails to load due to a configuration error.

  • Listener

    Commerce.subscribe( 'app.error', function ( event ) {
      // The app has encountered an error
      console.log( event )
    } )
    
  • Event

    // When no payment processors are configured
    {
      data: {
        documentation: 'https://docs.static.tools/commerce/guide/payment-processors.html',
        message: 'No payment processors',
        settings: 'https://admin.static.tools/commerce/settings/payments',
        type: 'processors-undefined'
      }
    }
    
    // When no shipping countries are configured
    {
      data: {
        documentation: 'https://docs.static.tools/commerce/guide/admin.html#shipping',
        message: 'No shipping countries',
        settings: 'https://admin.static.tools/commerce/settings/shipping',
        type: 'countries-undefined'
      }
    }
    
    // When no currencies are configured
    {
      data: {
        documentation: 'https://docs.static.tools/commerce/guide/currencies.html',
        message: 'No currencies',
        settings: 'https://admin.static.tools/commerce/settings/payments',
        type: 'currencies-undefined'
      }
    }
    

app.ready

The app.ready event is broadcast once Commerce has finished loading and initializing.

Once this event has been broadcast you can use the full range of JavaScript API Methods.

  • Listener
    Commerce.subscribe( 'app.ready', function () {
      // The app is ready
    } )
    

cart.add

The cart.add event is broadcast when an item is being added to the cart.

  • Listener

    Commerce.subscribe( 'cart.add', function ( event ) {
      // An item is being added to the cart
      console.log( event )
    } )
    
  • Event
    The data contains the items that were requested to be added.

    {
      data: [
        {
          id: '-LrpxAwMv1XZo8vyd0r8',
          quantity: 1
        }
      ]
    }
    

cart.change

The cart.change event is broadcast whenever the internal cart state changes.

This occurs when an item is added or removed, if the quantity increases or decreases and when an item is modified.

  • Listener

    Commerce.subscribe( 'cart.change', function ( event ) {
      // The cart has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.cart.get().

    {
      data: {
        discounts: [],
        items: { 
          '-LsUMTyd4XEDGZ9F_SGx': {
            discounts: [],
            fields: [],
            price: {
              subtotal: { amount: 9, formatted: '$9.00' },
              total: { amount: 9, formatted: '$9.00' },
              unit: { amount: 9, formatted: '$9.00' }
            },
            product: { ... },
            quantity: 1
          },
          '-LtX_BcA23Xv7Ols96kz': {
            discounts: [],
            fields: [],
            price: {
              subtotal: { amount: 3.75, formatted: '$3.75' },
              total: { amount: 3.75, formatted: '$3.75' },
              unit: { amount: 3.75, formatted: '$3.75' }
            },
            product: { ... },
            quantity: 1
          },
        },
        price: {
          saving: { amount: 0.0, formatted: '$0.00' }
          subtotal: { amount: 12.75, formatted: '$12.75' }
          total: { amount: 12.75, formatted: '$12.75' }
        },
        quantity: 2,
        valid: true
      }
    }
    

cart.error

The cart.error event is broadcast when an item in the cart experiences an error.

  • Listener

    Commerce.subscribe( 'cart.error', function ( event ) {
      // An item in the cart has experienced an error
      console.log( event )
    } )
    
  • Event

    // When the product does not exist
    {
      data: {
        item: { ... },
        message: 'This product does not exist or has been removed from sale',
        title: 'Missing',
        type: 'missing'
      }
    }
    
    // When the maximum quantity is exceeded
    {
      data: {
        item: { ... },
        message: 'Reduce the quantity of this item to below the maximum',
        title: 'Maximum exceeded',
        type: 'maximum'
      }
    }
    
    // When the product is malformed in the inventory
    {
      data: {
        item: { ... },
        message: 'This product is malformed',
        title: 'Malformed',
        type: 'malformed'
      }
    }
    
    // When the product does not have a price for the active currency
    {
      data: {
        item: { ... },
        message: "No price set for '...'",
        title: 'Missing currency',
        type: 'currency'
      }
    }
    
    // When the product does not have a price
    {
      data: {
        item: { ... },
        message: 'No default price set',
        title: 'Missing price',
        type: 'price'
      }
    }
    

config.ready

The config.ready event is broadcast once the full configuration has been loaded.

  • Listener

    Commerce.subscribe( 'config.ready', function ( event ) {
      // The configuration is ready
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.config.get().

    {
      data: {
        cart: {
          authenticators: [
            'email'
          ],
          messages: {
            'checkout-success': '',
            'shipping-address': '' ,
            'shipping-note': ''
          },
          notes: [
            {
              id: 'delivery',
              label: 'Delivery Instructions'
            },
            {
              id: 'order',
              label: 'Order Notes'
            }
          ],
          preferences: {
            'billingaddress-enabled': true,
            'lastname-required': false,
            'phone-required': false,
            'shippingnote-enabled': true
          }
        },
        currency: 'USD',
        embed: {
          key: '...'
        },
        environment: 'live',
        expose: 'Commerce',
        instance: '64cc70ba48',
        organization: 'VlWw8jlSw2',
        payments: {
          currencies: [
            'AUD',
            'CAD',
            'EUR',
            'GBP',
            'JPY',
            'USD'
          ],
          gateways: [
            'stripe',
            'paypal'
          ],
          paypal: {
            enabled: true
          },
          stripe: {
            enabled: true,
            publishableKey: '...'
          }
        },
        shipping: {
          countries: [
            'AU',
            'US'
          ]
        }
      }
    }
    

Note

Initial configuration is always ready as soon as the commerce.ready event occurs.

coupons.change

The coupons.change event is broadcast when the coupons change.

This will occur after calls to Commerce.coupons.add and Commerce.coupons.remove.

  • Listener

    Commerce.subscribe( 'coupons.change', function ( event ) {
      // The coupons have changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.coupons.get().

    {
      data: [
        'fitnessfirst',
        'WOAH-MULTIPLE-COUPONS!'
      ]
    }
    

currency.change

The currency.change event is broadcast when the currency is changed.

This will occur on every page load and after calls to Commerce.currency.set.

  • Listener

    Commerce.subscribe( 'currency.change', function ( event ) {
      // The currency has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.currency.get().

    {
      data: 'USD'
    }
    

discounts.change

The discounts.change event is broadcast when the discounts change.

  • Listener

    Commerce.subscribe( 'discounts.change', function ( event ) {
      // The discounts have changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.discounts.get().

    {
      data: [
        {
          applied: true,
          conditions: [ ... ],
          coupons: [ 'fitnessfirst' ],
          effects: [ ... ],
          id: '-LtXeaPlDtt-F-OxrZqu',
          saving: {
            amount: 3.23,
            formatted: '$3.23'
          }
        },
        {
          applied: false,
          conditions: [ ... ],
          effects: [ ... ],
          id: '-LtXeb26ClFnvwaXsQ81',
          saving: {
            amount: 0,
            formatted: '$0.00'
          }
        }
      ]
    }
    

inventory.change

The inventory.change event is broadcast when a product changes in the inventory.

  • Listener

    Commerce.subscribe( 'inventory.change', function ( event ) {
      // The remote inventory has changed
      console.log( event )
    } )
    
  • Event

    {
      data: {
        id: '...', // The id of the product
        product: { ... }, // The new data for the product
        previous: { ... } // The previous data for the product
      }
    }
    

order.addresses.billing.change

The order.addresses.billing.change event is broadcast when the order billing address changes.

  • Listener

    Commerce.subscribe( 'order.addresses.billing.change', function ( event ) {
      // The order billing address has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.order.addresses.get( 'billing' ).

    {
      data: {
        city: 'Westerville',
        country: 'US',
        fullname: 'Lorrie Glick',
        id: '-LtYPEmHSeo78Sz8CV5e',
        line1: '4595 Quilly Lane',
        line2: null,
        postcode: '43081',
        state: 'OH'
      }
    }
    

order.addresses.shipping.change

The order.addresses.shipping.change event is broadcast when the order shipping address changes.

  • Listener

    Commerce.subscribe( 'order.addresses.shipping.change', function ( event ) {
      // The order shipping address has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.order.addresses.get( 'shipping' ).

    {
      data: {
        city: 'Manhattan',
        country: 'US',
        fullname: 'Inez Ellis',
        id: '-LrM6xWAfLmnuuqYRIbl',
        line1: '1989 Settlers Lane',
        line2: null,
        postcode: '10016',
        state: 'NY'
      }
    }
    

order.addresses.change

The order.addresses.change event is broadcast when an order address changes.

  • Listener

    Commerce.subscribe( 'order.addresses.change', function ( event ) {
      // An order address has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.order.addresses.get().

    {
      data: {
        billing: {
          city: 'Westerville',
          country: 'US',
          fullname: 'Lorrie Glick',
          id: '-LtYPEmHSeo78Sz8CV5e',
          line1: '4595 Quilly Lane',
          line2: null,
          postcode: '43081',
          state: 'OH'
        },
        shipping: {
          city: 'Manhattan',
          country: 'US',
          fullname: 'Inez Ellis',
          id: '-LrM6xWAfLmnuuqYRIbl',
          line1: '1989 Settlers Lane',
          line2: null,
          postcode: '10016',
          state: 'NY'
        }
      }
    }
    

order.change

The order.change event is broadcast when anything about the order changes.

  • Listener

    Commerce.subscribe( 'order.change', function ( event ) {
      // The order has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.order.get().

    {
      data: {
        addresses: { ... },
        cart: { ... },
        modifiers: [ ... ],
        notes: [ ... ],
        payment: { ... },
        price: { ... },
        quote: {
          selected: '...',
          options: [ ... ]
        },
        shipping: { ... },
        user: { ... },
        valid: true
      }
    }
    

order.notes.change

The order.notes.change event is broadcast when an order note changes.

This will occur after calls to Commerce.order.notes.set.

  • Listener

    Commerce.subscribe( 'order.notes.change', function ( event ) {
      // An order note has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.order.notes.get().

    {
      data: [
        {
          id: 'delivery',
          label: 'Delivery Instructions',
          value: 'Please leave at the front door'
        },
        {
          id: 'order',
          label: 'Order Notes',
          value: 'Please match Dye Lot 7625'
        }
      ]
    }
    

order.payment.change

The order.payment.change event is broadcast when the order payment changes.

This will occur after calls to Commerce.order.payment.set.

  • Listener

    Commerce.subscribe( 'order.payment.change', function ( event ) {
      // The order payment has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.order.payment.get().

    // When the payment method is PayPal
    {
      data: {
        details: null,
        method: 'paypal'
      }
    }
    
    // When the payment method is Stripe
    // and payment details have been set
    {
      data: {
        details: { ... },
        method: 'stripe'
      }
    }
    

order.payment.details.change

The order.payment.details.change event is broadcast when the order payment details change.

This will occur after calls to Commerce.order.payment.set.

  • Listener

    Commerce.subscribe( 'order.payment.details.change', function ( event ) {
      // The order payment details have changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.order.payment.get().details.

    // When the payment method is PayPal
    {
      data: null
    }
    
    // When the payment method is Stripe
    // and payment details have been set
    {
      data: { ... }
    }
    

order.payment.method.change

The order.payment.method.change event is broadcast when the order payment method changes.

This will occur after calls to Commerce.order.payment.set.

  • Listener

    Commerce.subscribe( 'order.payment.method.change', function ( event ) {
      // The order payment method has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.order.payment.get().method.

    // When the payment method is PayPal
    {
      data: 'paypal'
    }
    
    // When the payment method is Stripe
    {
      data: 'stripe'
    }
    

order.quote.change

The order.quote.change event is broadcast when new quote options become available.

This will occur as a result of calling Commerce.order.quote.fetch().

  • Listener

    Commerce.subscribe( 'order.quote.change', function ( event ) {
      // A new set of quote options have been loaded
      console.log( event )
    } )
    
  • Event
    The data is the same as the options returned by Commerce.order.quote.fetch().

    {
      data: [
        {
          id: '27169130-4993-4fe7-b3fa-bb8b13b793f1',
          modifiers: [
            {
              name: 'Shipping',
              price: {
                amount: 11.95,
                formatted: '$11.95'
              },
              service: {
                name: 'Australia Post Express Parcel',
                provider: 'auspost'
              },
              type: 'shipping'
            },
            {
              included: true,
              name: 'GST (10%) Inc.',
              price: {
                amount: 0.06,
                formatted: '$0.06'
              },
              rate: 0.1,
              type: 'tax'
            }
          ],
          price: {
            subtotal: {
              amount: 7,
              formatted: '$7.00'
            },
            total: {
              amount: 18.95,
              formatted: '$18.95'
            }
          },
          shipping: {
            details: {
              costs: {
                cost: {
                  item: 'Express Post',
                  cost: '11.95'
                }
              },
              delivery_time: 'Guaranteed Next Business Day within the Express Post network (If posted on any business day Monday to Friday in accordance with the conditions set out on the item).',
              service: 'Express Post',
              total_cost: '11.95'
            },
            key: 'auspost-domestic-express-parcel',
            name: 'Australia Post Express Parcel',
            price: {
              amount: 11.95,
              formatted: '$11.95'
            },
            provider: 'auspost'
          }
        },
        {
          id: '05424b6e-b57f-4d98-b90f-7197455c98d0' ,
          modifiers: [
            {
              name: 'Shipping',
              price: {
                amount: 18.95,
                formatted: '$18.95'
              },
              service: {
                name: 'Australia Post Satchel (5kg)',
                provider: 'auspost'
              },
              type: 'shipping'
            },
            {
              included: true,
              name: 'GST (10%) Inc.',
              price: {
                amount: 0.06,
                formatted: '$0.06'
              },
              rate: 0.1,
              type: 'tax'
            }
          ],
          price: {
            subtotal: {
              amount: 7,
              formatted: '$7.00'
            },
            total: {
              amount: 25.95,
              formatted: '$25.95'
            }
          },
          shipping: {
            key: 'auspost-domestic-regular-satchel-5kg',
            name: 'Australia Post Satchel (5kg)',
            price: {
              amount: 18.95,
              formatted: '$18.95'
            },
            provider: 'auspost'
          }
        }
      ]
    }
    

order.quote.select

The order.quote.select event is broadcast when a quote option is selected.

  • Listener

    Commerce.subscribe( 'order.quote.select', function ( event ) {
      // A quote has been selected
      console.log( event )
    } )
    
  • Event
    The data is the same as an option returned by Commerce.order.quote.fetch().

    {
      data: {
        id: '27169130-4993-4fe7-b3fa-bb8b13b793f1',
        modifiers: [ ... ],
        price: {
          subtotal: {
            amount: 7,
            formatted: '$7.00'
          },
          total: {
            amount: 18.95,
            formatted: '$18.95'
          }
        },
        shipping: {
          details: { ... },
          key: 'auspost-domestic-express-parcel',
          name: 'Australia Post Express Parcel',
          price: {
            amount: 11.95,
            formatted: '$11.95'
          },
          provider: 'auspost'
        }
      }
    }
    

paypal.cancel

The paypal.cancel event is broadcast when the user prematurely closes the PayPal window.

  • Listener
    Commerce.subscribe( 'paypal.cancel', function () {
      // The user has prematurely cancelled the purchase
    } )
    

paypal.error

The paypal.error event is broadcast when PayPal encounters an error.

  • Listener
    Commerce.subscribe( 'paypal.error', function () {
      // An error has occured with PayPal
    } )
    

paypal.open

The paypal.open event is broadcast when the PayPal window opens to take a payment.

  • Listener
    Commerce.subscribe( 'paypal.open', function () {
      // The user has opened the PayPal window
    } )
    

transaction.complete

The transaction.complete event is broadcast when a transaction has completed successfully.

  • Listener

    Commerce.subscribe( 'transaction.complete', function ( event ) {
      // The transaction has been completed
      console.log( event )
    } )
    
  • Event

    {
      data: {
        invoice: { ... }, // The invoice response
        message: 'Thank you for your purchase. ...',
        order: { ... } // The order that was processed
      }
    }
    

transaction.error

The transaction.error event is broadcast when a transaction attempt encounters an error.

This will occur regardless of the payment method or payment details.

  • Listener

    Commerce.subscribe( 'transaction.error', function ( event ) {
      // The transaction has encountered an error
      console.log( event )
    } )
    
  • Event

    {
      data: {
        message: 'An error has occured ...',
        response: { ... },
        error: { ... }
      }
    }
    

user.addresses.change

The user.addresses.change event is broadcast when the user's addresses change.

  • Listener

    Commerce.subscribe( 'user.addresses.change', function ( event ) {
      // The user's addresses have changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.user.addresses.get().

    {
      data:  {
        '-LtYPEmHSeo78Sz8CV5e': {
          city: 'Westerville',
          country: 'US',
          fullname: 'Lorrie Glick',
          line1: '4595 Quilly Lane',
          line2: null,
          postcode: '43081',
          state: 'OH'
        },
        '-LrM6xWAfLmnuuqYRIbl': {
          city: 'Manhattan',
          country: 'US',
          fullname: 'Inez Ellis',
          line1: '1989 Settlers Lane',
          line2: null,
          postcode: '10016',
          state: 'NY'
        }
      }
    }
    

user.auth.change

The user.auth.change event is broadcast when the user's authentication changes.

This occurs when the users identity is determined and whenever it changes due to Login or Logout.

  • Listener

    Commerce.subscribe( 'user.auth.change', function ( event ) {
      // The user's authentication has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.user.get().auth.

    {
      data: {
        anonymous: false,
        uid: 'lOE8XjQ9LRQRqEQlXIJd7gyX7Qw2'
      }
    }
    
  • Examples

    // The user has become an authenticated account
    {
      data: {
        anonymous: false,
        uid: 'lOE8XjQ9LRQRqEQlXIJd7gyX7Qw2'
      }
    }
    
    // The user has become an anonymous account
    {
      data: {
        anonymous: true,
        uid: 'hZgAnT8xktdEsl8HvSTszplWrMS2'
      }
    }
    
    // The user has temporarily become 'no account'
    // This occurs for a short period while the system is logging out
    {
      data: {
        anonymous: true,
        uid: null
      }
    }
    

user.change

The user.change event is broadcast whenever the user state changes.

  • Listener

    Commerce.subscribe( 'user.change', function ( event ) {
      // The user has changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.user.get().

    {
      data: {
        addresses:  {
          '-LtYPEmHSeo78Sz8CV5e': {
            city: 'Westerville',
            country: 'US',
            fullname: 'Lorrie Glick',
            line1: '4595 Quilly Lane',
            line2: null,
            postcode: '43081',
            state: 'OH'
          },
          '-LrM6xWAfLmnuuqYRIbl': {
            city: 'Manhattan',
            country: 'US',
            fullname: 'Inez Ellis',
            line1: '1989 Settlers Lane',
            line2: null,
            postcode: '10016',
            state: 'NY'
          }
        },
        auth: {
          anonymous: false,
          uid: 'lOE8XjQ9LRQRqEQlXIJd7gyX7Qw2'
        },
        details: {
          email: 'lorrie@glickclack.com',
          firstname: 'Lorrie',
          fullname: 'Lorrie Glick',
          lastname: 'Glick',
          phone: '8159445464'
        }
      }
    }
    

user.details.change

The user.details.change event is broadcast when the user's details change.

  • Listener

    Commerce.subscribe( 'user.details.change', function ( event ) {
      // The user's details have changed
      console.log( event )
    } )
    
  • Event
    The data is the same as returned by Commerce.user.details.get().
    All details only appear if they have been provided.

    {
      data:  {
        email: 'lorrie@glickclack.com',
        firstname: 'Lorrie',
        fullname: 'Lorrie Glick',
        lastname: 'Glick',
        phone: '8159445464'
      }
    }