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'
  }
}

# Events

# app.error

# app.ready

# cart.add

# cart.change

# cart.error

# config.ready

# coupons.change

# currency.change

# discounts.change

# inventory.change

# order.addresses.billing.change

# order.addresses.shipping.change

# order.addresses.change

# order.change

# order.notes.change

# order.payment.change

# order.payment.details.change

# order.payment.method.change

# order.quote.change

# order.quote.select

# paypal.cancel

# paypal.error

# paypal.open

# transaction.complete

# transaction.error

# user.addresses.change

# user.auth.change

# user.change

# user.details.change

Events

app.error

app.ready

cart.add

cart.change

cart.error

config.ready

coupons.change

currency.change

discounts.change

inventory.change

order.addresses.billing.change

order.addresses.shipping.change

order.addresses.change

order.change

order.notes.change

order.payment.change

order.payment.details.change

order.payment.method.change

order.quote.change

order.quote.select

paypal.cancel

paypal.error

paypal.open

transaction.complete

transaction.error

user.addresses.change

user.auth.change

user.change

user.details.change