Malomo.js Reference

Build modern post-purchase experiences for the web

This is the API reference for Malomo.js. Use Malomo.js' API to retrieve shipment information and build delightful post-purchase experiences for your customers.

Including Malomo.js

However you're using Malomo.js, you always begin by including the library and setting your API key. To get started, include this script on your pages -- it should always be loaded directly from https://js.gomalomo.com/v2/:

<script src="https://js.gomalomo.com/v2/"></script>

Malomo object

Malomo(publishableKey[, options])

Use Malomo(publishableKey[, options]) to create an instance of the Malomo object. Your Malomo publishable key is required when calling this function as it identifies your account.

This function accepts an optional options object. Available options are documented below:

  • url - the URL used when making API calls. Defaults to https://api.gomalomo.com.

malomo.elements()

Create pre-built UI components that allow you to add post-purchase elements to any page.

malomo.retrieveOrder(query)

Retrieve an Order using either it's id or alternate_id.

malomo.retrieveOrder({ id: 'ccb71edc-2952-4709-8880-9cb08c26724a' })
  .then(
    function(response) {
      // Handle response
    }
  );

Please note that metadata will not be included on Order objects when using Malomo.js.

This method will return a Promise which resolves with a Response object. This object contains body, headers and status properties.

malomo.fetchOrder()

Retrieve an Order by automatically using values stored as URL query parameters _m_id and _m_alt_id. If both _m_id and _m_alt_id are both present then _m_id will be used.

malomo.fetchOrder()
  .then(
    function(response) {
      // Handle response
    }
  );

This method will return a Promise which resolves with an array of Response objects. This object contains body, headers and status properties.

Elements object

elements.create(type, options)

Creates an instance of a specific Element. This method takes a type of Element to create and an options object.

Element type

  • shipmentTracker - renders a complete block that can be used for displaying the status of a shipment

Element options

  • classNamePrefix - a string appended to all CSS class names rendered by an element. Defaults to malomo.

elements.create('shipmentTracker', options)

Creates an Element that renders a complete shipment tracking experience.

Options

<div id="shipment-tracker"></div>

Delivery state defaults

  • noDate - Check back for an estimated delivery date

  • default - Estimated Delivery

  • delivered - Delivered

Status message defaults

  • unknown - ready to go

  • pre_transit - ready to go

  • in_transit - on its way

  • out_for_delivery - out for delivery

  • delivered - delivered

  • available_for_pickup - available for pickup

  • return to sender - returning to sender

  • failure - failed to delivery

  • cancelled - cancelled

  • error - error

elements.create('orderLookup', options)

Creates an Element that renders a complete order lookup experience.

The orderLookup element provides a consumer with the ability to lookup their own order. Once an order lookup element is rendered consumer will be able to locate their order by providing either their order number and the email address they made the purchase with or their shipment tracking code.

Options

<div id="order-lookup"></div>

Element object

element.mount(domElement)

Attaches your Element inside a DOM element. This method accepts a CSS selector (e.g. #shipment-tracker), an HTMLElement or a Promise which resolves with an HTMLElement.

This method will return a Promise that resolves with the element mounted. You can pass the return value of this method to another mount function to ensure that Element will be mounted in relation to the returned Element. 

<div id="some-element"></div>

element.mountAfter(domElement)

Similar to element.mount(domElement) but attaches your Element after the element specified by domElement.

<div>
  <div id="some-element">
    Hello, world!
  </div>
</div>

element.mountBefore(domElement)

Similar to element.mount(domElement) but attaches your Element before the element specified by domElement.

<div>
  <div id="some-element">
    Hello, world!
  </div>
</div>
PreviousAdd a tracking block to your website using Malomo.js

Last updated